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

# Authentication

> OAuth2 password flow — exchange your email and password for a JWT Bearer token.

The Instant Classification API uses OAuth2 password-flow authentication. You send your email and password to the token endpoint and receive a JSON Web Token (JWT). Include that token as a Bearer credential in every subsequent request.

## Getting a token

Send a `POST` to `/api/v1/login/access-token` with `application/x-www-form-urlencoded` form data:

| Field      | Value                      |
| ---------- | -------------------------- |
| `username` | Your account email address |
| `password` | Your account password      |

```bash theme={null}
curl -sS -X POST "https://instant-classification-api.thedatacity.com/api/v1/login/access-token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=you@yourcompany.com&password=YOUR_PASSWORD"
```

Response:

```json theme={null}
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}
```

## Using the token

Add an `Authorization` header to every API request:

```http theme={null}
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

<Note>
  Treat your access token like a password. Store it in an environment variable or secrets manager. Never check it into source control or include it in client-side code.
</Note>

## Token lifetime

Tokens are valid for **8 days** from issue. After that, the API returns **`401`** and you need to request a new token.

There is no refresh-token flow — when your token expires, call `/api/v1/login/access-token` again with your credentials.

<Note>
  Refresh on `401`. A missing, expired or otherwise unusable token all return `401 Could not validate credentials` with a `WWW-Authenticate: Bearer` header.

  This changed in July 2026. The API previously returned `403` for an expired token, which meant the usual `if 401: refresh()` branch never fired. If your client was written against `403`, switch it to `401`.
</Note>

## Testing your token

To verify a token is valid without making a classification request, call:

```bash theme={null}
curl -sS -X POST "https://instant-classification-api.thedatacity.com/api/v1/login/test-token" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

A valid token returns your user profile. An invalid or expired token returns `401`.

```json theme={null}
{
  "email": "you@yourcompany.com",
  "full_name": "Your Name",
  "role": "standard",
  "is_active": true,
  "is_paid": false,
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-07-01T09:12:44Z"
}
```

`is_paid` tells you whether your account is still subject to the free-tier quota. See [Rate limits & quotas](/instant-classification/guides/rate-limits).

## Password recovery

If you forget your password:

1. Send a `POST` to `/api/v1/password-recovery/{email}` with your account email.
2. Check your inbox for a reset link containing a one-time token. The token expires after **48 hours**.
3. Send a `POST` to `/api/v1/reset-password/` with the token and your new password (8–128 characters).

An expired or already-used token returns `400 Invalid token`. Request a new one by repeating step 1.

The API always returns the same response regardless of whether the email exists, to prevent account enumeration.

## Failure modes

| Status | Meaning                                                                                            | What to do                                                         |
| ------ | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `400`  | Incorrect email or password.                                                                       | Check your credentials and try again.                              |
| `400`  | Inactive user. Returned on any authenticated endpoint, not just login.                             | Contact [support@thedatacity.com](mailto:support@thedatacity.com). |
| `401`  | No `Authorization` header, or the token is expired, malformed, or no longer identifies an account. | Request a new token from `/api/v1/login/access-token`.             |
| `429`  | Too many token requests. See below.                                                                | Back off and retry.                                                |

Both `/login/access-token` and `/password-recovery/{email}` are rate limited to **5 requests per minute** in production. Cache your token for its full 8 days rather than fetching a new one per request.

See [Errors](/instant-classification/guides/errors) for the full status-code matrix.

<Snippet file="need-help.mdx" />