To use Trulioo’s services, you need to authenticate your requests, and the method depends on the service you’re accessing. The Trulioo Platform and the latest Normalized API (NAPI v3) use OAuth 2.0, which requires you to obtain an access token to authorize your requests. In contrast, our legacy NAPI, uses Basic Authentication, where you include a Base64-encoded version of your API credentials in the request header. This page explains how to use both methods, format your credentials, send authentication requests, and handle errors.

Platform Authentication

Keys and Authentication

The Trulioo Platform API supports OAuth for enhanced security. OAuth 2.0 is the industry-standard protocol for authorization. OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications, desktop applications and mobile phones. Once you receive a Client ID and Client Secret for your Trulioo Platform API account, you're all set to request a token for access

Request for a Token

Use your Client ID and Client Secret to generate a bearer token by requesting the endpoint below. Make sure your request sets grant_type to client_credentials and the scope to workflow.studio.api. Scope represents the service you'd like to run against.

Token lifecycle

Tokens are time-sensitive and need to be used before they expire. A token request will also return its lifetime in seconds under the ExpiresIn field which typically lasts for one hour.

Request

POST /connect/token HTTP/1.1
Host: auth-api-primary.dev.trulioo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 150

grant_type=client_credentials&scope=workflow.studio.api&client_id=12345x2e0&client_secret=12345%3B

Response

{  
    "Token":  "authenticationtoken",  
    "TokenType": "bearer",  
    "ExpiresIn": 3599,
    "scope": "workflow.studio.api"
}

You can also find the expiration time within the token itself. The token's payload, encoded in base64, includes the expiration time under "exp", indicating the Epoch time when the token will expire.

If an expired token is used to call any endpoint that requires authentication, a 401 Unauthorized Error will be returned. Simply follow the token request steps again to obtain a new token.

Best Practices

Security

Always secure your API keys and tokens, avoid hardcoding in your codebase.

Logging and Monitoring

Implement logging for troubleshooting and monitoring the API usage for optimization.

Token lifecycle

Generating new token wil not invalidate the previous token. Allow for buffer time while updating the token.

Normalized API Authentication

Trulioo's Normalized API uses OAuth 2.0.

• You'll need a Client Id and Secret to generate a token. (The Client Id and Client Secret can be provided by your respective Customer Success Manager within Trulioo)
• With this Client Id and Secret a user can generate a bearer token. The API takes in the bearer token generated from api credentials with Identity Server. See "Requesting a Token" below for more details.
• You can now use the bearer token for any request to API.

See Test Authentication API reference for more examples.

Requesting a Token

Using your Client Id and Client Secret you can generate a bearer token by calling the following endpoint - https://auth-api.trulioo.com/connect/token. Set the grant_type as client_credentials.

Request

POST /connect/token
CONTENT-TYPE application/x-www-form-urlencoded

    client_id=client1&
    client_secret=secret&
    grant_type=client_credentials

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  	"access_token": "Eqb2qTGG9MV27k-10HH-wOtrOCZ0guooRJVw30z4QOc0194v3MC3-IwGtSXOeqS45IbElWSXKofdeypCPoVJ9A845VLD6B7Hj5Us9QTDSeFcNsPiTrYKobY12c8Zeq8BF632QnFOFXg4mvcyVz8a6WhkrhUOn5oV7X6sHvOfVeF1_B734O-ECYEAKwwj0TidYm1gnQ",
  	"expires_in": 1800,
  	"token_type": "Bearer",
  	"scope": “napi.api”
}

If your client_id or client_secret is wrong, you will see:

HTTP/1.1 400 BAD REQUEST
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
	"error": “invalid_client”
}

If provided grant_type is wrong, you will see:

HTTP/1.1 400 BAD REQUEST
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
	"error": “unsupported_grant_type”
}