Leggi la scheda di una persona

Leggi la scheda pubblica completa, il record firmato, la prova e la storia recente.

GET/u/{card}.json

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

Altri indirizzi#

/u/{card}
/v1/identities/{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/u/1.json'

javascript

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

Prova la richiesta#

Risposta#

HTTP 200application/json

La scheda contiene n, id, url, type, keys, links e proof. historyBefore indica la storia più vecchia. Una scheda cancellata restituisce una testimonianza pubblica con HTTP 410.

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, external (le chiavi pubbliche di altri sistemi, [] senza) e le radici degli insiemi; roots.external c’è solo quando la scheda ha chiavi pubbliche di altri sistemi.
`external`	`array<CardExternal> \| optional`	Formato 2: le chiavi pubbliche di altri sistemi come la pagina le mostra, con il controllo del server in proofOk. Il tuo client rifà il controllo di ogni prova da state.external e non si affida a proofOk.
`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.
`alerts`	`array<object> \| optional`	Formato 2, una persona: gli avvisi in vigore sui suoi account collegati, uno per account (platform, subject, display, state, since, to, logIndex, publishedAt). La parola del server: controllali con GET /v1/identities/{n}/alerts.
`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.

Chiave pubblica di altri sistemi

Campo	Tipo	Significato
`type`	`string`	ssh-ed25519, ssh-ecdsa-p256, ssh-ecdsa-p384, ssh-rsa, pgp, minisign, ed25519, ml-dsa-44, ml-dsa-65 o ml-dsa-87.
`fp`	`string`	L’impronta come la stampano i suoi strumenti: SHA256:… per SSH e ML-DSA, le 40 cifre esadecimali maiuscole dell’impronta di versione 4 per OpenPGP, l’ID di 16 cifre per minisign, la chiave in hex per Ed25519.
`label`	`string`	Il nome che la persona ha dato alla chiave, fino a 40 caratteri.
`pub`	`string`	La chiave pubblica nella sua forma canonica, senza commento. Per OpenPGP, la base64 dei suoi pacchetti: la chiave principale con le sue auto-firme, gli user ID che la persona ha tenuto, le sottochiavi di firma.
`ids`	`array<string> \| optional`	Solo OpenPGP, quando la chiave porta user ID: quelli che la persona ha scelto di tenere, come li scrive la chiave. Il tuo client li rilegge da pub e mostra solo quelli con un’auto-certificazione valida.
`addedIn`	`integer`	La versione della scheda che ha aggiunto la chiave.
`since`	`string`	Quando quella versione è stata pubblicata.
`logIndex`	`integer \| null`	La voce del registro di quella versione.
`proofOk`	`boolean`	Il controllo della prova fatto dal server. Solo informativo.
`anchor`	`object \| null`	Il checkpoint citato: origin, size, root e signedAt, l’orario delle controfirme del quorum.
`consistency`	`object \| null`	Una prova di coerenza RFC 6962 {size, proof} dalla taglia citata alla taglia del checkpoint della scheda, o 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.
`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 proof, la catena delle versioni e l’identità attesa. Il solo riepilogo non contiene questa prova.

Note d’uso#

Senza .json, manda Accept impostato a application/json. La variante /v1 richiede il numero permanente.
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

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.

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.

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