Manage the Cloud Administration API Keys

Clients calling the Cloud Administration REST APIs must authenticate themselves by including a JSON Web Token (JWT) in each request. The JWT is signed using an Administration API key. You can add up to 10 keys using the Cloud Administration Console. The keys do not expire. You must manually delete API keys from the Cloud Administration Console when they become compromised or are not in use. You can regenerate a key if it is lost or compromised.

Only a Super Administrator for the Cloud Administration Console can add or delete an API key. The Super Administrator provides the API key file to the endpoint administrator.

This topic includes:

For a complete list of Administration APIs, see Using the Cloud Administration REST APIs.

Integration with Authentication Manager

If Authentication Manager is configured to use the Cloud Authentication Service for authenticating users to agent-protected resources, a key for that purpose is automatically added to the Cloud Authentication Service and appears in the console. That key counts against the maximum number of keys allowed.

If you delete the SecurID Authentication Manager API Key, Authentication Manager will be disconnected from the Cloud Authentication Service. If you want to reconnect, you must perform the registration process again in the Authentication Manager Security Console. For instructions, see Connect SecurID Authentication Manager to the Cloud Authentication Service.

Security Best Practices for Administration API Keys

Follow these best practice recommendations to ensure that your API keys remain secure.

  • Delete the old API keys and generate new ones every 90 days.

    Note: Do not delete keys that were automatically generated to connect Authentication Manager to the Cloud Authentication Service. If these keys are accidentally deleted, you must re-establish the connection with Authentication Manager.

  • Do not embed API keys in the source code.

  • Do not store API keys in files inside source code repository.

  • Delete the keys from the Cloud Authentication Service if they are no longer being used.

  • Make sure the keys are encrypted at rest on the client file system.

  • Do not share API keys between different client application integrations. Use distinct API keys for each client application.

Administrative Roles for API Keys

Each API key is associated with an administrative role. The role ensures that the API has the appropriate administrative permissions in the Cloud Authentication Service. All APIs default to the Help Desk Administrator role, except for the SecurID Add/Remove High-Risk User API and SecurID Retrieve High-Risk User List API, which require the Super Admin role when you generate the key.

Administration API Key File Contents

An Administration API key file contains the following sensitive data:

  • Access ID - A unique identifier for the API key.
  • Access Key - A private key that you generate and download.

The following example displays the contents of an Administration API key file.

{

"customerName":"mycompanyname",

"accessID":"139f6495-e447-4a26-a765-5c01b6b152d5",

"description":"Integration with NetWitness",

"accessKey":"-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAtyDNwTjD1DEQRs2BjXy0U9I+tTOIzVMeve6cELmOCQgdLYjI\ntpw12FFZY4gT1JX9Mp/uVYKuZGhhvSbB/KhUTzQ9GrondRNto4zz7zOw4Qhzs xFd

"adminRestApiUrl":"https://access.securid.com/AdminInterface/restapi"

}

Add an API Key File

The Super Admin generates the Administration API key file.

Procedure

  1. In the Cloud Administration Console, click Platform > API Key Management and select the Administration API Key tab.

  2. In the Administrator Role field, select a role that gives the API the appropriate permissions in the Cloud Authentication Service. For more information, see Administrative Roles for API Keys.

  3. Click ADD. The new key is displayed.

  4. (Optional) Enter a description that identifies how the key will be used.

  5. Click Save and Download to save and download the file.

Note: If you click Regenerate, you cannot use the previous API key file.

After you finish

Use a secure method to deliver the API key file to the endpoint administrator.

Delete an API Key File

If your API key is compromised or if you want to change the role for an API, you must delete the old key and generate a new one. After you delete a key, the API using that key will no longer be able to authenticate to the Cloud Authentication Service.

Procedure

  1. In the Cloud Administration Console, click Platform > API Key Management and select the Administration API Key tab.

  2. Select securid_ngx_g_delete_icon_29x28.png next to the API key file that you want to delete.

  3. When prompted, click Delete.

    Publish is not required, as changes take effect immediately.

Regenerate an API Key File

If an API key file is lost or compromised, you can regenerate a new one.

Procedure

  1. In the Cloud Administration Console, click Platform > API Key Management and select the Administration API Key tab.

  2. In the Administrator Role field, select a role that gives the API the appropriate permissions in the Cloud Authentication Service. For more information, see Administrative Roles for API Keys.

  3. Click Regenerate to generate and download an API key file.

  4. Provide the new API key file to your endpoint administrator.

Update API Key File Description

To update an API key description, perform these steps.

Procedure

  1. In the Cloud Administration Console, click Platform > API Key Management and select the Administration API Key tab.

  2. Click inside the Description box and enter the new text.

  3. Click the check mark to save your changes, or click X to cancel your changes.

  4. (Optional) Regenerate the API key to see the updated description in the API key file. Provide the new API key file to your endpoint administrator.

Update Administrator Role for an API Key File

You can change the administrator role that is associated with a generated API key.

Procedure

  1. In the Cloud Administration Console, click Platform > API Key Management and select the Administration API Key tab.

  2. In the Administrator Role field, select a role from the drop-down menu.

    You will see a confirmation message indicating that the update took effect.

    Note: You do not need to regenerate an API key if you change the administrator role.