Authentication

You'll need to authenticate your requests to access any of the endpoints in the API. This guide covers the complete authentication flow, from registration to accessing protected endpoints using bearer tokens.

Authentication Flow

The authentication system uses a multi-factor authentication (MFA) flow with email verification codes and JWT tokens. The process involves the following steps:

Register or Login - Receive a verification code ID
Verify Code - Submit the verification code received via email to get access and refresh tokens
Use Access Token - Include the access token in requests to protected endpoints
Refresh Token - Use the refresh token to obtain new access tokens when they expire

Register

Create a new user account. This endpoint requires accepting terms of use and privacy policy, and optionally accepts a referral code and coupon.

Register a new user

curl -X POST https://api.example.com/api/auth/register \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "email": "user@example.com",
    "password": "secure-password",
    "termsOfUse": true,
    "privacyPolicy": true
  }'

Query Parameters (optional):

referral - Referral code
coupon - Coupon code

Response:

{
  "status": 200,
  "message": "Verification code sent",
  "data": {
    "verification_code_id": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Authenticate with an existing account. You'll receive a verification code ID that you'll need to complete the login process.

Login

curl -X POST https://api.example.com/api/auth/login \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "email": "user@example.com",
    "password": "secure-password"
  }'

Response:

{
  "status": 200,
  "message": "Verification code sent",
  "data": {
    "verification_code_id": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

A verification code will be sent to your email address.

Verify Code

After receiving the verification code via email, submit it along with your email to complete authentication and receive your access and refresh tokens.

Verify code and get tokens

curl -X POST https://api.example.com/api/auth/verify-code \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "email": "user@example.com",
    "code": "123456"
  }'

Response:

{
  "status": 200,
  "message": "Login successfully",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Using Bearer Token

Once you have an access token, include it in the Authorization header of all protected API requests. The access token expires after 8 hours.

Example request with bearer token

curl https://api.example.com/api/protected-endpoint \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Always keep your tokens safe and never commit them to version control.

Refresh Token

When your access token expires, use the refresh token to obtain a new access token. The refresh token expires after 12 hours.

Refresh access token

curl -X POST https://api.example.com/api/auth/refresh-token \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Response:

{
  "status": 200,
  "message": "Login successfully",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Resend Verification Code

If you didn't receive the verification code or it expired, you can request a new one.

Resend verification code

curl -X POST https://api.example.com/api/auth/resend-verification-code \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "verification_code_id": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Password Recovery

Forgot Password

Request a password reset email.

Request password reset

curl -X POST https://api.example.com/api/auth/forgot-password \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "email": "user@example.com"
  }'

Reset Password

Reset your password using the code received via email.

Reset password

curl -X POST https://api.example.com/api/auth/reset-password \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "password": "new-secure-password",
    "code": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Logout

Log out from your current session. This endpoint requires authentication.

Logout

curl -X POST https://api.example.com/api/auth/logout \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Required Headers

All API requests require the following header:

x-tenant-id - Your tenant identifier

Protected endpoints also require:

Authorization: Bearer {access_token} - Your access token

Token Expiration

Access Token: Expires after 8 hours
Refresh Token: Expires after 12 hours
Verification Code: Expires after 1 hour

Make sure to refresh your access token before it expires to maintain uninterrupted access to the API.