TracePass
Access grants

List access grants

The company's access grants, newest first, by cursor. A grant is the credential a recipient (a buyer, a repairer, a recycler) uses to read the restricted part of a passport. The list never returns a token, nor any part of one.

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

List access grants

The company's access grants, newest first, by cursor. A grant is the credential a recipient (a buyer, a repairer, a recycler) uses to read the restricted part of a passport. The list never returns a token, nor any part of one.

Filters: role, status (active, expired, revoked), passportId (grants that cover that passport: company-wide, its product, or the passport itself) and productId (company-wide grants and grants scoped to that product). Pass the previous page's nextCursor as cursor; nextCursor is null on the last page.

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:read scope and an editor role or above.

Query parameters

  • role

    string

    Only grants of this role, e.g. purchaser.

  • status

    string (active | expired | revoked)

    Only grants in this state.

  • passportId

    string (24 hex chars)

    Only grants that cover this passport.

  • productId

    string (24 hex chars)

    Only company-wide grants and grants scoped to this product.

  • limit

    integer

    Page size, 1 to 100 (default 50).

  • cursor

    string (24 hex chars)

    The nextCursor of the previous page.

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

Request

curl -sS "https://app.tracepass.eu/api/v1/access-grants?status=active&role=purchaser" \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx"

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"
    }
  ],
  "nextCursor": null
}