Headers & Authentication Reference

Required Headers

All Authenticated Requests

Header	Required	Description
Authorization	Yes	Bearer {accessToken}
X-Project-ID	Yes	Your project identifier (see Getting Started)
Content-Type	Yes	application/json for most endpoints

Example

GET /api/v1/auth/auth/user/ HTTP/1.1
Host: test.zonevast.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
X-Project-ID: <project-id>
Content-Type: application/json

JWT Token Structure

Auth Service Token (zv-auth-service)

{
  "token_type": "access",
  "exp": 1714500000,
  "iat": 1714496400,
  "jti": "unique-token-id",
  "user_id": 1,
  "username": "admin",
  "email": "admin@zonevast.com",
  "project_id": 11  // Your project ID
}

Flex Auth Service Token (zv-flex-auth-service)

{
  "sub": "user-uuid",
  "user_id": "uuid-string",
  "phone": "+966500000000",
  "projectId": <project-id>,
  "project_id": <project-id>,
  "role": "customer",
  "roles": ["customer"],
  "userType": "phone"
}

Token Lifecycle

Token	Expiry	Purpose
Access Token	60 minutes	API authorization
Refresh Token	7 days	Get new access token

Authentication Methods

Method 1: Email + Password (Auth Service)

POST /api/v1/auth/auth/token/
Body: { "username": "admin", "password": "admin123" }
Response: { "access": "...", "refresh": "..." }

Method 2: Phone + OTP (Flex Auth Service)

Step 1: POST /auth/api/v2/auth/send-otp
Body: { "phone": "+9647500000001", "projectId": <project-id> }

Step 2: POST /auth/api/v2/auth/login-otp
Body: { "phone": "+9647500000001", "otp": "123456", "projectId": <project-id> }
Response: { "user": {...}, "tokens": { "accessToken": "...", "refreshToken": "..." } }

Method 3: Phone + Password (Flex Auth Service)

POST /auth/api/v2/auth/login
Body: { "phone": "+966500000000", "password": "password123", "projectId": <project-id> }
Response: { "user": {...}, "tokens": { "accessToken": "...", "refreshToken": "..." } }

Refresh Token Flow

Auth Service

curl -X POST https://test.zonevast.com/api/v1/auth/auth/token/refresh/ \
  -H "Content-Type: application/json" \
  -d '{"refresh": "YOUR_REFRESH_TOKEN"}'

Response:

{
  "access": "new-access-token",
  "refresh": "new-refresh-token"
}

Flex Auth Service

curl -X POST https://test.zonevast.com/auth/api/v2/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "YOUR_REFRESH_TOKEN"}'

Response:

{
  "accessToken": "new-access-token",
  "refreshToken": "new-refresh-token"
}

Error Responses

401 Unauthorized

{
  "detail": "Given token not valid for any token type",
  "code": "token_not_valid",
  "messages": [
    {
      "token_class": "AccessToken",
      "token_type": "access",
      "message": "Token is invalid or expired"
    }
  ]
}

403 Forbidden

{
  "detail": "You do not have permission to perform this action."
}

Rate Limiting

{
  "detail": "Request was throttled.",
  "available_in": 60
}

Rate Limits

Endpoint Type	Limit
Global	10 requests/minute
OTP Send	Tiered: immediate, 1min, 5min, 24h
Login	5 attempts, then 15-min lockout

Cross-Service Auth

All services validate JWT tokens. The flow:

1. Client obtains token from auth service
2. Client sends token in Authorization header to any service
3. Target service validates the JWT signature
4. Request is authorized if token is valid and not expired

Note: X-Project-ID must match the project in the JWT. Mismatched project IDs will result in a 403 error.