Read a person’s card

Read the full public card, signed record, proof and recent history.

GET/u/{card}.json

Access: Public; API key optional
Client: Browser fetch supported

Other addresses#

/u/{card}
/v1/identities/{n}

Parameters#

Name	Location	Meaning
`card`Required	Path	A permanent card number or its current alias.

Request examples#

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();

Try the request#

Response#

HTTP 200application/json

The card includes n, id, url, type, keys, links and proof. historyBefore points to older history. An erased card returns a public tombstone with HTTP 410.

Field	Type	Meaning
`n`	`integer`	Permanent card number.
`url`	`string`	Permanent URL using the card number.
`name`	`string`	Current display name; a hidden name becomes Card followed by its number.
`initials`	`string`	Initials for an image fallback.
`since`	`string`	Version-one date in YYYY-MM-DD UTC.
`id`	`string`	Version-one commitment in hex; the source of the fingerprint.
`idSalt`	`object \| null`	server and client salt halves in hex. client can be null.
`token`	`string`	Stable public-log pseudonym in base64url.
`version`	`integer`	Current published version.
`keys`	`array<CardKey>`	All device and recovery keys, including revoked keys.
`links`	`array<CardLink>`	Linked accounts and pending takeovers.
`orgs`	`array<CardOrg>`	Accepted organisation affiliations of a person.
`events`	`array<CardEvent>`	Newest page of card history, ordered oldest first within the page.
`witnesses`	`object \| null`	signed, of and needed counts for the current version. These are server checks.
`nodes`	`integer \| null`	Number of hashes in the current inclusion path.
`fingerprint`	`Fingerprint`	Twelve words in each language and twelve five-digit groups.
`proof`	`CardProof \| null`	Current opening and inclusion proof. Null means the log could not be verified now; never treat it as verified.
`erasure`	`object \| null`	requestedAt and executesAt for a pending erasure.
`type`	`string`	person or organization.
`members`	`array<CardMember>, optional`	Present for an organisation, including pending invitations.
`moderation`	`object \| null`	Public moderation state and actions.
`eventsTotal`	`integer`	Total history events across all pages.
`historyBefore`	`integer \| null`	Pass as before to the history endpoint to read the older page.
`badges`	`array<object>`	Active signed or derived badges.
`nameHidden`	`object \| null`	Public reason, since and logIndex for a hidden name.
`logo`	`object, optional`	Image type and URL; omitted without a visible image.
`logoHidden`	`object, optional`	Public reason for a hidden logo.
`alias`	`string \| null`	Current alias; it can change.
`aliasUrl`	`string \| null`	Current alias address. Use n as the permanent identifier.
`format`	`integer \| optional`	2 on a log in format 2; absent in format 1.
`current`	`V2Version \| optional`	Format 2: the current version with label, body, signature, signedBy, logIndex, publishedAt and entry.
`authority`	`array<V2Version> \| optional`	Format 2: authority versions from version 1, at most 50, each with its log entry, i and inclusion proof on the index checkpoint.
`authorityNext`	`integer \| null \| optional`	Format 2: where GET /v1/identities/{n}/authority?after= continues, or null.
`state`	`object \| optional`	Format 2: head, keys, links, orgs, the first page of members, external (public keys from elsewhere, [] when none) and the set roots; roots.external is there only when the card has public keys from elsewhere.
`external`	`array<CardExternal> \| optional`	Format 2: the public keys from elsewhere as the page shows them, with the server’s check in proofOk. Your client checks each proof again from state.external and does not rely on proofOk.
`index`	`V2IndexBundle \| null \| optional`	Format 2: the card’s index bundle on the proof’s checkpoint, as the log serves it at /index/<token>, with statements and statementsNext added. Null when the log gave none.
`standing`	`integer \| null \| optional`	Format 2: the log position of the card’s last staff statement as the server knows it, or null. A staff browser puts it in prev of a new statement. The verified value is index.value.standing.
`alerts`	`array<object> \| optional`	Format 2, a person: the alerts in force on its linked accounts, one per account (platform, subject, display, state, since, to, logIndex, publishedAt). The server’s word: check them with GET /v1/identities/{n}/alerts.
`statements`	`object \| optional`	Format 2: the card’s signed statements in short: total, latest (the three newest: id, title, publishedAt, retracts, retracted, url), url and feed.

