API Tokens

Overview

The SheerID Verification API supports the OAuth 2.0 Authorization Framework for authentication and authorization using a “Bearer token” when accessing one or more protected resources (see RFC 6750). Note that only certain SheerID API endpoints require authentication.

The bearer token identifies a specific MySheerID user or Client application, so that when the token is used, we can ensure that the user or application has the proper permissions to make the request. SheerID also uses the access token when auditing API usage, and to aid in incident analysis.

Because bearer tokens can be used to access or manipulate data without demonstrating possession of any other security credentials (e.g. password), there is the potential that, if a token is ever compromised, it could be used by a third party until the token expires or is revoked. To prevent this, bearer tokens must be secured, both in storage and in transport. For specific recommendations, see RFC 6750, Section 5.3.

The API supports bearer tokens that are generated statically, within MySheerID, or dynamically, by requesting one from the SheerID Authentication API, which follows the OAuth 2.0 Authorization Framework specification (see RFC 6749).

A dynamic token automatically expires after one hour, thus limiting the risk of damage that can be done if it is compromised. A static token never expires, which is convenient, but if the token is ever compromised, means the risk for harm to be done exists until the token is manually revoked.

This document explains how to generate and use static and dynamic tokens, and the ways that SheerID systems can be configured to support Client applications that need to call our API in an automated fashion.

Generating a Static Token

Static API tokens can be managed within MySheerID by clicking on your user icon and choosing Access Tokens:

Generating Dynamic Tokens

Overview

To generate and use a dynamic token, a Client application would use this request/response flow, which follows the OAuth 2.0 specification for the “Client Credentials Grant” as described in RFC 6749 section 4.4*:

1. The Client Application makes an authorization request to the SheerID Authorization API using the appropriate credentials.
2. If the credentials are valid, SheerID Authorization API responds with an access token.
3. The Client application uses the access token to make authorized requests to the SheerID Verification API.
4. The SheerID Verification API validates the token before responding to the request.
5. The Client application can repeatedly use the token until it expires.

Since this follows the OAuth 2.0 specification, it should be possible to use any OAuth 2.0 framework/library/SaaS product that supports using the “Client Credentials Grant” to obtain bearer tokens.

*Note that the SheerID Authentication API currently only implements the “Client Credentials Grant”, and not the other grant types described in the OAuth 2.0 specification.

Obtaining the Credentials

Before attempting to generate a dynamic token, contact SheerID support to obtain credentials that will be used when generating the token.

The credentials consist of two parts:

• Client ID:
  • The username of a SheerID user that represents the Client application
  • Created by SheerID support, and cannot be changed
• Client Secret:
  • A password that must be used when generating a dynamic access token
  • Can be managed within MySheerID by editing the “Dynamic API Token Secrets” for the user
  • Multiple secrets can be active at the same time

Once the Client has been given these credentials, the Account Owner can administer that user within MySheerID like other users. They should ensure that the user has the necessary SheerID roles assigned for the Client application to perform its function.

Preparing the Credentials

When a request is sent to generate a new dynamic token, the credentials (as described in the previous section) will need to be encoded following the “Basic Authentication Scheme” as defined in RFC 2617, section 2. To summarize that specification: the Client ID and Client Secret are concatenated together, separated by a colon character, and the resulting string is Base-64 encoded.

For example, for the Client ID “Aladdin” and Client Secret “open sesame”, then the encoded credentials would be: QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Requesting a Dynamic Token

To generate a dynamic token, send a “Basic Authentication” request to the following SheerID Authentication API endpoint with an Authorization header that contains the encoded credentials (as described in the previous section):

• Method: POST
• URL: https://services.sheerid.com/rest/authv2/oauth2/default/v1/token
• Headers:
  • Authorization: Basic <encoded credentials> (see previous section)
  • Accept: application/json
  • Content-type: application/x-www-form-urlencoded
• Request Body:
  • grant_type=client_credentials&scope=sheerid_api

For example, to use curl to request a dynamic token using the credentials from the example in the previous section, the command would be:

curl --request POST \
  --url https://services.sheerid.com/rest/oauth2/default/v1/token \
  --header 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
  --header 'Accept: application/json' \
  --header 'Content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials&scope=sheerid_api'

Handling the Response

If the credentials are valid, the SheerID Authorization API will return a JSON response with the following fields:

• access_token: The generated token, to be used in requests to the SheerID Verification API
• token_type: The type of token issued
• scope: The scope(s) for which the token can be used
• expires_in: The amount of time, in seconds, for which the token is valid

For example, if the API were to return a response similar to the following:

