{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":896,"path":"api-reference/server-api-reference/RequestAuthAPI.md","title":"RequestAuthAPI - Scoped","bundle":null,"doc_type":null,"release":"australia","body":"\n# RequestAuthAPI- Scoped\n\nThe RequestAuthAPI provides methods to apply a signature to a REST request.\n\nGenerate outbound signing requests using these APIs in the following order:\n\n1.  HttpRequestData: Build the API request.\n2.  AuthCredential: Create a credential object or update an existing one. Use the credential to sign the request through the RequestAuthAPI class.\n3.  RequestAuthAPI: Sign the request and return an HttpRequestAuthedData object.\n4.  HttpRequestAuthedData: Get information about the signed request.\n5.  GlideHTTPRequest: Send the signed request.\n\nBefore using these APIs, you must [configure an authentication algorithm](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/configure-authentication-algorithm.md) to sign the request and associate it with the credential used to authenticate the request.\n\nUse this API in scoped scripts with the `sn_auth` namespace identifier.\n\n**Parent Topic:**[Server API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/api-server.md)\n\n## RequestAuthAPI - RequestAuthAPI\\(Object data, Object credential\\)\n\nInstantiates a RequestAuthAPI object using a REST request and a credential.\n\n|Name|Type|Description|\n|----|----|-----------|\n|data|Object|HttpRequestData object that contains the unsigned REST request. Use the HttpRequestData class to build this object. See [HttpRequestData API](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/HttpRequestDataAPI.md).|\n|credential|Object|Object that represents a record from the Credentials \\[discovery\\_credentials\\] table. Retrieve this object using the AuthCredential class. See [AuthCredential API](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/AuthCredentialAPI.md).|\n\n```\n// Define the HttpRequestData object\nvar endpoint= \"https://third-party-endpoint\";\nvar httpRequestData = new sn_auth.HttpRequestData();\nhttpRequestData.setEndpoint(endpoint);\nhttpRequestData.setService('s3');\nhttpRequestData.setRegion('us-east-1');\nhttpRequestData.setHttpMethod(\"PUT\");\nvar content = \"Action=SendMessage&MessageBody=This is a test message\";\nhttpRequestData.setContent(content);\nhttpRequestData.addHeader('x-amz-acl' , 'public-read' );\n \n // Get a credential record\nvar credential = new sn_cc.StandardCredentialsProvider().getAuthCredentialByID(\"88772d0d40990010f8772fdd9ebc8075\");\n \n// Instantiate a RequestAuthAPI object\nvar signingAPI = new sn_auth.RequestAuthAPI(httpRequestData, credential);\n```\n\n## RequestAuthAPI - generateAuth\\(\\)\n\nSigns the HttpRequestData object and returns an HttpRequestAuthedData object to use to send in the REST request.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|HttpRequestAuthedData|Object. Data to use to obtain information about the signed result. Use the methods in the HttpRequestAuthedData class to interact with the signed result. See [HttpRequestAuthedData API](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/HttpRequestAuthedDataAPI.md).|\n\nThis example creates a request and gets a credential record to pass to the RequestAuthAPI API. The generateAuth\\(\\) method then signs the request.\n\n```\n// Define the HttpRequestData object\nvar endpoint= \"https://third-party-endpoint\";\nvar httpRequestData = new sn_auth.HttpRequestData();\nhttpRequestData.setEndpoint(endpoint);\nhttpRequestData.setService('s3');\nhttpRequestData.setRegion('us-east-1');\nhttpRequestData.setHttpMethod(\"PUT\");\nvar content = \"Action=SendMessage&MessageBody=This is a test message\";\nhttpRequestData.setContent(content);\nhttpRequestData.addHeader('x-amz-acl' , 'public-read' );\n \n// Get a credential record\ngs.info( \"date:\" + httpRequestData.getDate() );\nvar credential = new sn_cc.StandardCredentialsProvider().getAuthCredentialByID(\"5b61c16f73533300f662cff8faf6a74b\");\n \n// Create the RequestAuthAPI object and sign the request\nvar signingAPI = new sn_auth.RequestAuthAPI(httpRequestData, credential);\nvar output = signingAPI.generateAuth();\n \n```\n\n## RequestAuthAPI - getAuthCredential\\(\\)\n\nReturns the credential record used to sign the request.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|AuthCredential|Object. Data to use to obtain information about the credential record used to sign the request. Use the methods in the AuthCredential class to interact with the credential. See [AuthCredential API](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/AuthCredentialAPI.md).|\n\n```\n// Define the HttpRequestData object\nvar endpoint= \"https://third-party-endpoint\";\nvar httpRequestData = new sn_auth.HttpRequestData();\nhttpRequestData.setEndpoint(endpoint);\nhttpRequestData.setService('s3');\nhttpRequestData.setRegion('us-east-1');\nhttpRequestData.setHttpMethod(\"PUT\");\nvar content = \"Action=SendMessage&MessageBody=This is a test message\";\nhttpRequestData.setContent(content);\nhttpRequestData.addHeader('x-amz-acl' , 'public-read' );\n \n// Get a credential record\nvar credential = new sn_cc.StandardCredentialsProvider().getAuthCredentialByID(\"5b61c16f73533300f662cff8faf6a74b\");\n \n// Return the AuthCredential object\nvar signingAPI = new sn_auth.RequestAuthAPI(httpRequestData, credential);\nvar signingCredential = signingAPI.getAuthCredential();\n```\n\n## RequestAuthAPI - getHttpRequestData\\(\\)\n\nReturns the HttpRequestData object that was used to instantiate the RequestAuthAPI class.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|HttpRequestData|Object. Contains the unsigned REST request. Use the methods in the HttpRequestData class to interact with the request. See [HttpRequestData API](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/HttpRequestDataAPI.md).|\n\n```\n// Define the HttpRequestData object\nvar endpoint= \"https://third-party-endpoint\";\nvar httpRequestData = new sn_auth.HttpRequestData();\nhttpRequestData.setEndpoint(endpoint);\nhttpRequestData.setService('s3');\nhttpRequestData.setRegion('us-east-1');\nhttpRequestData.setHttpMethod(\"PUT\");\nvar content = \"Action=SendMessage&MessageBody=This is a test message\";\nhttpRequestData.setContent(content);\nhttpRequestData.addHeader('x-amz-acl' , 'public-read' );\n \n // Get a credential record\nvar credential = new sn_cc.StandardCredentialsProvider().getAuthCredentialByID(\"88772d0d40990010f8772fdd9ebc8075\");\n \n// Return the HttpRequestData object\nvar signingAPI = new sn_auth.RequestAuthAPI(httpRequestData, credential);\nvar unsignedRequest = signingAPI.getHttpRequestData();\n \ngs.info(\"Endpoint is: \" + unsignedRequest.getEndpoint());\n```\n\nOutput:\n\n```\nEndpoint is: https://third-party-endpoint\n```\n\n## RequestAuthAPI - resetAuthCredential\\(\\)\n\nGenerates a temporary, limited privilege token that you can use to provide trusted users with temporary security credentials to control third-party resources.\n\nTo use this method, the third-party service must include an API or SDK that processes and manages limited access tokens.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n```\n// Creates a temporary token \nfunction(authAPI) {​\n    var requestData = authAPI.getHttpRequestData();​\n    var credential= authAPI.getAuthCredential();​\n    credential.setAttribute('Action', 'aws_sessionToken');​  \n    authAPI.resetAuthCredential();\t\n\n    //Returns status information\n    var status = credential.getAttribute('credential_reset_status'); ​\n}\n```\n\n"}}