Die Beschreibungen der Operationen und Felder stammen aus dem Vertrag und sind auf Englisch.
/identity/v1/registrationsRegister a human and organization with email verification
- Anmeldedaten
- Keine: eine öffentliche Operation
- Berechtigung
- Keine außer den Anmeldedaten
- Request-Body
- Body bis 16384 bytes
Public: it takes no credential, and it is available only on a plane where sign-up is configured (503 onboarding-unavailable otherwise).
Weiterlesen
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 -X POST "https://console.eu.ccsio.ai/identity/v1/registrations" \
-H "Content-Type: application/json" \
-d '{
"request_id": "string",
"first_name": "string",
"last_name": "string",
"email": "ada@example.com",
"password": "string"
}'Parameter
| Name | In | Beschreibung |
|---|---|---|
X-Request-IDoptional | 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
request_idstring (uuid)PflichtA random UUID (version 1 to 8) the client generates for this registration and keeps for uncertain retries.
organization_namestringoptionalThe organization's display name, trimmed: 1 to 128 bytes of UTF-8 (a multi-byte character counts for each of its bytes). Required unless kind is 'personal'.
1 to 128 characters
first_namestringPflichtThe owner's first name, trimmed: 1 to 200 characters.
1 to 200 characters
last_namestringPflichtThe owner's last name, trimmed: 1 to 200 characters.
1 to 200 characters
emailstring (email)PflichtThe 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
passwordstringPflichtThe 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
kindstringoptional'personal' registers an individual: the organization names itself after its owner (organization_name must then be absent, 400 registration-invalid otherwise), holds exactly one human member, and carries the personal plan as a pending subscription the owner must pay after email verification. Absent means 'organization'.
Erlaubte Werte:
"organization""personal"default "organization"
Antworten
- 202
Check the verification email, then sign in. An identical successful retry returns the same response.
Schema
PublicRegistrationResponsestatusstringPflichtThe person must verify the email address the provider sent, then sign in.
Erlaubte Werte:
"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.
/identity/v1/registrations/email-verificationVerify the email address of a public registration
- Anmeldedaten
- Keine: eine öffentliche Operation
- Berechtigung
- Keine außer den Anmeldedaten
- Request-Body
- Body bis 4096 bytes
Public: it takes no credential, and it is available only on a plane where sign-up is configured (503 onboarding-unavailable otherwise).
Weiterlesen
The console calls it from the page the verification email links to (CONTROL_CONSOLE_URL/verify-email/confirm), with the user and the code of that link, so the person never lands on the identity provider's own success page. Only a subject that began a public registration on this plane is verified; any other subject, a wrong code and an expired code are the same 400 email-verification-invalid, which never discloses whether the subject exists. An address that is already verified answers 200 verified, so a link opened twice (by a mail scanner, or a second click) still continues to the console. No membership or session is issued: the person signs in through ordinary OIDC sign-in, and the first GET /identity/v1/onboarding after that finalizes the organization. Two budgets are shared by all replicas: 60 attempts per minute for the plane and 10 per subject per hour (429 email-verification-rate-limited, with Retry-After). The body is strict JSON of at most 4 KiB. Failures: 400 email-verification-invalid; 413 email-verification-invalid (the body is over 4 KiB); 429 email-verification-rate-limited; 503 onboarding-unavailable or organization-identity-unavailable.
curl -X POST "https://console.eu.ccsio.ai/identity/v1/registrations/email-verification" \
-H "Content-Type: application/json" \
-d '{
"user_id": "string",
"code": "string"
}'Parameter
| Name | In | Beschreibung |
|---|---|---|
X-Request-IDoptional | 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
user_idstringPflichtThe subject the verification email names (its userId): the identity a public registration created on this plane.
pattern ^cp-user-[0-9A-HJKMNP-TV-Z]{26}$
codestringPflichtThe verification code of the link, as the identity provider generated it.
1 to 64 characters · pattern ^[0-9A-Za-z]+$
Antworten
- 200
The email address is verified: now, or already before this request.
Schema
EmailVerificationResponsestatusstringPflichtverified: the address is verified, sign in to continue; sent: a new verification email is on its way.
Erlaubte Werte:
"verified""sent"
- 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.
- 413
The request is over 4 KiB.
- 429
A shared verification budget is used up: the plane's, or the subject'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.
/identity/v1/registrations/email-verification/codeSend a new verification email for a public registration
- Anmeldedaten
- Keine: eine öffentliche Operation
- Berechtigung
- Keine außer den Anmeldedaten
- Request-Body
- Body bis 4096 bytes
Public: it takes no credential, and it is available only on a plane where sign-up is configured (503 onboarding-unavailable otherwise). The console's recovery for an expired or invalid verification link: the identity provider sends a new code, in a message that links to the console again.
Weiterlesen
A subject with no public registration on this plane is answered 202 sent exactly as one that has one, and nothing is sent: the answer never discloses whether the subject exists. An address that is already verified answers 200 verified and sends nothing. It shares the budgets of POST /identity/v1/registrations/email-verification (429 email-verification-rate-limited, with Retry-After). The body is strict JSON of at most 4 KiB. Failures: 400 email-verification-invalid; 413 email-verification-invalid (the body is over 4 KiB); 429 email-verification-rate-limited; 503 onboarding-unavailable or organization-identity-unavailable.
curl -X POST "https://console.eu.ccsio.ai/identity/v1/registrations/email-verification/code" \
-H "Content-Type: application/json" \
-d '{
"user_id": "string"
}'Parameter
| Name | In | Beschreibung |
|---|---|---|
X-Request-IDoptional | 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
user_idstringPflichtThe subject the verification email names (its userId): the identity a public registration created on this plane.
pattern ^cp-user-[0-9A-HJKMNP-TV-Z]{26}$
Antworten
- 200
The email address is already verified; nothing was sent.
Schema
EmailVerificationResponsestatusstringPflichtverified: the address is verified, sign in to continue; sent: a new verification email is on its way.
Erlaubte Werte:
"verified""sent"
- 202
A new verification email is on its way, if the subject began a public registration on this plane.
Schema
EmailVerificationResponsestatusstringPflichtverified: the address is verified, sign in to continue; sent: a new verification email is on its way.
Erlaubte Werte:
"verified""sent"
- 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.
- 413
The request is over 4 KiB.
- 429
A shared verification budget is used up: the plane's, or the subject'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.
/identity/v1/onboardingDiscover the signed-in human's organizations
- Anmeldedaten
- Token einer angemeldeten Person (Console-Sitzung)
- Berechtigung
- Keine außer den Anmeldedaten
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.
Weiterlesen
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 "https://console.eu.ccsio.ai/identity/v1/onboarding" \
-H "Authorization: Bearer $CCSIO_ACCESS_TOKEN"Parameter
| Name | In | Beschreibung |
|---|---|---|
X-Request-IDoptional | 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. |
Antworten
- 200
The organizations the person can reach, and whether this plane can create one for them.
Schema
OnboardingOrganizationsResponseorganizationsarray of OnboardingOrganizationPflichtorganization_idstringPflichtat least 1 characters
display_namestringPflichtaliasOrganizationAlias or nullPflichtThe organization's alias; null while it has none (an alias exists only for an organization with single sign-on).
residencystringPflichtErlaubte Werte:
"eu""us""latam"statusstringPflichtErlaubte Werte:
"provisioning""active""suspended""disabled""deleted"kindstringPflichtWhat the organization is: 'organization' is an ordinary company tenant; 'personal' is one person's own organization (AI-279) — exactly one human member, no invitation, and the personal plan as its billing unit.
Erlaubte Werte:
"organization""personal"
registration_availablebooleanPflichtWhether this plane can create organizations for the caller's identity provider.
registration_residenciesarray of stringPflichtThe residencies this plane offers for sign-up: its own when registration_available is true, otherwise empty.
Erlaubte Werte:
"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.
/identity/v1/onboardingCreate an organization for the signed-in human
- Anmeldedaten
- Token einer angemeldeten Person (Console-Sitzung)
- Berechtigung
- Keine außer den Anmeldedaten
- Request-Body
- Body bis 1 MiB
Provisions one organization at the identity provider, with its local tenant record and the caller's root membership, as an idempotent operation.
Weiterlesen
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 -X POST "https://console.eu.ccsio.ai/identity/v1/onboarding" \
-H "Authorization: Bearer $CCSIO_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"residency": "eu"
}'Parameter
| Name | In | Beschreibung |
|---|---|---|
X-Request-IDoptional | 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-KeyPflicht | 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
display_namestringoptionalThe organization's display name, trimmed: 1 to 128 bytes of UTF-8 (a multi-byte character counts for each of its bytes). Required unless kind is 'personal'; for a personal organization it must be absent (400 invalid-request otherwise): the name comes from the owner.
1 to 128 characters
residencystringPflichtThe data residency. It must be the one this plane serves (400 invalid-request otherwise): GET /identity/v1/onboarding lists it in registration_residencies.
Erlaubte Werte:
"eu""us""latam"kindstringoptional'personal' registers a personal organization for the caller: no display name is typed (it names itself after its owner), the organization holds exactly one human member, and it carries the personal plan as a pending subscription the owner must pay before the platform serves it. Absent means 'organization'.
Erlaubte Werte:
"organization""personal"default "organization"
Antworten
- 200
The organization, already complete, returned on a retry.
Schema
OnboardingOrganizationorganization_idstringPflichtat least 1 characters
display_namestringPflichtaliasstring or nullPflichtThe 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])$
residencystringPflichtErlaubte Werte:
"eu""us""latam"statusstringPflichtErlaubte Werte:
"provisioning""active""suspended""disabled""deleted"kindstringPflichtWhat the organization is: 'organization' is an ordinary company tenant; 'personal' is one person's own organization (AI-279) — exactly one human member, no invitation, and the personal plan as its billing unit.
Erlaubte Werte:
"organization""personal"
- 201
The new organization and the caller's root membership are ready.
Schema
OnboardingOrganizationorganization_idstringPflichtat least 1 characters
display_namestringPflichtaliasstring or nullPflichtThe 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])$
residencystringPflichtErlaubte Werte:
"eu""us""latam"statusstringPflichtErlaubte Werte:
"provisioning""active""suspended""disabled""deleted"kindstringPflichtWhat the organization is: 'organization' is an ordinary company tenant; 'personal' is one person's own organization (AI-279) — exactly one human member, no invitation, and the personal plan as its billing unit.
Erlaubte Werte:
"organization""personal"
- 202
Provisioning is pending; retry the same operation.
Schema
OnboardingOrganizationorganization_idstringPflichtat least 1 characters
display_namestringPflichtaliasstring or nullPflichtThe 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])$
residencystringPflichtErlaubte Werte:
"eu""us""latam"statusstringPflichtErlaubte Werte:
"provisioning""active""suspended""disabled""deleted"kindstringPflichtWhat the organization is: 'organization' is an ordinary company tenant; 'personal' is one person's own organization (AI-279) — exactly one human member, no invitation, and the personal plan as its billing unit.
Erlaubte Werte:
"organization""personal"
- 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.
Erzeugt aus den Plattformverträgen beim Commit 5954fbc1.