Identity and Access

Client users sign in through gateway-service. Platform operators use a separate admin key for tasks such as user setup, balance changes and routing configuration.

Tenant login

Each client user has a unique username, BCrypt-protected password, status, and parent organization. A successful login returns:

• an HS512 bearer access token;
• an opaque refresh token;
• access and refresh expiry durations;
• the Bearer token type.

Login requires the client user to be ACTIVE. Invalid username, password, and inactive-user cases share a generic error so the API does not reveal whether an account exists.

Client status boundary

Login checks the client user's status, but not the parent organization's status. To suspend access, deactivate the client user. Existing sessions remain active until they expire or are ended.

Active-session authorization

sequenceDiagram
    actor App as Client application
    participant G as Gateway
    participant J as JWT validation
    participant R as Redis sessions
    participant S as Router/client API
    App->>G: Request + Bearer JWT
    G->>J: Verify signature and expiry
    G->>R: Read sms:token:{JWT}
    R-->>G: Client/user session context
    G->>S: Trusted identity headers
    S-->>App: Tenant-scoped response

Hold "Ctrl" to enable pan & zoom

The gateway requires both a valid JWT and its live Redis session entry. This provides two useful properties:

• any gateway instance can authorize the request without local session state;
• logout can invalidate an otherwise unexpired JWT by deleting its Redis entry.

After authorization, the gateway forwards client ID, user ID, username, and session status as trusted headers. Message and campaign APIs use this context for ownership and account-state enforcement.

Refreshing a session

Client applications use a refresh token to get a new access token without asking the user to log in again. Each refresh token can only be used once:

1. The application sends the current refresh token.
2. The platform confirms that the user is still active.
3. The platform returns new access and refresh tokens.
4. The old refresh token stops working.

If two requests use the same refresh token at the same time, only one succeeds. The application should save the new tokens before trying to refresh again.

Logging out

Logout can end:

• the current access token;
• the refresh token included in the request.

Send both tokens to fully end the session. Repeating the same logout request is safe.

Changing a user's password or status prevents future login and refresh attempts, but does not immediately end an active session. The session remains valid until logout or expiry. If access must end immediately, an operator must also delete the active session.

Administrative access

Platform administration and peer-service calls use X-Admin-API-Key, including:

• client/user provisioning and top-up;
• reporting and exports;
• routing, sender, carrier-credential, channel and price configuration;
• internal client configuration, debit, refund and reversal operations.

Audience model

Audience	Entry point	Credential	Typical capability
External client	Gateway	Username/password, refresh token, or bearer JWT	Login, direct SMS, campaigns, session context
Internal operator	Gateway or private service port	X-Admin-API-Key	Provisioning, routing configuration, reporting
Internal service	Private network/discovery	X-Admin-API-Key	Router balance deduction/refund/config lookup
Platform probe	Service management port	Network trust; service-specific policy	Liveness/readiness checks

See the Identity and Session API, client-service architecture, and gateway architecture.