Overview

Location Intelligence APIs restrict access to protected API resources by means of security credentials. A client applications must pass valid security credentials in every request it makes to the API. These credentials enable the platform to authenticate the identity of the client application and confirm that the client application is authorized to access and leverage the requested resources.

The Location Intelligence API supports two authentication methods:

• The API key identifies a project or client application that is entitled to call the API. The API key provides the client with long-term access to API resources.
• The access token identifies a user account that is entitled to call the API. The access token provides the client with temporary access to API resources. OAuth access tokens are generated "on a per-session basis."

The client must pass an API key or access token in the Authorization header of every request made to the API. If the API cannot authenticate the client, the API rejects the request.

📷

RECOMMENDATION

Moody's RMS recommends that tenants use API keys to authenticate application clients accessing the Location Intelligence API. API keys provide client applications with long-term access to API resources and do not require refreshing. Token-based authentication is an appropriate solution for evaluating and testing, but should not be used in production.

API key authentication

An API key is an encrypted string that identifies an application client that is entitled to access protected API resources. Unlike a web token, the API key is not tied to a particular user account.

The API key enables API to authenticate the client and authorize requests from that application client based on access rights and permissions granted to that API key. The client application as the bearer of the API key has all access rights and permissions encoded in that key.

The client application passes the API key in the Authorization header of every request it makes to the API.

Obtain API keys

Developers must contact their tenant administrator to acquire an API key.

All API keys are created and managed by tenant administrators in Admin Center. For more information on the administration of API keys, see the Intelligent Risk Administrator Guide.

Submit API keys in requests

The client must provide credentials whenever it makes a request using Location Intelligence API. The API key may be specified in the HTTP Authorization request header:

curl --location --request GET 'https://{{host}/riskmodelerv1/datasources' \
--header 'Authorization: {api_key}'

The API key enables the API to authenticate the client and determine if the client is authorized to perform the requested operation.

Web token authentication

An access token is a type of web token that provides client applications with temporary access to API resources. The client uses the access token as a bearer token that it passes as a credential in the HTTP Authorization header of every request.

In token-based authentication, the client accesses the API on behalf of a user account and utilizes that user account's credentials to identify itself. The access token encodes the access rights and permissions of a specific user account.

For security purposes, access tokens are issued on a per-session basis. When the access token expires, the client must re-authenticate with the API Server to obtain a new access token using ID tokens and refresh tokens.

📷

RECOMMENDATION

Token-based authentication is not supported for tenants using a single sign-on (SSO) authentication service. Client applications cannot retrieve web tokens from the RMS Authentication Service because Location Intelligence user authorization is managed by the tenant's IdP. Tenants that have implemented SSO, must use API keys to authenticate their client applications. For more information on SSO, see the Intelligent Risk Platform Administrator Guide.

Web tokens must be periodically requested or renewed by making calls to the RMS Authentication Service. RMS Authentication Service API services specify the tenant's host in endpoint path. The {host} variable identifies the data center (EU or US) that has provisioned the tenant.

• EU host: api-euw1.rms.com
• US host: api-use1.rms.com

Obtain web tokens

Client applications may obtain web tokens from the RMS Authentication Service by providing a valid tenant name, user name and password.

The POST /login/implicit service requires that three request parameters are defined in the request body: a tenantName, username, and password.

curl --location --request POST 'https://{host}/sml/auth/v1/login/implicit' \
--header 'Content-Type: application/json' \
--data-raw '{
    "tenantName": "{tenantName}",
    "username": "{username}",
    "password": "{password}"
}'

The client application uses the login credentials of a user account whenever it requests web tokens. The access token returned by the RMS Authentication Service encodes the access rights and permissions granted to that user account.

If the request is successful, the response returns an access token, ID token, and refresh token:

• The accessToken is a bearer token that identifies the client application. The client passes the access token in the HTTP Authorization header whenever it requests access to API resources. The access token is valid for one hour.
• The idToken is a web token that enables the client application to identify the user account represented by the client. The ID token enables the service to cache information about the user including the user's access rights and permissions.
• The refreshToken is a web token that enables the client to refresh an access token.

Refresh access tokens

Access tokens provide client applications with temporary access to API resources. When an access token expires, the client application may obtain a new set of web tokens (access token, ID token, and refresh token) or refresh the existing access token.

The POST /login/refresh service requires that the current refreshToken be specified in request body.

curl --location --request POST 'https://{host}/sml/auth/v1/login/refresh' \
--header 'Content-Type: application/json' \
--data-raw '{
    "refreshToken": "{refreshToken}"}'

A successful request renews the client's connection and returns a new set of web tokens.

Submit access tokens in requests

The client must pass a valid access token or API key with every request. If you are using token-based authentication, specify the access token in the HTTP Authorization header of the request:

curl --location --request GET 'https://{host}/riskmodeler/datasources' \
--header 'Authorization: Bearer {accessToken}'