{"revision":"0ed62d2c742f8e20","language":"it","entry":{"id":"verify-message","kind":"endpoint","group":"keys","title":"Verifica un messaggio","method":"POST","path":"/v1/verify","paths":[],"summary":"Controlla un blocco firma oppure chiave, messaggio e firma espliciti. Questa POST legge soltanto.","response":"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.","parameters":[],"sample":"/v1/verify","access":"public","base":"directory","notes":["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."],"errors":["400 invalid_block","400 invalid_json","400 invalid_parameter","401 invalid_api_key","403 api_key_scope","403 api_key_suspended","403 developer_suspended","413 payload_too_large","429 rate_limited","500 internal_error","503 busy"],"related":["message-verification","proofs","verify-file"],"sections":[{"kind":"code","language":"javascript","code":"const headers = new Headers();\nheaders.set(\"Content-Type\", \"application/json\");\nconst response = await fetch(\"https://veil.rip/v1/verify\", {\n  method: \"POST\",\n  headers,\n  credentials: \"omit\",\n  body: JSON.stringify({ block })\n});\nconst verdict = await response.json();"},{"kind":"verify-form"}],"verify":"Questo è il verdetto del server. Per una verifica indipendente, controlla la prova della scheda e verifica localmente la firma.","bodyFields":[{"name":"block","description":"Blocco firma completo come incollato. Al massimo 32768 caratteri.","in":"body","required":false},{"name":"at","description":"Secondi Unix facoltativi. Il default è adesso. Usa un orario di pubblicazione fidato.","in":"body","required":false},{"name":"key, message, signature","description":"Modalità esplicita al posto di block. Ed25519 usa hex, chiavi e firme composite usano base64. message è il testo UTF-8 esatto.","in":"body","required":false},{"name":"platform, subject","description":"Coppia facoltativa nella modalità esplicita per controllare il possesso dell’account al momento scelto.","in":"body","required":false}],"live":false,"responses":[{"status":200,"contentType":"application/json","description":"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.","fields":[{"name":"valid","type":"boolean","description":"Verdetto complessivo su firma, stato della chiave ed eventuale titolarità dell’account. HTTP 200 comprende anche `valid=false`."},{"name":"signatureOk","type":"boolean","description":"Indica se la firma crittografica è valida."},{"name":"identity","type":"IdentityRef | null","description":"Scheda associata alla chiave o indicata dal blocco, se nota."},{"name":"device","type":"string | null","description":"Dispositivo di firma, se identificato."},{"name":"role","type":"string | null","description":"Ruolo di firma, se identificato."},{"name":"keyState","type":"KeyState | null","description":"Validità della chiave nell’istante richiesto."},{"name":"account","type":"object | null","description":"platform, subject, owned e reason quando sono stati richiesti platform/subject."},{"name":"reason","type":"string | null","description":"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."},{"name":"key","type":"string, optional","description":"Chiave pubblica corrispondente in modalità blocco; omessa se nessuna chiave corrisponde."},{"name":"block","type":"object, optional","description":"Blocco interpretato con n, url, message, alg, lang, quoted e flattened."}],"example":{"language":"json","code":"{\n  \"valid\": false,\n  \"signatureOk\": true,\n  \"identity\": null,\n  \"device\": null,\n  \"role\": null,\n  \"keyState\": null,\n  \"account\": null,\n  \"reason\": \"unknown_key\"\n}"}}],"responseObjects":[{"id":"key-ref","title":"Riferimento alla scheda","fields":[{"name":"n","type":"integer","description":"Numero permanente della scheda."},{"name":"url","type":"string","description":"URL permanente della scheda."},{"name":"name","type":"string","description":"Nome visualizzato corrente."},{"name":"nameHidden","type":"boolean","description":"Indica se lo staff nasconde il nome."}],"typeName":"IdentityRef"},{"id":"key-state","title":"Stato della chiave in un istante","fields":[{"name":"at","type":"integer","description":"Istante controllato, in secondi Unix."},{"name":"active","type":"boolean","description":"Indica se la chiave era attiva in quell’istante."},{"name":"reason","type":"string","description":"active, not_yet_valid o revoked."},{"name":"validFrom","type":"string","description":"Data e ora di pubblicazione della versione che l’ha aggiunta."},{"name":"validUntil","type":"string | null","description":"Data e ora di pubblicazione della revoca, oppure null."}],"typeName":"KeyState"}],"errorFormat":"json","errorDetails":[{"status":400,"code":"invalid_block","description":"Il blocco firma non è leggibile o indica un’altra rubrica.","action":"Incolla il blocco completo con il messaggio e usa la rubrica che indica.","scope":"endpoint"},{"status":400,"code":"invalid_json","description":"Il corpo non è un oggetto JSON, contiene chiavi duplicate o dati finali.","action":"Invia un solo oggetto JSON valido con `Content-Type` application/json.","scope":"endpoint"},{"status":400,"code":"invalid_parameter","description":"Un campo del percorso, della query o del corpo manca, è malformato o fuori intervallo.","action":"Correggi il campo indicato in `error.message` prima di inviare di nuovo.","scope":"endpoint"},{"status":401,"code":"invalid_api_key","description":"La credenziale Bearer è malformata, sconosciuta, scaduta o revocata.","action":"Usa una chiave attiva. Per l’accesso pubblico anonimo, rimuovi del tutto `Authorization`. Credenziali non valide non attivano automaticamente l’accesso anonimo.","scope":"optional-api-key"},{"status":403,"code":"api_key_scope","description":"La chiave API non ha il permesso read o verify, oppure l’endpoint non accetta chiavi Bearer.","action":"Usa il permesso corretto. Le modifiche alle schede e la gestione delle chiavi richiedono una firma del dispositivo.","scope":"optional-api-key"},{"status":403,"code":"api_key_suspended","description":"Questa chiave API è sospesa.","action":"Chiedi allo staff di ripristinarla; un’altra chiave non rimuove la sospensione dell’account.","scope":"optional-api-key"},{"status":403,"code":"developer_suspended","description":"L’account API del titolare è sospeso oppure la scheda titolare non è disponibile.","action":"Controlla l’account titolare e le restrizioni dello staff. Creare un’altra chiave non aggira la sospensione.","scope":"optional-api-key"},{"status":413,"code":"payload_too_large","description":"Il corpo della richiesta supera il limite in byte dell’endpoint.","action":"Riduci il corpo codificato. La gestione delle chiavi API ammette al massimo 8 KiB.","scope":"endpoint"},{"status":429,"code":"rate_limited","description":"È stato superato un limite anonimo, delle richieste firmate o della chiave API.","action":"Attendi almeno i secondi indicati da `Retry-After`. Condividi coda e budget dei tentativi tra i tuoi processi.","scope":"common"},{"status":500,"code":"internal_error","description":"Si è verificato un errore imprevisto del server. I dettagli interni non vengono restituiti.","action":"Riprova le letture con attese crescenti e un limite. Controlla l’esito delle scritture prima di inviare una nuova operazione firmata.","scope":"common"},{"status":503,"code":"busy","description":"L’applicazione ha raggiunto un limite temporaneo di concorrenza o del database.","action":"Attendi i secondi indicati da `Retry-After` e riprova con attese crescenti e un limite.","scope":"common"}],"responseHeaders":[{"name":"Content-Type","value":"application/json","description":"Usa il tipo dichiarato per scegliere come leggere il corpo."},{"name":"Date","value":"HTTP date","description":"Ora del server. Confrontala con il tuo orologio per firmare le richieste."},{"name":"Retry-After","value":"integer seconds, on rate_limited or busy","description":"Attendi almeno questo intervallo prima di riprovare. Altri codici 429/503 non lo includono necessariamente."}],"documentationUrl":"https://veil.rip/docs/verify-message?lang=it","supportsBrowserFetch":true,"browserMode":"fetch"}}