Leggi la scheda di un’organizzazione

Leggi un’organizzazione, il suo record firmato dei membri, i collegamenti pubblici e la prova.

GET/o/{card}.json

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

Altri indirizzi#

/o/{card}
/v1/organizations/{n}

Parametri#

Nome	Posizione	Significato
`card`Obbligatorio	Percorso	Il numero permanente o l’alias corrente della scheda.

Esempi di richiesta#

cURL

curl -fsS 'https://veil.rip/o/veil.json'

javascript

const response = await fetch("https://veil.rip/o/veil.json");
const result = await response.json();

Prova la richiesta#

Risposta#

HTTP 200application/json

La scheda ha tipo organizzazione, membri, logo, record firmato e prova. Un invito in attesa non significa che il membro abbia accettato.

Campo	Tipo	Significato
`n`	`integer`	Numero permanente della scheda.
`url`	`string`	URL permanente con il numero della scheda.
`name`	`string`	Nome visualizzato corrente; un nome nascosto diventa Card seguito dal numero.
`initials`	`string`	Iniziali da mostrare in assenza di un’immagine.
`since`	`string`	Data della prima versione in YYYY-MM-DD UTC.
`id`	`string`	Impegno della prima versione in hex, da cui deriva l’impronta.
`idSalt`	`object \| null`	Metà server e client del sale in hex. client può essere null.
`token`	`string`	Pseudonimo stabile nel registro pubblico in base64url.
`version`	`integer`	Versione pubblicata corrente.
`keys`	`array<CardKey>`	Tutte le chiavi dei dispositivi e di recupero, incluse quelle revocate.
`links`	`array<CardLink>`	Account collegati e subentri in attesa.
`orgs`	`array<CardOrg>`	Affiliazioni accettate alle organizzazioni di una persona.
`events`	`array<CardEvent>`	Pagina più recente della storia, ordinata al suo interno dalla più vecchia.
`witnesses`	`object \| null`	Conteggi signed, of e needed per la versione corrente. Sono controlli del server.
`nodes`	`integer \| null`	Numero di hash nel percorso di inclusione corrente.
`fingerprint`	`Fingerprint`	Dodici parole per lingua e dodici gruppi di cinque cifre.
`proof`	`CardProof \| null`	Apertura e prova di inclusione correnti. Null indica che non è stato possibile verificare il registro; non considerarla verificata.
`erasure`	`object \| null`	requestedAt ed executesAt di una cancellazione in attesa.
`type`	`string`	person o organization.
`members`	`array<CardMember>, optional`	Presente per un’organizzazione, inclusi gli inviti in attesa.
`moderation`	`object \| null`	Stato e azioni pubbliche di moderazione.
`eventsTotal`	`integer`	Totale degli eventi della storia in tutte le pagine.
`historyBefore`	`integer \| null`	Passalo come before all’endpoint della storia per leggere la pagina precedente.
`badges`	`array<object>`	Badge attivi firmati o derivati.
`nameHidden`	`object \| null`	Motivo pubblico, since e logIndex del nome nascosto.
`logo`	`object, optional`	Tipo e URL dell’immagine; omesso in assenza di un’immagine visibile.
`logoHidden`	`object, optional`	Motivo pubblico del logo nascosto.
`alias`	`string \| null`	Alias corrente, che può cambiare.
`aliasUrl`	`string \| null`	Indirizzo dell’alias corrente. Usa n come identificatore permanente.
`format`	`integer \| optional`	2 su un registro in formato 2; assente nel formato 1.
`current`	`V2Version \| optional`	Formato 2: la versione corrente con label, body, signature, signedBy, logIndex, publishedAt ed entry.
`authority`	`array<V2Version> \| optional`	Formato 2: le versioni di autorità dalla 1, al più 50, ognuna con la sua voce del registro, i e la prova di inclusione sul checkpoint di index.
`authorityNext`	`integer \| null \| optional`	Formato 2: da dove continua GET /v1/identities/{n}/authority?after=, o null.
`state`	`object \| optional`	Formato 2: head, keys, links, orgs, la prima pagina di members e le quattro radici.
`index`	`V2IndexBundle \| null \| optional`	Formato 2: il pacchetto d’indice della scheda sul checkpoint della prova, come il registro lo serve a /index/<token>, con in più statements e statementsNext. Null quando il registro non l’ha dato.
`standing`	`integer \| null \| optional`	Formato 2: la posizione nel registro dell’ultima dichiarazione dello staff sulla scheda come la sa il server, o null. Il browser di un membro dello staff la mette in prev di una dichiarazione nuova. Il valore verificato è index.value.standing.
`statements`	`object \| optional`	Formato 2: le dichiarazioni firmate della scheda in breve: total, latest (le tre più recenti: id, title, publishedAt, retracts, retracted, url), url e feed.

HTTP 304none

Non modificato. La scheda ricostruita ha gli stessi byte dell’ETag che hai mandato. Riusa la scheda salvata con quell’ETag e verificala come sempre. Non c’è corpo nella risposta, e una scheda cancellata risponde comunque 410.

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.

