Authenticating

The very first REST API request must be to authenticate to a specific Responsys account using a username and a password or certificates.

Upon successful authentication, a token and an endpoint are returned in the response. You must use these authToken and endPoint values for any subsequent REST API request.

Transport Layer Security Support

Ensure that your client systems use Transport Layer Security (TLS) version 1.2.

Login with username and password

IMPORTANT NOTE: For security reasons you must pass username and password as parameters in the POST request body only with the correct content type ('Content-Type': 'application/x-www-form-urlencoded'). Therefore, you must NOT use the URL string for passing in the authentication credentials.

Service URL:

/rest/api/v1.3/auth/token

Request Method:

POST

Request Header

Content-Type: application/x-www-form-urlencoded

Request Parameters

Send in message body, x-www-form-urlencoded:

user_name=<USER_NAME>
password=<PASSWORD>
auth_type=password

Sample Login Request:

URL:

/rest/api/v1.3/auth/token

Sample Request Body:

user_name=<USER_NAME>&password=<PASSWORD>&auth_type=password

Response:

{
 "authToken" : "<AUTH_TOKEN>",
 "issuedAt" :  < TIMESTAMP > ,
 "endPoint" : "<ENDPOINT_URI>"
}

Login with username and certificates

Instead of using a password, a server and a client certificate can be used for authenticating with a username. Logging in with certificates is based on the use of a digital certificate in accordance with the X.509 standard for public key infrastructure (PKI).

Before you can use this type of login in a client application, the Oracle Responsys account administrator must log in to the Oracle Responsys user interface and navigate to the admin console for managing users. From the console, the admin must enable the API user to use certificates, upload a digital certificate (client user public key), and download the Responsys API server digital certificate (server public key).

Performing this type of authentication requires two REST API calls, as described in the steps below. To see this illustrated in an example script, refer to Authentication with Certificates.

  1. Authenticate server by sending the following REST request.

    IMPORTANT NOTE: For security reasons you must pass username and password as parameters in the POST request body only with the correct content type ('Content-Type': 'application/x-www-form-urlencoded'). Therefore, you must NOT use the URL string for passing in the authentication credentials.

    Service URL:

    /rest/api/v1.3/auth/token

    Request Method:

    POST

    Request Header

    Content-Type: application/x-www-form-urlencoded

    Request Parameters

    Send in the Request Body in x-www-form-urlencoded format:

    user_name=<USER_NAME>
auth_type=server
client_challenge=<CLIENT_CHALLENGE_VALUE>

    For REST, the client_challenge must be a plain random number and/or text string of your choice, which you must then convert to byte and then Base64 encode.

  2. You should receive the following response from the server. Decrypt (using the RSA algorithm) the encrypted clientChallenge using server certificate’s public key (which you should have downloaded and stored on your system). If they match, proceed to the next step. If they don’t match, please do not proceed with steps 3 and 4 in this section. Instead, contact Oracle Support.

    Response:

    {
 "authToken" : "<TEMP_AUTH_TOKEN>",
 "serverChallenge" : "<BASE_64_ENCODED_SERVER_CHALLENGE>",
 "clientChallenge" : "<ENCRYPTED_AND_THEN_BASE_64_ENCODED_CLIENT_CHALLENGE>"
}

  3. Log in with username and certificate using the following REST request (do the encryption using the public key from the Responsys server certificate):

    Service URL:

    /rest/api/v1.3/auth/token

    Request Method:

    POST

    Request Header

    Authorization=<TEMP_AUTH_TOKEN>   (this is obtained from the response in step 2 above)
Content-Type: application/x-www-form-urlencoded

    Request Parameters:

    user_name=<USER_NAME>
auth_type=client
server_challenge=<SERVER_CHALLENGE_ENCRYPTED_USING_CLIENT_USER_PRIVATE_KEY>

  4. You should receive the following response from the server. You can use this authentication token and endpoint until the token expires (2 hours from issue time) or until you refresh the token and receive a new one, as described in the next section.

    Response:

    {
 "authToken" : "<AUTH_TOKEN>",
 "issuedAt" :  <TIMESTAMP>,
 "endPoint" : "<ENDPOINT_URI>"	
}

Refresh token

In the REST API, the authorization token is stateless and it always expires after two hours. However, you can refresh the existing token before it expires. If you refresh the token, the system generates a new token from the existing valid one, so that you will not need to re-authenticate. The same token used previously is not returned.

Service URL:

/rest/api/v1.3/auth/token

Request Method:

POST

Request Parameters:

auth_type=token

Request Header:

Authorization=<AUTH_TOKEN>

Response:

{
 "authToken" : "<NEW_AUTH_TOKEN>",
 "issuedAt" :  <TIMESTAMP> ,
 "endPoint" : "<ENDPOINT_URI>"
}

Learn more