API reference · Identity & onboarding

PediID Authorisation

Federated sign-in with consented field sharing. About pediid sign-in Next

POST/id/authorisation/pushPush an authorisation request
POST/id/authorisation/{requestUri}/approveApprove, field by field
POST/id/authorisation/{requestUri}/declineDecline
GET/id/authorisation/{requestUri}/signing-orderThe exact sentence you are being asked to approve
POST/id/token/exchangeExchange the code for an id_token and the approved fields

POST Push an authorisation request

POST /id/authorisation/push

The integrator asks, back-channel, BEFORE the person is shown anything. Pushing first is what stops request parameters being tampered with in a redirect, and it is why the discovery document advertises requirePushedAuthorizationRequests. A field the integrator was never approved for is refused HERE, before the person is disturbed: out of scope is an error to the integrator, never a prompt somebody has to decline. A required field without a justification is refused for the same reason.

Headers

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

Example

Request body: PushedAuthorisationRequest · Response: GenericResponsePushedAuthorisationResponse

curl -X POST "https://api.bridgemoni.com/id/authorisation/push" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
  "authorisationType": "VERIFICATION",
  "requestFlow": "HANDLE_PUSH",
  "codeChallenge": "string",
  "codeChallengeMethod": "string",
  "nonce": "string",
  "state": "string",
  "redirectUri": "string",
  "purpose": "string",
  "fields": [
    {
      "resourceCode": "string",
      "fieldName": "string",
      "required": true,
      "justification": "string"
    }
  ]
}'

{
  "authorisationType": "VERIFICATION",
  "requestFlow": "HANDLE_PUSH",
  "codeChallenge": "string",
  "codeChallengeMethod": "string",
  "nonce": "string",
  "state": "string",
  "redirectUri": "string",
  "purpose": "string",
  "fields": [
    {
      "resourceCode": "string",
      "fieldName": "string",
      "required": true,
      "justification": "string"
    }
  ]
}

{
  "data": {
    "requestUri": "string",
    "matchingCode": "string",
    "expiresDateTime": "2026-09-25T10:00:00Z"
  },
  "description": "Pushed; redeem the requestUri"
}

Responses

Status	When
`200`	Pushed; redeem the requestUri
`400`	No proof key, wrong method, or a redirect the flow does not permit
`403`	This integrator may not ask, or was never approved for a field

POST Approve, field by field

POST /id/authorisation/{requestUri}/approve

The caller is the person, resolved from their own token. Optional fields they left off do not leave; a required field cannot be selectively withheld, though declining the whole request always can and costs nothing.

Headers

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

Path parameters

Name
`requestUri`

Example

Request body: List<RequestedField> · Response: GenericResponseString

curl -X POST "https://api.bridgemoni.com/id/authorisation/value/approve" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '[
  {
    "resourceCode": "string",
    "fieldName": "string",
    "required": true,
    "justification": "string"
  }
]'

[
  {
    "resourceCode": "string",
    "fieldName": "string",
    "required": true,
    "justification": "string"
  }
]

{
  "data": "string",
  "description": "Approved"
}

Responses

Status	When
`200`	Approved
`409`	A required field was withheld, or the request is no longer open

POST Decline

POST /id/authorisation/{requestUri}/decline

Costs the person nothing and earns them nothing: no penalty, no reduced rate, no worse terms, and no accrual. A decline is audited exactly like an approval, because a log that records only the times somebody said yes cannot answer 'did they ever refuse'.

Headers

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

Path parameters

Name
`requestUri`

Example

Response: GenericResponseString

curl -X POST "https://api.bridgemoni.com/id/authorisation/value/decline" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": "string",
  "description": "Declined"
}

Responses

Status	When
`200`	Declined

GET The exact sentence you are being asked to approve

GET /id/authorisation/{requestUri}/signing-order

What the person's app renders. Composed by PediID, not by the integrator - one that could write the sentence could write a different one from what it is actually asking for. It ends with 'Declining costs you nothing', because that is only true if the person is told.

Headers

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

Path parameters

Name
`requestUri`

Example

Response: GenericResponseSigningOrderResponse

curl -X GET "https://api.bridgemoni.com/id/authorisation/value/signing-order" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "visibleText": "string",
    "visibleTextDigest": "string",
    "matchingCode": "string"
  },
  "description": "The signing order"
}

Responses

Status	When
`200`	The signing order

POST Exchange the code for an id_token and the approved fields

POST /id/token/exchange

Requires the verifier for the challenge the request was opened with: whoever intercepted the code did not open the request and cannot produce it. A code presented twice is recorded as a REPLAY rather than merely refused, because a second presentation is the signature of an interception. Every field is checked against the catalogue AND a live consent at the moment of release, so a revocation between approval and exchange stops it. Each field carries the grade it held when it left.

Headers

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

Example

Request body: TokenExchangeRequest · Response: GenericResponseTokenExchangeResponse

curl -X POST "https://api.bridgemoni.com/id/token/exchange" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "string",
  "codeVerifier": "string"
}'

{
  "code": "string",
  "codeVerifier": "string"
}

{
  "data": {
    "idToken": "string",
    "released": [
      {
        "resourceCode": "string",
        "fieldName": "string",
        "value": "string",
        "assuranceGrade": "string"
      }
    ]
  },
  "description": "The id_token and the approved fields"
}

Responses

Status	When
`200`	The id_token and the approved fields
`401`	Wrong verifier, or the code was already redeemed
`403`	Consent was revoked, or the resource is not consented

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