Read authority versions

Page through the versions that changed who can sign the card.

GET/v1/identities/{n}/authority

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

Parameters#

Name	Location	Meaning
`n`Required	Path	Permanent positive card number.
`after`	Query	Version to continue after, 0 by default.
`limit`	Query	1 to 200. Default 50.

Request examples#

cURL

curl -fsS 'https://veil.rip/v1/identities/1/authority?after=0&limit=50'

javascript

const response = await fetch("https://veil.rip/v1/identities/1/authority?after=0&limit=50");
const result = await response.json();

Response#

HTTP 200application/json

authority is ordered from version 1. Pass next as after until it is null.

Field	Type	Meaning
`authority`	`array<V2Version>`	Authority versions in ascending order.
`next`	`integer \| null`	The version number to pass as after; null ends the list.

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.

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.

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.
`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#

Each label hashes to a c of the card’s index value auth, and each is signed by a key of the authority before it.

Usage notes#

Only on a log in format 2 (GET /v1/log says format 2). A log in format 1 answers 400 wrong_format.

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	`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.
400	`wrong_format`	The request or the read belongs to the other log format than this server’s: a v1 record on a format 2 log, or a format 2 read on a format 1 log. Read `format` in GET /v1/log (absent means 1) and send the shape of that format.
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