API tokens

The Clumio REpresentational State Transfer (REST) Application Programming Interface (API) provides a simple interface for the Clumio operations you need to perform to fully protect your data.

Accessing the Clumio REST API gateway requires authentication. To ensure data is transmitted between parties securely, each Clumio user must authenticate into the REST API using a signed JSON Web Token (JWT). For more information about the Clumio REST API, refer to the Clumio REST API Reference (Help > REST API Reference).

Authenticating into the Clumio REST API involves the following high level steps:

Generate an API token through the Clumio UI. The API token is a long-lived JWT bearer token that can be used until the token is manually refreshed or deleted.
Send the API token as a bearer token in the Authorization header with each Clumio REST API request that requires authentication. For example,
curl -X GET \ https://us-west-2.api.clumio.com/users \ -H 'Authorization: Bearer ${BEARER_TOKEN}’

Token Types

There are two types of tokens that can be used with the Clumio REST API; a Service Token, or a Personal Token. A Personal Token is best used for development and testing purposes. Service tokens can be used to automate common tasks across the Clumio platform and integrate with other 3rd party tools. Service tokens are designed for production use.

Personal Tokens

Created and managed by an individual user.
Token has the same permissions and access as the associated user.
Token role changes along with its creator’s role. For example, if a user is moved from the Super Admin role to the Help Desk role, so would the Token.
If a user account is suspended or deleted the token is also suspended or deleted.
Only one token can be created per user.

Service Tokens

Created and managed by Administrators (Super Admin/OU Admin).
Has the same permissions and OU access or less than the user who creates the token. For example an OU Administrator cannot create a Super Administrator Token.
Token access is static, meaning even if the creator's permissions change, the token access remains the same.
Tokens can be deleted, but are not tied to the deletion of the token creator.
There is a soft limit of 10 Service Tokens per account. Contact [email protected] if you require additional service tokens.

Managing Tokens

API tokens are generated from the Account Settings > API Tokens screen of the Clumio UI.

Generate a personal token

Each user must generate their own API token. Users cannot generate tokens for other users or see other users’ tokens. Individual users can only have one token.

Navigate to the Administration > Access Management > API Tokens.
Click Generate API Token.
Click the Download API Token to download the CSV file. Click Proceed to continue with the download process.
After the download process completes, save the file to a secure location and do not share the token with anyone. You can only download the CSV file once.

Note: If you refresh the screen, navigate to another page in the UI, or log out, you will no longer be able to download the CSV file. You can only download the CSV file once per API token generation

Generate a service token

Super Administrators or OU Administrators can generate up to 10 service tokens, this is the default limit.
Navigate to the Administration > Access Management > API Tokens.
Click Generate API Token in the Service Token section of the screen.
Enter details for the token. The name of the token identifies the token and cannot be changed. The Organizational Unit field is not displayed if you are in the lowest level OU and the current OU is selected by default. Select a role for the level of access required for the token.
You must complete all fields to enable the Next button.
The Generate Service Token dialog displays. Click Generate and Download to complete the process and download a CSV file with the token. Save the file to a secure location. You can only download the CSV file once.
The new Service Token displays in the Service Token table and is managed from the table.

Note: If the number of existing tokens has reached the limit, a dialog displays notifying you that the limit has been reached and that you can contact [email protected] for more information.

Delete a token

Delete an API token when you no longer need to authenticate into the REST API. Once an API token is deleted, it becomes invalid and any existing scripts that use the token stop working. You can generate a new API token at any time.

If a Clumio user account is either suspended or deleted, the associated Personal Token is deleted with it.

A user must have the required permission to delete a Service Token, otherwise the delete icon is disabled. A delete icon is available in the Service token table in the Action column for each token row.

Refresh a token

You can refresh an API token at any time. Clumio recommends that you refresh your token every three months. Refreshing an API token invalidates the previous token. If you have scripts that use the token, update those scripts to use the new token. After you have refreshed the token, immediately download the CSV file containing the full token string, and save the file to a secure location. If you refresh the screen, navigate to another page in the UI, or log out, you will no longer be able to download the CSV file. You can only download the CSV file once per API token refresh.

A refresh icon is available in the Action column of the Service Token table in each token row. The icon is enabled if the user has the required permission to refresh a token.

Service token audit report

The Action column of the Service Token table also has an Audit button. Click to display an audit report of actions taken by a specific token. You can generate and download a CSV file of the audit report.