> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/cvat-ai/cvat/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://app.cvat.ai/api/auth/access_tokens",
      headers={"Authorization": "Token <your_token>"},
      json={
          "name": "My API Token",
          "expiry_date": "2025-12-31T23:59:59Z",
          "read_only": False
      }
  )
  token_data = response.json()
  ```
</CodeGroup>

#### Request Body

<ParamField body="name" type="string" required>
  Token name for identification
</ParamField>

<ParamField body="expiry_date" type="string">
  Token expiration date in ISO 8601 format
</ParamField>

<ParamField body="read_only" type="boolean" default={false}>
  Whether the token is read-only
</ParamField>

#### Response

<ResponseField name="id" type="integer">
  Token ID
</ResponseField>

<ResponseField name="name" type="string">
  Token name
</ResponseField>

<ResponseField name="token" type="string">
  The access token (only returned on creation)
</ResponseField>

<ResponseField name="created_date" type="string">
  Token creation timestamp
</ResponseField>

<ResponseField name="expiry_date" type="string">
  Token expiration timestamp
</ResponseField>

<ResponseField name="read_only" type="boolean">
  Whether the token is read-only
</ResponseField>

<ResponseField name="last_used_date" type="string">
  Last usage timestamp
</ResponseField>

### List Access Tokens

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

#### Query Parameters

<ParamField query="name" type="string">
  Filter by token name
</ParamField>

<ParamField query="page" type="integer">
  Page number for pagination
</ParamField>

<ParamField query="page_size" type="integer">
  Number of results per page
</ParamField>

<ParamField query="sort" type="string">
  Sort field (name, id, created\_date, updated\_date, expiry\_date)
</ParamField>

### Get Token Details

```bash theme={null}
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:

```bash theme={null}
curl -X GET "https://app.cvat.ai/api/auth/access_tokens/self" \
  -H "Authorization: Token <your_token>"
```

### Update a Token

```bash theme={null}
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

```bash theme={null}
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:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://app.cvat.ai/api/auth/login" \
    -H "Content-Type: application/json" \
    -d '{
      "username": "your_username",
      "password": "your_password"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://app.cvat.ai/api/auth/login",
      json={
          "username": "your_username",
          "password": "your_password"
      }
  )
  token = response.json()["key"]
  ```
</CodeGroup>

#### Request Body

<ParamField body="username" type="string" required>
  Username or email address
</ParamField>

<ParamField body="password" type="string" required>
  User password
</ParamField>

#### Response

<ResponseField name="key" type="string">
  Authentication token
</ResponseField>

## Logout

Invalidate the current authentication token:

```bash theme={null}
curl -X POST "https://app.cvat.ai/api/auth/logout" \
  -H "Authorization: Token <your_token>"
```

## Register

Create a new user account:

```bash theme={null}
curl -X POST "https://app.cvat.ai/api/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "email": "user@example.com",
    "password1": "securepassword",
    "password2": "securepassword",
    "first_name": "John",
    "last_name": "Doe"
  }'
```

## Password Management

### Change Password

Change the password for the authenticated user:

```bash theme={null}
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:

```bash theme={null}
curl -X POST "https://app.cvat.ai/api/auth/password/reset" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'
```

### Confirm Password Reset

Reset password using the token from the reset email:

```bash theme={null}
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:

```bash theme={null}
curl -X GET "https://app.cvat.ai/api/projects" \
  -u "username:password"
```

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

## 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

```python theme={null}
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}"}
)
```