Developer portal

Consent API documentation.

A secure and structured API for creating, reviewing, and auditing consent decisions across regulated digital environments.

OAuth2 bearer authJSON payloadsAudit trail

5documentation sections

3core API actions

v1.3.0current API version

Read overview Request access

Required headersAuthorization: Bearer <oauth2-access-token>Content-Type: application/jsonX-Correlation-ID: unique-request-id

curl https://api.consenza.com/v1/consents   -H "Authorization: Bearer <oauth2-access-token>"   -H "Content-Type: application/json"   -H "X-Correlation-ID: unique-request-id"   -d '{
    "subject": "subject-identifier",
    "subjectMobileNumber": "255700000000",
    "requester": "consent-requester",
    "provider": "provider-code",
    "purpose": {
      "code": "ACCOUNT_ACCESS"
    }
  }'

Sample response

{
  "consentId": "CNZ-4C800607",
  "status": "PENDING",
  "message": "Consent request created successfully.",
  "correlationId": "3f3f5d4c-1c0d-4b99-8a57-8b7d9d1b31f9"
}

1. Introduction

Overview, purpose, and audience.

Consenza provides a secure, auditable API that connects applications, enterprise teams, and partners to manage consent decisions in a compliant and consistent way.

Overview

Consenza exposes a consent API for regulated digital identity and data-sharing workflows across business, enterprise, and partner integrations.

Purpose

The API allows authorized systems to create, review, revoke, and audit consent records while preserving a traceable compliance trail.

Audience

This reference is intended for developers, product teams, operations engineers, and compliance stakeholders implementing or verifying consent workflows.

2. Use cases and quick start

Step-by-step implementation guide.

Use the following flow to obtain credentials, authenticate, submit a request, and monitor the consent lifecycle.

01Request credentials

Contact the Consenza team to obtain OAuth2 credentials and your environment-specific base URL.

02Authenticate

Exchange your client credentials for a bearer token and send it in every protected request.

03Submit a consent request

Create a consent record using the JSON payload structure shown in the examples below.

04Track the outcome

Monitor request status, audit entries, and revocation events to maintain operational visibility.

3. Documentation and code examples

Core API actions and usage examples.

These methods are the foundation of the consent workflow and are designed to remain consistent across internal and external implementations.

Secure bearer authentication
Standard JSON contract
Correlation ID tracing
Lifecycle audit support

Required headersAuthorization: Bearer <oauth2-access-token>Content-Type: application/jsonX-Correlation-ID: unique-request-id

curl https://api.consenza.com/v1/consents   -H "Authorization: Bearer <oauth2-access-token>"   -H "Content-Type: application/json"   -H "X-Correlation-ID: unique-request-id"   -d '{
    "subject": "subject-identifier",
    "subjectMobileNumber": "255700000000",
    "requester": "consent-requester",
    "provider": "provider-code",
    "purpose": {
      "code": "ACCOUNT_ACCESS"
    }
  }'

Sample response

{
  "consentId": "CNZ-4C800607",
  "status": "PENDING",
  "message": "Consent request created successfully.",
  "correlationId": "3f3f5d4c-1c0d-4b99-8a57-8b7d9d1b31f9"
}

3. Documentation

Key functions.

POST

/v1/consents

Create consent

Create a new consent record with subject, provider, purpose, and scope details.

GET

/v1/consents/{subject}

List consents

Fetch the active or historical consent record set for a known subject.

POST

/v1/consents/{id}/revoke

Revoke consent

End an active consent and store the decision alongside the audit trail.

Language examples

Quick code samples.

curl

curl -X POST https://api.consenza.com/v1/consents   -H "Authorization: Bearer <token>"   -H "Content-Type: application/json"   -H "X-Correlation-ID: trace-123"   -d '{
    "subject": "subject-identifier",
    "provider": "provider-code",
    "purpose": { "code": "ACCOUNT_ACCESS" }
  }'

JavaScript

const response = await fetch("https://api.consenza.com/v1/consents", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json",
    "X-Correlation-ID": "trace-123"
  },
  body: JSON.stringify({
    subject: "subject-identifier",
    provider: "provider-code",
    purpose: { code: "ACCOUNT_ACCESS" }
  })
});

Python

import requests

response = requests.post(
    "https://api.consenza.com/v1/consents",
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json",
        "X-Correlation-ID": "trace-123",
    },
    json={
        "subject": "subject-identifier",
        "provider": "provider-code",
        "purpose": {"code": "ACCOUNT_ACCESS"},
    },
)

4. Error message guide

Common errors and their meaning.

401 Unauthorized

The bearer token is missing, expired, or rejected by the gateway.

400 Bad Request

Required payload fields are missing or the JSON schema does not match the contract.

403 Forbidden

The calling client is authenticated but not permitted to perform this operation.

429 Too Many Requests

The API rate limit was exceeded; retry after the interval returned in the response headers.

5. Versioning

Current API version and changelog.

v1.3.0

2026-10-15

Added stronger audit traceability and improved consent status synchronization.

v1.2.0

2026-09-02

Improved request validation and standardized correlation ID handling for all consent operations.

v1.1.0

2026-08-15

Introduced revoke and restore flows for enterprise lifecycle management.

curl https://api.consenza.com/v1/consents -H "Authorization: Bearer <oauth2-access-token>" -H "Content-Type: application/json" -H "X-Correlation-ID: unique-request-id" -d '{ "subject": "subject-identifier", "subjectMobileNumber": "255700000000", "requester": "consent-requester", "provider": "provider-code", "purpose": { "code": "ACCOUNT_ACCESS" } }'

curl -X POST https://api.consenza.com/v1/consents -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -H "X-Correlation-ID: trace-123" -d '{ "subject": "subject-identifier", "provider": "provider-code", "purpose": { "code": "ACCOUNT_ACCESS" } }'

const response = await fetch("https://api.consenza.com/v1/consents", { method: "POST", headers: { Authorization: "Bearer <token>", "Content-Type": "application/json", "X-Correlation-ID": "trace-123" }, body: JSON.stringify({ subject: "subject-identifier", provider: "provider-code", purpose: { code: "ACCOUNT_ACCESS" } }) });

import requests response = requests.post( "https://api.consenza.com/v1/consents", headers={ "Authorization": "Bearer <token>", "Content-Type": "application/json", "X-Correlation-ID": "trace-123", }, json={ "subject": "subject-identifier", "provider": "provider-code", "purpose": {"code": "ACCOUNT_ACCESS"}, }, )