TracePass
Access grants

Create an access grant

Give a recipient access to the restricted part of your passports, with the same rules as the dashboard: the role decides which data points the grant shows, a purchaser grant names the passports it covers and ends when the battery changes hands, and a company has at most 50 active grants.

POST/api/v1/access-grants
Download OpenAPI 3.1
POST/api/v1/access-grants

Create an access grant

Give a recipient access to the restricted part of your passports, with the same rules as the dashboard: the role decides which data points the grant shows, a purchaser grant names the passports it covers and ends when the battery changes hands, and a company has at most 50 active grants.

The raw pa_ token is returned once, in this 201, and never again. Only a hash is stored. Hand it to the recipient straight away and do not log it. An idempotent replay (same Idempotency-Key, same body) returns the grant without the token and with tokenDelivered: true, so the idempotency store never holds a credential. If the token is lost, revoke the grant and create a new one. The notice field says the same in the response.

Authority roles stay in the dashboard. market_surveillance, notified_body, commission and customs, and the authority tier on the other role, answer 400 role_dashboard_only. The access log records which API key or app created the grant.

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.

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

  • rolerequired

    string

    The recipient's role: repairer, remanufacturer, repurposer, recycler, waste_treatment, training_centre, purchaser, purchaser_agent, elv_treatment, weee_treatment or other. The four authority roles are refused.

  • labelrequired

    string (1-120 chars)

    Who the grant is for, as you want to see it.

  • scope

    object

    { "kind": "company" }, { "kind": "products", "ids": [...] } or { "kind": "passports", "ids": [...] } (up to 500 ids, all in your company). A purchaser grant must list passports.

  • purpose

    string (max 500 chars)

    Why the recipient gets access.

  • evidence

    object

    { type, reference, note? } where type is register_entry, invoice, authority_letter, contract or other. Recorded, not verified.

  • expiresInDays

    integer | null (1-1825)

    Days until expiry. Omit for the role's default (12 months; none for a purchaser, whose grant ends when the battery changes hands). null = no expiry.

Request

curl -sS -X POST https://app.tracepass.eu/api/v1/access-grants \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "role": "purchaser",
  "label": "Buyer GmbH, order 4711",
  "scope": { "kind": "passports", "ids": ["6650a1b2c3d4e5f6a7b8c9d0"] }
}'

Response

{
  "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",
  "token": "pa_REDACTED_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "notice": "Pass this token to the recipient now. It cannot be shown again: only a hash is stored, and neither the list nor an idempotent replay returns it."
}