Accedi: il consenso firmato

Il testo del consenso firmato da una chiave di dispositivo attiva della scheda di una persona. Il server lo controlla con la scheda e la sua versione nel registro verificato, tiene l'accesso e dà il codice.

POST/oidc/requests/{id}/consent

Accesso: Serve un codice privato
Client: Client locale o server

Parametri#

Nome	Posizione	Significato
`id`Obbligatorio	Percorso	L'id della richiesta: 43 caratteri dall'indirizzo della pagina di consenso (`?req=`) o dal suo elemento meta.

Corpo JSON#

Nome	Posizione	Significato
`consent`Obbligatorio	JSON	veil-rubrica:oidc-consent:v1, a capo, poi il JSON canonico {card, challenge, client, iss, key, nonce, redirect, request, scopes, state, time, v: 1}.
`signature`Obbligatorio	JSON	La firma della chiave di dispositivo sui byte UTF-8 esatti di consent (hex per Ed25519).

Esempi di richiesta#

cURL

curl -fsS --json @consent.json "https://veil.rip/oidc/requests/$REQUEST_ID/consent"

Risposta#

HTTP 200application/json

{redirect, login, version, log}: il browser va a redirect.

Campo	Tipo	Significato
`redirect`	`string`	redirect_uri con code, state e iss.
`login`	`integer`	L'id dell'accesso (sid l<id> nel token ID).
`version`	`integer`	La versione della scheda con cui l'accesso è stato controllato.
`log`	`object`	{origin, index, size, root}: la voce della versione e il checkpoint verificato.

Intestazioni della risposta#

Intestazione	Valore	Significato
`Content-Type`	`application/json`	JSON, anche per gli errori.
`Cache-Control`	`no-store`	Privata: mai in una cache.

Note d’uso#

time sono secondi Unix entro due minuti dall'ora del server. Una richiesta prende un solo consenso; la stessa firma ripetuta risponde 410.

Errori#

Gli errori API restituiscono un oggetto error. Usa error.code nella logica del programma; error.message è un testo inglese per le persone e può cambiare. Guida a risposte ed errori

HTTP	Codice	Significato e cosa fare
400	`invalid_json`	Il corpo non è un oggetto JSON, contiene chiavi duplicate o dati finali. Invia un solo oggetto JSON valido con `Content-Type` application/json.
400	`invalid_parameter`	Un campo del percorso, della query o del corpo manca, è malformato o fuori intervallo. Correggi il campo indicato in `error.message` prima di inviare di nuovo.
401	`invalid_signature`	La firma della richiesta HTTP non è valida. Firma metodo, percorso e byte del corpo esatti, senza modificarli dopo.
401	`stale_timestamp`	Il timestamp firmato è fuori dalla finestra temporale ammessa. Confronta l’intestazione Date del server con il tuo orologio, poi genera nuovi nonce, timestamp e firma.
403	`key_banned`	La chiave del dispositivo che firma è sospesa dallo staff di Veil. Usa una chiave attiva autorizzata o chiedi allo staff di riesaminare la restrizione.
403	`key_mismatch`	La chiave di firma non è autorizzata per questa scheda o operazione. Usa una chiave di dispositivo attiva con il ruolo di titolare o membro richiesto.
403	`veil_suspended`	La scheda è sospesa dallo staff di Veil, quindi non accede alle app. Non c'è niente da riprovare finché dura la sospensione.
404	`not_found`	La scheda, la chiave, l’alias, il codice o la risorsa richiesti non sono stati trovati. Controlla l’identificatore. Codici e anteprime temporanei potrebbero essere scaduti o già usati.
410	`erased`	La scheda esisteva ed è stata cancellata o rimossa. La risposta contiene anche la ricevuta pubblica di cancellazione. Smetti di usare questa scheda come autorità corrente. Conserva soltanto la ricevuta pubblica se serve.
410	`request_expired`	La richiesta di accesso è già stata usata o ha più di 30 minuti. Torna all'app e ricomincia.
413	`payload_too_large`	Il corpo della richiesta supera il limite in byte dell’endpoint. Riduci il corpo codificato. La gestione delle chiavi API ammette al massimo 8 KiB.
422	`invalid_consent`	Il testo del consenso non è quello che questa richiesta vuole: un campo è diverso, manca o è in più, oppure il JSON non è canonico. Costruisci il testo da GET /oidc/requests/{id} così com'è, poi firmalo.
503	`log_unavailable`	Al momento il registro pubblico non può essere letto, verificato o usato per pubblicare. Per le letture, considera il risultato non verificato e riprova più tardi. Prima di ripetere una scrittura, leggi la scheda per controllare se la pubblicazione è terminata.

Errori comuni delle richieste

HTTP Codice Significato e cosa fare

429

HTTP	Codice	Significato e cosa fare
429	`rate_limited`	È stato superato un limite anonimo, delle richieste firmate o della chiave API. Attendi almeno i secondi indicati da `Retry-After`. Condividi coda e budget dei tentativi tra i tuoi processi.
500	`internal_error`	Si è verificato un errore imprevisto del server. I dettagli interni non vengono restituiti. Riprova le letture con attese crescenti e un limite. Controlla l’esito delle scritture prima di inviare una nuova operazione firmata.
503	`busy`	L’applicazione ha raggiunto un limite temporaneo di concorrenza o del database. Attendi i secondi indicati da `Retry-After` e riprova con attese crescenti e un limite.

rate_limited

È stato superato un limite anonimo, delle richieste firmate o della chiave API.

Attendi almeno i secondi indicati da Retry-After. Condividi coda e budget dei tentativi tra i tuoi processi.

500

internal_error

Si è verificato un errore imprevisto del server. I dettagli interni non vengono restituiti.

Riprova le letture con attese crescenti e un limite. Controlla l’esito delle scritture prima di inviare una nuova operazione firmata.

503

busy

L’applicazione ha raggiunto un limite temporaneo di concorrenza o del database.

Attendi i secondi indicati da Retry-After e riprova con attese crescenti e un limite.

Leggi questa voce in JSON