Authentication

How to authenticate with the Auth Service API using JWT tokens.

Overview

The auth-svc is the central authentication and authorization service for the EventZR platform. It issues JWT access tokens and refresh tokens that are used by all other services. Most endpoints require a Bearer token except public endpoints like /login, /signup/*, and /health.

Login Flow

1. Login with email/passwordbash

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

# Success Response:
# {
#   "data": {
#     "accessToken": "eyJhbGciOiJSUzI1NiIs...",
#     "refreshToken": "eyJhbGciOiJSUzI1NiIs...",
#     "expiresIn": 900,
#     "user": { "id": "...", "email": "partner@eventzr.com", "roles": ["partner"] }
#   }
# }

# MFA Required Response (for MFA-enabled accounts):
# {
#   "data": {
#     "mfaRequired": true,
#     "mfaToken": "mfa-session-token",
#     "availableMethods": ["totp"]
#   }
# }

2. Use the token on any endpointbash

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

curl -X GET https://535ubezkse.execute-api.us-east-1.amazonaws.com/auth/v1/profile \
  -H "Authorization: Bearer $TOKEN"

3. 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": "<refresh-token>"}'

Test Credentials

Staging Environment Credentials

Use these credentials to test the API in the Scalar playground. Accounts marked with MFA will return a challenge instead of a token on login.

Role	Email	Password	Tenant	MFA
Partner	`partner@eventzr.com`	`Password123!`	T1 (EventZR)	No
User	`user@eventzr.com`	`Password123!`	T1 (EventZR)	No
Organizer	`organizer@eventzr.com`	`Password123!`	T1 (EventZR)	No
Admin	`admin@eventzr.com`	`Password123!`	T1 (EventZR)	No
Developer	`dev@eventzr.com`	`Password123!`	T1 (EventZR)	Yes
Admin (Startup)	`admin@startup.co`	`Password123!`	T3 (StartupCo)	No

MFA-Enabled Accounts

Accounts with MFA enabled will return a mfaRequired: true response instead of tokens. Use non-MFA accounts (partner, user, organizer, admin) for quick API testing.

JWT Claims Structure

Decoded JWT payloadjson

{
  "sub": "user-uuid",
  "tenantId": "00000000-0000-0000-0000-000000000001",
  "email": "partner@eventzr.com",
  "roles": ["partner"],
  "planTier": "base",
  "iat": 1740000000,
  "exp": 1740000900
}

Standard Headers

Header	Required	Description
`Authorization`	Most endpoints	Bearer JWT access token
`Content-Type`	POST/PUT/PATCH	application/json
`x-tenant-id`	No (from JWT)	Tenant UUID, auto-extracted from JWT claims
`x-request-id`	No	Request trace ID (UUID), auto-generated if absent
`Idempotency-Key`	No	Idempotency key for write operations (Redis, 24h TTL)

Response Envelope

Standard response formatjson

{
  "data": { ... },
  "error": null,
  "page": {
    "next_cursor": "eyJwYWdlIjoyLCJsaW1pdCI6MjB9",
    "has_more": true,
    "limit": 20
  },
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Authentication Methods

The auth-svc supports multiple authentication methods:

Method	Endpoint	Description
Email/Password	`POST /login`	Standard login with email and password
Username/Password	`POST /login`	Login with username instead of email
OAuth/Social	`POST /oauth/:provider/callback`	Google, GitHub, Microsoft, Apple
Magic Link	`POST /passwordless/magic-link`	Passwordless email login
WebAuthn/FIDO2	`POST /webauthn/authenticate`	Biometric/hardware key authentication
MFA (TOTP)	`POST /mfa/totp/verify`	Time-based one-time password