API reference · Access & roles

Credentials

POST/credentialSet a credential the caller does not yet have
PUT/credentialChange a credential using its current value
POST/credential/resetComplete a credential reset
POST/credential/reset/otpInitiate a credential reset
POST/credential/unblockUnblock a blocked credential

POST Set a credential the caller does not yet have

POST /credential

Registers a credential of the given type - a PIN, most often - for the authenticated caller. Unlike PUT /credential this takes no old value, because there is nothing to replace, and no user identifier, because the session already says who the caller is. Setting a type the caller already holds is a conflict, not an overwrite: use PUT /credential to change one that exists, or the reset flow if the current value is unknown.

Headers

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

Example

Request body: SetCredentialRequest · Response: Void

curl -X POST "https://api.bridgemoni.com/credential" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
    "secretType": "PIN",
    "secret": "text"
  }'

{
  "secretType": "PIN",
  "secret": "text"
}

{
  "description": "Set a credential the caller does not yet have"
}

Responses

Status	When
`200`	Credential set successfully
`409`	A credential of this type is already registered for the caller

PUT Change a credential using its current value

PUT /credential

Lets a caller who still knows their current credential value replace it with a new one, identifying themselves by msisdn/username/emailAddress rather than a Bearer/Basic Authorization header - most commonly used right after a login attempt fails because the credential has expired, since unlike the normal authentication path this deliberately accepts an expired-but-correct value.

Headers

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

Example

Request body: ChangeCredentialRequest · Response: Void

curl -X PUT "https://api.bridgemoni.com/credential" \
  -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",
    "secretType": "PIN",
    "oldSecret": "text",
    "newSecret": "text"
  }'

{
  "msisdn": "+2348012345678",
  "username": "ada.obi",
  "emailAddress": "ada@example.com",
  "secretType": "PIN",
  "oldSecret": "text",
  "newSecret": "text"
}

{
  "description": "Change a credential using its current value"
}

Responses

Status	When
`200`	Credential changed successfully
`400`	The request named no user - supply one of msisdn, username or emailAddress
`401`	The supplied old value does not match the stored credential
`404`	No user exists for the given identifier, or no credential of the given type is registered for it
`500`	The credential is blocked

POST Complete a credential reset

POST /credential/reset

Validates the supplied OTP against the OTP identified by the given reference, and replaces the credential it was generated for with the supplied new value. Fails after 5 incorrect attempts or once the OTP expires (10 minutes after generation).

Headers

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

Example

Request body: CompleteCredentialResetRequest · Response: Void

curl -X POST "https://api.bridgemoni.com/credential/reset" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
    "otpReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "otp": "482913",
    "newSecret": "text"
  }'

{
  "otpReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
  "otp": "482913",
  "newSecret": "text"
}

{
  "description": "Complete a credential reset"
}

Responses

Status	When
`200`	Credential reset completed successfully
`400`	The OTP does not match, or has expired
`404`	No OTP exists for the given reference, or it has already been used

POST Initiate a credential reset

POST /credential/reset/otp

Identifies the user by msisdn and/or emailAddress, generates a 6-digit OTP valid for 10 minutes, and publishes a CredentialResetInitiatedEvent so it can be dispatched to the user's mobile number or email address. Works for any credential type the user already has registered, for example PASSWORD or PIN. Does not return the OTP itself, but returns a reference identifying it, to be supplied back on the complete call.

Headers

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

Example

Request body: InitiateCredentialResetRequest · Response: InitiateCredentialResetResponse

curl -X POST "https://api.bridgemoni.com/credential/reset/otp" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
    "msisdn": "+2348012345678",
    "emailAddress": "ada@example.com",
    "secretType": "PIN"
  }'

{
  "msisdn": "+2348012345678",
  "emailAddress": "ada@example.com",
  "secretType": "PIN"
}

{
  "data": {
    "otpReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e"
  },
  "description": "Initiate a credential reset"
}

Responses

Status	When
`200`	Credential reset initiated successfully
`404`	No user exists for the given identifier, or no credential of the given type is registered for it

POST Unblock a blocked credential

POST /credential/unblock

Clears the failed-attempt counter on a user's credential and returns it to ACTIVE if it was BLOCKED, so the owner can authenticate again. Needed because a credential that has reached the limit of consecutive failed attempts re-arms its lockout on every further attempt, so a client retrying on a timer never escapes it unaided. This does not change the credential value and does not extend its expiry: an unblocked credential whose value is unknown still needs the reset flow, and an expired one still needs to be changed.

Headers

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

Example

Request body: UnblockCredentialRequest · Response: GenericResponseVoid

curl -X POST "https://api.bridgemoni.com/credential/unblock" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
  "msisdn": "+2348000000000",
  "username": "string",
  "emailAddress": "ada@example.com",
  "secretType": "PIN"
}'

{
  "msisdn": "+2348000000000",
  "username": "string",
  "emailAddress": "ada@example.com",
  "secretType": "PIN"
}

{
  "data": "string",
  "description": "Credential unblocked successfully"
}

Responses

Status	When
`200`	Credential unblocked successfully
`400`	The request named no user - supply one of msisdn, username or emailAddress
`404`	No user exists for the given identifier, or no credential of the given type is registered for it

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