TracePass
Zugangsberechtigungen

Zugangsberechtigung erstellen

Geben Sie einem Empfänger Zugriff auf den eingeschränkten Teil Ihrer Pässe, nach denselben Regeln wie im Dashboard: Die Rolle bestimmt, welche Datenpunkte die Berechtigung zeigt, eine Käufer-Berechtigung nennt die Pässe, die sie abdeckt, und endet beim Eigentümerwechsel der Batterie, und ein Unternehmen hat höchstens 50 aktive Berechtigungen.

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

Zugangsberechtigung erstellen

Geben Sie einem Empfänger Zugriff auf den eingeschränkten Teil Ihrer Pässe, nach denselben Regeln wie im Dashboard: Die Rolle bestimmt, welche Datenpunkte die Berechtigung zeigt, eine Käufer-Berechtigung nennt die Pässe, die sie abdeckt, und endet beim Eigentümerwechsel der Batterie, und ein Unternehmen hat höchstens 50 aktive Berechtigungen.

Das pa_-Token wird einmal in diesem 201 zurückgegeben und nie wieder. Gespeichert wird nur ein Hash. Geben Sie es sofort an den Empfänger weiter und protokollieren Sie es nicht. Eine idempotente Wiederholung (gleicher Idempotency-Key, gleicher Body) liefert die Berechtigung ohne Token und mit tokenDelivered: true, sodass der Idempotenz-Speicher nie ein Zugangsdatum enthält. Ist das Token verloren, widerrufen Sie die Berechtigung und erstellen eine neue. Das Feld notice sagt dasselbe in der Antwort.

Behörden-Rollen bleiben im Dashboard. market_surveillance, notified_body, commission und customs sowie die Stufe authority bei der Rolle other ergeben 400 role_dashboard_only. Das Zugriffsprotokoll hält fest, welcher API-Schlüssel oder welche App die Berechtigung erstellt hat.

Wer darf aufrufen. Ein API-Schlüssel nur, wenn sein Eigentümer „May manage access grants“ für diesen Schlüssel auf der Developer-Seite eingeschaltet hat (standardmäßig aus; sonst 403 access_grants_not_enabled). Ein OAuth-Token braucht den Scope access_grants:write und einen Admin- oder Owner-Nutzer. Erfordert ein zahlendes Konto. Zählt als ein v1-Schreibvorgang.

Header

  • Authorizationerforderlich

    string

    Bearer <token> — entweder ein tp_ API-Schlüssel (Developer → API Keys; am einfachsten, für Server-zu-Server) oder ein OAuth-2.0-Access-Token (Developer → OAuth Apps; für nutzerautorisierte Apps, scoped und widerrufbar). Die Authentication-Seite enthält den vollständigen OAuth-Flow und die Scope-Liste.

    e.g. Bearer tp_REDACTED_xxxxxxxxxxxx

  • Idempotency-Key

    string

    UUID v4.

Body-Felder

  • roleerforderlich

    string

    Die Rolle des Empfängers: repairer, remanufacturer, repurposer, recycler, waste_treatment, training_centre, purchaser, purchaser_agent, elv_treatment, weee_treatment oder other. Die vier Behörden-Rollen werden abgelehnt.

  • labelerforderlich

    string (1-120 chars)

    Für wen die Berechtigung ist, so wie Sie sie sehen möchten.

  • scope

    object

    { "kind": "company" }, { "kind": "products", "ids": [...] } oder { "kind": "passports", "ids": [...] } (bis zu 500 IDs, alle in Ihrem Unternehmen). Eine Käufer-Berechtigung muss Pässe auflisten.

  • purpose

    string (max 500 chars)

    Warum der Empfänger Zugriff erhält.

  • evidence

    object

    { type, reference, note? }, wobei type register_entry, invoice, authority_letter, contract oder other ist. Wird festgehalten, nicht geprüft.

  • expiresInDays

    integer | null (1-1825)

    Tage bis zum Ablauf. Weglassen für den Standard der Rolle (12 Monate; keiner für einen Käufer, dessen Berechtigung beim Eigentümerwechsel endet). null = kein Ablauf.

Anfrage

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"] }
}'

Antwort

{
  "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."
}