Authentication

Authenticate API requests to CVAT

Overview

CVAT API supports multiple authentication methods:

• Token Authentication - API tokens for programmatic access
• Access Token Authentication - Personal access tokens with expiration
• Session Authentication - Browser session cookies
• Basic Authentication - Username and password (not recommended for production)

Token Authentication

Token authentication is the recommended method for API access.

Using Tokens

Include your token in the Authorization header:

curl -X GET "https://app.cvat.ai/api/projects" \
  -H "Authorization: Token <your_token>"

Access Tokens

Access tokens provide more control with features like expiration dates and read-only access.

Create an Access Token

cURL

curl -X POST "https://app.cvat.ai/api/auth/access_tokens" \
  -H "Authorization: Token <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API Token",
    "expiry_date": "2025-12-31T23:59:59Z",
    "read_only": false
  }'

Request Body

name · string · required

Token name for identification

expiry_date · string

Token expiration date in ISO 8601 format

read_only · boolean · default: false

Whether the token is read-only

Response

id · integer

Token ID

name · string

Token name

token · string

The access token (only returned on creation)

created_date · string

Token creation timestamp

expiry_date · string

Token expiration timestamp

read_only · boolean

Whether the token is read-only

last_used_date · string

Last usage timestamp

List Access Tokens

curl -X GET "https://app.cvat.ai/api/auth/access_tokens" \
  -H "Authorization: Token <your_token>"

Query Parameters

name · string

Filter by token name

page · integer

Page number for pagination

page_size · integer

Number of results per page

sort · string

Sort field (name, id, created_date, updated_date, expiry_date)

Get Token Details

curl -X GET "https://app.cvat.ai/api/auth/access_tokens/{id}" \
  -H "Authorization: Token <your_token>"

Get Current Token Details

Get details about the token used for the current request:

curl -X GET "https://app.cvat.ai/api/auth/access_tokens/self" \
  -H "Authorization: Token <your_token>"

Update a Token

curl -X PATCH "https://app.cvat.ai/api/auth/access_tokens/{id}" \
  -H "Authorization: Token <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Token Name"
  }'

Revoke a Token

curl -X DELETE "https://app.cvat.ai/api/auth/access_tokens/{id}" \
  -H "Authorization: Token <your_token>"

Login

Obtain an authentication token by logging in with credentials:

cURL

curl -X POST "https://app.cvat.ai/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_username",
    "password": "your_password"
  }'

Request Body

username · string · required

Username or email address

password · string · required

User password

Response

key · string

Authentication token

Logout

Invalidate the current authentication token:

curl -X POST "https://app.cvat.ai/api/auth/logout" \
  -H "Authorization: Token <your_token>"

Register

Create a new user account:

curl -X POST "https://app.cvat.ai/api/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "email": "[e-mail]",
    "password1": "securepassword",
    "password2": "securepassword",
    "first_name": "John",
    "last_name": "Doe"
  }'

Password Management

Change Password

Change the password for the authenticated user:

curl -X POST "https://app.cvat.ai/api/auth/password/change" \
  -H "Authorization: Token <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "new_password1": "newsecurepassword",
    "new_password2": "newsecurepassword"
  }'

Reset Password

Request a password reset email:

curl -X POST "https://app.cvat.ai/api/auth/password/reset" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]"
  }'

Confirm Password Reset

Reset password using the token from the reset email:

curl -X POST "https://app.cvat.ai/api/auth/password/reset/confirm" \
  -H "Content-Type: application/json" \
  -d '{
    "uid": "user-id",
    "token": "reset-token",
    "new_password1": "newsecurepassword",
    "new_password2": "newsecurepassword"
  }'

Session Authentication

When using the CVAT web interface, sessions are managed automatically through cookies. This method includes CSRF protection:

• sessionid cookie for authentication
• csrftoken cookie for CSRF protection
• X-CSRFToken header with CSRF token value

Basic Authentication

Basic authentication uses base64-encoded credentials:

curl -X GET "https://app.cvat.ai/api/projects" \
  -u "username:password"

Basic authentication is less secure and should only be used for testing or in secure environments.

Security Best Practices

1. Use Access Tokens - Create dedicated tokens for different applications
2. Set Expiration Dates - Tokens should expire periodically
3. Use Read-Only Tokens - When write access isn’t needed
4. Revoke Unused Tokens - Remove tokens that are no longer needed
5. Keep Tokens Secret - Never commit tokens to version control
6. Use HTTPS - Always make API requests over HTTPS

Example: Complete Authentication Flow

import requests

# Step 1: Login to get initial token
login_response = requests.post(
    "https://app.cvat.ai/api/auth/login",
    json={
        "username": "your_username",
        "password": "your_password"
    }
)
auth_token = login_response.json()["key"]

# Step 2: Create a long-lived access token
token_response = requests.post(
    "https://app.cvat.ai/api/auth/access_tokens",
    headers={"Authorization": f"Token {auth_token}"},
    json={
        "name": "My Application",
        "expiry_date": "2025-12-31T23:59:59Z"
    }
)
access_token = token_response.json()["token"]

# Step 3: Use the access token for API requests
projects = requests.get(
    "https://app.cvat.ai/api/projects",
    headers={"Authorization": f"Token {access_token}"}
)