Skip to main content

Accessing the API

Once your registration is approved, authID will send you a welcome email with your username, temporary password, and a link to the authID Identity Portal. Upon login to the Identity Portal, you will be prompted to update the credentials. These credentials will be your starting point for accessing our APIs.

API Authentication and Security​

The Verified platform APIs support HTTP bearer authentication (also called token authentication) to authorize access. The bearer access and refresh tokens are generated in response to providing the appropriate values to the Identity Service token endpoint.

info

authID.ai supports encryption to protect communications between your system and the Verified platform. Unencrypted HTTP calls are not supported.

After you've registered for Verified and have your updated credentials available, you can test access here: IdentityService API. Click the small green box that says Authorize. You will need to supply the username/password combination to the modal that appears in order to interact with some of the API endpoints.

Getting a Token​

Access tokens are returned in JWT format from the token endpoint after providing the appropriate credentials. The credentials may be supplied by encoding usernames/password combinations or API key/value combinations.

Basic Auth​

Basic authentication is useful for testing code and deploying to non-production environments.

First, create a base64-encoded string using the credentials you were issued:

// JavaScript


btoa("username:password") // output is dXNlcm5hbWU6cGFzc3dvcmQ=

Next, call the token endpoint and add the following header with the value from the first step:

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

API Keys​

API keys are the recommended approach to authentication since they serve as a more secure substitute to embedding your username and password into application code. You can create API keys in one of two ways:

  1. Use the CreateApiKey API endpoint, and be sure to capture both ExternalID and Value from the response.
  2. Create an API key from the user screen in the identity portal. This will generate an External ID and Value that must be captured before navigating away, since the Identity Portal will not retain these values.

The Key ID/Value pair are used in place of username/password when obtaining the access token. So similarly to the Basic auth step, you would generate a base64-encoded string using these values:

// JavaScript

btoa("apiKeyId:apiKeyValue") // output is YXBpS2V5SWQ6YXBpS2V5VmFsdWU=

This value is then passed as a header on the token endpoint:

Authorization: Basic YXBpS2V5SWQ6YXBpS2V5VmFsdWU=
caution

If your application configuration file gets compromised, you can call the DeleteApiKey API endpoint and create a new key.

Using the Access Token​

The access token needs to be passed in an HTTP Authorization header when invoking any of the API endpoints for the Verified platform. Since authID uses the bearer token format, an example header would look like this:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5c...

Renewing Access Token​

The access token expires quickly so it needs to be renewed, or "refreshed" on a regular basis.

You can implement a simple strategy: inspect the exp field (see sample below), and if there is little time left, refresh the token via the IdentityService API using the Refresh endpoint.

  • Be sure to save both new access and refresh tokens.
  • If you receive 401 error when running a token refresh, obtain new access/refresh pair by reauthenticating using your credentials. This can happen if system determines that the refresh token was compromised.

Sample JWT Access Token Payload​

{
  "nameid": "e1a5011f-dc3f-405e-8465-3897fd75f39a",
  "unique_name": "TestUser",
  "custid": "1256g699-1cdc-40ad-bfaf-93ac4fe1800e",
  "custnum": "TestCustomer",
  "role": [
    "Administrator",
    "Transactor",
    "External Verificator",
    "Configurator"
  ],
  "nbf": 1633710455,
  "exp": 1633710755,
  "iat": 1633710455,
  "iss": "http://authid.ai",
  "aud": "http://customer.idcomplete.authid.ai"
}
info

To learn more about JWT tokens: https://jwt.io

Which API Endpoints Can I Call?​

The Verified platform APIs support Role Based Access Control which defines the service(s) you can use.

  • View your roles by inspecting your access token.
  • Obtain the list of actions available to your assigned role by calling the GetAdministrativeUserActions API endpoint.

If you attempt to call an API outside of your assigned roles, you will receive an HTTP 403 response code.

Here is an example of the roles in an access token:

  "role": [
    "Administrator",
    "Transactor",
    "External Verificator",
    "Configurator"
  ],