TracePass
Reference

Access grants

Share restricted passport data with a buyer, repairer or recycler and revoke it again: create, list, change, revoke, and the access log.

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.

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.

GET/api/v1/access-grants/{id}

Read an access grant

One grant of your company, live, expired or revoked. The `state` field says which. The response never carries the token or any part of it.

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`.

DELETE/api/v1/access-grants/{id}

Revoke an access grant

Revoke a grant: its token stops working at once. Idempotent: revoking a grant that is already revoked answers `200` with it again. Only an id that is not your company's answers `404`. An authority grant (an authority role or the authority tier) can only be revoked in the dashboard: through the API it answers `400 role_dashboard_only`.

GET/api/v1/access-grants/{id}/activity

Access log of a grant

The grant's log rows, newest first, by cursor. Grant events (`grant_created`, `grant_changed`, `grant_revoked`) name who acted: `via` is the API key (by its label) or the OAuth app, and is `null` for the dashboard; `actorId` is the user it acted for. `read` rows carry one count per passport, channel and day.