Risk Cloud API: Authentication

The Risk Cloud API uses OAuth 2.0 for authentication, which uses a bearer token in the Authorization HTTP header. Please take note that these tokens have an expiration time of one year. After the token expires, you will need to generate a new one.

In order to start using the API, first retrieve your Client and Secret keys from the Profile page. This can be navigated to by clicking the Person icon in the top right corner and then the Profile button.

In the Profile page, go to the Access Key tab. If this tab is not there, please contact your Risk Cloud administrator as you may not have API privileges.

• In the Access Key tab, you will see both Client and Secret keys. These are both necessary to generate an access key or retrieve an existing access key.
• Use the Reset Secret Key NOT the Generate Access Key button to generate a new secret. The client should stay visible. If this is your FIRST TIME using our API, please reset your secret.
• This panel also has the ability to generate the Access Key aka the “Bearer Token” on its own. After clicking on Generate Access Key button, the Bearer Token will appear in the Access Key textbox.

After having both Client and Secret keys they will need to be base64 encoded.

• Encode via Terminal:
  echo -n '{CLIENT}:{SECRET}' | base64 
• Encode via PowerShell:
  [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes('{CLIENT}:{SECRET}'))

Once they are encoded, take your encoded string and place it in the authorization header as a “Basic Token” ex Authorization: Basic {ENCODED_BASE64_STRING}

Once this URL is pinged with the correct Authorization Header a JSON response will appear mimicking the following structure:

Response:

{
    "access_token": "KEY_HERE",
    "token_type": "bearer",
    "expires_in": 31532918,
    "scope": "read write"
}

{
    "access_token": "KEY_HERE",
    "token_type": "bearer",
    "expires_in": 31532918,
    "scope": "read write"
}

The returned access_token can then be used in the authorization header as a “Bearer Token” to interact with Risk Cloud’s API

Authorization: Bearer {ACCESS_TOKEN}

Authorization: Bearer {ACCESS_TOKEN}

Token Lifecycle

  Tokens live for one year, but two other events can end a token’s life before then:

• Regenerating invalidates all prior tokens. Every call to POST /api/v1/account/token for a given user deletes every existing access token for that user, then issues a fresh one. There is no way to have two valid tokens for the same user at the same time. This applies regardless of which client or machine made the request, two processes sharing the same Client ID and Secret share the same user, and either one can invalidate the other.
• Disabling the owning user invalidates their tokens. Tokens for disabled users are deleted immediately.

• Expired tokens are auto-removed. A token presented after its expires_in has elapsed returns 401 Unauthorized and is removed server-side on first use.

Revoking a token manually

To invalidate a token without issuing a replacement:

Best Practices

Cache tokens for the full year

Generate a token, store it (with its expiry timestamp) in your secrets manager or a process-local cache, and re-use it for every API call. Do not call POST /api/v1/account/token at the start of every request, beyond the latency cost, each call rotates your token and invalidates anything else that was using it.

Handle 401 with one retry, then fail loud

When a request returns 401 Unauthorized:

  1. Generate a fresh token.

  2. Replay the request once with the new token.

  3. If it still fails, surface the error, don’t loop.

A persistent 401 after a successful re-generate usually means there is another service regenerating and invalidating the token using the same credentials.

Rotate the Client Secret on a schedule

The access token rotates every time you generate a new one. The Client Secret does not, it lives until you replace it. Treat it like any production credential:

•  Rotate on a defined schedule (quarterly is common).

•  Rotate immediately on personnel changes or any suspected exposure.

•  When you rotate, update the secret in your secrets manager first, then trigger a re-generate of the access token using the new secret.

Store credentials in a secrets manager

Never commit the Client ID or Client Secret to source control, and don’t bake them into container images. Use a real secret store and pull them at runtime.

Next Steps

Once your Bearer token is created, you’re ready to start interacting with our API. For more details, check out our API Documentation.

For instructions on interacting with our API via Postman, check out our Postman Help Article.