/api/v1/access-grantsCreare 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 APItp_(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_treatmentoppureother. 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? }, dovetypeèregister_entry,invoice,authority_letter,contractoppureother. 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."
}