API reference · Access & roles

Access Tokens

POST/tokenGenerate an access token

POST Generate an access token

POST /token

Single entry point covering every stage of token issuance, inferred from which fields are supplied: the password grant (one of msisdn/username/emailAddress, plus password), the client credentials grant (clientId plus clientSecret), completing a pending MFA challenge (mfaReference plus otp, from a prior response), completing role selection for a multi-role user (userReference plus the chosen roleReference, from a prior response), or exchanging a refresh token (refreshToken alone, from a prior response - it takes priority over every other field, keeps the role the session was opened with, and is rotated, so the token presented stops working once exchanged). The response is always this same shape: accessToken populated means done; mfaReference populated means an MFA challenge is pending - re-call with mfaReference + otp; userReference/roles populated means the user has more than one role - re-call with userReference + the chosen roleReference. Any access token previously issued to the resolved user is revoked once a real token is issued.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live
`Content-Type`	application/json

Example

Request body: AccessTokenRequest · Response: AccessTokenResponse

curl -X POST "https://api.bridgemoni.com/token" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
    "msisdn": "+2348012345678",
    "username": "ada.obi",
    "emailAddress": "ada@example.com",
    "password": "a-strong-password",
    "clientId": "cli_7f3k2m9",
    "clientSecret": "sk_live_REPLACE_ME",
    "mfaReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "otp": "482913",
    "userReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "roleReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "refreshToken": "rt_9k2m4x8"
  }'

{
  "msisdn": "+2348012345678",
  "username": "ada.obi",
  "emailAddress": "ada@example.com",
  "password": "a-strong-password",
  "clientId": "cli_7f3k2m9",
  "clientSecret": "sk_live_REPLACE_ME",
  "mfaReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
  "otp": "482913",
  "userReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
  "roleReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
  "refreshToken": "rt_9k2m4x8"
}

{
  "data": {
    "accessToken": "eyJhbGciOi...",
    "refreshToken": "rt_9k2m4x8",
    "tokenType": "bearer",
    "scope": "scope",
    "expiresIn": 1,
    "mfaReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "userReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "roles": [
      {
        "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "name": "Ada Obi"
      }
    ],
    "tenantId": "tenant id",
    "clientId": "cli_7f3k2m9",
    "environment": "environment"
  },
  "description": "Generate an access token"
}

Responses

Status	When
`200`	An access token was generated successfully, an MFA challenge is pending, or the user must select a role before a token can be issued
`400`	None of the supported field combinations was supplied, or the OTP does not match or has expired
`404`	No user exists for the given identifier/client ID/userReference, or no pending MFA challenge exists for the given mfaReference
`401`	The password/client secret does not match, the user is not active (blocked or deleted), or the refresh token has expired (REFRESH_TOKEN_EXPIRED) or does not match an active session (REFRESH_TOKEN_NOT_VALID) - sign in again in either case
`403`	The chosen role is not one of the user's assigned roles
`500`	The stored credential is inactive or expired

Generated from the OpenAPI document. Branch on the HTTP status: there is no machine-readable error code on the wire. Errors