Chiave del dispositivo CardKey

Campo	Tipo	Significato
`id`	`string`	Etichetta del dispositivo mostrata sulla scheda.
`alg`	`string`	Nome leggibile dell’algoritmo.
`fp`	`string`	Chiave pubblica completa presente nel record firmato.
`ed25519`	`string`	Chiave Ed25519 o metà della chiave composita, in hex.
`since`	`string`	Data di aggiunta della chiave.
`state`	`string`	active, offline o revoked. Offline indica una chiave di recupero.
`revoked`	`string \| null`	Data di revoca, se revocata.
`role`	`string`	Ruolo di firma assegnato alla chiave.
`addedIn`	`integer`	Versione che ha aggiunto la chiave.
`revokedIn`	`integer \| null`	Versione che ha revocato la chiave.

Account collegato CardLink

Campo	Tipo	Significato
`service`	`string`	Identificatore della piattaforma.
`handle`	`string`	Nome visualizzato o account normalizzato.
`id`	`string \| null`	ID stabile del provider, quando distinto dal nome.
`how`	`string`	Metodo di prova, per esempio oauth, dns_txt, well_known, emailCode o backlink.
`at`	`string`	Data e ora del collegamento.
`state`	`string`	active o pending.
`until`	`string \| null`	Scadenza del subentro in attesa.
`takeover`	`integer \| null`	ID del subentro in attesa.
`unicode`	`string, optional`	Forma Unicode di un dominio internazionale. Usa il nome ASCII come identificatore.
`addedIn`	`integer \| null`	Versione che ha aggiunto il collegamento.
`logIndex`	`integer \| null`	Indice della versione nel registro, a partire da zero.
`check`	`CardLinkCheck, optional`	Il ricontrollo periodico della prova fatto dal server (dal 30 ottobre 2026), per un collegamento attivo a un dominio, al Fediverso o a GitHub che ha controllato almeno una volta. È la sua parola, non fa parte della scheda firmata.

Ricontrollo di una prova CardLinkCheck

Campo	Tipo	Significato
`state`	`string`	ok, failing (il posto ha risposto e la prova non c’è) o unreachable (nessuna risposta).
`at`	`string`	Data e ora dell’ultimo controllo che ha avuto una risposta.
`since`	`string, optional`	Da quando la prova non si conferma. Manca finché è ok.
`reported`	`boolean`	Vero quando sono passati 30 giorni senza conferma e il proprietario è stato avvisato. Il collegamento resta.

Impronta della scheda Fingerprint

Campo	Tipo	Significato
`words`	`object`	en e it contengono le stesse dodici posizioni nelle rispettive liste di parole.
`digits`	`array<string>`	Dodici gruppi di cinque cifre decimali.

Affiliazione a un’organizzazione CardOrg

Campo	Tipo	Significato
`n`	`integer`	Numero permanente della scheda.
`url`	`string`	URL permanente della scheda.
`name`	`string`	Nome visualizzato, soggetto a moderazione.
`role`	`string`	Ruolo dell’affiliazione accettata.
`since`	`string`	Data e ora di inizio dell’affiliazione.
`nameHidden`	`boolean`	Indica se lo staff nasconde il nome.
`logo`	`object \| null`	Tipo e URL dell’immagine, se disponibile.

Membro dell’organizzazione CardMember

Campo	Tipo	Significato
`n`	`integer`	Numero permanente della scheda del membro.
`url`	`string`	URL della scheda del membro.
`name`	`string`	Nome visualizzato del membro.
`role`	`string`	Ruolo del membro.
`state`	`string`	Stato dell’affiliazione, inclusi gli inviti in attesa.
`since`	`string \| null`	Data e ora di accettazione, se accettato.
`icon`	`string \| null`	Icona del ruolo, se presente.
`nameHidden`	`boolean`	Indica se lo staff nasconde il nome del membro.
`logo`	`object \| null`	Tipo e URL dell’immagine.

Evento nella storia della scheda CardEvent

Campo	Tipo	Significato
`t`	`string`	Data e ora di pubblicazione in ISO 8601 UTC.
`kind`	`string`	Tipo di modifica, per esempio created, added, revoked, renamed o takeover.
`by`	`object`	device, key e identity di chi firma, dove disponibili.
`n`	`integer \| null`	Versione della scheda, oppure null per un evento esterno.
`logIndex`	`integer \| null`	Indice nel registro a partire da zero.
`device`	`string \| null`	Dispositivo interessato dalla modifica.
`service`	`string \| null`	Piattaforma interessata dalla modifica.
`handle`	`string \| null`	Account interessato dalla modifica.
`changes`	`array<string>`	Tutte le modifiche della versione, in ordine fisso.

Prova della scheda CardProof

