Task 1: Create a Simphony Transaction Services Gen2 Account

The information needed to add an API account depends on the API for which you are adding the account. When you add an account for the second generation of the Simphony Transaction Services API, select Simphony Transaction Services as the account type. See Adding API Accounts.

The following table describes permissions and authorization details for the Simphony Transaction Services Generation 2 API:

The unique Client ID generated for the API account is used for authenticating when calling the API.

A Welcome email is sent to the registered email address of the API account with instructions to set the password for the API account.

Task 2: Authorize with OpenID

Authorize the account with the OpenID provider to sign in with the API account. This step is required to subsequently sign in to the API account.

1. Generate a code_verifier.

   A code_verifier is a cryptographic string that is Base64 encoded. Example:

   // Dependency: Apache Commons Codec
   // https://commons.apache.org/proper/commons-codec/
   // Import the Base64 class.
   // import java.util.Base64;
   SecureRandom sr = new SecureRandom();
   byte[] code_string = new byte[32];
   sr.nextBytes(code_string);
   String code_verifier = Base64.getUrlEncoder().withoutPadding().encodeToString(code_string);

2. Generate a code_challenge.

   A code_challenge is a cryptographic key that encrypts the code_verifier using SHA256 algorithm. Example:

   // Dependency: Apache Commons Codec
   // https://commons.apache.org/proper/commons-codec/
   // Import the Base64 class.
   // import org.apache.commons.codec.binary.Base64;
   byte[] verifier_bytes = code_verifier.getBytes("US-ASCII");
   MessageDigest msgdigest = MessageDigest.getInstance("SHA-256");
   msgdigest.update(verifier_bytes, 0, verifier_bytes.length);
   byte[] digest = msgdigest.digest();
   String challenge = Base64.encodeBase64URLSafeString(digest);

3. Authorize with OpenID.

   The client application must invoke the following API for OpenID authorization to get an authorization_code. The following table describes the components that comprise the request for an authorization_code:

   Request

   API Request Parameters	Description	Example
   URL	URL for the authorize API. Replace {HOST} with the actual host server name and port where the Authentication Server is hosted for the enterprise.	{HOST}/oidc-provider/v1/oauth2/authorize
   Operation Type	HTTP GET request type.	GET
   cookiefilename	Temporary file name to save the cookies in the response.	<cookiefilename>
   Query Parameters	List of query parameters. See next table for parameters.

   Query Parameter	Description	Example
   response_type	Set to code.	code
   client_id	OAuth 2.0 Client Identifier that is generated when the API account was created.	<client_id>
   scope	Set to openid.	openid
   redirect_uri	Set to apiaccount://callback.	apiaccount://callback
   code_challenge	This is a 43-128 character-long client-generated string. This string must first be hashed using SHA-256 and then Base 64 encoded. Use the code_challenge that was generated in previous step.	H9K........Ik
   code_challenge_method	Set to S256.	S256

   Sample Request

   curl -c <cookiefilename> --request GET "{HOST}/oidc-provider/v1/oauth2/authorize?response_type=code&client_id=NTAzMDQ0NjItNzA5Yy00YjZlLWI0NjItN2U1YWRhZDBmYzcxLmE4OGM4Njg0LTNmMmMtNGFlYS1hMjdjLTdhZTU4MTJhYzIwNw%3D%3D&scope=openid&redirect_uri=apiaccount://callback&code_challenge=H9KVBZo4Zwa_rRR_X-KyfycPWuP2417K15w42JqsAIk&code_challenge_method=S256"

   Sample Response

   A successful request creates a temporary cookie file that saves the cookies required for subsequent API calls.

   HTTP/1.1 200 OK

   Sample Cookie File Contents

   #HttpOnly_{HOST}      FALSE   /       FALSE   0       redirect_uri    apiaccount://callback
   #HttpOnly_{HOST}      FALSE   /       FALSE   0       client_id       NTAzMDQ0NjItNzA5Yy00YjZlLWI0NjItN2U1YWRhZDBmYzcxLmE4OGM4Njg0LTNmMmMtNGFlYS1hMjdjLTdhZTU4MTJhYzIwNw==
   #HttpOnly_{HOST}      FALSE   /       FALSE   0       response_type   code
   #HttpOnly_{HOST}      FALSE   /       FALSE   0       state
   #HttpOnly_{HOST}      FALSE   /       FALSE   1601465478      code_challenge  H9KVBZo4Zwa_rRR_X-KyfycPWuP2417K15w42JqsAIk
   #HttpOnly_{HOST}      FALSE   /       FALSE   1601465478      code_challenge_method   S256

   Sample Error Response

   The following example shows an error caused by invalid input in the request:

   HTTP/1.1 400 Bad Request
   Content-Type: application/json
   {
       "status":400,
       "message":"INVALID_CLIENT",
       "code":"VALIDATION_ERRORS"
   }

