Authentication
ArelHub exposes two authentication mechanisms for the public API surface:
| Mechanism | Header | When to use |
|---|---|---|
| User JWT | Authorization: Bearer <token> |
User-session flows, dashboards, browser clients |
| API Key | X-Api-Key: <key> |
Server-to-server integrations, automation, CI |
Endpoints that accept either scheme are marked in the reference spec with both
jwt and
api-key security alternatives.
User JWT flow
Login
POST /v1/auth/login
Content-Type: application/json
{
"email": "dev@example.com",
"password": "YourPassword123!"
}
Returns accessToken (short-lived) and refreshToken (long-lived). Store the refresh token
securely — it is a bearer credential.
Refresh
POST /v1/auth/token/refresh
Content-Type: application/json
{
"refreshToken": "<your-refresh-token>"
}
Revoke
POST /v1/auth/token/revoke
Authorization: Bearer eyJ...
Session management
GET /v1/auth/token/sessions
POST /v1/auth/token/sessions/terminate-others
Authorization: Bearer eyJ...
API key flow
API keys carry a set of permissions (ApiKeyRights) scoped at creation time.
POST /v1/api-keys
Authorization: Bearer eyJ...
Content-Type: application/json
{
"name": "CI pipeline key",
"rights": ["MessageSend", "MessageRead"]
}
POST /v1/accounts/{accountId}/messages
X-Api-Key: arh_live_...
Content-Type: application/json
{
"subaccountId": "...",
"to": "+15551234567",
"body": "Hello!"
}
Email OTP step-up
POST /v1/email-otp/issue
POST /v1/email-otp/verify
Authorization: Bearer eyJ...
Password management
POST /v1/auth/forgot-password # unauthenticated
POST /v1/auth/reset-password # with reset token from email
POST /v1/auth/change-password # authenticated
Security considerations
- Never embed JWT tokens or API keys in client-side code or version control.
- Refresh tokens are long-lived bearer credentials — treat them with the same care as passwords.
- Prefer API keys with minimum required rights for automation.
- Rotate API keys on suspected compromise via
POST /v1/api-keys/{keyId}/rotate.