Authentication - The Data City

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

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:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Using the token

Add an Authorization header to every API request:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

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.

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.

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.

Testing your token

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

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.

{
  "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.

Password recovery

If you forget your password:

Send a POST to /api/v1/password-recovery/{email} with your account email.
Check your inbox for a reset link containing a one-time token. The token expires after 48 hours.
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.
`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 for the full status-code matrix.

​Getting a token

​Using the token

​Token lifetime

​Testing your token

​Password recovery

​Failure modes

Getting a token

Using the token

Token lifetime

Testing your token

Password recovery

Failure modes