Bearer Token and Scopes

One of the first integration milestone is to establish a correctly authenticated request with World-Check On Demand. The first step is by retrieving an OAuth 2.0 token using the credentials that you have been issued by LSEG or retrieved via the Platform Admin App (PAA).

Token URL

Token URL	Grant Type	Token Duration (default)	Token Type
https://login.ciam.refinitiv.com/as/token.oauth2	client_credentials	120 minutes	JWT

Scope

When requesting for a token using the token URL above, the appropriate scope must be sent in the request's scope payload depending on the target World-Check On Demand environment:

Environment	Scope
Production	trapi.risk-intel.wcod.
Sandbox	trapi.risk-intel.wcod-sandbox. trapi.risk-intel.wcod.

While it is possible to use one service account for both environments, it is highly recommended that access to these environments are made through separate accounts that are assigned their respective licenses.

Token Duration

World-Check On Demand offers three token duration options:

lifetime code	validity (mins)	aud parameter value
short	5	jwt:short:default
medium	120	jwt:medium:default or jwt:default:default
long	1440	jwt:long:default

The default is medium. When specifying the token lifetime in the token request, this must be sent as part of the audience (aud) parameter value.

Please see the Authentication section for more details.

Retrieval Variations

There are two accepted variations to token retrieval, as shown by these examples:

Credentials are sent in the Authorization header as Basic Authentication.

curl --location 'https://login.ciam.refinitiv.com/as/token.oauth2' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ••••••' \
--header 'Cookie: PF=xzHlIxELDuTKeKOMuR4jl0' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=trapi.risk-intel.wcod.' \
--data-urlencode 'aud=jwt:short:default'

Post Authentication where credentials are sent in the payload.

curl --location 'https://login.ciam.refinitiv.com/as/token.oauth2' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Cookie: PF=xzHlIxELDuTKeKOMuR4jl0' \
--data-urlencode 'client_secret=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
--data-urlencode 'client_id=XXXXXXXXXXXXXXXXXX' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=trapi.risk-intel.wcod.' \
--data-urlencode 'aud=jwt:short:default'

If successful, either of these requests will generate an HTTP/200 response like this:

A typical response to a successful authentication.

{
    "access_token": "eyMk80VFM3x4VnNtMTlyejkwbyIsInBpLmF0bSI6ImdncWkiLCJ0eXAiOiJhdCtKV1QifQeyJzY29wZSI6InRyYXB29kLmRhdGEuaWVpLnJlYWQiC4iLCJhdXRob3JpemF0aW9uX2RldGFpbHMiOltdLCJjbGllbnRfaWQiOiJHRS0zMk80VFM3Vk1IMkUiLCJlbnRpdGxvcmRzLnJlYWQiLCJ0cmFwaS5yaXNrLWludGVsLndjb2QucmVmZXJlbmNlcy5yZWFkIiwidHJhcGkucmlzay1pbnRlbC53Y29kLmRhdGEuaWVpLnJlYWQiLCJ0cmFwaS5yaXNrLWludGVsLndjb2QuZGF0YS5hbGwucmVhZCJdLCJzdWIiOiJHRS0zMk80VS5yZWZpbml0TUgyRSIsImV4cCI6MTc1NjQzMzE5Mn0.p_lFpzuabySgYMj5BeAdyVxy7BO2VkGngZSpr5v3wflK9-GUp-DBHam3Smtq8mUs7pdoVwN4fvxA6gFBIr0piw",
    "token_type": "Bearer",
    "expires_in": 299
}

Securely keep this token and re-use it for all subsequent API requests within its validity period. Only request for a new token when at or close to the token expiration.

Errors

If your credentials are not accepted, you will get a HTTP/401 error like this:

A typical HTTP/401 message due to invalid credentials when retrieving a token.

{
    "error_description": "Invalid client or client credentials.",
    "error": "invalid_client"
}

Please ensure that your application gracefully handles this error and only have a small number of retries.

Rate Limit

The token URL is rate-limited to 1500 requests per IP address on a rolling 5-minute evaluation window. Request rates going beyond that will be temporarily blocked until rates go below the limit within the next evaluation window.

BEST PRACTICE

Re-use the token within the same process while is it valid instead of retrieving a new token for each API request.

Please see the section on Authentication & Authorisation for more details.