API reference · Access & roles

Users

POST/userCreate a user
DELETE/user/{id}Delete a user
GET/user/{id}Fetch a user by reference
PUT/user/{id}Update a user
POST/user/{id}/blockBlock a user
POST/user/{id}/mfa/disableDisable two-factor authentication
POST/user/{id}/mfa/enableEnable two-factor authentication
POST/user/{id}/secretIssue or rotate a client secret
POST/user/{id}/unblockUnblock a user
GET/user/{type}/{value}Fetch a user by mobile number, email address, or username
GET/usersList users

POST Create a user

POST /user

Registers a new user. A PASSWORD credential is created from the supplied password, and a CLIENT_SECRET credential is generated automatically. The generated secret key is returned only once, in this response — it cannot be retrieved again afterwards. The user is created with status ACTIVE and unverified mobile number / email address.

Headers

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

Example

Request body: UserRequest · Response: UserCreationResponse

curl -X POST "https://api.bridgemoni.com/user" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
    "mobileNumber": "+2348012345678",
    "emailAddress": "ada@example.com",
    "username": "ada.obi",
    "roleReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "password": "a-strong-password"
  }'

{
  "mobileNumber": "+2348012345678",
  "emailAddress": "ada@example.com",
  "username": "ada.obi",
  "roleReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
  "password": "a-strong-password"
}

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "mobileNumber": "+2348012345678",
    "emailAddress": "ada@example.com",
    "username": "ada.obi",
    "clientId": "cli_7f3k2m9",
    "roleReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "status": "REGISTERED",
    "twoFactorAuthenticationStatus": true,
    "emailAddressVerificationStatus": true,
    "mobileNumberVerificationStatus": true,
    "secretKey": "text"
  },
  "description": "Create a user"
}

Responses

Status	When
`200`	User created successfully, including the one-time secret key
`409`	The mobile number, email address, or username is already registered to another user

DELETE Delete a user

DELETE /user/{id}

Soft-deletes the user by setting their status to DELETED. Associated credentials and OTP records are retained.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`id`

Example

Response: Void

curl -X DELETE "https://api.bridgemoni.com/user/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "description": "Delete a user"
}

Responses

Status	When
`200`	User deleted successfully
`404`	No user exists for the given reference

GET Fetch a user by reference

GET /user/{id}

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`id`

Example

Response: UserResponse

curl -X GET "https://api.bridgemoni.com/user/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "mobileNumber": "+2348012345678",
    "emailAddress": "ada@example.com",
    "username": "ada.obi",
    "clientId": "cli_7f3k2m9",
    "clientSecret": "sk_live_REPLACE_ME",
    "roleReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "status": "REGISTERED",
    "twoFactorAuthenticationStatus": true,
    "emailAddressVerificationStatus": true,
    "mobileNumberVerificationStatus": true
  },
  "description": "Fetch a user by reference"
}

Responses

Status	When
`200`	User fetched successfully
`404`	No user exists for the given reference

PUT Update a user

PUT /user/{id}

Partially updates a user's mobile number, email address, username, or role. Only non-null fields in the request body are applied. Changing the mobile number or email address does not reset its verification status automatically — re-verify explicitly if required.

Headers

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

Path parameters

Name
`id`

Example

Request body: UpdateUserRequest · Response: UserResponse

curl -X PUT "https://api.bridgemoni.com/user/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
    "mobileNumber": "+2348012345678",
    "emailAddress": "ada@example.com",
    "username": "ada.obi",
    "roleReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e"
  }'

{
  "mobileNumber": "+2348012345678",
  "emailAddress": "ada@example.com",
  "username": "ada.obi",
  "roleReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e"
}

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "mobileNumber": "+2348012345678",
    "emailAddress": "ada@example.com",
    "username": "ada.obi",
    "clientId": "cli_7f3k2m9",
    "clientSecret": "sk_live_REPLACE_ME",
    "roleReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "status": "REGISTERED",
    "twoFactorAuthenticationStatus": true,
    "emailAddressVerificationStatus": true,
    "mobileNumberVerificationStatus": true
  },
  "description": "Update a user"
}

Responses

Status	When
`200`	User updated successfully
`404`	No user exists for the given reference
`409`	The new mobile number, email address, or username is already registered to another user

POST Block a user

POST /user/{id}/block

Sets the user's status to BLOCKED, preventing them from authenticating.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`id`

Example

Response: UserResponse

curl -X POST "https://api.bridgemoni.com/user/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/block" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "mobileNumber": "+2348012345678",
    "emailAddress": "ada@example.com",
    "username": "ada.obi",
    "clientId": "cli_7f3k2m9",
    "clientSecret": "sk_live_REPLACE_ME",
    "roleReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "status": "REGISTERED",
    "twoFactorAuthenticationStatus": true,
    "emailAddressVerificationStatus": true,
    "mobileNumberVerificationStatus": true
  },
  "description": "Block a user"
}

Responses

Status	When
`200`	User blocked successfully
`404`	No user exists for the given reference

POST Disable two-factor authentication

