TracePass
Autorizzazioni di accesso

Creare un'autorizzazione di accesso

Date a un destinatario accesso alla parte riservata dei vostri passaporti, con le stesse regole della dashboard: il ruolo decide quali punti dati mostra l'autorizzazione, un'autorizzazione da acquirente indica i passaporti che copre e termina quando la batteria cambia proprietario, e un'azienda ha al massimo 50 autorizzazioni attive.

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

Creare un'autorizzazione di accesso

Date a un destinatario accesso alla parte riservata dei vostri passaporti, con le stesse regole della dashboard: il ruolo decide quali punti dati mostra l'autorizzazione, un'autorizzazione da acquirente indica i passaporti che copre e termina quando la batteria cambia proprietario, e un'azienda ha al massimo 50 autorizzazioni attive.

Il token pa_ è restituito una sola volta, in questo 201, e mai più. Viene salvato solo un hash. Consegnatelo subito al destinatario e non registratelo nei log. Una ripetizione idempotente (stessa Idempotency-Key, stesso corpo) restituisce l'autorizzazione senza token e con tokenDelivered: true, così l'archivio di idempotenza non contiene mai una credenziale. Se il token è perso, revocate l'autorizzazione e createne una nuova. Il campo notice lo dice nella risposta.

I ruoli delle autorità restano nella dashboard. market_surveillance, notified_body, commission e customs, e il livello authority sul ruolo other, rispondono 400 role_dashboard_only. Il registro degli accessi annota quale chiave API o app ha creato l'autorizzazione.

Chi può chiamarlo. Una chiave API solo se il suo titolare ha attivato «May manage access grants» per quella chiave nella pagina Developer (disattivato per impostazione predefinita; altrimenti 403 access_grants_not_enabled). Un token OAuth richiede lo scope access_grants:write e un utente admin o owner. Richiede un account a pagamento. Conta come una scrittura v1.

Header

  • Authorizationobbligatorio

    string

    Bearer <token> — una chiave API tp_ (Developer → API Keys; più semplice, per server-to-server) oppure un access token OAuth 2.0 (Developer → OAuth Apps; per app autorizzate dall'utente, scoped e revocabili). La pagina Authentication contiene il flusso OAuth completo e l'elenco degli scopes.

    e.g. Bearer tp_REDACTED_xxxxxxxxxxxx

  • Idempotency-Key

    string

    UUID v4.

Campi del corpo

  • roleobbligatorio

    string

    Il ruolo del destinatario: repairer, remanufacturer, repurposer, recycler, waste_treatment, training_centre, purchaser, purchaser_agent, elv_treatment, weee_treatment oppure other. I quattro ruoli delle autorità sono rifiutati.

  • labelobbligatorio

    string (1-120 chars)

    Per chi è l'autorizzazione, come desiderate vederla.

  • scope

    object

    { "kind": "company" }, { "kind": "products", "ids": [...] } oppure { "kind": "passports", "ids": [...] } (fino a 500 id, tutti nella vostra azienda). Un'autorizzazione da acquirente deve elencare passaporti.

  • purpose

    string (max 500 chars)

    Perché il destinatario ottiene l'accesso.

  • evidence

    object

    { type, reference, note? }, dove type è register_entry, invoice, authority_letter, contract oppure other. Registrata, non verificata.

  • expiresInDays

    integer | null (1-1825)

    Giorni alla scadenza. Omettere per il valore predefinito del ruolo (12 mesi; nessuno per un acquirente, la cui autorizzazione termina al cambio di proprietà). null = nessuna scadenza.

Richiesta

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

Risposta

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