Skip to main content
Most API endpoints use bearer token authentication.
Authentication endpoints issue tokens for the matching portal domain. Each portal API should be documented separately so the playground uses the correct base URL and token context.

​
Access And Refresh Tokens

Normal login, registration, creditor email verification, consumer OTP verification, and trusted-device login responses include token metadata:
  • meta.access_token is the Sanctum bearer token used on authenticated API calls.
  • meta.refresh_token is a plaintext refresh token returned once. Store it securely and send it to POST /auth/refresh when a new access token is needed.
  • meta.token_type is Bearer.
  • meta.access_token_expires_at is the access-token expiry timestamp when an expiry is assigned; otherwise it is null.
  • meta.refresh_token_expires_at is the refresh-token expiry timestamp.
Creditor, Superadmin, and EcoMail Hub login endpoints accept optional remember. Omitted or true uses the remembered refresh-token TTL, which defaults to 30 days. remember: false uses the standard refresh-token TTL, which defaults to 12 hours. Refresh rotation keeps the original remember mode. POST /auth/refresh rotates both tokens. A successful refresh revokes the old refresh token, deletes the old linked Sanctum access token, and returns replacement token metadata. Expired, revoked, malformed, or reused refresh tokens return 401.

​
Superadmin Login-As Handoffs

Superadmin login-as uses a two-step handoff so target-portal credentials are never returned from the Superadmin domain:
  1. The authenticated Superadmin endpoint creates an 80-character handoff token and expiry timestamp. No access or refresh token is included in this response.
  2. The frontend immediately sends the handoff token in the JSON body of POST /auth/login-as/exchange on the target Creditor or EcoMail Hub API.
  3. A successful exchange consumes the handoff and returns a non-remembered access and refresh token pair for the target user.
Handoffs are single-use, default to a 60-second lifetime, and only work on the portal for which they were issued. Invalid, expired, reused, wrong-portal, deleted-user, and ineligible-creditor handoffs return 422 with the same generic validation message. Their refresh-token TTL follows the standard non-remembered duration. Treat the plaintext handoff like a credential: keep it only in memory, never place it in a URL, and discard it after exchange.

​
Token Scope

Last modified on July 19, 2026