HTTP 304none

Not modified. The rebuilt card has the same bytes as the ETag you sent. Reuse the card stored with it and verify it as usual. There is no response body, and an erased card still answers 410.

Expand a nested object for its fields. Types ending in null allow a null value; optional fields may be absent. Other fields are present in that object.

Device key CardKey

Field	Type	Meaning
`id`	`string`	Device label shown on the card.
`alg`	`string`	Readable algorithm name.
`fp`	`string`	Full public key as stored in the signed record.
`ed25519`	`string`	Ed25519 key or composite-key half, in hex.
`since`	`string`	Date the key was added.
`state`	`string`	active, offline or revoked. Offline denotes a recovery key.
`revoked`	`string \| null`	Revocation date, when revoked.
`role`	`string`	Signing role assigned to the key.
`addedIn`	`integer`	Version that added the key.
`revokedIn`	`integer \| null`	Version that revoked the key.

Linked account CardLink

Field	Type	Meaning
`service`	`string`	Platform identifier.
`handle`	`string`	Display handle or normalised account.
`id`	`string \| null`	Stable provider ID, when separate from the handle.
`how`	`string`	Proof method, such as oauth, dns_txt, well_known, emailCode or backlink.
`at`	`string`	Time the link was established.
`state`	`string`	active or pending.
`until`	`string \| null`	Pending takeover deadline.
`takeover`	`integer \| null`	Pending takeover ID.
`unicode`	`string, optional`	Unicode spelling of an international domain. Keep the ASCII handle as the identifier.
`addedIn`	`integer \| null`	Version that added the link.
`logIndex`	`integer \| null`	Zero-based log index of that version.
`check`	`CardLinkCheck, optional`	The server’s periodic re-check of the proof (since 30 October 2026), for an active domain, Fediverse or GitHub link it has checked at least once. Its word, not part of the signed card.

Re-check of a proof CardLinkCheck

Field	Type	Meaning
`state`	`string`	ok, failing (the place answered and the proof is not there) or unreachable (no answer).
`at`	`string`	Time of the last check that got an answer.
`since`	`string, optional`	Since when the proof has not confirmed. Absent while ok.
`reported`	`boolean`	True once 30 days passed without a confirmation and the owner was told. The link stays.

Card fingerprint Fingerprint

Field	Type	Meaning
`words`	`object`	en and it each contain the same twelve word-list positions in their language.
`digits`	`array<string>`	Twelve groups of five decimal digits.

Organisation affiliation CardOrg

Field	Type	Meaning
`n`	`integer`	Permanent card number.
`url`	`string`	Permanent card URL.
`name`	`string`	Display name, subject to moderation.
`role`	`string`	Accepted membership role.
`since`	`string`	Membership start time.
`nameHidden`	`boolean`	Whether staff hide the name.
`logo`	`object \| null`	Image type and URL, when available.

Organisation member CardMember

Field	Type	Meaning
`n`	`integer`	Member’s permanent card number.
`url`	`string`	Member card URL.
`name`	`string`	Member’s display name.
`role`	`string`	Membership role.
`state`	`string`	Membership state, including pending invitations.
`since`	`string \| null`	Acceptance time, when accepted.
`icon`	`string \| null`	Role icon, when provided.
`nameHidden`	`boolean`	Whether staff hide the member’s name.
`logo`	`object \| null`	Image type and URL.

Card history event CardEvent

Field	Type	Meaning
`t`	`string`	Publication time in ISO 8601 UTC.
`kind`	`string`	Change kind, such as created, added, revoked, renamed or takeover.
`by`	`object`	device, key and identity of the signer, where available.
`n`	`integer \| null`	Card version, or null for an external event.
`logIndex`	`integer \| null`	Zero-based log index.
`device`	`string \| null`	Device concerned by the change.
`service`	`string \| null`	Platform concerned by the change.
`handle`	`string \| null`	Account concerned by the change.
`changes`	`array<string>`	All changes in this version, in a fixed order.

Card proof CardProof

