Authentication

How to authenticate with the Integration Hub Service API using JWT tokens.

Overview

All endpoints (except Health and WhatsApp webhooks) require a Bearer JWT token and an x-tenant-id header. The tenant ID must match the tenantId claim in the JWT. Internal endpoints (prefixed with _internal/) require mTLS client certificates instead of JWT.

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": "admin@eventzr.com",
    "password": "Admin123!"
  }'

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

Use the token with Integration Hubbash

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

curl -X GET "https://535ubezkse.execute-api.us-east-1.amazonaws.com/integrationhub/v1/providers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-tenant-id: a0000001-0000-0000-0000-000000000001"

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. All passwords are for the staging environment only.

Role	Email	Password	Access Level
admin	`admin@eventzr.com`	`Admin123!`	All 107 endpoints, admin APIs, internal APIs
organizer	`organizer@eventzr.com`	`Organizer123!`	Executions, credentials, OAuth, WhatsApp, marketplace
user	`user@eventzr.com`	`User123!`	Read-only: provider listing, marketplace browsing
developer	`dev@eventzr.com`	`Password123!`	Full API access for testing and development

Tenant ID for all test users

a0000001-0000-0000-0000-000000000001

JWT Claims Structure

Decoded JWT payloadjson

{
  "sub": "user-uuid",
  "tenantId": "a0000001-0000-0000-0000-000000000001",
  "email": "admin@eventzr.com",
  "roles": ["user", "organizer", "admin"],
  "planTier": "enterprise",
  "iat": 1740000000,
  "exp": 1740003600
}

Required Headers

Header	Required	Description
`Authorization`	Yes	Bearer JWT token from auth-svc
`x-tenant-id`	Yes	UUID of the tenant (must match JWT tenantId claim)
`Content-Type`	POST/PUT/PATCH	application/json
`x-request-id`	No	Request trace ID (UUID), auto-generated if absent
`Idempotency-Key`	No	UUID to prevent duplicate write operations (24h TTL in Redis)
`x-sandbox`	No	Set to "true" for sandbox mode (no quota charges)

Role-Based Access Control

Endpoints enforce role-based access via the @Roles() decorator. The JWT must contain the required role in its roles claim.

Endpoint Group	Minimum Role
Health / Liveness / Readiness	None (public)
GET /providers, GET /marketplace	user
POST /execute, OAuth, Credentials, WhatsApp	organizer
Admin, Jobs, Internal APIs	admin

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"
  }
}

Error response formatjson

{
  "statusCode": 401,
  "code": "ERR_INTEGRATION_HUB_SVC_UNAUTHORIZED",
  "message": "Authentication failed for the execution request",
  "path": "/integrationhub/v1/execute",
  "timestamp": "2026-02-24T12:00:00.000Z"
}