API Reference

Authentication

Authenticate with the AI Interview System API using JWT, API Keys, or OAuth 2.0.

The API supports three authentication methods. Choose based on your use case: JWT for user sessions, API Keys for server-to-server integrations, and OAuth 2.0 for scoped client credentials.

JWT Bearer Token

Obtain a JWT by logging in with email and password. The token is valid for 1 hour by default.

bash

curl -X POST http://localhost:3009/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@demo.ai-interview.com",
    "password": "Admin123!"
  }'

Response 200

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 3600,
  "user": {
    "id": "user-uuid",
    "email": "admin@demo.ai-interview.com",
    "role": "ADMIN",
    "tenantId": "tenant-uuid"
  }
}

Use the token in subsequent requests:

bash

curl http://localhost:3009/api/v1/interviews \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

API Key

API keys are ideal for server-to-server integrations and A2A protocol calls. Create keys from the admin dashboard at /admin/api-keys.

bash

curl -X POST http://localhost:3009/api/v1/a2a/interview \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Creating an API Key

bash

curl -X POST http://localhost:3009/api/v1/api-keys \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ATS Integration",
    "permissions": ["interview:create", "interview:read"],
    "expiresAt": "2026-01-01T00:00:00.000Z"
  }'

Response 201 (key shown once)

{
  "id": "key-uuid",
  "name": "ATS Integration",
  "key": "ak_live_abc123xyz...",
  "permissions": ["interview:create", "interview:read"],
  "expiresAt": "2026-01-01T00:00:00.000Z"
}

The API key is only shown once at creation time. Store it securely in an environment variable.

OAuth 2.0 Client Credentials

For machine-to-machine integrations that need scoped access, use OAuth 2.0 client credentials flow.

Get a Token

bash

curl -X POST http://localhost:3009/api/v1/auth/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret",
    "grantType": "client_credentials"
  }'

Response 200

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "scope": "interview:create interview:read"
}

Scope	Permission
interview:create	Create new interview requests
interview:read	Read interview status and details
interview:update	Update interview information
interview:approve	Approve or reject plans and assessments

Testing Credentials

Role	Email	Password
Admin	admin@demo.ai-interview.com	Admin123!
Recruiter	recruiter@demo.ai-interview.com	Recruiter123!
Viewer	user@demo.ai-interview.com	User123!

Demo API key (for development only):

text

demo_api_key_12345678901234567890123456789012345678901234567890123456

Rate Limiting

All endpoints are rate-limited to 100 requests per minute per IP address. OTP endpoints have stricter limits: 5 requests per 10 minutes per token.

Header	Description
X-RateLimit-Limit	Maximum requests per window
X-RateLimit-Remaining	Remaining requests in current window
X-RateLimit-Reset	Unix timestamp when the window resets

Was this page helpful?

Previous← Overview

NextInterviews →