Field	Type	Meaning
`version`	`integer`	Version covered by this proof.
`record`	`string`	Exact canonical JSON text that was signed. Do not reformat before verifying.
`salt`	`string`	Commitment salt in hex.
`serverSalt`	`string`	Server’s salt contribution in hex.
`clientSalt`	`string \| null`	Device’s salt contribution in hex, when used.
`commitment`	`string`	SHA-256 of salt bytes followed by record bytes, in hex.
`signedBy`	`string`	Public signing key.
`signature`	`string`	Signature over the identity-version prefix and exact record.
`entry`	`string`	Exact canonical log entry text.
`logIndex`	`integer`	Zero-based leaf index.
`leafHash`	`string`	SHA-256 of 0x00 followed by entry bytes, in hex.
`checkpoint`	`Checkpoint`	Signed checkpoint containing size, root and note.
`inclusion`	`array<string>`	Audit-path hashes in hex, deepest sibling first.
`witnesses`	`array<string>`	Witness cosignature lines also present in checkpoint.note.

Checkpoint Checkpoint

Field	Type	Meaning
`size`	`integer`	Number of leaves in the signed tree.
`root`	`string`	Root hash in base64.
`note`	`string`	Full signed note, including log and witness signatures.

Version in format 2 V2Version

Field	Type	Meaning
`label`	`string`	The canonical label exactly as signed, after the prefix veil-rubrica:identity-version:v2 and a line break. For an organisation it carries signer, the member card that signs and its version. Its hash is the c that the index keeps for the version.
`body`	`string`	The canonical body: the operations outside label.auth and the salt. It never carries signer. label.body is its hash.
`signature`	`string`	The signature over the prefix and the label.
`signedBy`	`string`	The key that signed.
`logIndex`	`integer \| null`	Zero-based position of the version’s entry in the log.
`publishedAt`	`string \| null`	Earliest cosignature time on the first checkpoint that held it.
`entry`	`string`	The version’s log entry as text: key, label, signature and v. The index checks the signature from this entry alone.
`i`	`integer, optional`	In the authority list of a card: the entry’s log position, the same as logIndex.
`inclusion`	`array<string>, optional`	In the authority list of a card: the entry’s inclusion proof in hex, deepest sibling first, on the checkpoint of index. Absent without a verified log.

Index bundle V2IndexBundle

Field	Type	Meaning
`checkpoint`	`object`	note, the checkpoint signed by the log with the witness cosignatures, and size.
`entry`	`object`	The checkpoint’s last index entry: i, entry and its inclusion proof.
`value`	`object \| null`	The card’s value in the index: auth, closed, latest and standing. Null when the card is not in the index.
`proof`	`object`	bitmap and siblings: the proof of value under the root of the index entry.
`tail`	`array<object>`	The entries after the index entry, each with i, entry and inclusion. Apply those of this card to value yourself.
`statements`	`array<StatementEntry> \| null`	The first page, at most 200, of the card’s counted staff statements, newest first. The first is value.standing and each prev is the i of the next. An empty array means no statements, null means the server could not read or prove the chain.
`statementsNext`	`string \| null`	The address of the next page of statements, or null when the chain ends here.

Statement entry StatementEntry

Field	Type	Meaning
`i`	`integer`	The entry’s position in the log.
`entry`	`string`	The entry text as the log holds it, signature included.
`inclusion`	`array<string>`	Inclusion proof in hex, deepest sibling first, on the checkpoint of the card’s index bundle.
`by`	`integer, optional`	Card number of the staff member who signed. A hint for display: the signer in the entry is what counts.

Public key from elsewhere

Field	Type	Meaning
`type`	`string`	ssh-ed25519, ssh-ecdsa-p256, ssh-ecdsa-p384, ssh-rsa, pgp, minisign, ed25519, ml-dsa-44, ml-dsa-65 or ml-dsa-87.
`fp`	`string`	The fingerprint as its own tools print it: SHA256:… for SSH and ML-DSA, the 40 hex digits of the version 4 fingerprint in capitals for OpenPGP, the 16-digit key ID for minisign, the key in hex for Ed25519.
`label`	`string`	The name the person gave the key, up to 40 characters.
`pub`	`string`	The public key in its canonical form, without comment. For OpenPGP, the base64 of its packets: the primary key with its self-signatures, the user IDs the person kept, the signing subkeys.
`ids`	`array<string> \| optional`	OpenPGP only, when the key carries user IDs: the ones the person chose to keep, as the key writes them. Your client reads them again from pub and shows only those with a valid self-certification.
`addedIn`	`integer`	The card version that added the key.
`since`	`string`	When that version was published.
`logIndex`	`integer \| null`	The log entry of that version.
`proofOk`	`boolean`	The server’s own check of the proof. Informative only.
`anchor`	`object \| null`	The quoted checkpoint: origin, size, root and signedAt, the quorum’s cosigning time.
`consistency`	`object \| null`	An RFC 6962 consistency proof {size, proof} from the quoted size to the size of the card’s checkpoint, or null.

