Skip to main content

​
Endpoint

POST /v1/dpdp/consent-records

​
Authentication

Requires a developer API key in the Authorization header.

​
Request Headers

HeaderValue
AuthorizationBearer <api_key>
Content-Typeapplication/json

​
Request Body

FieldTypeRequiredDescription
grantIdstringYesThe grant to attach the consent record to
dataPrincipalIdstringYesThe data principal (end-user) providing consent
purposesobject[]YesArray of purpose objects ({ code, description })
consentNoticeIdstringYesID of the consent notice shown to the principal
processingExpiresAtstringYesISO-8601 timestamp when data processing permission expires

​
Purpose Object

FieldTypeDescription
codestringMachine-readable purpose code (e.g., "analytics", "personalization")
descriptionstringHuman-readable description of the purpose

​
Example Request

curl -X POST https://grantex-auth-dd4mtrt2gq-uc.a.run.app/v1/dpdp/consent-records \
  -H "Authorization: Bearer gx_..." \
  -H "Content-Type: application/json" \
  -d '{
    "grantId": "grnt_01HXYZ...",
    "dataPrincipalId": "user_abc123",
    "purposes": [
      { "code": "analytics", "description": "Usage analytics for service improvement" },
      { "code": "personalization", "description": "Personalized recommendations" }
    ],
    "consentNoticeId": "notice_v2",
    "processingExpiresAt": "2027-01-01T00:00:00.000Z"
  }'

​
Response — 201 Created

{
  "recordId": "cr_01HXYZ...",
  "grantId": "grnt_01HXYZ...",
  "dataPrincipalId": "user_abc123",
  "consentNoticeHash": "a1b2c3d4e5f6...",
  "consentProof": {
    "type": "Ed25519Signature2020",
    "proofJwt": "eyJ...",
    "signedAt": "2026-04-05T12:00:00.000Z"
  },
  "processingExpiresAt": "2027-01-01T00:00:00.000Z",
  "retentionUntil": "2027-01-31T00:00:00.000Z",
  "status": "active",
  "createdAt": "2026-04-05T12:00:00.000Z"
}

​
Response Fields

FieldTypeDescription
recordIdstringUnique consent record ID
grantIdstringThe grant this consent is attached to
dataPrincipalIdstringThe data principal who gave consent
consentNoticeHashstringSHA-256 hash of the consent notice content
consentProofobjectCryptographic proof of consent (Ed25519 signature or none if key unavailable)
processingExpiresAtstringISO-8601 timestamp when processing permission expires
retentionUntilstringISO-8601 timestamp for data retention limit (30 days after processing expiry)
statusstringRecord status: active
createdAtstringISO-8601 creation timestamp

​
Error Responses

StatusCodeDescription
400BAD_REQUESTMissing required fields
400INVALID_GRANTGrant not found or not owned by developer
400INVALID_NOTICEConsent notice not found
401UNAUTHORIZEDInvalid or missing API key

​
SDK Examples

import Grantex from '@grantex/sdk';

const grantex = new Grantex({ apiKey: 'gx_...' });

const record = await grantex.dpdp.createConsentRecord({
  grantId: 'grnt_01HXYZ...',
  dataPrincipalId: 'user_abc123',
  purposes: [
    { code: 'analytics', description: 'Usage analytics' },
  ],
  consentNoticeId: 'notice_v2',
  processingExpiresAt: '2027-01-01T00:00:00.000Z',
});