Onboarding

The descriptions of the operations and fields are the contract’s own, in English.

POST/identity/v1/registrations

Register a human and organization with email verification

Credential: None: a public operation
Permission: None beyond the credential
Request body: Body up to 16384 bytes

Public: it takes no credential, and it is available only on a plane where sign-up is configured (503 onboarding-unavailable otherwise).

A request of at most 16 KiB creates one durable registration operation and, at the identity provider, the organization and its first human member, the owner, with the password they chose. No membership or session is issued here: the person verifies the email address the provider sends them and then signs in through ordinary OIDC sign-in, and the first GET /identity/v1/onboarding after that finalizes the organization, for exactly the verified issuer and subject. An uncertain outcome (a timeout, a 503) is retried with the same request_id and the same details: the password is never persisted or fingerprinted, and a retry never resets the password of an account that was already created. Two budgets are shared by all replicas: 30 attempts per minute for the plane and 5 per email address per hour (429 registration-rate-limited, with Retry-After). Email is never an identity-linking authority, and the answer never discloses whether an email address is already registered. The body is strict JSON: the registration takes no alias (an organization alias exists only for an organization with single sign-on, which a new organization never has; it sets one from its single sign-on settings once the connection is enabled), so naming an alias, like any other member the registration does not define, is refused with 400 registration-invalid. Failures: 400 registration-invalid (a member missing, unknown or outside its limits, or refused by the identity provider's password policy; the provider's reasons are not disclosed); 409 registration-conflict (the registration could not be completed with these details); 413 registration-invalid (the body is over 16 KiB); 429 registration-rate-limited; 503 onboarding-unavailable (sign-up is not configured) or organization-identity-unavailable (the provider or the storage could not be reached; retry with the same request_id).

curl

curl -X POST "https://console.us.ccsio.ai/identity/v1/registrations" \
  -H "Content-Type: application/json" \
  -d '{
  "request_id": "string",
  "organization_name": "string",
  "first_name": "string",
  "last_name": "string",
  "email": "[email protected]",
  "password": "string"
}'

Built from the schema’s required members: replace the values.

Parameters

Name	In	Description
`X-Request-ID` optional	header	string Optional request ULID. A valid ULID (upper or lowercase) is honored; when the header is absent or invalid, the runtime mints the id. The response X-Request-ID header carries the canonical uppercase form.

Request body application/json

PublicRegistrationRequest

request_idstring (uuid)required
A random UUID (version 1 to 8) the client generates for this registration and keeps for uncertain retries.
organization_namestringrequired
The organization's display name, trimmed: 1 to 128 bytes of UTF-8 (a multi-byte character counts for each of its bytes).
1 to 128 characters
first_namestringrequired
The owner's first name, trimmed: 1 to 200 characters.
1 to 200 characters
last_namestringrequired
The owner's last name, trimmed: 1 to 200 characters.
1 to 200 characters
emailstring (email)required
The owner's email address: a bare address (no display name), trimmed, at most 200 bytes. The provider sends the verification email here.
at most 200 characters
passwordstringrequired
The owner's password, 8 to 200 characters, kept exactly as sent (spaces included). It needs an uppercase letter, a lowercase letter, a digit and a symbol; the identity provider's password policy is authoritative and may be stricter. It is never stored on this platform.
8 to 200 characters

Responses

202
Check the verification email, then sign in. An identical successful retry returns the same response.
Schema
PublicRegistrationResponse
statusstringrequired
The person must verify the email address the provider sent, then sign in.
Allowed values: "verification_required"
400
Client refusal unrelated to authentication, including malformed input, a denied or failed request.
405
The path is claimed but the request method is not allowed. Go ServeMux returns its standard plain-text response and lists permitted methods in Allow.
409
The registration could not be completed with these details. The answer does not disclose whether an email address is registered.
413
The request is over 16 KiB.
429
A shared registration budget is used up: the plane's, or the email address's.
500
Platform failure, rendered without internal cause details.
503
Sign-up is disabled on this plane, or the identity provider or the storage could not be reached. Retry an uncertain attempt with the same request_id and details.