Response headers#

Header	Value	Meaning
`Content-Type`	`application/json`	Use the declared media type before choosing a parser.
`Date`	`HTTP date`	Server time. Compare it with your clock when signing requests.
`ETag`	`W/"<SHA-256 of the JSON bytes>"`	Send it back in `If-None-Match`. The server rebuilds the card with current visibility, moderation and proofs, and answers 304 only when the JSON bytes are the same.
`Cache-Control`	`private, no-cache, must-revalidate`	A shared cache does not keep the card, and a client revalidates it before every reuse.
`Retry-After`	`integer seconds, on rate_limited or busy`	Wait at least this long before retrying. Other 429/503 codes do not necessarily include it.

What to verify#

Verify proof, the version chain and the expected identity. The summary endpoint alone does not carry this proof.

Usage notes#

Without .json, send Accept set to application/json. The /v1 variant requires the permanent number.
On a log in format 2 the card adds format, current, authority, authorityNext, state, index and standing, and proof carries the v2 entry instead of the record. index.statements is the first page of the card’s staff statements, and index.statementsNext leads to the next one.

Errors#

API errors return an error object. Use error.code for program logic; error.message is English text for people and can change. Response and error guide

HTTP Code Meaning and next step

400

HTTP	Code	Meaning and next step
400	`invalid_parameter`	A path, query or body field is missing, malformed or outside its accepted range. Correct the field named in `error.message` before sending again.
404	`not_found`	The requested card, key, alias, code or resource was not found. Check the identifier. Temporary codes and previews may already have expired or been used.
410	`erased`	The card existed and was erased or removed. The response also carries its public erasure receipt. Stop using this card as current authority. Retain only the public receipt if needed.

invalid_parameter

A path, query or body field is missing, malformed or outside its accepted range.

Correct the field named in error.message before sending again.

404

not_found

The requested card, key, alias, code or resource was not found.

Check the identifier. Temporary codes and previews may already have expired or been used.

410

erased

The card existed and was erased or removed. The response also carries its public erasure receipt.

Stop using this card as current authority. Retain only the public receipt if needed.

When using an optional API key

HTTP	Code	Meaning and next step
401	`invalid_api_key`	The bearer credential is malformed, unknown, expired or revoked. Use an active key. To use anonymous public access, remove `Authorization` entirely. Invalid credentials never fall back automatically.
403	`api_key_scope`	The API key lacks read or verify scope, or the endpoint does not accept bearer keys. Use the correct scope. Identity writes and key management still require a device signature.
403	`api_key_suspended`	This API key is suspended. Ask staff to restore it; another key cannot lift an account suspension.
403	`developer_suspended`	The owner’s API account is suspended or the owner card is unavailable. Check the owner account and any staff restriction. Creating another key does not bypass suspension.

Shared request errors

HTTP Code Meaning and next step

429

HTTP	Code	Meaning and next step
429	`rate_limited`	An anonymous, signed-request or API-key allowance was exceeded. Wait at least `Retry-After` seconds. Share a queue and retry budget across your workers.
500	`internal_error`	An unexpected server error occurred. Internal details are not returned. Retry reads with bounded backoff. Check write results before sending a new signed operation.
503	`busy`	The application has reached a temporary concurrency or database limit. Wait `Retry-After` seconds and retry with bounded backoff.

rate_limited

An anonymous, signed-request or API-key allowance was exceeded.

Wait at least Retry-After seconds. Share a queue and retry budget across your workers.

500

internal_error

An unexpected server error occurred. Internal details are not returned.

Retry reads with bounded backoff. Check write results before sending a new signed operation.

503

busy

The application has reached a temporary concurrency or database limit.

Wait Retry-After seconds and retry with bounded backoff.

Read this entry as JSON