API Reference

API Keys & OAuth

Create and manage API keys and OAuth 2.0 clients for programmatic access.

API keys are the recommended authentication method for server-to-server integrations. OAuth 2.0 clients support the Client Credentials flow for automated external systems.

API Key Endpoints

Method	Endpoint	Description
POST	/api-keys	Create a new API key
GET	/api-keys	List all API keys for tenant
DELETE	/api-keys/:id	Revoke an API key

OAuth Client Endpoints

Method	Endpoint	Description
POST	/auth/oauth/clients	Register OAuth 2.0 client
GET	/auth/oauth/clients	List registered clients
DELETE	/auth/oauth/clients/:id	Delete OAuth client
POST	/auth/oauth/token	Exchange credentials for access token (public)

POST /api-keys — Create API Key

Create a new API key scoped to your tenant. The key is displayed only once — store it securely immediately after creation.

bash

curl -X POST http://localhost:3009/api/v1/api-keys \
  -H "Authorization: Bearer <admin-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production ATS Integration",
    "description": "Used by Workday ATS for interview creation"
  }'

Response 201

{
  "id": "key-uuid",
  "name": "Production ATS Integration",
  "key": "prod_api_key_abc123def456...",
  "keyPrefix": "prod_api_key_abc1",
  "tenantId": "tenant-uuid",
  "createdAt": "2024-01-15T10:00:00.000Z"
}

The full key value is shown only once. Store it in your secrets manager immediately. Future requests will only show the keyPrefix for identification.

GET /api-keys — List Keys

bash

curl http://localhost:3009/api/v1/api-keys \
  -H "Authorization: Bearer <admin-jwt>"

Response 200

[
  {
    "id": "key-uuid",
    "name": "Production ATS Integration",
    "keyPrefix": "prod_api_key_abc1",
    "lastUsedAt": "2024-01-15T09:45:00.000Z",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
]

OAuth 2.0 Client Credentials

For automated systems that need short-lived access tokens rather than long-lived API keys. Register a client to get a clientId and clientSecret, then exchange them for a JWT.

bash

# Step 1: Register client (requires admin JWT)
curl -X POST http://localhost:3009/api/v1/auth/oauth/clients \
  -H "Authorization: Bearer <admin-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Workday Integration",
    "description": "ATS integration for interview creation"
  }'

Response 201

{
  "clientId": "client-uuid",
  "clientSecret": "cs_abc123...",
  "name": "Workday Integration"
}

bash

# Step 2: Exchange for access token (no auth required)
curl -X POST http://localhost:3009/api/v1/auth/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "client-uuid",
    "client_secret": "cs_abc123..."
  }'

Response 200

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Using an API Key

Pass the API key in the X-API-Key header:

bash

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

Method	Header	Use Case
API Key	X-API-Key: <key>	Server-to-server, ATS integrations
JWT	Authorization: Bearer <token>	Admin dashboard, user sessions
OAuth Token	Authorization: Bearer <access_token>	Automated systems with short-lived tokens

Was this page helpful?

Previous← Users & Tenants

NextAdmin Monitoring →