GET/identity/v1/onboarding

Discover the signed-in human's organizations

Credential: A signed-in person’s token (Console session)
Permission: None beyond the credential

Verifies the human OIDC access token without requiring a selected organization (it takes no X-Organization-Id) and lists the organizations of this plane that the signed-in person can reach: those of their active memberships, and the organization of theirs whose creation is still being finished.

Reading it also finishes what is pending for the person: it provisions a person who signed in through an organization's own single sign-on into that organization on their first sign-in (the one case where the identity provider alone grants a membership), and it completes the registration that the person's verified email address started. API keys and bootstrap credentials are refused (403 onboarding-credential-required). registration_available says whether this plane can create organizations for the caller's identity provider, and registration_residencies lists the residencies it offers for sign-up (its own, or none). The answer is never cached (Cache-Control: no-store). Failures: 401; 403 (a service or bootstrap credential, or a human identity that is unavailable or disabled; a public-registration account whose provider email is not verified yet, email-verification-required; a person whose first sign-in through the organization's own single sign-on would need a seat above the plan's included ones, seat-limit-reached: single sign-on never buys a seat, so nothing is written, the next sign-in asks again and the sign-in is refused); 503 (onboarding-unavailable, or the identity provider could not confirm the person); 500 server faults.

curl

curl "https://console.us.ccsio.ai/identity/v1/onboarding" \
  -H "Authorization: Bearer $CCSIO_ACCESS_TOKEN"

Parameters

Name	In	Description
`X-Request-ID` optional	header	string Optional request ULID. A valid ULID (upper or lowercase) is honored; when the header is absent or invalid, the runtime mints the id. The response X-Request-ID header carries the canonical uppercase form.

Responses

200
The organizations the person can reach, and whether this plane can create one for them.
Schema
OnboardingOrganizationsResponse
organizationsarray of OnboardingOrganizationrequired
organization_idstringrequired
at least 1 characters
display_namestringrequired
aliasOrganizationAlias or nullrequired
The organization's alias; null while it has none (an alias exists only for an organization with single sign-on).
residencystringrequired
Allowed values: "eu""us""latam"
statusstringrequired
Allowed values: "provisioning""active""suspended""disabled""deleted"
registration_availablebooleanrequired
Whether this plane can create organizations for the caller's identity provider.
registration_residenciesarray of stringrequired
The residencies this plane offers for sign-up: its own when registration_available is true, otherwise empty.
Allowed values: "eu""us""latam"
400
Client refusal unrelated to authentication, including malformed input, a denied or failed request.
401
The human OIDC access token is missing or invalid.
403
A service or bootstrap credential, or an identity that cannot onboard: its account is disabled, its provider email is not verified yet (email-verification-required), or its first sign-in through the organization's own single sign-on would need a seat above the plan's included ones (seat-limit-reached).
405
The path is claimed but the request method is not allowed. Go ServeMux returns its standard plain-text response and lists permitted methods in Allow.
500
Platform failure, rendered without internal cause details.
503
Sign-up is disabled on this plane, or the identity provider could not confirm the person's identity or status.

POST/identity/v1/onboarding

Create an organization for the signed-in human

Credential: A signed-in person’s token (Console session)
Permission: None beyond the credential
Request body: Body up to 1 MiB

Provisions one organization at the identity provider, with its local tenant record and the caller's root membership, as an idempotent operation.

The owner is derived from the verified token: no client owner, role, organization id, placement identifiers or alias are accepted (an alias exists only for an organization with single sign-on, which a new organization never has). The residency must be served by this plane. Send an Idempotency-Key and keep it for retries: the same key and body resume a pending step and return the organization once it is complete (200), while the same key with another body is 409 onboarding-conflict. A new organization is 201; one whose creation is still pending is 202 with Retry-After. API keys and bootstrap credentials are refused. Failures: 400 invalid-request (a member missing or unknown, the Idempotency-Key outside 16 to 128 characters, or a residency this plane does not serve); 400 organization-invalid (display_name over 128 bytes); 401; 403 (a service or bootstrap credential, or an unavailable or disabled human identity; email-verification-required for a public-registration account whose email is not verified yet); 409 onboarding-conflict; 503 onboarding-unavailable or organization-identity-unavailable; 500 server faults.

