Risk Cloud API: Authentication

Updated on: January 17, 2022

Background

The Risk Cloud API uses OAuth 2.0 for authentication, which uses a bearer token in the Authorization HTTP header. 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 the Client key and the Secret key will be hidden. 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.
  • Note: This panel also has the ability to Generate Access Key aka the "Bearer Token" on its own so that you do NOT need to go thru the api route.

Generating Bearer Token via API

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:

POST/api/v1/account/token

Response:

{
    "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}

Troubleshoot & Tips

  1. Bearer Token
    1. The token has a life span of one year.
    2. Reuse tokens whenever possible. Avoid generating a new token for every API request. Instead, generate a token once and reuse it across multiple requests until it expires. This reduces unnecessary load and helps prevent rate limiting.
    3. Automate token generation thoughtfully. For long-running scripts or unattended integrations, programmatic token generation is a good fit. Generate a new token at the start of each session or process, not per request. Strive for a balance: generate tokens when needed, but avoid excessive regeneration within loops or frequent intervals.
    4. Generate a secret for first time api access. Regenerate your secret if you have forgotten it.
  2. Ensure you have the correct syntax and are using the correct fields ex using client id and not user id.