Skip to main content

​
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 -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 -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": "[email protected]",
    "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": "[email protected]"
  }'

​
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}"}
)

Build docs developers (and LLMs) love

Get started for freeTalk to us