Authentication

Overview

FutureSMS Merchant API uses Bearer access tokens. A client logs in with an API user, stores the returned token pair, sends the access token on business requests, and refreshes the token pair before continuing.

Authentication also checks whether the user, account, role, and session are allowed to use the requested API surface.

Endpoints

Before You Begin

Create a dedicated API user for server-to-server Merchant API access. Do not reuse a human portal account for automated traffic.

Make sure the integration can persist the latest token pair, coordinate token refresh across workers, and use UTC timestamps from the auth response when deciding when to refresh.

Request Flow

1. Call POST /api/v1/auth/login with username and password.
2. Store access_token, refresh_token, and both expiry timestamps.
3. Send Authorization: Bearer <access_token> on protected API requests.
4. When the access token expires, call POST /api/v1/auth/refresh with the latest refresh token.
5. Replace both stored tokens with the refresh response.
6. Call POST /api/v1/auth/logout when the integration should end the session.

Authorization Header

Authentication-protected endpoints use the same header shape.

{
  "Authorization": "Bearer <access_token>"
}

Login

Use Login when your integration needs to start a Merchant API session and obtain a token pair.

Endpoint

POST /api/v1/auth/login

Authentication: none.

Before You Begin

Use an API user for server-to-server Merchant API integrations. Portal users can authenticate for portal flows, but merchant business API usage should not depend on a human portal session.

The user must be active and allowed to use the requested API surface.

Request fields

Response fields

Behavior

When login succeeds, FutureSMS:

1. Applies login protection checks.
2. Validates username and password.
3. Confirms the user can authenticate for this API surface.
4. Checks the account and role permissions.
5. Handles MFA state if the account requires it.
6. Replaces older sessions for the same user.
7. Issues a new access token and refresh token.

New login can replace older sessions for the same user. If an old token stops working after a new login, log in again and update stored credentials.

Status codes

Examples

{
  "username": "api_user_example",
  "password": "REPLACE_WITH_STRONG_PASSWORD"
}

{
  "message": "OK",
  "details": null,
  "data": {
    "mfa_required": false,
    "mfa_token": null,
    "access_token": "<access_token>",
    "refresh_token": "<refresh_token>",
    "token_type": "bearer",
    "access_token_expires_at": "2026-03-25T11:30:00Z",
    "refresh_token_expires_at": "2026-04-01T10:30:00Z",
    "user": {
      "username": "api_user_example",
      "role": "api"
    }
  },
  "meta": null
}

Token Storage

Store tokens on the server side of your integration when possible. Treat both tokens as credentials.

Access tokens are short-lived. Refresh tokens live longer, but can still become invalid before their timestamp if the user logs in again, logs out, changes password, is disabled, or the session is ended.

Refresh

Use Refresh when the access token is expired or close to expiry and the integration should continue the same authenticated session.

Endpoint

POST /api/v1/auth/refresh

Authentication: refresh token in request body.

Before You Begin

Use the latest refresh token only. A successful refresh rotates the pair, so the previous refresh token should be treated as spent.

If multiple workers share one API user, coordinate refresh so only one worker rotates the session and the others reuse the stored new token pair.

Request fields

Response fields

Behavior

Refresh revalidates the session before issuing a new pair. FutureSMS:

1. Verifies the refresh token.
2. Confirms the session can continue.
3. Rechecks user, account, and role permissions.
4. Applies refresh protection checks.
5. Issues a new token pair.

After a successful refresh, store the new refresh token and discard the previous one. If several workers need to refresh, let one worker refresh and share the updated token pair with the others.

Status codes

Examples

{
  "refresh_token": "<refresh_token>"
}

{
  "message": "OK",
  "details": null,
  "data": {
    "mfa_required": false,
    "mfa_token": null,
    "access_token": "<new_access_token>",
    "refresh_token": "<new_refresh_token>",
    "token_type": "bearer",
    "access_token_expires_at": "2026-03-25T12:30:00Z",
    "refresh_token_expires_at": "2026-04-01T11:30:00Z",
    "user": {
      "username": "api_user_example",
      "role": "api"
    }
  },
  "meta": null
}

Current User

Use Current User to check whether the current access token is valid and to read the current user and merchant summary.

Endpoint

GET /api/v1/auth/me

Authentication: Bearer access token.

Before You Begin

Send a current access token in the Authorization header. This endpoint is useful for startup checks and diagnostics, but each business endpoint still performs its own authorization checks.

Request fields

No JSON request body. Send the access token in the Authorization header.

Response fields

Behavior

FutureSMS validates the access token and session state before returning the profile. This endpoint is useful for startup checks and operator diagnostics, but it should not replace endpoint-specific validation.

Status codes

Examples

{
  "message": "OK",
  "details": null,
  "data": {
    "current_user": {
      "username": "api_user_example",
      "email": "api-user@example.com",
      "role": "api",
      "is_active": true
    },
    "merchant": {
      "merchant_id": "MCH-1",
      "name": "Merchant A",
      "merchant_prepaid_cash": "0.000000",
      "merchant_credit_available": "0.000000",
      "is_active": true
    }
  },
  "meta": null
}

Logout

Use Logout when the integration should explicitly end the current session.

Endpoint

POST /api/v1/auth/logout

Authentication: Bearer access token.

Before You Begin

Call logout when your integration intentionally ends a session or rotates to a different API user. After logout succeeds, remove the stored access token and refresh token from your integration.

Request fields

No JSON request body. Send the access token in the Authorization header.

Response fields

Behavior

Logout ends the current session. After logout succeeds, clear the stored access token and refresh token.

Status codes

Examples

{
  "message": "OK",
  "data": null,
  "details": null,
  "meta": null
}

Session Rules

FutureSMS sessions can end before the token timestamp when account or session state changes.

Access Scope

Roles map to different access scopes.

For Merchant API integrations, use an api user. Login and protected API calls can be rejected if the user, merchant, or role does not satisfy the configured access rules.

MFA Field

The login and refresh response shape includes mfa_required and mfa_token because the shared auth response supports MFA. For normal server-to-server Merchant API usage, an API user should receive access and refresh tokens directly.

If mfa_required is true, no usable Merchant API token pair has been issued yet. Complete the account's authentication flow or contact your FutureSMS administrator before using business endpoints.

Client Guidance

Only one worker should refresh a session at a time. If several API calls all receive TOKEN_EXPIRED, let one refresh request rotate the token pair and make the others reuse the new tokens.

For long-running jobs, refresh before starting a large batch if the access token is close to expiry. For business requests, never retry forever on auth errors: after one successful refresh attempt, a repeated 401 should be treated as a new login or operator action problem.