Consent Records

Base URL: https://api.codespar.dev

Every operation below requires a Bearer token. See Authentication.

GET /v1/consent-records

List consent evidence

The organization's consent evidence, most recent first. It is append-only: nothing here is edited after it is signed.

The response is { consents: [...] }.

Query parameters

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/consent-records \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/consent-records HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/consent-records",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/consent-records", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/consent-records");

{
  "consents": [
    {
      "id": "obj_0000000000000000",
      "consumer_id": "csm_0000000000000000",
      "funding_source_id": "fundingsource_0000000000000000",
      "agent_id": "agt_0000000000000000",
      "kind": "grant",
      "hmac_secret_version": 0,
      "cap_minor": "1000",
      "per_tx_cap_minor": "1000",
      "currency": "BRL",
      "purpose": "string",
      "ip_address": "string",
      "signed_at": "2026-01-15T12:00:00.000Z",
      "expires_at": "2026-01-15T12:00:00.000Z",
      "metadata": {}
    }
  ]
}

GET /v1/consent-records/{id}

Read one consent record

One row of the consent log: the moment a consumer authorized a specific agent to debit a specific funding source up to a specific cap. Requires the consents:read scope.

APPEND-ONLY EVIDENCE. consumer_consents is the LGPD audit log — rows are never rewritten and never deleted, and a revocation is a new row with kind = 'revoke'. That is what lets a revocation be replayed from the log alone, and it is why this read returns exactly what the listing returns: there is no derived state for a point read to add.

RESOLUTION IS SCOPED TO THE ORGANIZATION ONLY — the query predicates on org_id and the id, with no project term. A consent record created under a sibling project in the same organization IS readable with this credential. The funding-source read in this same group is narrower, so do not carry an assumption across the two.

NO SIGNATURE MATERIAL LEAVES. The row carries payload_hash and hmac_signature; both are dropped before the body is built. What crosses the wire is hmac_secret_version — the stamp that says which secret signed it — and its note explains why that stamp is what makes secret rotation safe rather than destructive.

PERSONAL DATA, TRUNCATED. ip_address is the network of the consumer's address (/24 for IPv4, /64 for IPv6); the full address stays on the row, recorded because a consent event has to be replayable with its origin.

Path parameters

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/consent-records/{id} \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/consent-records/{id} HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/consent-records/{id}",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/consent-records/{id}", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/consent-records/{id}", {
  path: {
    id: "consentrecord_0000000000000000"
  }
});

{
  "id": "obj_0000000000000000",
  "consumer_id": "csm_0000000000000000",
  "funding_source_id": "fundingsource_0000000000000000",
  "agent_id": "agt_0000000000000000",
  "kind": "grant",
  "hmac_secret_version": 0,
  "cap_minor": "1000",
  "per_tx_cap_minor": "1000",
  "currency": "BRL",
  "purpose": "string",
  "ip_address": "string",
  "signed_at": "2026-01-15T12:00:00.000Z",
  "expires_at": "2026-01-15T12:00:00.000Z",
  "metadata": {}
}