POST/auth/register
Register an identity and bootstrap its root state
Operation auth.register
Description
Creates a new identity from its signing and encapsulation public keys and, in one transaction, provisions its personal organization: the reserved Admins and Members groups, the root container, and their signed policies and metadata documents. The response carries a fresh login challenge, so the client signs in next with POST /auth/verify. A signing key that is already registered returns 409.
Authentication
No session is required.
Request body
application/jsonRegistrationRequest
A new identity's public keys plus every signed artifact that bootstraps its personal organization, all created atomically.
15 fields
The organization's other system containers, such as Trash, each with its metadata document.
organizationIdstringrequired- lowercase UUID v4
rootContainerIdstringrequired- lowercase UUID v4
userIdstringrequired- lowercase UUID v4
encapsulationPublicKeystringrequired- exactly 2,092 characters
- base64, pattern
^(?:[A-Za-z0-9+/]{4}){522}[A-Za-z0-9+/]{2}[AEIMQUYcgkosw048]=$
Base64 ML-KEM-1024 public key that key material is wrapped to.
signingPublicKeystringrequired- exactly 3,456 characters
- base64, pattern
^(?:[A-Za-z0-9+/]{4}){864}$
Base64 ML-DSA-87 public key that signs the identity's events and sign-in challenges.
Other fields are allowed.
Responses
200 OK
application/jsonRegistrationResponse
Acknowledges a registration by the ids and hashes of what it created, plus a sign-in challenge.
19 fields
committedCoreMetadataUpdateIdslist of stringrequired- each item: lowercase UUID v4
Ids of the seeded metadata updates the server committed with the provisioning.
committedProfileUpdateIdslist of stringrequired- each item: lowercase UUID v4
Ids of the seeded profile updates the server committed with the provisioning.
organizationIdstringrequiredorganizationMetadataContainerIdstringrequiredorganizationProfileDocumentIdstringoptionalrootContainerIdstringrequiredrootMetadataAccessEpochnumberrequiredAccess epoch of the root container's metadata document.
rootMetadataAccessStateHashstringrequired- not empty
Access state hash of the root container's metadata document.
rootMetadataDocumentIdstringrequiredrosterProfileContainerIdstringoptionalrosterProfileDocumentIdstringoptionaluserIdstringrequiredchallengestringrequired- exactly 64 characters
- lowercase hexadecimal
Sign-in challenge to sign and send to
POST /auth/verify, so the new identity can sign in without another request.
Other fields are allowed.
Other responses
| Status | Meaning | Body |
|---|---|---|
| 400 | Bad Request |
|
| 403 | Forbidden |
|
| 404 | Not Found |
|
| 409 | Conflict |
|
| 500 | Internal Server Error |
|
| 503 | Service Unavailable |
|
Additional rules
The server also enforces these rules, which the schema above cannot express.
inlineRekeyCommitIdmust be present exactly whencontainerRekeysis non-empty.authorizingContainerPathRefsis required whenoutgoingUpdatesis non-empty.containerRekeysmay be non-empty only whenoutgoingUpdatesis non-empty.Outgoing update ids must be unique within the request.
A request carrying
pullCursormust not contain outgoing updates, container rekeys, a content-key bundle, or authorizing paths.historyMode"raw" must not be combined with outgoing updates, container rekeys, a content-key bundle, or authorizing paths.historyMode"raw" requireslocalVersionVectorto be null so the complete retained history is requested.checkpointKind,checkpointPayloadKind, andsourceVersionVectormust be absent together or form a rotation baseline.Each provisioned system-container metadata seed must contain exactly one outgoing update and no container rekeys.
Each provisioned document seed must contain exactly one outgoing update and no container rekeys.
Core and profile metadata update id arrays contain no duplicates.
A container response keyring is null exactly for container key epoch 1.