API reference
Consent Records
Generated HTTP reference for the 1 operation the published OpenAPI document describes under consent-records.
3 min read
Consent Records
This page is generated from the published OpenAPI document. It is complete with respect to that document and says nothing about surfaces the document does not describe yet. See what is generated here for what that means.
Base URL: https://api.codespar.dev
Every operation below requires a Bearer token. See Authentication.
GET /v1/consent-records/{id}
Read one consent record
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | The consent record id. |
Responses
| Status | Body | Description |
|---|---|---|
200 | object | OK |
404 | object | Not Found. No consent record with this id in the caller's organization. |
Response 200
| Field | Type | Required | Description |
|---|---|---|---|
agent_id | string,null | yes | The agent the consumer authorized, when the row names one. |
cap_minor | string,null | yes | A STRING, not a number. The column is bigint and the driver hands bigints back as strings; the handler passes the value straight through. Parse it as an integer in the row's currency, and do not assume it survives a float. Null on revoke / amend rows. |
consumer_id | string | yes | — |
currency | "BRL" | "USD" | "MXN" | "COP" | "ARS" | "USDC" | "BRLA" | yes | Closed by consumer_consents_currency_check (name in exactly one migration file), which admits NULL as well as the seven values. Non-null on grant rows, which the completeness constraint requires to declare one. |
expires_at | string,null (date-time) | yes | — |
funding_source_id | string,null | yes | The consumer_funding_sources row this consent authorizes debits against. Nullable on the column, and required by consumer_consents_grant_completeness on kind = 'grant' rows: a grant must declare what it authorizes, while revoke and amend reference the original grant. |
hmac_secret_version | integer | yes | Which version of the consumer's HMAC secret signed this row. This is the field that makes rotation safe, and the half that is usually left out when the rule is quoted. Rotating a consumer's secret invalidates FUTURE mandates only, and the reason is here rather than in the rotation: the verifier resolves the secret by (consumer, version) and the mandate itself carries the version it was signed under, so a mandate signed under the prior version still resolves the prior secret and still verifies. Rotation marks the old row and inserts version+1; it deletes nothing. Without the version stamp the sentence would mean the opposite — that rotating breaks the audit trail. |
id | string | yes | ccsnt_-prefixed on rows the mandate-lifecycle writer creates. |
ip_address | string,null | yes | The consumer's IP at signing time, from an inet column — personal data, held because a consent event has to be replayable with timestamp and origin. user_agent is recorded alongside it and is NOT returned. |
kind | "grant" | "revoke" | "amend" | yes | Closed by consumer_consents_kind_check, whose name appears in exactly one migration file. The log is append-only: a revocation is a NEW row with kind = 'revoke', never a rewrite of the grant, which is what makes a revocation replayable from the log alone. |
metadata | object | yes | Defaults to \{\}. Rows written by the mandate-lifecycle handler carry the transition instead: action, from, to, and reason when the caller gave one. |
per_tx_cap_minor | string,null | yes | Same bigint-as-string treatment as cap_minor. |
purpose | string,null | yes | The purpose the consumer signed. Non-null on grant rows. |
signed_at | string (date-time) | yes | When the consent event happened. The listing orders by this. |
Example response
{
"id": "obj_0000000000000000",
"consumer_id": "csm_0000000000000000",
"kind": "grant",
"hmac_secret_version": 0,
"currency": "BRL",
"signed_at": "2026-01-15T12:00:00.000Z",
"metadata": {}
}Example request
curl -X GET https://api.codespar.dev/v1/consent-records/{id} \
-H "Authorization: Bearer $CODESPAR_API_KEY"