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 https://mayaapi.teamcast.ai/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 https://mayaapi.teamcast.ai/api/v1/interviews \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

API Key

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

When using an API Key, you must also include the X-Tenant-ID header to specify which tenant the request is scoped to. API keys work on all integration, interview, workflow, and API key management endpoints.

bash

curl -X POST https://mayaapi.teamcast.ai/api/v1/integration/interviews \
  -H "X-API-Key: your_api_key_here" \
  -H "X-Tenant-ID: your_tenant_id" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Creating an API Key

bash

curl -X POST https://mayaapi.teamcast.ai/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 https://mayaapi.teamcast.ai/api/v1/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

Platform Integration Model

Integration partners (platforms) authenticate using a single platform-level API key issued by Teamcast. Each request also carries an X-Tenant-ID header that identifies which of the platform's customers the request is for. Tenants do not have their own API keys.

text

Teamcast SuperAdmin
    │
    └── Platform: LinkedIn
            │  One API key issued by Teamcast.
            │  All tenant requests flow through this key.
            │
            ├── Tenant: Acme Corp    (X-Tenant-ID: tenant_acme)
            └── Tenant: TechCo       (X-Tenant-ID: tenant_techco)

Header	Set By	Description
X-API-Key	Platform	Platform-level key issued by Teamcast SuperAdmin — covers all tenants on this platform
X-Tenant-ID	Platform	Identifies the specific tenant customer for this request — required on every Integration API call

Example — LinkedIn sending on behalf of Acme Corp

curl -X POST https://mayaapi.teamcast.ai/api/v1/integration/interviews \
  -H "X-API-Key: lk_platform_key_..." \
  -H "X-Tenant-ID: tenant_acme" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

This design means LinkedIn manages one key and routes to any of their customers using the X-Tenant-ID header. Webhook configuration, auto-approve behaviour, and data retention windows are all scoped per-tenant — not platform-wide.

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 →