Skip to main content

Authentication Guide

Choosing an Auth Method​

MethodUse CaseWhen to Use
OTP → JWTHuman usersAdmin dashboards, mobile apps, booking UIs
API Key (x-api-key)System integrationService-to-service communication
Org API Key (x-org-api-key)External integrationThird-party apps scoped to one organization

OTP → JWT Flow​

1. Request OTP​

POST /api/v1/auth/otp/request
{ "email": "user@example.com" }

2. Verify OTP and Get JWT​

POST /api/v1/auth/otp/verify
{ "email": "user@example.com", "otp": "123456" }
# Returns: { "data": { "access_token": "eyJ..." } }

3. Use JWT​

Authorization: Bearer eyJ...

API Key Authentication​

x-api-key: your-system-api-key

Used for system-level access (e.g., ZenEdge → ZenCore integration).

Org API Key Authentication​

x-org-api-key: your-org-api-key

Scoped to a single organization with configurable permissions.

Token Storage Best Practices​

  • Web apps: Store JWT in memory or httpOnly cookie
  • Mobile apps: Use secure storage (iOS Keychain, Android Keystore)
  • Server-side: Use environment variables for API keys

Next Steps​