Exchange Service Token

POST

/internal/service-token

Exchange service API key for short-lived JWT.

This endpoint allows registered service accounts to exchange their API key for a short-lived JWT token (5 minutes TTL). The JWT can then be used to authenticate with other services.

Requirements: - Valid API key in X-API-Key header - API key must have is_service_account=true

The returned JWT contains: - sub: “service:{service_name}” - service_name: Service identity - business_id: Optional business context (null for multi-tenant) - scope: “multi-tenant” or “single-tenant” (FR-TOKEN-001) - permissions: Service-specific permissions - token_type: “service”

Multi-tenant tokens (business_id=null) require allow_multi_tenant=True on the API key per FR-SERVICE-003 and FR-SERVICE-004.

Args: request: Service token request with service_name and optional business_id x_api_key: Service API key from X-API-Key header db: Database session from dependency injection

Returns: ServiceTokenResponse with access_token and expires_in

Raises: 401: If API key is invalid or revoked 403: If API key is not a service account or lacks multi-tenant permission

Parameters

Header Parameters

X-API-Key

required

X-Api-Key

string

Request Body ^required

ServiceTokenRequest

Request body for service token exchange.

Attributes: service_name: Identity of the requesting service business_id: Optional business context for scoped operations

object

service_name

required

Service Name

Identity of the requesting service (e.g., ‘analytics-service’)

string

>= 1 characters <= 255 characters

business_id

Any of:

string

string

null

null

Responses

200

Successful Response

ServiceTokenResponse

Response from service token exchange.

Attributes: access_token: JWT access token for service authentication token_type: Token type (always ‘Bearer’) expires_in: Token TTL in seconds

object

access_token

required

Access Token

JWT access token

string

token_type

Token Type

Token type

string

default: Bearer

expires_in

required

Expires In

Token TTL in seconds

integer

401

Invalid API key

Example

{
  "detail": {
    "error": "invalid_api_key"
  }
}

403

API key is not a service account or multi-tenant not allowed

Examples

{
  "detail": {
    "error": "not_service_account"
  }
}

{
  "detail": {
    "error": "multi_tenant_not_allowed",
    "message": "API key does not have multi-tenant permission"
  }
}

422

Validation Error

HTTPValidationError

object

detail

Detail

Array<object>

ValidationError

object

loc

required

Location

Array

msg

required

Message

string

type

required

Error Type

string

input

Input

ctx

Context

object

429

Rate limited

Example

{
  "detail": {
    "error": "rate_limited",
    "retry_after": 60
  }
}