Pubblica la versione successiva di un’organizzazione

Pubblica una modifica autorizzata da un proprietario o amministratore accettato. Restano valide le regole dei ruoli.

POST/v1/organizations/{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/organizations/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.

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	`authority_limit`	Su un registro in formato 2 la versione lascerebbe più di 1.024 membri nell’autorità di un’organizzazione: proprietari e amministratori, o ogni ruolo dello staff nell’organizzazione Veil. Togli prima un proprietario o un amministratore. Anche una rimozione nella stessa versione libera un posto.
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	`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	`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	`members_limit`	Su un registro in formato 2 un invito porterebbe un’organizzazione oltre 100.000 membri e inviti in vigore. Togli dei membri o ritira degli inviti prima di invitare ancora.
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_an_organization`	La scheda è una persona dove è richiesta un’organizzazione. Usa l’endpoint delle persone oppure la scheda di un’organizzazione.
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