curl

curl -X POST "https://console.us.ccsio.ai/identity/v1/onboarding" \
  -H "Authorization: Bearer $CCSIO_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "display_name": "string",
  "residency": "eu"
}'

Built from the schema’s required members: replace the values.

Parameters

Name	In	Description
`X-Request-ID` optional	header	string Optional request ULID. A valid ULID (upper or lowercase) is honored; when the header is absent or invalid, the runtime mints the id. The response X-Request-ID header carries the canonical uppercase form.
`Idempotency-Key` required	header	string An opaque operation key scoped to the verified account, 16 to 128 characters (anything else is refused with 400 invalid-request). Send the same key on every retry of the same sign-up.

Request body application/json

OnboardingOrganizationRequest

display_namestringrequired
The organization's display name, trimmed: 1 to 128 bytes of UTF-8 (a multi-byte character counts for each of its bytes).
1 to 128 characters
residencystringrequired
The data residency. It must be the one this plane serves (400 invalid-request otherwise): GET /identity/v1/onboarding lists it in registration_residencies.
Allowed values: "eu""us""latam"

Responses

200
The organization, already complete, returned on a retry.
Schema
OnboardingOrganization
organization_idstringrequired
at least 1 characters
display_namestringrequired
aliasstring or nullrequired
The organization's alias; null while it has none (an alias exists only for an organization with single sign-on).
3 to 63 characters · pattern ^[a-z0-9](?:[a-z0-9-]{1,61}[a-z0-9])$
residencystringrequired
Allowed values: "eu""us""latam"
statusstringrequired
Allowed values: "provisioning""active""suspended""disabled""deleted"
201
The new organization and the caller's root membership are ready.
Schema
OnboardingOrganization
organization_idstringrequired
at least 1 characters
display_namestringrequired
aliasstring or nullrequired
The organization's alias; null while it has none (an alias exists only for an organization with single sign-on).
3 to 63 characters · pattern ^[a-z0-9](?:[a-z0-9-]{1,61}[a-z0-9])$
residencystringrequired
Allowed values: "eu""us""latam"
statusstringrequired
Allowed values: "provisioning""active""suspended""disabled""deleted"
202
Provisioning is pending; retry the same operation.
Schema
OnboardingOrganization
organization_idstringrequired
at least 1 characters
display_namestringrequired
aliasstring or nullrequired
The organization's alias; null while it has none (an alias exists only for an organization with single sign-on).
3 to 63 characters · pattern ^[a-z0-9](?:[a-z0-9-]{1,61}[a-z0-9])$
residencystringrequired
Allowed values: "eu""us""latam"
statusstringrequired
Allowed values: "provisioning""active""suspended""disabled""deleted"
400
Client refusal unrelated to authentication, including malformed input, a denied or failed request.
401
The human OIDC access token is missing or invalid.
403
A service or bootstrap credential, or an identity that cannot onboard: its account is disabled, or its provider email is not verified yet (email-verification-required).
405
The path is claimed but the request method is not allowed. Go ServeMux returns its standard plain-text response and lists permitted methods in Allow.
409
This Idempotency-Key is already bound to a different request (onboarding-conflict).
500
Platform failure, rendered without internal cause details.
503
Sign-up is disabled on this plane, or the identity provider could not provision the organization or confirm its status.

Generated from the platform contracts at commit 5f833620.

Register a human and organization with email verification

Parameters

Request body application/json

Responses

Discover the signed-in human's organizations

Parameters

Responses

Create an organization for the signed-in human

Parameters

Request body application/json

Responses

Get your first API key