Tearleads
Open app

POST/organizations

Create an organization

Operation organizations.create

Description

Provisions an additional organization for the signed-in user, who becomes its founding administrator: reserved Admins and Members groups, root container, signed policies, and metadata documents in one transaction. It also creates the replacement for the caller's purged personal organization, which must use a fresh organization id.

Authentication

Requires a signed-in session: the client sends its session token as a bearer token in the Authorization header.

Request body

application/jsonCreateOrganizationRequest

Every signed artifact of a new organization, signed with the caller's existing identity: the same set registration provisions.

17 fields

Other fields are allowed.

Responses

200 OK

application/jsonCreateOrganizationResponse

Acknowledges a new organization by the ids and hashes of what it created.

19 fields
  • committedCoreMetadataUpdateIdslist of stringrequired
    • each item: lowercase UUID v4

    Ids of the seeded metadata updates the server committed.

  • committedProfileUpdateIdslist of stringrequired
    • each item: lowercase UUID v4

    Ids of the seeded profile updates the server committed.

  • organizationIdstringrequired
  • organizationMetadataContainerContainerCreateWithMetadataDocumentResponserequired
  • organizationMetadataContainerIdstringrequired
  • organizationProfileDocumentDocumentCreateResponseoptional
  • organizationProfileDocumentIdstringoptional
  • rootContainerIdstringrequired
  • rootMetadataAccessEpochnumberrequired

    Access epoch of the root container's metadata document.

  • rootMetadataAccessStateHashstringrequired
    • not empty

    Access state hash of the root container's metadata document.

  • rootMetadataDocumentDocumentCreateResponserequired
  • rootMetadataDocumentIdstringrequired
  • rosterProfileContainerContainerCreateWithMetadataDocumentResponseoptional
  • rosterProfileContainerIdstringoptional
  • rosterProfileDocumentDocumentCreateResponseoptional
  • rosterProfileDocumentIdstringoptional
  • systemContainerslist of ContainerCreateWithMetadataDocumentResponserequired
  • userIdstringrequired
  • replacementAuthorizationOrganizationReplacementAuthorizationrequirednullable

    For a replacement, the identity-signed authorization clients verify before following it.

Other fields are allowed.

Other responses

StatusMeaningBody
400Bad Request

application/jsonErrorResponse

401Unauthorized

application/jsonSessionFailureResponse

403Forbidden

application/jsonErrorResponse

404Not Found

application/jsonErrorResponse

409Conflict

application/jsonErrorResponse

500Internal Server Error

application/jsonErrorResponse

503Service Unavailable

application/jsonErrorResponse

Additional rules

The server also enforces these rules, which the schema above cannot express.

  • inlineRekeyCommitId must be present exactly when containerRekeys is non-empty.

  • authorizingContainerPathRefs is required when outgoingUpdates is non-empty.

  • containerRekeys may be non-empty only when outgoingUpdates is non-empty.

  • Outgoing update ids must be unique within the request.

  • A request carrying pullCursor must 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" requires localVersionVector to be null so the complete retained history is requested.

  • checkpointKind, checkpointPayloadKind, and sourceVersionVector must 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.