Create an organisation

Publish an organisation’s first record, signed by its founder’s active person key.

POST/v1/organizations

Access: Signed request
Client: Local or server client

JSON body#

Name	Location	Meaning
`record`Required	JSON	The complete canonical identity or organisation record, including its history fields.
`signature`Required	JSON	The record signature, separate from the request signature header.
`logoData`	JSON	The image that record.logo names by hash, in standard padded base64 on one line. Required when the version brings a new image. With an unchanged image it can be left out, and if sent it must match.
`nonce`Required	JSON	A fresh 16 to 128 character nonce using letters, digits, underscore or hyphen.
`timestamp`Required	JSON	Unix milliseconds within two minutes of the server clock.
`clientSalt, saltTicket`	JSON	Optional pair for the first version. Request the ticket before drawing the client salt.
`label`	JSON	Format 2: the label as a JSON object; the server encodes it canonically and checks the signature on those bytes.
`body`	JSON	Format 2: the body as a JSON object, its hash in label.body.
`pictureData`	JSON	Format 2: the bytes of a new picture the body names by hash, in standard padded base64.

This call also needs the common signed-request headers, nonce and timestamp. Prepare and sign request.json before using the example. Request signing

Request examples#

cURL

curl -fsS -X POST \
  -H "X-Public-Key: $PUBLIC_KEY" \
  -H "X-Signature: $REQUEST_SIGNATURE" --json @request.json \
  "https://veil.rip/v1/organizations"

Response#

HTTP 201application/json

201 with n, id, url, token, version, commitment, logIndex, publishedAt and checkpoint. The response follows witnessed publication.

Field	Type	Meaning
`n`	`integer`	Permanent card number.
`id`	`string`	Version-one commitment in hex.
`url`	`string`	Permanent card URL.
`token`	`string`	Stable log pseudonym in base64url.
`version`	`integer`	Published version number.
`commitment`	`string`	This version’s commitment in hex.
`logIndex`	`integer`	Zero-based log index.
`publishedAt`	`string`	Earliest cosignature time at publication.
`checkpoint`	`Checkpoint`	First checkpoint covering the version.

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.

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.

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.
`Location`	`relative URL`	Published card/proof address, or permanent widget redirect target.
`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.

Usage notes#

On a log in format 2 the body is {label, body, signature, pictureData?}, with clientSalt and saltTicket required for version 1; a record is refused with 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_alias`	The alias does not meet the ASCII name rules. Use 3 to 32 lowercase ASCII letters, digits, hyphens or underscores; start with a letter and end with a letter or digit.
400	`invalid_json`	The body is not a JSON object, contains duplicate keys or has trailing data. Send one valid JSON object with `Content-Type` application/json.
400	`invalid_name`	A name contains invisible, direction-control or unsupported format characters. Use a visible name in the accepted Unicode form and sign the corrected request.
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.
403	`identity_banned`	The acting identity is suspended by Veil staff. Wait for the restriction to end or ask staff to review it.
403	`key_mismatch`	The signing key does not have authority over this card or operation. Use an active device key with the required owner or member role.
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.
409	`account_locked`	Moderation prevents this account from being claimed. Check the current card’s public moderation state.
409	`alias_quarantined`	The alias is in its 30-day release quarantine. Inspect `reusableAt` and the previous holder through the alias endpoint.
409	`alias_reserved`	The chosen alias is reserved for the service. Choose another alias.
409	`alias_taken`	The alias is claimed or a publication has reserved it. Choose another alias or check availability again after the publication finishes.
409	`already_member`	This membership already exists. Read current memberships before publishing another invitation.
409	`grant_used`	A verification or membership grant has already been consumed. Check the resulting card version, then obtain a fresh grant if still needed.
409	`identity_exists`	An identity already uses this token. Check the existing publication. Generate a new identity only when a different card is intended.
409	`invitation_withdrawn`	The organisation no longer offers the invitation. Ask for a new invitation.
409	`key_already_used`	A device key already belongs to an identity and cannot be reused by another. Use the existing card or generate a fresh device key.
409	`salt_ticket_invalid`	The salt ticket is unknown, expired or already consumed. Request a fresh ticket and rebuild and sign version one with it.
409	`takeover_already_open`	A takeover for this linked account is already open. Read the pending takeover instead of opening another.
409	`version_conflict`	The version cannot be published against the card’s current state. Read the latest card, reconcile the intended change and sign a new version.
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.
413	`payload_too_large`	The request body exceeds this endpoint’s byte limit. Reduce the encoded body. API-key management accepts at most 8 KiB.
422	`grant_expired`	The verification or membership grant expired. Obtain a fresh grant before publishing the version.
422	`invalid_grant`	The verification or membership grant is invalid or belongs to another operation. Use the grant issued for this exact card, account or membership.
422	`invalid_logo`	The image fails type, size, dimensions or content validation. Correct the image according to `error.message` before uploading again.
422	`invalid_op`	An operation is unknown, malformed, not one of this card’s type or version, or changes nothing. Correct the operation named in `error.message`.
422	`invalid_record`	The identity version violates the signed-record rules. Correct the validation issue, canonicalise the record and sign it again.
422	`invalid_record_signature`	The identity-version signature does not verify. Sign the exact canonical record with its identity-version prefix and declared key.
422	`label_mismatch`	The label’s prev, body, auth or state is not what the chain, the body and the operations give. Read the card again, plan the operations on its current state and sign the new label.
422	`last_owner`	The change would leave an organisation without an accepted owner. Add or accept another owner before removing the last one.
422	`links_need_verification`	A new account link has no acceptable verification grant. Complete the account proof before publishing its link.
422	`membership_needs_grant`	An organisation membership lacks its acceptance grant. Accept the invitation and include its grant in the next signed version.
422	`not_an_organization`	The card is a person where an organisation is required. Use the person endpoint or an organisation card.
502	`log_mismatch`	The log response did not match the expected signed entry or proof. Do not accept the publication as verified. Check the card and log before retrying.
503	`log_unavailable`	The public log cannot currently be read, verified or used for publication. For reads, keep the result unverified and try later. Before retrying a write, read the card to check whether publication completed.

Shared request errors

HTTP	Code	Meaning and next step
400	`invalid_nonce`	The signed-request nonce has an invalid format. Generate a fresh 16 to 128-character nonce using letters, digits, _ or -.
400	`invalid_signature_alg`	`X-Signature-Alg` is unsupported. Use a supported signing algorithm and matching key/signature encoding.
400	`invalid_timestamp`	The signed-request timestamp is not Unix milliseconds. Use an integer Unix timestamp in milliseconds and sign the corrected request.
401	`invalid_signature`	The HTTP request signature does not verify. Sign the exact method, path and body bytes, without changing them afterwards.
401	`missing_signature`	The request requires a device signature and its headers are missing or unreadable. Send `X-Public-Key`, `X-Signature` and the signed-request metadata. An API key does not replace a device signature.
401	`stale_timestamp`	The signed timestamp is outside the accepted clock window. Compare the server Date header with your clock, then generate a fresh nonce, timestamp and signature.
403	`key_banned`	The device signing key is suspended by Veil staff. Use an authorised active key or ask staff to review the restriction.
409	`replayed_nonce`	The signing key already used this nonce. Check whether the previous request succeeded before making a fresh signed request.
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.

Read this entry as JSON