Pubblica la versione successiva di una persona

Modifica chiavi, account collegati, alias o altri campi firmati della scheda.

POST/v1/identities/{n}/versions

Accesso: Richiesta firmata
Client: Client locale o server

Parametri#

Nome	Posizione	Significato
`n`Obbligatorio	Percorso	Numero permanente positivo della scheda.

Corpo JSON#

Nome	Posizione	Significato
`record`Obbligatorio	JSON	Il record canonico completo della persona o organizzazione, inclusi i campi della storia.
`signature`Obbligatorio	JSON	La firma del record, distinta dall’intestazione di firma della richiesta.
`logoData`	JSON	L’immagine che record.logo nomina per hash, in base64 standard con padding su una riga. Obbligatorio quando la versione porta un’immagine nuova. Con un’immagine invariata si può omettere, e se arriva deve corrispondere.
`nonce`Obbligatorio	JSON	Un nonce nuovo da 16 a 128 caratteri con lettere, cifre, trattino basso o trattino.
`timestamp`Obbligatorio	JSON	Millisecondi Unix entro due minuti dall’orologio del server.
`label`	JSON	Formato 2: l’intestazione come oggetto JSON; il server la codifica in forma canonica e controlla la firma su quei byte.
`body`	JSON	Formato 2: il corpo come oggetto JSON, con il suo hash in label.body.
`pictureData`	JSON	Formato 2: i byte di una nuova immagine che il corpo nomina per hash, in base64 standard con padding.

Questa chiamata richiede anche le intestazioni comuni di firma, nonce e timestamp. Prepara e firma request.json prima di usare l’esempio. Firma delle richieste

Esempi di richiesta#

cURL

curl -fsS -X POST \
  -H "X-Public-Key: $PUBLIC_KEY" \
  -H "X-Signature: $REQUEST_SIGNATURE" --json @request.json \
  "https://veil.rip/v1/identities/1/versions"

Risposta#

HTTP 201application/json

201 con n, id, url, token, version, commitment, logIndex, publishedAt e checkpoint. La risposta segue la pubblicazione controfirmata.

Campo	Tipo	Significato
`n`	`integer`	Numero permanente della scheda.
`id`	`string`	Impegno della prima versione in hex.
`url`	`string`	URL permanente della scheda.
`token`	`string`	Pseudonimo stabile nel registro in base64url.
`version`	`integer`	Numero della versione pubblicata.
`commitment`	`string`	Impegno di questa versione in hex.
`logIndex`	`integer`	Indice nel registro a partire da zero.
`publishedAt`	`string`	Prima data e ora di controfirma alla pubblicazione.
`checkpoint`	`Checkpoint`	Primo checkpoint che copre la versione.

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.

Checkpoint Checkpoint

Campo	Tipo	Significato
`size`	`integer`	Numero di foglie nell’albero firmato.
`root`	`string`	Hash della radice in base64.
`note`	`string`	Nota firmata completa, incluse le firme del registro e dei testimoni.

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.
`Location`	`relative URL`	Indirizzo della scheda o prova pubblicata, oppure destinazione permanente del widget.
`Retry-After`	`integer seconds, on rate_limited or busy`	Attendi almeno questo intervallo prima di riprovare. Altri codici 429/503 non lo includono necessariamente.

Note d’uso#

