UCAP

API reference

All endpoints rooted at /api/public. Authentication is HTTP Basic with your client_id and client_secret.

Errors

All errors return a JSON body shaped as:

{ "error": { "code": "invalid_input", "message": "Human readable" } }
  • 401 unauthorized — missing/invalid credentials
  • 403 origin_not_allowed — embed-only
  • 404 not_found — session doesn't belong to you
  • 409 not_granted — payload not ready yet
  • 429 rate_limited — slow down
  • 503 schema_unavailable — partner table not provisioned
POST/v1/sessionssecret client

Create a new consent session for a product.

Request
{
  "product_id": "prd_...",
  "external_reference": "optional-string",
  "return_url": "https://yourapp.com/callback"
}
Response
{
  "session_id": "ses_...",
  "session_url": "https://notify.ucap.africa/consent/ses_...",
  "expires_at": "ISO-8601",
  "status": "created"
}
GET/v1/sessions/{id}secret client

Poll a session's status: created · awaiting_consumer · granted · denied · expired · revoked.

GET/v1/sessions/{id}/datasecret client

Fetch the consented data payload. 409 if the session is not granted.

POST/v1/sessions/{id}/revokesecret client

Partner-initiated revoke. Fires a grant.revoked webhook.

POST/v1/sessions/embedpublic client

Used by /embed/button.js. Origin-allowlisted, public client only.