Authentication
How to authenticate with the Cypher Service API using JWT tokens, WhatsApp webhooks, and budget headers.
Overview
Most endpoints require a Bearer JWT token. The tenantId is extracted from the JWT claims automatically via the @CurrentTenant() decorator. WhatsApp webhook endpoints use HMAC signature verification instead.
ECS Fargate Deployment
cypher-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/cypher/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
# }
# }export TOKEN="<access-token-from-response>"
# Process a text command
curl -X POST https://eventzr-staging-alb-134677813.us-east-1.elb.amazonaws.com/cypher/v1/command \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "x-tenant-id: 00000000-0000-0000-0000-000000000001" \
-d '{
"message": "Create a tech conference event for next month",
"channel": "web"
}'curl -X POST https://535ubezkse.execute-api.us-east-1.amazonaws.com/auth/v1/refresh \
-H "Content-Type: application/json" \
-d '{ "refreshToken": "eyJhbGciOiJSUzI1NiIs..." }'WhatsApp Webhook Authentication
WhatsApp webhook endpoints use Meta's HMAC-SHA256 signature verification instead of JWT. The signature is passed in the X-Hub-Signature-256 header and verified against the configured app secret.
# Webhook verification (GET) - Meta sends this to verify endpoint
curl "https://eventzr-staging-alb-134677813.us-east-1.elb.amazonaws.com/cypher/v1/webhook/whatsapp?hub.mode=subscribe&hub.verify_token=YOUR_VERIFY_TOKEN&hub.challenge=CHALLENGE_STRING"
# Webhook message delivery (POST) - Meta sends incoming messages here
curl -X POST https://eventzr-staging-alb-134677813.us-east-1.elb.amazonaws.com/cypher/v1/webhook/whatsapp \
-H "Content-Type: application/json" \
-H "X-Hub-Signature-256: sha256=<hmac-signature>" \
-d '{
"object": "whatsapp_business_account",
"entry": [...]
}'Test Credentials
Staging Environment Credentials
Use these credentials to test the API in the Scalar playground above.
| Role | Password | Tenant ID | |
|---|---|---|---|
| Developer | dev@eventzr.com | Password123! | 00000000-...-000001 |
| Admin | admin@eventzr.com | Password123! | 00000000-...-000001 |
JWT Claims Structure
{
"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 (except webhook endpoints) |
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-Hub-Signature-256 | Webhooks only | HMAC-SHA256 signature for WhatsApp webhook payloads |
Idempotency-Key | No | Idempotency key for write operations (24h TTL) |
Response Envelope
{
"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"
}
}Communication Channels
Cypher supports multiple communication channels. The channel field in command requests determines how the AI response is formatted and delivered.
| Channel | Description | Auth Method |
|---|---|---|
WEB | Web portal chat widget | JWT Bearer |
MOBILE | React Native mobile apps | JWT Bearer |
WHATSAPP | WhatsApp Business API (primary channel) | HMAC-SHA256 signature |
VOICE | Voice calls with STT/TTS | JWT Bearer |
API | Direct REST API integration | JWT Bearer |