ALOTDocumentation
Go to Dashboard →

Authentication

ALOT supports two authentication methods: JWT Bearer tokens (for dashboard / user sessions) and API Keys (for server-to-server integrations).

JWT Authentication

Used by the dashboard and any user-facing client. Tokens are issued on login/register.

Login

POST /v1/auth/login
Content-Type: application/json

{
  "email": "you@company.com",
  "password": "your-password"
}

// Response
{
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1...",
    "refreshToken": "eyJhbGciOiJIUzI1...",
    "user": { "id": "...", "name": "...", "email": "..." }
  }
}

Using the access token

GET /v1/assessments
Authorization: Bearer eyJhbGciOiJIUzI1...

Access tokens expire after 15 minutes. Use the refresh token to get a new one:

POST /v1/auth/refresh
Content-Type: application/json

{
  "refreshToken": "eyJhbGciOiJIUzI1..."
}

// Response
{
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1...",
    "refreshToken": "eyJhbGciOiJIUzI1..."
  }
}

Refresh tokens expire after 7 days.

API Key Authentication

Used for server-to-server integrations. API keys are prefixed with pk_live_ followed by 64 hex characters.

Keys are hashed with SHA-256 before storage. The full key is only shown once at creation — store it securely.

Creating an API key

POST /v1/api-keys
Authorization: Bearer <your-jwt>
Content-Type: application/json

{
  "name": "Production Integration",
  "scopes": ["assessments:read", "candidates:read", "results:read"]
}

// Response (key shown only once)
{
  "data": {
    "id": "...",
    "name": "Production Integration",
    "key": "pk_live_a3f1c2...",   // ← Store this now
    "scopes": ["assessments:read", "candidates:read", "results:read"]
  }
}

Available scopes

  • assessments:read — List and get assessments
  • candidates:read — List and get candidate sessions
  • candidates:write — Invite candidates
  • results:read — Retrieve result tokens

Using an API key

GET /v1/public/assessments
X-API-Key: pk_live_a3f1c2...

API key requests are scoped to your organization automatically. You do not need to pass an org ID.

Result tokens

After a candidate completes an assessment, a short-lived result token (JWT, 15 minutes) is issued. Candidates are redirected to your configured URL with ?result=<token>.

Exchange the token for the full result:

GET /v1/public/results/:token
X-API-Key: pk_live_...