Su un registro in formato 2 il corpo è {label, body, signature, pictureData?}, con clientSalt e saltTicket obbligatori per la versione 1; un record si rifiuta con wrong_format.
Dal 29 ottobre 2026 il corpo di una persona può portare addExternalKey {type, pub, fp, label, proof: {anchor, at, by, sig, variant?}} e removeExternalKey {fp}: chiavi pubbliche di altri sistemi con la loro prova di possesso. proof.variant dice la forma della sfida firmata quando non sono i byte offerti (crlf, bom, noeol e le loro combinazioni). La sfida e i controlli sono nella voce delle chiavi pubbliche di altri sistemi (external-keys-file) e in docs/formato-v2.md, sezione 4.

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_alias`	L’alias non rispetta le regole ASCII del nome. Usa da 3 a 32 lettere ASCII minuscole, cifre, trattini o trattini bassi; inizia con una lettera e termina con una lettera o cifra.
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_name`	Un nome contiene caratteri invisibili, controlli di direzione o caratteri di formato non ammessi. Usa un nome visibile nella forma Unicode ammessa e firma la richiesta corretta.
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.
400	`wrong_format`	La richiesta o la lettura appartiene all’altro formato del registro di questo server: un record v1 su un registro in formato 2, o una lettura del formato 2 su un registro in formato 1. Leggi `format` in GET /v1/log (assente vuol dire 1) e manda la forma di quel formato.
403	`identity_banned`	La scheda che agisce è sospesa dallo staff di Veil. Attendi la fine della restrizione o chiedi allo staff di riesaminarla.
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	`recovery_key_only`	Un’operazione riservata al recupero è stata firmata con un altro ruolo. Usa la chiave di recupero nel flusso documentato.
403	`role_not_allowed`	Il ruolo che firma non può eseguire questa modifica. Usa una chiave con il ruolo richiesto.
403	`signer_not_authorised`	Il membro dell’organizzazione o il ruolo di firma non può pubblicare questa modifica. Controlla l’affiliazione accettata e il ruolo richiesto per la modifica.
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.
409	`account_locked`	La moderazione impedisce di richiedere questo account. Controlla lo stato pubblico di moderazione della scheda corrente.
409	`alias_quarantined`	L’alias è nei 30 giorni di quarantena dopo il rilascio. Leggi `reusableAt` e il titolare precedente tramite l’endpoint degli alias.
409	`alias_reserved`	L’alias scelto è riservato al servizio. Scegli un altro alias.
409	`alias_taken`	L’alias è assegnato oppure riservato da una pubblicazione in corso. Scegli un altro alias oppure ricontrolla la disponibilità dopo la pubblicazione.
409	`already_member`	Questa affiliazione esiste già. Leggi le affiliazioni correnti prima di pubblicare un altro invito.
409	`erase_pending`	Su un registro in formato 2 la scheda ha una cancellazione in attesa. La sua chiusura firmata nomina la versione corrente, quindi la scheda non pubblica finché la cancellazione non è annullata. Annulla la cancellazione con POST /v1/identities/{n}/erase/cancel, poi pubblica la versione.
409	`grant_used`	Un grant di verifica o affiliazione è già stato usato. Controlla la versione risultante della scheda, poi ottieni un nuovo grant se serve ancora.
409	`invitation_withdrawn`	L’organizzazione non offre più l’invito. Chiedi un nuovo invito.
409	`key_already_used`	Una chiave del dispositivo appartiene già a un’identità e non può essere riusata da un’altra. Usa la scheda esistente oppure genera una nuova chiave del dispositivo.
409	`takeover_already_open`	Un subentro per questo account collegato è già aperto. Leggi il subentro in attesa invece di aprirne un altro.
409	`version_conflict`	La versione non può essere pubblicata rispetto allo stato corrente della scheda. Leggi la scheda più recente, riconcilia la modifica e firma una nuova versione.
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.
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	`cannot_revoke_self`	La revoca della propria chiave lascerebbe la scheda senza una chiave attiva, oppure la chiave di recupero viene revocata senza sostituirla. Mantieni un’altra chiave attiva. Sostituisci la chiave di recupero nella stessa versione che la revoca.
422	`external_limit`	La scheda terrebbe più di 16 chiavi pubbliche di altri sistemi, o un’operazione addExternalKey supera 16 KiB in JSON canonico. Togli prima una chiave. Anche una rimozione nella stessa versione libera un posto.
422	`grant_expired`	Il grant di verifica o affiliazione è scaduto. Ottieni un nuovo grant prima di pubblicare la versione.
422	`invalid_grant`	Il grant di verifica o affiliazione non è valido oppure appartiene a un’altra operazione. Usa il grant emesso per questa specifica scheda, account o affiliazione.
422	`invalid_logo`	L’immagine non supera i controlli su tipo, dimensione, risoluzione o contenuto. Correggi l’immagine secondo `error.message` prima di caricarla di nuovo.
422	`invalid_op`	Un’operazione è sconosciuta, malformata, non è del tipo o della versione della scheda, oppure non cambia niente. Correggi l’operazione indicata in `error.message`.
422	`invalid_record`	La versione dell’identità viola le regole del record firmato. Correggi il problema di convalida, rendi canonico il record e firmalo di nuovo.
422	`invalid_record_signature`	La firma della versione dell’identità non è valida. Firma il record canonico esatto con il prefisso identity-version e la chiave dichiarata.
422	`key_expired`	La chiave OpenPGP o la sua sottochiave di firma è scaduta. Prolungane la scadenza sul tuo computer (gpg --quick-set-expire), poi incolla di nuovo la chiave e firma una sfida nuova.
422	`key_extra_packets`	La chiave OpenPGP porta ancora una foto, la certificazione di un’altra persona o altro materiale che la scheda non tiene. Aggiungi la chiave dalla pagina della tua scheda, che tiene solo quello che una scheda porta: la chiave, le sue sottochiavi di firma e gli user ID che scegli.
422	`key_revoked`	La chiave OpenPGP porta una firma di revoca. Una chiave revocata non va su una scheda. Porta una chiave che usi ancora.
422	`key_unsupported`	Un tipo di chiave che Veil non tiene: chiavi SSH su chiave di sicurezza (sk-…), ECDSA P-521, certificati SSH, una chiave OpenPGP che non è di versione 4, o un algoritmo OpenPGP diverso da RSA, ECDSA P-256 o P-384 ed Ed25519. Usa uno dei tipi elencati: ssh-ed25519, ssh-ecdsa-p256, ssh-ecdsa-p384, ssh-rsa, pgp, minisign, ed25519, ml-dsa-44, ml-dsa-65, ml-dsa-87.
422	`key_weak`	RSA sotto 2048 bit o DSA, in SSH o in OpenPGP, un punto Ed25519 di ordine piccolo, o una firma RSA fatta con SHA-1 (ssh-rsa). Porta una chiave più forte. ssh-keygen -Y sign firma RSA con rsa-sha2-512 per impostazione predefinita.
422	`keys_limit`	Su un registro in formato 2 la versione lascerebbe a una persona più di 64 chiavi attive. Revoca prima una chiave. Anche una revoca nella stessa versione libera un posto.
422	`label_mismatch`	prev, body, auth o state dell’intestazione non sono quelli che danno la catena, il corpo e le operazioni. Rileggi la scheda, pianifica le operazioni sul suo stato corrente e firma la nuova intestazione.
422	`last_owner`	La modifica lascerebbe un’organizzazione senza un proprietario accettato. Aggiungi o accetta un altro proprietario prima di rimuovere l’ultimo.
422	`links_need_verification`	Un nuovo collegamento di account non ha un grant di verifica accettabile. Completa la prova dell’account prima di pubblicarne il collegamento.
422	`membership_needs_grant`	Un’affiliazione all’organizzazione non ha il grant di accettazione. Accetta l’invito e includi il grant nella prossima versione firmata.
422	`not_a_person`	La scheda è un’organizzazione dove è richiesta una persona. Usa l’endpoint delle organizzazioni oppure la scheda di una persona idonea.
422	`private_key_material`	Un testo di un’operazione addExternalKey contiene materiale privato: una chiave privata PEM o OpenSSH, un blocco privato PGP o un pacchetto di chiave segreta, una chiave segreta minisign, una chiave segreta Ed25519 di 64 byte, o il seme o la chiave segreta di ML-DSA. Non si salva niente e la risposta non ripete il testo. Considera quella chiave esposta e sostituiscila. Manda solo la chiave pubblica e la firma della sfida.
422	`proof_anchor`	Il checkpoint citato non è di questo registro, non ha la firma del registro o il quorum delle controfirme, o la sua radice non è quella del registro a quella taglia. Cita intera la nota del checkpoint controfirmato come la scheda la dà in index.checkpoint.note.
422	`proof_invalid`	La sfida nomina un’altra chiave di dispositivo di quella che firma la versione, o la firma non è la firma della chiave sulla sfida di questa scheda. Il messaggio dice la causa: un’altra chiave, un altro namespace SSH, un hash che non vale, la sfida salvata in UTF-16 o con una riga vuota dopo, un altro testo, o una forma diversa da quella che dice proof.variant. Firma di nuovo i byte esatti della sfida dal browser che pubblica la versione: con namespace veil per SSH, con una firma staccata o in chiaro del file per OpenPGP. Una copia salvata su Windows (CRLF, un BOM UTF-8, senza l’ultimo a capo) vale se proof.variant ne dice la forma.
422	`proof_stale`	Il checkpoint citato dalla sfida è stato controfirmato più di 7 giorni fa, o l’ora dichiarata at è più vecchia di 7 giorni o avanti rispetto all’orologio del server. Prepara una sfida nuova dall’ultimo checkpoint della scheda e firmala di nuovo.
502	`log_mismatch`	La risposta del registro non corrisponde alla voce firmata o alla prova attese. Non considerare verificata la pubblicazione. Controlla scheda e registro prima di riprovare.
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
400	`invalid_nonce`	Il nonce della richiesta firmata ha un formato errato. Genera un nuovo nonce da 16 a 128 caratteri usando lettere, cifre, _ o -.
400	`invalid_signature_alg`	`X-Signature-Alg` non è supportato. Usa un algoritmo di firma supportato e la codifica corretta per chiave e firma.
400	`invalid_timestamp`	Il timestamp della richiesta firmata non è espresso in millisecondi Unix. Usa un timestamp Unix intero in millisecondi e firma la richiesta corretta.
401	`invalid_signature`	La firma della richiesta HTTP non è valida. Firma metodo, percorso e byte del corpo esatti, senza modificarli dopo.
401	`missing_signature`	La richiesta richiede una firma del dispositivo e le intestazioni mancano o non sono leggibili. Invia `X-Public-Key`, `X-Signature` e i metadati della richiesta firmata. Una chiave API non sostituisce la firma del dispositivo.
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.
409	`replayed_nonce`	La chiave di firma ha già usato questo nonce. Controlla se la richiesta precedente è riuscita prima di crearne una nuova firmata.
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.

Leggi questa voce in JSON