Verifica un messaggio

Controlla un blocco firma oppure chiave, messaggio e firma espliciti. Questa POST legge soltanto.

POST/v1/verify

Accesso: Pubblico; chiave API facoltativa
Client: Fetch dal browser supportato

Corpo JSON#

Nome	Posizione	Significato
`block`	JSON	Blocco firma completo come incollato. Al massimo 32768 caratteri.
`at`	JSON	Secondi Unix facoltativi. Il default è adesso. Usa un orario di pubblicazione fidato.
`key, message, signature`	JSON	Modalità esplicita al posto di block. Ed25519 usa hex, chiavi e firme composite usano base64. message è il testo UTF-8 esatto.
`platform, subject`	JSON	Coppia facoltativa nella modalità esplicita per controllare il possesso dell’account al momento scelto.

Esempi di richiesta#

javascript

const headers = new Headers();
headers.set("Content-Type", "application/json");
const response = await fetch("https://veil.rip/v1/verify", {
  method: "POST",
  headers,
  credentials: "omit",
  body: JSON.stringify({ block })
});
const verdict = await response.json();

Prova la richiesta#

Blocco firma

Il controllo qui manda il messaggio a Veil. Usa /verify per un controllo che resta nel browser.

Risposta#

HTTP 200application/json

valid è il verdetto complessivo. signatureOk, identity, device, keyState, account e reason lo spiegano. La modalità block restituisce anche il blocco letto e la chiave trovata.

Campo	Tipo	Significato
`valid`	`boolean`	Verdetto complessivo su firma, stato della chiave ed eventuale titolarità dell’account. HTTP 200 comprende anche `valid=false`.
`signatureOk`	`boolean`	Indica se la firma crittografica è valida.
`identity`	`IdentityRef \| null`	Scheda associata alla chiave o indicata dal blocco, se nota.
`device`	`string \| null`	Dispositivo di firma, se identificato.
`role`	`string \| null`	Ruolo di firma, se identificato.
`keyState`	`KeyState \| null`	Validità della chiave nell’istante richiesto.
`account`	`object \| null`	platform, subject, owned e reason quando sono stati richiesti platform/subject.
`reason`	`string \| null`	Null quando valida. Altrimenti bad_signature, unknown_key, not_yet_valid, revoked, key_banned, identity_banned, not_linked, pending_takeover, identity_erased o unknown_identity. Sono motivi del verdetto, non codici di errore HTTP.
`key`	`string, optional`	Chiave pubblica corrispondente in modalità blocco; omessa se nessuna chiave corrisponde.
`block`	`object, optional`	Blocco interpretato con n, url, message, alg, lang, quoted e flattened.

Esempio di risposta

Valori illustrativi. Leggi la risposta corrente della tua richiesta.

json

{
  "valid": false,
  "signatureOk": true,
  "identity": null,
  "device": null,
  "role": null,
  "keyState": null,
  "account": null,
  "reason": "unknown_key"
}

Apri un oggetto annidato per leggerne i campi. I tipi con null ammettono un valore null; i campi optional possono essere assenti. Gli altri campi sono presenti nell’oggetto.

Riferimento alla scheda IdentityRef

Campo	Tipo	Significato
`n`	`integer`	Numero permanente della scheda.
`url`	`string`	URL permanente della scheda.
`name`	`string`	Nome visualizzato corrente.
`nameHidden`	`boolean`	Indica se lo staff nasconde il nome.

Stato della chiave in un istante KeyState

Campo	Tipo	Significato
`at`	`integer`	Istante controllato, in secondi Unix.
`active`	`boolean`	Indica se la chiave era attiva in quell’istante.
`reason`	`string`	active, not_yet_valid o revoked.
`validFrom`	`string`	Data e ora di pubblicazione della versione che l’ha aggiunta.
`validUntil`	`string \| null`	Data e ora di pubblicazione della revoca, oppure null.

Intestazioni della risposta#

Intestazione	Valore	Significato
`Content-Type`	`application/json`	Usa il tipo dichiarato per scegliere come leggere il corpo.
`Date`	`HTTP date`	Ora del server. Confrontala con il tuo orologio per firmare le richieste.
`Retry-After`	`integer seconds, on rate_limited or busy`	Attendi almeno questo intervallo prima di riprovare. Altri codici 429/503 non lo includono necessariamente.

Cosa verificare#

Questo è il verdetto del server. Per una verifica indipendente, controlla la prova della scheda e verifica localmente la firma.

Note d’uso#

block si combina soltanto con at. Usa la forma con key, message e signature per includere platform e subject. Non servono intestazioni di firma della richiesta.
Per un file o un rilascio, lo stesso percorso prende una firma con gli hash del file o un elenco di checksum: vedi Verifica un file o un rilascio.

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_block`	Il blocco firma non è leggibile o indica un’altra rubrica. Incolla il blocco completo con il messaggio e usa la rubrica che indica.
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.
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.

Quando usi una chiave API facoltativa

HTTP	Codice	Significato e cosa fare
401	`invalid_api_key`	La credenziale Bearer è malformata, sconosciuta, scaduta o revocata. Usa una chiave attiva. Per l’accesso pubblico anonimo, rimuovi del tutto `Authorization`. Credenziali non valide non attivano automaticamente l’accesso anonimo.
403	`api_key_scope`	La chiave API non ha il permesso read o verify, oppure l’endpoint non accetta chiavi Bearer. Usa il permesso corretto. Le modifiche alle schede e la gestione delle chiavi richiedono una firma del dispositivo.
403	`api_key_suspended`	Questa chiave API è sospesa. Chiedi allo staff di ripristinarla; un’altra chiave non rimuove la sospensione dell’account.
403	`developer_suspended`	L’account API del titolare è sospeso oppure la scheda titolare non è disponibile. Controlla l’account titolare e le restrizioni dello staff. Creare un’altra chiave non aggira la sospensione.

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