TracePass
Access grants

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.

PATCH/api/v1/access-grants/{id}
Download OpenAPI 3.1
PATCH/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 a tp_ 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"
  }
}