POST /user/{id}/mfa/disable

Reverts login to require only the primary credential (password). Refused for a user who holds any role outside the customer category, since those roles always require two-factor authentication, and refused when the caller targets themselves.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`id`

Example

Response: UserResponse

curl -X POST "https://api.bridgemoni.com/user/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/mfa/disable" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "mobileNumber": "+2348012345678",
    "emailAddress": "ada@example.com",
    "username": "ada.obi",
    "clientId": "cli_7f3k2m9",
    "clientSecret": "sk_live_REPLACE_ME",
    "roleReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "status": "REGISTERED",
    "twoFactorAuthenticationStatus": true,
    "emailAddressVerificationStatus": true,
    "mobileNumberVerificationStatus": true
  },
  "description": "Disable two-factor authentication"
}

Responses

Status	When
`200`	Two-factor authentication disabled
`404`	No user exists for the given reference

POST Enable two-factor authentication

POST /user/{id}/mfa/enable

Requires an OTP, sent to the user's mobile number or email address, to be supplied and verified via POST /token/mfa on every subsequent login.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`id`

Example

Response: UserResponse

curl -X POST "https://api.bridgemoni.com/user/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/mfa/enable" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "mobileNumber": "+2348012345678",
    "emailAddress": "ada@example.com",
    "username": "ada.obi",
    "clientId": "cli_7f3k2m9",
    "clientSecret": "sk_live_REPLACE_ME",
    "roleReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "status": "REGISTERED",
    "twoFactorAuthenticationStatus": true,
    "emailAddressVerificationStatus": true,
    "mobileNumberVerificationStatus": true
  },
  "description": "Enable two-factor authentication"
}

Responses

Status	When
`200`	Two-factor authentication enabled
`404`	No user exists for the given reference

POST Issue or rotate a client secret

POST /user/{id}/secret

Generates a new CLIENT_SECRET for the user and returns it in clientSecret. This is the only response, apart from user creation, that ever carries the secret: it is stored as a keyed hash and every read returns clientSecret as null. If the user already has a client secret it is replaced, and the previous secret stops working immediately.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`id`

Example

Response: UserResponse

curl -X POST "https://api.bridgemoni.com/user/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/secret" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "mobileNumber": "+2348012345678",
    "emailAddress": "ada@example.com",
    "username": "ada.obi",
    "clientId": "cli_7f3k2m9",
    "clientSecret": "sk_live_REPLACE_ME",
    "roleReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "status": "REGISTERED",
    "twoFactorAuthenticationStatus": true,
    "emailAddressVerificationStatus": true,
    "mobileNumberVerificationStatus": true
  },
  "description": "Ensure a client secret exists"
}

Responses

Status	When
`200`	Client secret ensured and returned
`404`	No user exists for the given reference

POST Unblock a user

POST /user/{id}/unblock

Sets a previously blocked user's status back to ACTIVE.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`id`

Example

Response: UserResponse

curl -X POST "https://api.bridgemoni.com/user/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/unblock" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "mobileNumber": "+2348012345678",
    "emailAddress": "ada@example.com",
    "username": "ada.obi",
    "clientId": "cli_7f3k2m9",
    "clientSecret": "sk_live_REPLACE_ME",
    "roleReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "status": "REGISTERED",
    "twoFactorAuthenticationStatus": true,
    "emailAddressVerificationStatus": true,
    "mobileNumberVerificationStatus": true
  },
  "description": "Unblock a user"
}

Responses

Status	When
`200`	User unblocked successfully
`404`	No user exists for the given reference

GET Fetch a user by mobile number, email address, or username

GET /user/{type}/{value}

Resolves a user from a raw identifier value. The type segment tells the authorization service which field to match against (msisdn, email, or username); id matches the value against mobile number, username, and email address, for callers that don't know which field it corresponds to. Callers never resolve the reference themselves — they always send the raw identifier and get the resolved user back.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`type`
`value`

Example

Response: UserResponse

curl -X GET "https://api.bridgemoni.com/user/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "mobileNumber": "+2348012345678",
    "emailAddress": "ada@example.com",
    "username": "ada.obi",
    "clientId": "cli_7f3k2m9",
    "clientSecret": "sk_live_REPLACE_ME",
    "roleReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "status": "REGISTERED",
    "twoFactorAuthenticationStatus": true,
    "emailAddressVerificationStatus": true,
    "mobileNumberVerificationStatus": true
  },
  "description": "Fetch a user by mobile number, email address, or username"
}

Responses

Status	When
`200`	User fetched successfully
`404`	No user matches the given identifier

GET List users

GET /users

Returns a paginated list of all registered users.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Query parameters

Name	Default
`page`	Optional
`size`	Optional

Example

Response: PageResponse<UserResponse>

curl -X GET "https://api.bridgemoni.com/users?page=value&size=value" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "contents": [
      {
        "...": "the resource"
      }
    ],
    "page": 1,
    "size": 1,
    "total": 1,
    "pages": 1
  },
  "description": "List users"
}

Responses

Status	When
`200`	Users fetched successfully

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