DocsAPI ReferenceAuthentication

Authentication

Authenticate with the TalentOS API using JWT tokens. All requests require a valid Bearer token and tenant context.

Authentication Flow

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

{
  "email": "[email protected]",
  "password": "your-secure-password"
}

// Response:
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Access Token — Short-lived JWT (1 hour). Include in Authorization header for all API requests

Refresh Token — Long-lived token (30 days). Use to obtain new access tokens without re-login

Tenant Scope — Include X-Tenant-Id header with every request. The API validates tenant membership

Making Authenticated Requests

GET /v1/talents
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
X-Tenant-Id: tnt_abc123
Content-Type: application/json

Error Handling

All API errors follow a consistent format:

Error Response

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Access token expired",
    "details": { "expired_at": "2026-03-28T10:00:00Z" },
    "requestId": "req_xyz789"
  }
}

Code	HTTP Status	Meaning
UNAUTHORIZED	401	Invalid or expired token
FORBIDDEN	403	Valid token but insufficient permissions
NOT_FOUND	404	Resource does not exist or is not in your tenant
POLICY_DENIED	403	RBAC/ABAC policy evaluation denied the action
RATE_LIMITED	429	Too many requests. Check Retry-After header
VALIDATION_ERROR	422	Invalid request payload. Check details for field errors

Webhooks Talent Endpoints