Endpoint
GET /v1/dpdp/data-principals/:principalId/records
Authentication
Requires a developer API key in the Authorization header.
| Header | Value |
|---|
Authorization | Bearer <api_key> |
Path Parameters
| Parameter | Type | Required | Description |
|---|
principalId | string | Yes | The data principal ID |
Example Request
curl https://grantex-auth-dd4mtrt2gq-uc.a.run.app/v1/dpdp/data-principals/user_abc123/records \
-H "Authorization: Bearer gx_..."
Response — 200 OK
{
"dataPrincipalId": "user_abc123",
"records": [
{
"recordId": "cr_01HXYZ...",
"grantId": "grnt_01HXYZ...",
"dataFiduciaryName": "Acme Corp",
"purposes": [
{ "code": "analytics", "description": "Usage analytics" }
],
"scopes": ["calendar:read"],
"consentNoticeId": "notice_v2",
"status": "active",
"consentGivenAt": "2026-04-05T12:00:00.000Z",
"processingExpiresAt": "2027-01-01T00:00:00.000Z",
"retentionUntil": "2027-01-31T00:00:00.000Z",
"accessCount": 3,
"lastAccessedAt": "2026-04-05T14:00:00.000Z",
"withdrawnAt": null,
"withdrawnReason": null,
"createdAt": "2026-04-05T12:00:00.000Z"
}
],
"totalRecords": 1
}
Response Fields
| Field | Type | Description |
|---|
dataPrincipalId | string | The data principal ID |
records | object[] | Array of consent record objects |
totalRecords | number | Total number of records |
Record Object
| Field | Type | Description |
|---|
recordId | string | Unique consent record ID |
grantId | string | The associated grant ID |
dataFiduciaryName | string | Name of the data fiduciary (developer) |
purposes | object[] | Array of purpose objects ({ code, description }) |
scopes | string[] | Scopes from the associated grant |
consentNoticeId | string | ID of the consent notice |
status | string | Record status: active, withdrawn, expired, or erased |
consentGivenAt | string | ISO-8601 timestamp of original consent |
processingExpiresAt | string | ISO-8601 processing expiry timestamp |
retentionUntil | string | ISO-8601 data retention limit |
accessCount | number | Number of times this record has been accessed (incremented on each call) |
lastAccessedAt | string | ISO-8601 timestamp of last access |
withdrawnAt | string | null | ISO-8601 timestamp of withdrawal (if withdrawn) |
withdrawnReason | string | null | Reason for withdrawal (if withdrawn) |
createdAt | string | ISO-8601 creation timestamp |
Each call to this endpoint increments the accessCount on all returned records, providing a built-in audit trail of data access for DPDP compliance.
Error Responses
| Status | Code | Description |
|---|
| 401 | UNAUTHORIZED | Invalid or missing API key |
SDK Examples
import Grantex from '@grantex/sdk';
const grantex = new Grantex({ apiKey: 'gx_...' });
const { records, totalRecords } = await grantex.dpdp.listPrincipalRecords('user_abc123');