Task 3: API Account Sign-In

The client application must submit the API account's sign-in credentials to the server. Upon successfully signing in, the system returns a response with an authorization code that can be exchanged for an id_token in the following task.

Request

Invoke the API request below and pass the required information for obtaining an authorization code. The following table describes the components that comprise the request for an authorization code:

Sample Request

curl -b <cookiefilename> --request POST "{HOST}/oidc-provider/v1/oauth2/signin" --header "Content-Type: application/x-www-form-urlencoded" --data-urlencode "username=<apiaccountusername>" --data-urlencode "password=<apiaccountpassword>" --data-urlencode "orgname=<organizationshortname>"

Sample Successful Response

The response returns the authorization code (auth_code) in the redirectUrl attribute of the response if the request is successful.

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
{"nextOp":"redirect","success":true,"redirectUrl":"apiaccount://callback?code=<auth_code>"}

Sample Response for a Locked Account

If you use the wrong account password too many times, the account becomes locked and the account owner receives an email. Try to sign in again in 30 minutes or reset the password by clicking Can't sign in on the Reporting and Analytics sign-in page.

{
    "status": 401,
    "message": "Invalid credentials.",
    "code": "AUTHENTICATION_INVALID"
}

Sample Response for Expired Password

If the account password expires, the response includes details in the nextOp, success, redirectURL, and error attribute values. To resolve this, update or reset the account password from the Reporting and Analytics sign-in page.

{
    "nextOp": "expired",
    "success": false,
    "redirectUrl": "<application server URL>",
    "userName": "<api account name>",
    "emailAddress": "<email address assigned to the api account>",
    "orgName": "<organization short name>",
    "opUserId": "<used for internal application purposes>",
    "orgId": <used for internal application purposes>,
    "tenantId": "<used for internal application purposes>",
    "language": "en-US",
    "pwdResetToken": "<used for internal application purposes",
    "error": "You must change your password."
}

Sample Error Response

The following example shows an error caused by invalid input in the request:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{"status":401,"message":"Invalid credentials.","code":"AUTHENTICATION_INVALID"}

Task 4: Get or Refresh a Token

Once you have the authorization code, your client application needs an OAuth2.0-based ID token to make the API call. The ID token provides a session (with scope and expiration), that your client application uses to make API calls.

The token API returns an ID token and a refresh token. Your integration should save both.

Request

Your application passes the following for obtaining a token:

Sample Request to Get a New Token

curl -b cookiefile -c cookiefile --request POST "{HOST}/oidc-provider/v1/oauth2/token" --header "Content-Type: application/x-www-form-urlencoded" --data-urlencode "scope=openid" --data-urlencode "grant_type=authorization_code" --data-urlencode "client_id=<client_id>" --data-urlencode "code_verifier=<code_verifier>" --data-urlencode "code=<auth_code>" --data-urlencode "redirect_uri=apiaccount://callback"

Sample Request to Refresh a Token

curl -b cookiefile -c cookiefile
--request POST "{HOST}/oidc-provider/v1/oauth2/token" --header "Content-Type: application/x-www-form-urlencoded" --data-urlencode "scope= openid" --data-urlencode "grant_type= refresh_token" --data-urlencode "client_id=<client_id>" --data-urlencode "refresh_token=<refresh_token>" --data-urlencode "redirect_uri=apiaccount://callback"

Sample Successful Response

The response returns the OAuth2.0 token string if the request is successful.

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
{ 
	"access_token": "<access_token string>", 
	"token_type": "Bearer",
	"expires_in": "1209600", 
	"id_token": "<token string>", 
	"refresh_token": "<token string>"
}

Sample Error Response

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{"status": 401,"message": "AUTHENTICATION_CODE_NOT_FOUND","code": "RECORD_NOT_FOUND"}

JSON Response

Contains the access token request output in JSON format. The response contains the attributes access_token, id_token, refresh_token, token_type, and expires_in.

If you see the error AUTHENTICATION_INVALID after a Reporting and Analytics upgrade, clients should go through the authentication process again and obtain a new token.

You must repeat the authentication process if your client lost the ID token or the refresh token or if the client missed a refresh to the token prior to its expiration. The password of the API account expires after 60 days and needs to be changed after that. The account password can be reset from the Reporting and Analytics sign-in page by clicking Can't sign in?.

Task 5: Using the id_token in API Calls

Once you have successfully received the authentication id_token, the client application can use the same to make API requests. Use the following header parameters to insert the id_token.

Sample