/api/v1/access-grants/{id}Change an access grant
Change a live grant's label, purpose, evidence, expiry or scope. Send only the keys you want to change, and at least one. The role cannot be changed: revoke the grant and create a new one. An authority grant (an authority role or the authority tier) can only be changed in the dashboard: through the API it answers 400 role_dashboard_only.
Moving an expired grant's expiry forward makes it active again, and the cap of 50 active grants applies as it does on creation. A revoked grant answers 404. The change is written to the grant's access log with the API key or app that made it.
Who may call it. An API key only when its owner switched on "May manage access grants" for that key on the Developer page (off by default; otherwise 403 access_grants_not_enabled). An OAuth token needs the access_grants:write scope and a user who is an admin or owner. Needs a paying account. Counts as one v1 write. Honours Idempotency-Key.
Path parameters
- idrequired
string (24 hex chars)
Access grant ID.
Headers
- Authorizationrequired
string
Bearer <token>— either atp_API key (Developer → API Keys; simplest, for server-to-server) or an OAuth 2.0 access token (Developer → OAuth Apps; for user-authorized apps, scoped + revocable). The Authentication page has the full OAuth flow and scope list.e.g. Bearer tp_REDACTED_xxxxxxxxxxxx
- Idempotency-Key
string
UUID v4.
Body fields
- label
string (1-120 chars)
New label.
- purpose
string (max 500 chars)
New purpose.
- scope
object
New scope, same shape as on creation. A purchaser grant must stay on passports.
- evidence
object
New evidence
{ type, reference, note? }. - expiresInDays
integer | null (1-1825)
Days from now until expiry;
null= no expiry.
Request
curl -sS -X PATCH https://app.tracepass.eu/api/v1/access-grants/6650c1d2e3f4a5b6c7d8e9f0 \
-H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "expiresInDays": 90 }'Response
{
"data": {
"id": "6650c1d2e3f4a5b6c7d8e9f0",
"accessLevel": "restricted",
"label": "Buyer GmbH, order 4711",
"role": "purchaser",
"scope": { "kind": "passports", "ids": ["6650a1b2c3d4e5f6a7b8c9d0"] },
"purpose": null,
"evidence": null,
"state": "active",
"expiresAt": null,
"useCount": 0,
"createdAt": "2026-06-01T09:30:00.000Z"
}
}