Authentication

How to authenticate with the AIBrain Service API using JWT tokens, budget headers, and AI credit enforcement.

Overview

All endpoints (except Health) require a Bearer JWT token. The tenantId is extracted from the JWT claims automatically via the @CurrentTenant() decorator. AI operations consume credits from the user or team wallet.

ECS Fargate Deployment

aibrain-svc runs on AWS ECS Fargate (not Lambda). The staging ALB endpoint is available at https://eventzr-staging-alb-134677813.us-east-1.elb.amazonaws.com/aibrain/v1

Obtaining a JWT Token

curl -X POST https://535ubezkse.execute-api.us-east-1.amazonaws.com/auth/v1/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@eventzr.com",
    "password": "Password123!"
  }'

# Response:
# {
#   "data": {
#     "accessToken": "eyJhbGciOiJSUzI1NiIs...",
#     "refreshToken": "eyJhbGciOiJSUzI1NiIs...",
#     "expiresIn": 3600
#   }
# }

Use the token with aibrain-svcbash

export TOKEN="<access-token-from-response>"

# AI Orchestration (main endpoint)
curl -X POST https://eventzr-staging-alb-134677813.us-east-1.elb.amazonaws.com/aibrain/v1/orchestrate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: 00000000-0000-0000-0000-000000000001" \
  -d '{
    "prompt": "Plan a corporate team-building event for 50 people",
    "mode": "single",
    "maxTokens": 500,
    "context": "Budget: $5000, Location: Mumbai"
  }'

ZAR Ensemble (3-model consensus)bash

# ZAR costs 60 credits (vs 5-25 for single mode)
curl -X POST https://eventzr-staging-alb-134677813.us-east-1.elb.amazonaws.com/aibrain/v1/orchestrate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: 00000000-0000-0000-0000-000000000001" \
  -d '{
    "prompt": "Design a multi-day music festival with vendor management",
    "mode": "zar",
    "maxTokens": 1000,
    "context": "3-day outdoor festival, 10,000 capacity"
  }'

Refresh an expired tokenbash

curl -X POST https://535ubezkse.execute-api.us-east-1.amazonaws.com/auth/v1/refresh \
  -H "Content-Type: application/json" \
  -d '{ "refreshToken": "eyJhbGciOiJSUzI1NiIs..." }'

Test Credentials

Staging Environment Credentials

Use these credentials to test the API in the Scalar playground above.

Role	Email	Password	Tenant ID
Developer	`dev@eventzr.com`	`Password123!`	`00000000-...-000001`
Admin	`admin@eventzr.com`	`Password123!`	`00000000-...-000001`

JWT Claims Structure

Decoded JWT payloadjson

{
  "sub": "user-uuid",
  "tenantId": "tenant-uuid",
  "email": "user@example.com",
  "roles": ["user", "organizer", "admin"],
  "planTier": "professional",
  "iat": 1740000000,
  "exp": 1740003600
}

Standard Headers

Header	Required	Description
`Authorization`	Yes	Bearer JWT token
`Content-Type`	POST/PUT/PATCH	application/json
`x-request-id`	No	Request trace ID (UUID), auto-generated if absent
`x-tenant-id`	Recommended	Tenant UUID for explicit tenant filtering
`x-budget-max-usd`	No	Maximum budget in USD for this AI operation (cost ceiling)
`Idempotency-Key`	No	Idempotency key for write operations (24h TTL)

Response Envelope

Standard response formatjson

{
  "data": { ... },
  "error": null,
  "page": {
    "next_cursor": "eyJwYWdlIjoyLCJsaW1pdCI6MjB9",
    "has_more": true,
    "limit": 20
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "trace_id": "abc123",
    "tenant_id": "tenant-uuid"
  }
}

AI Credit Budget Headers

AI operations consume credits from the user or team wallet. Use the x-budget-max-usd header to enforce a cost ceiling per request. ZAR ensemble mode costs 60 credits per query (vs 5-25 for single mode).

Budget-constrained orchestration requestbash

curl -X POST https://eventzr-staging-alb-134677813.us-east-1.elb.amazonaws.com/aibrain/v1/orchestrate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: 00000000-0000-0000-0000-000000000001" \
  -H "x-budget-max-usd: 0.10" \
  -d '{ "prompt": "Plan a surprise birthday party", "mode": "single", "maxTokens": 300 }'

Voice Orchestration

aibrain-svc supports voice-to-AI orchestration: audio input is transcribed via STT (studio-svc/AWS Transcribe), processed by the AI brain, and optionally returned as TTS audio. The Authorization header is automatically forwarded to studio-svc for STT/TTS authentication.

Voice orchestration requestbash

curl -X POST https://eventzr-staging-alb-134677813.us-east-1.elb.amazonaws.com/aibrain/v1/voice/orchestrate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: 00000000-0000-0000-0000-000000000001" \
  -d '{
    "audioUrl": "https://s3.amazonaws.com/bucket/recording.m4a",
    "format": "m4a",
    "languageHint": "en-US",
    "mode": "single",
    "ttsResponse": true
  }'