Access Tokens
Overview
When interacting with the API, there are several authentication options available in CVAT:
- Basic authentication, with a username and a password
- Legacy token authentication, with an API key (deprecated)
- Session authentication, with a session ID and a CSRF token
- Personal Access Token (PAT) authentication, with an access token value
Personal Access Token (PAT) is an authentication option dedicated to CLI, SDK and Server API clients. To authenticate using this method, you need an access token that can be created and configured in the user settings section in the UI. It is the recommended authentication option for CVAT API interaction and integrations.
Compared to the other authentication options, PATs provide a more convenient, controlled, and secure way to authenticate requests from the CLI, scripts, and 3rd-party applications. They improve the security of your account by allowing you to use separate credentials for each application and by removing the need to use the password. Tokens can be created and revoked at any time by a user request. The security is further improved by configuring the allowed operations and setting expiration dates for each token.
Warning
Please take special care to store the tokens securely. While CVAT takes extra steps to improve the security of the tokens, their security is primarily the user’s responsibility. It’s recommended to configure each token to only allow the required operations and to have an expiration date. Avoid sharing your tokens with other people. If you think a token might have been leaked, revoke the token immediately.How to manage Personal Access Tokens
It’s possible to create, edit, and revoke tokens. The tokens can be created, edited, and revoked at any time by a user request. You can configure the name, expiration date, and permissions for each token.
It’s recommended to always specify the expiration date for tokens. Please note that unused tokens are automatically considered “stale” and removed after some time period of inactivity (1 year by default).
Note
When using a self-hosted version, the staleness period can be configured via theACCESS_TOKEN_STALE_PERIOD setting.
Note
When using a self-hosted version, the maximum number of tokens per user can be configured via theMAX_ACCESS_TOKENS_PER_USER setting.
Note
CVAT Online users can have up to 50 Personal Access Tokens.Permissions
It’s possible to configure allowed operations for a token. Currently, there is an option to make a token read-only or read/write capable. A read-only token will only be allowed to make safe requests that do not modify the server state.
Warning
For security reasons, token-authenticated clients are not allowed to modify tokens and user details, regardless of the configuration.How to create a Personal Access Token
- Open the user settings page
- Navigate to the “Security” section
- Create a new token using the “+” button
- Configure the name, expiration date, and permissions for the new token. Once ready, click “Save”.
- You will be shown the new token. Make sure to securely save this value, it will not be available in CVAT after the dialog window is closed.
- Once the value is saved, close the dialog window.
The new token is ready for use.
How to edit a Personal Access Token
- Open the user settings page
- Navigate to the “Security” section
- Click the “Edit” button for the token.
- The token editing page will be displayed. Here you can configure token name, permissions, and expiration date.
- After the required changes are made, click the “Update” button to confirm the updates.
How to revoke Personal Access Tokens
Revocation allows you to prevent further uses of a token. Once a token is revoked, it cannot be restored.
- Open the user settings page
- Navigate to the “Security” section
- Click the “Revoke” button for the token.
- Confirm revocation in the dialog
The token will not be available for use anymore.