Skip to main content

Authentication & Authorisation

Authentication​

World-Check On Demand only supports authorisation using OpenID Connect (OIDC) using either Basic or Post authentication mechanisms.

Basic Authentication​

In this method, the client ID and client secret are combined into a single string, separated by a colon, and then Base64-encoded. The resulting string is included in the Authorization header of the HTTP request.

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​

In situations where Basic Authentication is not supported or preferred, the credentials can be sent in the body of the HTTP request. The request includes the client_id and client_secret as form parameters, along with other parameters such as the grant type, scope and audience.

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'

As shown using either mechanisms above, the client_id and client_secret are provided to the token URL in exchange for a token:

EnvironmentToken URLGrant TypeToken Duration (default)
Production + Sandboxhttps://login.ciam.refinitiv.com/as/token.oauth2client_credentials7200 seconds

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
}

Once the token is received, it must be sent in the Authorization header with every API request, except for the OPTION method.

It is good security practice to allow each process that is interacting with the API to have their own tokens. The tokens must be securely kept and re-used for all subsequent API requests within its validity period. Only request for a new token when at or close to the token expiration.

If the credentials are not accepted, an HTTP/401 error similar to this will be returned:

A typical HTTP/401 message due to invalid credentials when retrieving a token.
{
    "error_description": "Invalid client or client credentials.",
    "error": "invalid_client"
}

OAuth 2.0 Authorisation​

Token Type​

The only supported token type is JSON Web Token (JWT). Although the token URL can issue opaque tokens, such will not be valid and will be responded with:

Error message when a reference or opaque token is used
{
    "error": {
        "code": "403",
        "id": "d987654321-3f56-4556-967d-123abc987",
        "message": "Access denied",
        "status": "Forbidden",
        "errors": [
            {
                "key": "entitlement",
                "reason": "access denied. No entitlement found in the token."
            }
        ]
    }
}

All LSEG-issued credentials are configured with JWT as the default token type. However, clients issuing or managing their own credentials using the Platform Admin Application (PAA) must ensure that the token type is JWT and not Reference. Alternatively, clients can force a JWT type token when calling the token URL by explicitly setting the first audience (aud) parameter value in the x-www-form-urlencoded body:

Audience parameter requesting a JWT type token in the request body (bottom parameter)
client_secret: "a12345678-b987-5678-c987-987654321"
client_id: "GE-ABC123456XYZ"
grant_type: "client_credentials"
scope: "trapi.risk-intel.wcod."
aud: "jwt:short:default"

Another way is simply pass this as a query string when calling the token URL:

Audience parameter as query parameter
https://login.ciam.refinitiv.com/as/token.oauth2?aud=jwt:default:default

Please refer to the API Reference for additional information related to the token request.

Audience Parameter​

The audience parameter consists of three parameters separated by a semicolon in the format:

{Token Type}:{Lifetime}:{Control}

  • Token Type: Specifies whether the requested token is a reference token (aka opaque token) or a JSON Web Token (JWT) type. The latter is also called a self-contained token which includes all entitlements based on the requested scope. World-Check On Demand only supports the JWT type token.
  • Lifetime: Tokens issued by the token URL can have different duration of validity or lifetime. The default value is 120 minutes (2 hours). Here are the possible token lifetime values:
lifetime codevalidity (mins)notes
short5
medium120also known as default
long1440
  • Control: This is currently not configurable and must remain as default.

Considering that the token type and control must remain the same, the audience parameter is effectively used to modify the token lifetime, matching your risk appetite and other related security policies.

When the token has expired, an HTTP/401 error will be provided when it is used in an API request.

HTTP/401 error when a token has expired.
{
    "error": {
        "id": "1d710cb2-6e18-4d25-b0de-9847b025e4ff",
        "code": "401",
        "message": "token expired",
        "status": "Unauthorized"
    }
}

Examples:

  1. jwt:default:default - This is a JWT type token with a default lifetime of 120 minutes. This can also be written as jwt:medium:default.
  2. jwt:short:default - This is a JWT type token with a short lifetime of 5 minutes.
  3. jwt:long:default - This is a JWT type token with a long lifetime of 24 hours.

As noted in the previous section, the audience parameter can be provided in two different ways.

Scope​

The scope parameter limits an account's access to certain endpoints, features, or data. An application can request one or more scopes, or a single but wider or narrower scope. The issued access token will then be limited to the granted scopes out of what was requested.

Available scopes for World-Check On Demand:

EnvironmentScopeAccessAccess Type
Productiontrapi.risk-intel.wcod.records.readPOST /recordsGateway
Productiontrapi.risk-intel.wcod.references.readGET /schemes
GET /concepts		Gateway
Data
Sandboxtrapi.risk-intel.wcod-sandbox.records.readPOST /recordsGateway
Sandboxtrapi.risk-intel.wcod-sandbox.references.readGET /schemes
GET /concepts		Gateway
Data
Production
Sandbox		trapi.risk-intel.wcod.data.all.readAll World-Check data, except IEI*Data

*Iran Economic Indicators

Access Type​

Scopes are classified as either Gateway or Data entitlements:

  • Gateway: Allows specific requests to be accepted by the LSEG API gateway.
  • Data: Allows the retrieval of a specific type of data.

Effective access to certain types of data may require a specific scope to get through the gateway to reach a specific endpoint, and another data-level scope to get the right data. For example, getting World-Check records requires gateway access to the POST /records endpoint. That alone does not allow access to the data, just the ability to request the data. A data-level scope is required for data access.

Examples:

  1. scope: "trapi.risk-intel.wcod.references.read trapi.risk-intel.wcod.records.read trapi.risk-intel.wcod.data.all.read"
    • allows the account to call any of the Reference API endpoints and retrieve reference information
    • allows the account to call the Records API endpoint
    • allows the account to retrieve any World-Check record except IEI
    • make sure that there is a single space between scopes
  2. scope: "trapi.risk-intel.wcod.
    • scopes can be shortened and effectively means requesting for all possible entitlements that starts with the requested scope string
    • this example allows the account to do everything in the previous example
  3. scope: "trapi.risk-intel.wcod-sandbox."
    • allows the account to request and retrieve all references from the Sandbox environment
    • allows the request for synthetic records from the Sandbox environment, but does not allow the data retrieval as this requires the trapi.risk-intel.wcod.data.all.read scope, which is not covered by the requested scope
tip

Use the following scopes if fine-grained control isn't required by the application:

  • Production: trapi.risk-intel.wcod.
  • Sandbox: trapi.risk-intel.wcod-sandbox. trapi.risk-intel.wcod.all.read (two scopes with a space in between)

Token URL Rate Limit​

LSEG is enforcing a rate limit on the token URL to effectively manage system performance, protect the service, and ensure an equitable distribution of resources among users.

The current rate limits is:

Rate LimitTypeDescription
1500 token requests in 5 minutesToken RequestMaximum number of token requests within 5 minutes. The IP will be blocked for 5 minutes if this is breached and no response will be provided.

Tokens should be securely stored and re-used while it is active. Applications should check the token's expiry and only request a new one when necessary, instead of requesting a new token for each API call.