{
  "access_token": "uli80c21Zk0kRu2ODzK9HRmKE3gpK581",
  "token_type": "Bearer",
  "scope": "sheerid_api",
  "expires_in": 3600
}

then the generated dynamic token is uli80c21Zk0kRu2ODzK9HRmKE3gpK581

If the credentials are invalid, a 401 Unauthorized response will be returned.

If any other other portion of the request is invalid, a 400 Bad Request will be returned.

In either case, the error response will contain the following fields:

• error: An error code, per RFC 6749, section 5.2
• error_description: A human-readable description of the error that should provide useful information about what was wrong

Using a Static or Dynamic Token

Request

Any static or dynamic token can be used when making any request to the SheerID Verification API by using the Bearer authorization scheme as described in RFC 6750, section 2.1. Simply add an Authorization header, with a value of Bearer followed by the token.

For example, if the token being used is uli80c21Zk0kRu2ODzK9HRmKE3gpK581, then to use curl to get the details of a Verification, the command would be:

curl --request POST \
--url /rest/v2/verification/6631e8700000000000000000/details \
--header 'Authorization: Bearer uli80c21Zk0kRu2ODzK9HRmKE3gpK581' \
--header 'Accept: application/json'

Token Validation

The token will be validated to ensure it was issued by the SheerID Authorization API, that it has not been tampered with, and that it is not expired. The MySheerID user associated with the token will then be used when carrying out the requested action.

Response

If the token is valid, the request will be handled as described in the SheerID Verification API documentation.

If the token is not valid for any reason, a 401 Unauthorized response will be returned, as described in the documentation for the SheerID Verification API endpoint being consulted.

Token Expiration and Reuse

Dynamic tokens expire after one hour. Static tokens do not expire.

• There is no mechanism in any SheerID API to evaluate a dynamic token to determine when it will expire.
• There is no mechanism in any SheerID API to extend the expiration date of a dynamic token.

We strongly recommend that, if a Client application might be performing a number of API calls within a short period of time, that the dynamic token be reused, so long as it is not expired, in order to reduce the overhead of re-validating the credentials and generating a new token for each call.

When reusing a token, it is considered good practice to handle the case of an expired token gracefully when making an API call. For example, when a 401 Unauthorized status code is received, the Client application could automatically generate a new token, and retry the API call. However, if repeated attempts continue to respond with a 401 Unauthorized status code, that would indicate a different problem than the token being expired, and the Client application should not continue to retry.

To avoid the likelihood of using an expired token and encountering an error, the Client application could keep track of when the token is going to expire, and request a new token when needed. The expires_in field in the response gives the number of seconds for which the token will be valid. So, one could add that to the current time to get the approximate expiration time. However, it is best to allow for a safety margin, to account for server processing time and network transport time.

Testing

A static or dynamic token can be validated by sending a request to the following endpoint within the SheerID Verification API.

Request

• Method: GET
• URL: https://services.sheerid.com/rest/v2/test/validateAuthToken
• Headers:
  • Authorization: Bearer <any static or dynamic token>
  • Accept: application/json

For example, to use curl to test the validity of the dynamic token from the previous examples, uli80c21Zk0kRu2ODzK9HRmKE3gpK581, the command would be:

curl --request GET \
--url /rest/v2/test/validateAuthToken \
--header 'Authorization: Bearer uli80c21Zk0kRu2ODzK9HRmKE3gpK581' \
--header 'Accept: application/json'

Response

If the token is valid, a 200 OK status code will be returned. If the token is invalid, a 401 Unauthorized status code will be returned. The response body will be a JSON object having the following structure:

• type: a string, having one of the following possible values:
  • “UNAUTHORIZED” for an invalid token
  • “DYNAMIC_BEARER_TOKEN” for a valid dynamic token
  • “STATIC_BEARER_TOKEN” for a valid static token

Requiring a Token for all Endpoints

With the default SheerID account configuration, only certain endpoints in the SheerID Verification API will require a token, as described in the API documentation.

If a SheerID Client desires it, an account can be configured to require a token for all endpoints (with the exception of those that do not access and/or modify any data in the Client’s account).

When adding this restriction to an account, the configuration can specify that API endpoints will accept either any static or dynamic token, or only dynamic tokens.

NOTE: This feature is only supported when the Client has integrated with SheerID APIs directly. It is not supported for Programs that are created and managed in MySheerID, or certain other legacy Programs.

NOTE: It is not recommended to use static or dynamic tokens directly from pages rendered within the web browser. To prevent misuse, bearer tokens need to be secured, both in storage and in transport. For specific recommendations, see RFC 6750, Section 5.3.