Campo	Tipo	Significato
`version`	`integer`	Versione coperta dalla prova.
`record`	`string`	Testo JSON canonico esatto che è stato firmato. Non riformattarlo prima della verifica.
`salt`	`string`	Sale dell’impegno in hex.
`serverSalt`	`string`	Contributo del server al sale, in hex.
`clientSalt`	`string \| null`	Contributo del dispositivo al sale, in hex, se usato.
`commitment`	`string`	SHA-256 dei byte del sale seguiti dai byte del record, in hex.
`signedBy`	`string`	Chiave pubblica di firma.
`signature`	`string`	Firma sul prefisso identity-version e sul record esatto.
`entry`	`string`	Testo canonico esatto della voce del registro.
`logIndex`	`integer`	Indice della foglia a partire da zero.
`leafHash`	`string`	SHA-256 di 0x00 seguito dai byte della voce, in hex.
`checkpoint`	`Checkpoint`	Checkpoint firmato con size, root e note.
`inclusion`	`array<string>`	Hash del percorso di inclusione in hex, dal fratello più profondo.
`witnesses`	`array<string>`	Righe delle controfirme dei testimoni, presenti anche in checkpoint.note.

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.

Versione nel formato 2 V2Version

Campo	Tipo	Significato
`label`	`string`	L’intestazione canonica esattamente come firmata, dopo il prefisso veil-rubrica:identity-version:v2 e un a capo. Per un’organizzazione porta signer, la scheda del membro che firma e la sua versione. Il suo hash è il c che l’indice tiene per la versione.
`body`	`string`	Il corpo canonico: le operazioni fuori da label.auth e il sale. Non porta mai signer. label.body è il suo hash.
`signature`	`string`	La firma sul prefisso e sull’intestazione.
`signedBy`	`string`	La chiave che ha firmato.
`logIndex`	`integer \| null`	Posizione della voce della versione nel registro, da zero.
`publishedAt`	`string \| null`	Prima controfirma sul primo checkpoint che la conteneva.
`entry`	`string`	La voce della versione nel registro, come testo: key, label, signature e v. L’indice verifica la firma da questa sola voce.
`i`	`integer, optional`	Nell’elenco authority di una scheda: la posizione della voce nel registro, uguale a logIndex.
`inclusion`	`array<string>, optional`	Nell’elenco authority di una scheda: la prova di inclusione della voce in hex, dal fratello più profondo, sul checkpoint di index. Manca senza un registro verificato.

Pacchetto d’indice V2IndexBundle

Campo	Tipo	Significato
`checkpoint`	`object`	note, il checkpoint firmato dal registro con le controfirme dei testimoni, e size.
`entry`	`object`	L’ultima voce d’indice del checkpoint: i, entry e la sua prova di inclusione.
`value`	`object \| null`	Il valore della scheda nell’indice: auth, closed, latest e standing. Null quando la scheda non è nell’indice.
`proof`	`object`	bitmap e siblings: la prova di value sotto la radice della voce d’indice.
`tail`	`array<object>`	Le voci dopo la voce d’indice, ognuna con i, entry e inclusion. Applica tu a value quelle di questa scheda.
`statements`	`array<StatementEntry> \| null`	La prima pagina, al più 200, delle dichiarazioni dello staff contate per la scheda, dalla più recente. La prima è value.standing e ogni prev è la i della successiva. Un array vuoto vuol dire nessuna dichiarazione, null che il server non è riuscito a leggere o a provare la catena.
`statementsNext`	`string \| null`	L’indirizzo della pagina dopo delle dichiarazioni, o null quando la catena finisce qui.

Voce di una dichiarazione StatementEntry

Campo	Tipo	Significato
`i`	`integer`	La posizione della voce nel registro.
`entry`	`string`	Il testo della voce come lo tiene il registro, firma compresa.
`inclusion`	`array<string>`	Prova di inclusione in hex, dal fratello più profondo, sul checkpoint del pacchetto d’indice della scheda.
`by`	`integer, optional`	Numero della scheda del membro dello staff che ha firmato. Un’indicazione per la pagina: conta il signer della voce.

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.
`ETag`	`W/"<SHA-256 of the JSON bytes>"`	Rimandalo in `If-None-Match`. Il server ricostruisce la scheda con visibilità, moderazione e prove correnti, e risponde 304 solo se i byte del JSON sono gli stessi.
`Cache-Control`	`private, no-cache, must-revalidate`	Una cache condivisa non conserva la scheda, e un client la riconvalida prima di ogni riuso.
`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#

Verifica la catena delle versioni dell’organizzazione e l’autorità del firmatario. Controlla l’appartenenza accettata quando mostri un ruolo.

Note d’uso#

Il valore JSON di type è organization. Usa il numero permanente per ricordare l’organizzazione quando cambia alias.
Su un registro in formato 2 la scheda aggiunge format, current, authority, authorityNext, state, index e standing, e proof porta la voce v2 al posto del record. index.statements è la prima pagina delle dichiarazioni dello staff sulla scheda, e index.statementsNext porta alla pagina dopo.

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_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.
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.
422	`not_an_organization`	La scheda è una persona dove è richiesta un’organizzazione. Usa l’endpoint delle persone oppure la scheda di un’organizzazione.

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