Authentication

Vanillatots uses Auth0 for OAuth2/JWT-based authentication.

Overview

All API endpoints (except /health) require a valid JWT Bearer token in the Authorization header:

Authorization: Bearer <token>

Obtaining a Token

Client Credentials Flow (Machine-to-Machine)

For server-to-server communication, use the Auth0 Client Credentials flow:

curl -X POST https://YOUR_AUTH0_DOMAIN/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "YOUR_API_AUDIENCE",
    "grant_type": "client_credentials"
  }'

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 86400
}

Authorization Code Flow (User-Facing Apps)

For web or mobile applications, use the standard Authorization Code flow via Auth0's Universal Login.

Token Validation

The API validates tokens by:

1. Verifying the JWT signature against Auth0's JWKS endpoint
2. Checking the audience claim matches the configured API audience
3. Validating token expiration

Required Headers

Header	Required	Description
Authorization	Yes	Bearer <JWT token>
X-SCHOOL-ID	Most endpoints	UUID of the target school tenant

Error Responses

Status	Description
401 Unauthorized	Missing or invalid token
403 Forbidden	Valid token but insufficient permissions