🔑API Tokens

Programmatic REST API access to your configuration data.

A CloudTruth API Token can be used with the CloudTruth CLI and for authorization directly with the REST API. When you create an API Token, we create a Service Account automatically - this is a non-interactive User, but for purposes of access control it behaves just like a regular User. All of the actions performed with the API Token are entered into the Audit Log using this Service Account.

Creating a Service Account and generating a token:

Only Contributor and higher roles can create Service Accounts and generate tokens. Service account role selection is based on the role of the user creating the service account, i.e. Contributor can only create a Service Account with Contributor or a lower privilege role. See Role Permissions for more details.

1. From the left-hand navigation locate Admin -> API Tokens:

2. Click + Create Token​ to open the CREATE NEW API TOKEN modal:

• TOKEN NAME - Typically the name of the service the Service Account's token will be used for

• DESCRIPTION - Optionally, describe the token's usage

• OWNER - Typically the User who created the Service Account or is actively using the token in their environment. Used mainly for auditing purposes. Admins and Owners can view and manage all tokens regardless of ownership.

• TOKEN PERMISSIONS - Set the Role the Service Account will have across the organization

Service Account role assignments are organization-wide and treated the same as a User Account following the defined organization role permissions.

3. Click Generate Token to create the new Service Account and generate the ACCESS TOKEN. The Service Account along with the exposed and copyable token are now in the tokens list:

The ability to copy the new token string is only available immediately after creating or generating a new token for the Service Account. Once the page has been navigated away from or refreshed the token will no longer visible or obtainable.

Managing Service Accounts (API Tokens)

Service Accounts, for all intents and purposes, are treated the same as User Accounts without the ability to log in interactively. We provide easy mechanisms to update the Service Account's role, regenerate a token, or delete the Service Account. These options are found in the selection menu to the right of the token:

Manage API Token

1. Select Manage API Token from the menu to open the EDIT API TOKEN modal:

2. Here you can modify the Description, change Owner, and modify the Role.

3. Click Update to save the changes

Regenerate API Token

1. Select Regenerate API Token from the menu to open the REGENERATE TOKEN modal:

• Here we have two options:

  • Regenerate and immediately expire the previous token

  • Regenerate and set an expiration date and time for the previous token to expire

Regenerate and expire immediately

Clicking Regenerate will close the modal and display the new token as we did during Service Account creation.

Regenerate and expire in the future

If expiring the token at a later date and time is desired, as in cases where updating critical processes to use the new token may take some time, we can leave the previous token active by checking the box and entering a date and time:

2. After deciding which option is best, click the Regenerate button to create a new token for the service account. The token string will be displayed as before during Service Account creation.

Deleting a Service Account

1. Selecting `Delete API Token from the menu will prompt for confirmation:

2. Click Yes, delete to delete the Service Account along with any associated token(s)

This will immediately prevent access to CloudTruth via the Service Account's associated token(s) and is irreversible! Take care when deleting Service Accounts and make their tokens are no longer in use.