Onboarding

Las descripciones de las operaciones y los campos son las del contrato, en inglés.

POST/identity/v1/registrations

Register a human and organization with email verification

Credencial: Ninguna: una operación pública
Permiso: Ninguno además de la credencial
Cuerpo de la solicitud: Cuerpo de hasta 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.latam.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"
}'

Construido con los campos obligatorios del esquema: reemplaza los valores.

Parámetros

Nombre	En	Descripción
`X-Request-ID` opcional	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.

Cuerpo de la solicitud application/json

PublicRegistrationRequest

request_idstring (uuid)obligatorio
A random UUID (version 1 to 8) the client generates for this registration and keeps for uncertain retries.
organization_namestringobligatorio
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_namestringobligatorio
The owner's first name, trimmed: 1 to 200 characters.
1 to 200 characters
last_namestringobligatorio
The owner's last name, trimmed: 1 to 200 characters.
1 to 200 characters
emailstring (email)obligatorio
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
passwordstringobligatorio
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

Respuestas

202
Check the verification email, then sign in. An identical successful retry returns the same response.
Esquema
PublicRegistrationResponse
statusstringobligatorio
The person must verify the email address the provider sent, then sign in.
Valores permitidos: "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

Credencial: El token de una persona con sesión iniciada (consola)
Permiso: Ninguno además de la credencial

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.latam.ccsio.ai/identity/v1/onboarding" \
  -H "Authorization: Bearer $CCSIO_ACCESS_TOKEN"

Parámetros

Nombre	En	Descripción
`X-Request-ID` opcional	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.

Respuestas

200
The organizations the person can reach, and whether this plane can create one for them.
Esquema
OnboardingOrganizationsResponse
organizationsarray of OnboardingOrganizationobligatorio
organization_idstringobligatorio
at least 1 characters
display_namestringobligatorio
aliasOrganizationAlias or nullobligatorio
The organization's alias; null while it has none (an alias exists only for an organization with single sign-on).
residencystringobligatorio
Valores permitidos: "eu""us""latam"
statusstringobligatorio
Valores permitidos: "provisioning""active""suspended""disabled""deleted"
registration_availablebooleanobligatorio
Whether this plane can create organizations for the caller's identity provider.
registration_residenciesarray of stringobligatorio
The residencies this plane offers for sign-up: its own when registration_available is true, otherwise empty.
Valores permitidos: "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

Credencial: El token de una persona con sesión iniciada (consola)
Permiso: Ninguno además de la credencial
Cuerpo de la solicitud: Cuerpo de hasta 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.latam.ccsio.ai/identity/v1/onboarding" \
  -H "Authorization: Bearer $CCSIO_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "display_name": "string",
  "residency": "eu"
}'

Construido con los campos obligatorios del esquema: reemplaza los valores.

Parámetros

Nombre	En	Descripción
`X-Request-ID` opcional	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` obligatorio	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.

Cuerpo de la solicitud application/json

OnboardingOrganizationRequest

display_namestringobligatorio
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
residencystringobligatorio
The data residency. It must be the one this plane serves (400 invalid-request otherwise): GET /identity/v1/onboarding lists it in registration_residencies.
Valores permitidos: "eu""us""latam"

Respuestas

200
The organization, already complete, returned on a retry.
Esquema
OnboardingOrganization
organization_idstringobligatorio
at least 1 characters
display_namestringobligatorio
aliasstring or nullobligatorio
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])$
residencystringobligatorio
Valores permitidos: "eu""us""latam"
statusstringobligatorio
Valores permitidos: "provisioning""active""suspended""disabled""deleted"
201
The new organization and the caller's root membership are ready.
Esquema
OnboardingOrganization
organization_idstringobligatorio
at least 1 characters
display_namestringobligatorio
aliasstring or nullobligatorio
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])$
residencystringobligatorio
Valores permitidos: "eu""us""latam"
statusstringobligatorio
Valores permitidos: "provisioning""active""suspended""disabled""deleted"
202
Provisioning is pending; retry the same operation.
Esquema
OnboardingOrganization
organization_idstringobligatorio
at least 1 characters
display_namestringobligatorio
aliasstring or nullobligatorio
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])$
residencystringobligatorio
Valores permitidos: "eu""us""latam"
statusstringobligatorio
Valores permitidos: "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.

Generado a partir de los contratos de la plataforma en el commit 5f833620.

Register a human and organization with email verification

Parámetros

Cuerpo de la solicitud application/json

Respuestas

Discover the signed-in human's organizations

Parámetros

Respuestas

Create an organization for the signed-in human

Parámetros

Cuerpo de la solicitud application/json

Respuestas

Obtén tu primera key API