Die Beschreibungen der Operationen und Felder stammen aus dem Vertrag und sind auf Englisch.
/identity/v1/organizationsList organizations
- Anmeldedaten
- API-Key
- Berechtigung
organization.read
Lists organizations deterministic by organization id. The list projection carries no placement (rendered null). Failures: 500 server faults; no 400/404 class applies to a global list. Needs organization.read in the caller's own organization (a platform operator holds it at platform level).
curl "https://console.eu.ccsio.ai/identity/v1/organizations" \
-H "Authorization: Bearer $CCSIO_API_KEY"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 organization list (views without placement).
Schema
ListOrganizationsResponseorganizationsarray of OrganizationPflichtorganization_idstringPflichtpattern ^[a-z][a-z0-9._-]{0,63}$
display_namestringPflicht1 to 128 characters
created_atstring (date-time)PflichtRFC 3339, second precision, UTC.
placementPlacement or nullPflichtThe placement; null in the list projection (the list carries no placement).
- 400
Client refusal unrelated to authentication, including malformed input, a denied or failed request.
- 401
The request carries no credential, more than one, or one the platform does not accept, and is refused before the operation runs; `error.code` says why. Supply exactly one credential. Codes: invalid-request (no credential, or both Authorization:
Weiterlesen
Bearer and x-api-key), api-key-invalid (a value that is not a platform API key, or a key of a kind the platform does not accept), api-key-unknown, api-key-revoked, api-key-expired, bootstrap-disabled (the one-shot installation credential, once a key exists), token-malformed (a bearer token that is not a JWT), token-algorithm-unsupported, token-signature-invalid, token-claim-invalid, token-issuer-mismatch, token-audience-mismatch, token-expired, token-not-yet-valid, issuer-untrusted, issuer-residency-mismatch (the issuer belongs to another plane), issuer-resolution-unknown, jwks-unavailable, jwks-key-not-found, staff-token-inactive (a platform operator's token), staff-not-operator, staff-directory-unavailable, identity-not-provisioned (a verified identity with no account on this plane), organization-not-found (a verified identity or key whose organization this plane does not know), internal-error (a fault while the credential is checked is refused too, fail closed), context-cancelled
- 402
The organization has to pay first: its standing is payment_required.
Weiterlesen
The request boundary applies this payment gate to every route except an organization's billing routes, the caller's own context, organization list, onboarding, session report and personal keys, the public routes, and the routes of platform operators, who administer an organization that has to pay. The operations the gate covers declare this response. On /v1 the refusal is rendered in the OpenAI error format. Code: payment-required
- 403
The credential is valid but may not do this here; the request is refused by the request boundary before the handler runs, and `error.code` says which refusal. An operation may add codes of its own.
Weiterlesen
Codes: policy-denied (no role of the caller holds the permission the operation needs, or the credential class may not call it: a personal API key outside inference and MCP, a route that needs a signed-in person, the one-shot installation credential outside its three steps), tenant-mismatch (the organization a path, query, body or X-Tenant header names is not the caller's own), organization-provisioning, organization-suspended, organization-disabled, organization-deleted (the state of the caller's organization), user-disabled, residency-mismatch (the organization lives on another plane), organization-selection-required (a caller with more than one organization, or a platform operator, must name one in X-Organization-Id), organization-not-selectable, no-active-organization-membership, team-not-selectable (the X-Organization-Id or X-Team-Id the caller sent does not name an organization or team it may act in), identity-managed-by-provider (a person who is not a platform operator changes an organization's status, which belongs to the identity provider), support-session-required (a platform operator reads an organization's data without an open support session)
- 404
The requested resource or path was not found.
- 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.
/identity/v1/organizations/{org}Read an organization with its placement
- Anmeldedaten
- API-Key
- Berechtigung
organization.read
The organization DETAIL view: the create and list fields plus alias, status, metadata and updated_at, with its placement (never null here). Failures: 400 name-invalid (path value outside the C7 pattern); 404 organization-not-found; 500 server faults.
Weiterlesen
Needs organization.read in the route's organization, which must be the organization the request resolved to: a platform operator selects it with X-Organization-Id (any existing organization) and holds the permission whether or not they are a member.
curl "https://console.eu.ccsio.ai/identity/v1/organizations/{org}" \
-H "Authorization: Bearer $CCSIO_API_KEY"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. |
orgPflicht | path | string The organization id (C7 identifier). A value outside the pattern is refused with 400 name-invalid. |
Antworten
- 200
The organization detail view with its placement.
Schema
OrganizationDetailorganization_idstringPflichtpattern ^[a-z][a-z0-9._-]{0,63}$
display_namestringPflicht1 to 128 characters
aliasstring or nullPflichtThe organization's alias (its sign-in link is <console>/<alias>); null while it has none - an alias exists only while the organization has an enabled single sign-on connection, and removing or disabling the connection releases it. Editable through PATCH; the organization_id never changes.
3 to 63 characters · pattern ^[a-z0-9](?:[a-z0-9-]{1,61}[a-z0-9])$
statusstringPflichtdeleted is the terminal soft-deleted state: only DELETE /identity/v1/organizations/{org} enters it, never the status transition route.
Erlaubte Werte:
"provisioning""active""suspended""disabled""deleted"metadataobjectPflichtcreated_atstring (date-time)PflichtRFC 3339, second precision, UTC.
updated_atstring (date-time)PflichtRFC 3339, second precision, UTC.
placementobject or nullPflichtThe placement (never null on this operation's response).
residencystringPflichtpattern ^[a-z][a-z0-9._-]{0,63}$
data_regionstringPflichtpattern ^[a-z][a-z0-9._-]{0,63}$
operational_cluster_idstringPflichtpattern ^[a-z][a-z0-9._-]{0,63}$
knowledge_cluster_idstringPflichtpattern ^[a-z][a-z0-9._-]{0,63}$
search_cluster_idstringPflichtpattern ^[a-z][a-z0-9._-]{0,63}$
object_store_idstringPflichtpattern ^[a-z][a-z0-9._-]{0,63}$
placement_modestringPflichtErlaubte Werte:
"auto""pinned"updated_atstring (date-time)PflichtRFC 3339, second precision, UTC.
- 400
Client refusal unrelated to authentication, including malformed input, a denied or failed request.
- 401
The request carries no credential, more than one, or one the platform does not accept, and is refused before the operation runs; `error.code` says why. Supply exactly one credential. Codes: invalid-request (no credential, or both Authorization:
Weiterlesen
Bearer and x-api-key), api-key-invalid (a value that is not a platform API key, or a key of a kind the platform does not accept), api-key-unknown, api-key-revoked, api-key-expired, bootstrap-disabled (the one-shot installation credential, once a key exists), token-malformed (a bearer token that is not a JWT), token-algorithm-unsupported, token-signature-invalid, token-claim-invalid, token-issuer-mismatch, token-audience-mismatch, token-expired, token-not-yet-valid, issuer-untrusted, issuer-residency-mismatch (the issuer belongs to another plane), issuer-resolution-unknown, jwks-unavailable, jwks-key-not-found, staff-token-inactive (a platform operator's token), staff-not-operator, staff-directory-unavailable, identity-not-provisioned (a verified identity with no account on this plane), organization-not-found (a verified identity or key whose organization this plane does not know), internal-error (a fault while the credential is checked is refused too, fail closed), context-cancelled
- 402
The organization has to pay first: its standing is payment_required.
Weiterlesen
The request boundary applies this payment gate to every route except an organization's billing routes, the caller's own context, organization list, onboarding, session report and personal keys, the public routes, and the routes of platform operators, who administer an organization that has to pay. The operations the gate covers declare this response. On /v1 the refusal is rendered in the OpenAI error format. Code: payment-required
- 403
The credential is valid but may not do this here; the request is refused by the request boundary before the handler runs, and `error.code` says which refusal. An operation may add codes of its own.
Weiterlesen
Codes: policy-denied (no role of the caller holds the permission the operation needs, or the credential class may not call it: a personal API key outside inference and MCP, a route that needs a signed-in person, the one-shot installation credential outside its three steps), tenant-mismatch (the organization a path, query, body or X-Tenant header names is not the caller's own), organization-provisioning, organization-suspended, organization-disabled, organization-deleted (the state of the caller's organization), user-disabled, residency-mismatch (the organization lives on another plane), organization-selection-required (a caller with more than one organization, or a platform operator, must name one in X-Organization-Id), organization-not-selectable, no-active-organization-membership, team-not-selectable (the X-Organization-Id or X-Team-Id the caller sent does not name an organization or team it may act in), identity-managed-by-provider (a person who is not a platform operator changes an organization's status, which belongs to the identity provider), support-session-required (a platform operator reads an organization's data without an open support session)
- 404
The requested resource or path was not found.
- 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.
/identity/v1/organizations/{org}Update an organization's allowed properties
- Anmeldedaten
- API-Key
- Berechtigung
organization.update- Request-Body
- Body bis 1 MiB
Changes the properties of an organization that may change: display_name, alias and metadata, all optional (a request that names none is a legal no-op, and a member sent as null is the same as one left out).
Weiterlesen
Needs organization.update in the route's organization (the Root and Organization Admin roles hold it). alias sets or renames the organization's public alias, which is unique across the plane, validated and checked against the reserved words, and never the organization id (the id does not change). An alias exists only for an organization with an ENABLED single sign-on connection: setting or changing one without it is refused with 409 alias-requires-sso (an alias the organization already holds is left alone by other updates). Changing the alias records the organization.updated security event with the details alias_from and alias_to. residency and organization_id are immutable after provisioning: naming either at all (any value, including the current one) is refused with 409 organization-immutable-field. Failures: 400 invalid-request (an unknown member, or a body that is not strict JSON); 400 name-invalid (the path organization is outside the C7 pattern); 400 organization-invalid (display_name out of range, or metadata outside its key, value and entry limits); 400 alias-invalid / alias-reserved; 404 organization-not-found; 409 organization-immutable-field / alias-taken / alias-requires-sso; 500 server faults.
curl -X PATCH "https://console.eu.ccsio.ai/identity/v1/organizations/{org}" \
-H "Authorization: Bearer $CCSIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'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. |
orgPflicht | path | string The organization id (C7 identifier). A value outside the pattern is refused with 400 name-invalid. |
Request-Body application/json
display_namestringoptionalThe new display name, 1 to 128 bytes of UTF-8 (a multi-byte character counts for each of its bytes).
1 to 128 characters
aliasstringoptionalSets or renames the organization's alias: unique across the plane, never the organization id. The server trims and lower-cases the value before it checks it against the shape of OrganizationAlias, so ACME-Co is stored as acme-co. Only an organization with an ENABLED single sign-on connection can hold an alias: 409 alias-requires-sso otherwise. The old alias is released at once and its sign-in link stops working. 409 alias-taken, 400 alias-reserved, 400 alias-invalid. A change is recorded in the security event log as organization.updated, with the details alias_from (left out when there was none) and alias_to.
metadataobjectoptionalReplaces the metadata wholesale (an empty object clears it); left out, it is unchanged. At most 32 entries, keys of 1 to 64 bytes, values of at most 256 bytes (400 organization-invalid otherwise). It is shown to every reader of the organization: put no secrets in it.
residencystringoptionalImmutable. Naming this member at all, with any value, is refused with 409 organization-immutable-field.
organization_idstringoptionalImmutable. Naming this member at all, with any value, is refused with 409 organization-immutable-field.
Antworten
- 200
The updated organization detail view.
Schema
OrganizationDetailorganization_idstringPflichtpattern ^[a-z][a-z0-9._-]{0,63}$
display_namestringPflicht1 to 128 characters
aliasstring or nullPflichtThe organization's alias (its sign-in link is <console>/<alias>); null while it has none - an alias exists only while the organization has an enabled single sign-on connection, and removing or disabling the connection releases it. Editable through PATCH; the organization_id never changes.
3 to 63 characters · pattern ^[a-z0-9](?:[a-z0-9-]{1,61}[a-z0-9])$
statusstringPflichtdeleted is the terminal soft-deleted state: only DELETE /identity/v1/organizations/{org} enters it, never the status transition route.
Erlaubte Werte:
"provisioning""active""suspended""disabled""deleted"metadataobjectPflichtcreated_atstring (date-time)PflichtRFC 3339, second precision, UTC.
updated_atstring (date-time)PflichtRFC 3339, second precision, UTC.
placementobject or nullPflichtThe placement (never null on this operation's response).
residencystringPflichtpattern ^[a-z][a-z0-9._-]{0,63}$
data_regionstringPflichtpattern ^[a-z][a-z0-9._-]{0,63}$
operational_cluster_idstringPflichtpattern ^[a-z][a-z0-9._-]{0,63}$
knowledge_cluster_idstringPflichtpattern ^[a-z][a-z0-9._-]{0,63}$
search_cluster_idstringPflichtpattern ^[a-z][a-z0-9._-]{0,63}$
object_store_idstringPflichtpattern ^[a-z][a-z0-9._-]{0,63}$
placement_modestringPflichtErlaubte Werte:
"auto""pinned"updated_atstring (date-time)PflichtRFC 3339, second precision, UTC.
- 400
Client refusal unrelated to authentication, including malformed input, a denied or failed request.
- 401
The request carries no credential, more than one, or one the platform does not accept, and is refused before the operation runs; `error.code` says why. Supply exactly one credential. Codes: invalid-request (no credential, or both Authorization:
Weiterlesen
Bearer and x-api-key), api-key-invalid (a value that is not a platform API key, or a key of a kind the platform does not accept), api-key-unknown, api-key-revoked, api-key-expired, bootstrap-disabled (the one-shot installation credential, once a key exists), token-malformed (a bearer token that is not a JWT), token-algorithm-unsupported, token-signature-invalid, token-claim-invalid, token-issuer-mismatch, token-audience-mismatch, token-expired, token-not-yet-valid, issuer-untrusted, issuer-residency-mismatch (the issuer belongs to another plane), issuer-resolution-unknown, jwks-unavailable, jwks-key-not-found, staff-token-inactive (a platform operator's token), staff-not-operator, staff-directory-unavailable, identity-not-provisioned (a verified identity with no account on this plane), organization-not-found (a verified identity or key whose organization this plane does not know), internal-error (a fault while the credential is checked is refused too, fail closed), context-cancelled
- 402
The organization has to pay first: its standing is payment_required.
Weiterlesen
The request boundary applies this payment gate to every route except an organization's billing routes, the caller's own context, organization list, onboarding, session report and personal keys, the public routes, and the routes of platform operators, who administer an organization that has to pay. The operations the gate covers declare this response. On /v1 the refusal is rendered in the OpenAI error format. Code: payment-required
- 403
The credential is valid but may not do this here; the request is refused by the request boundary before the handler runs, and `error.code` says which refusal. An operation may add codes of its own.
Weiterlesen
Codes: policy-denied (no role of the caller holds the permission the operation needs, or the credential class may not call it: a personal API key outside inference and MCP, a route that needs a signed-in person, the one-shot installation credential outside its three steps), tenant-mismatch (the organization a path, query, body or X-Tenant header names is not the caller's own), organization-provisioning, organization-suspended, organization-disabled, organization-deleted (the state of the caller's organization), user-disabled, residency-mismatch (the organization lives on another plane), organization-selection-required (a caller with more than one organization, or a platform operator, must name one in X-Organization-Id), organization-not-selectable, no-active-organization-membership, team-not-selectable (the X-Organization-Id or X-Team-Id the caller sent does not name an organization or team it may act in), identity-managed-by-provider (a person who is not a platform operator changes an organization's status, which belongs to the identity provider), support-session-required (a platform operator reads an organization's data without an open support session)
- 404
The requested resource or path was not found.
- 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 request conflicts with the current state of the resource or with an invariant it protects (a taken name, a role still in use, an organization that must not be deleted, an archived team, the last active root, a seat or service account limit).
- 500
Platform failure, rendered without internal cause details.
/identity/v1/organizations/{org}Delete (soft) an organization
- Anmeldedaten
- API-Key
- Berechtigung
organization.delete- Request-Body
- Body bis 1 MiB
Requires organization.delete: held by the organization's root alone (and the platform ccsio_admin: an authority-stamped API key, or a human platform operator who selected this organization with X-Organization-Id) — organization_admin is refused (403 policy-denied).
Weiterlesen
The body must carry the organization's slug as confirm (400 confirmation-mismatch otherwise, nothing changes). In ONE transaction the organization becomes the terminal status deleted (deleted_at, deleted_by recorded) and every API key of it — service-account and personal — is revoked; memberships and audit rows are kept. The organization is then inaccessible everywhere exactly like a non-active one (tenant resolution, /v1, every control route; platform ccsio_admin keeps read access to its record). Afterwards the linked Zitadel organization is deactivated (POST /v2/organizations/{id}/deactivate); if that fails the local delete stands, provider_deactivation reports failed and a repeated DELETE retries it. Idempotent: deleting an already-deleted organization answers 200 with the same body (platform administrators and in-flight retries reach it; an ordinary member's session is refused with 403 organization-deleted or no-active-organization-membership, which after a delete attempt means the delete completed). An organization still holding an active platform credential cannot be deleted (409 organization-protected). Sensitive: audited. Failures: 400 invalid-request; 400 confirmation-mismatch; 403 policy-denied / organization-delete-forbidden; 404 organization-not-found; 409 organization-protected; 500 server faults.
curl -X DELETE "https://console.eu.ccsio.ai/identity/v1/organizations/{org}" \
-H "Authorization: Bearer $CCSIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"confirm": "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. |
orgPflicht | path | string The organization id (C7 identifier). A value outside the pattern is refused with 400 name-invalid. |
Request-Body application/json
confirmstringPflichtThe organization's slug (its organization_id). Anything else is 400 confirmation-mismatch and nothing changes.
pattern ^[a-z][a-z0-9._-]{0,63}$
Antworten
- 200
The organization representation, status deleted, plus the provider step's outcome.
Schema
DeletedOrganizationorganization_idstringPflichtpattern ^[a-z][a-z0-9._-]{0,63}$
display_namestringPflicht1 to 128 characters
aliasstring or nullPflichtAlways null: a deleted organization releases its alias, so the name is free for the next organization.
3 to 63 characters · pattern ^[a-z0-9](?:[a-z0-9-]{1,61}[a-z0-9])$
statusstringPflichtErlaubte Werte:
"deleted"metadataobjectPflichtcreated_atstring (date-time)PflichtRFC 3339, second precision, UTC.
updated_atstring (date-time)PflichtThe moment of the delete. RFC 3339, second precision, UTC.
placementobject or nullPflichtresidencystringPflichtpattern ^[a-z][a-z0-9._-]{0,63}$
data_regionstringPflichtpattern ^[a-z][a-z0-9._-]{0,63}$
operational_cluster_idstringPflichtpattern ^[a-z][a-z0-9._-]{0,63}$
knowledge_cluster_idstringPflichtpattern ^[a-z][a-z0-9._-]{0,63}$
search_cluster_idstringPflichtpattern ^[a-z][a-z0-9._-]{0,63}$
object_store_idstringPflichtpattern ^[a-z][a-z0-9._-]{0,63}$
placement_modestringPflichtErlaubte Werte:
"auto""pinned"updated_atstring (date-time)PflichtRFC 3339, second precision, UTC.
provider_deactivationstringPflichtdeactivated: the linked Zitadel organization is inactive. not_linked: the organization has no provider link. failed: the provider could not be reached or refused; the local delete stands and a repeated DELETE retries exactly this step.
Erlaubte Werte:
"deactivated""not_linked""failed"
- 400
Client refusal unrelated to authentication, including malformed input, a denied or failed request.
- 401
The request carries no credential, more than one, or one the platform does not accept, and is refused before the operation runs; `error.code` says why. Supply exactly one credential. Codes: invalid-request (no credential, or both Authorization:
Weiterlesen
Bearer and x-api-key), api-key-invalid (a value that is not a platform API key, or a key of a kind the platform does not accept), api-key-unknown, api-key-revoked, api-key-expired, bootstrap-disabled (the one-shot installation credential, once a key exists), token-malformed (a bearer token that is not a JWT), token-algorithm-unsupported, token-signature-invalid, token-claim-invalid, token-issuer-mismatch, token-audience-mismatch, token-expired, token-not-yet-valid, issuer-untrusted, issuer-residency-mismatch (the issuer belongs to another plane), issuer-resolution-unknown, jwks-unavailable, jwks-key-not-found, staff-token-inactive (a platform operator's token), staff-not-operator, staff-directory-unavailable, identity-not-provisioned (a verified identity with no account on this plane), organization-not-found (a verified identity or key whose organization this plane does not know), internal-error (a fault while the credential is checked is refused too, fail closed), context-cancelled
- 402
The organization has to pay first: its standing is payment_required.
Weiterlesen
The request boundary applies this payment gate to every route except an organization's billing routes, the caller's own context, organization list, onboarding, session report and personal keys, the public routes, and the routes of platform operators, who administer an organization that has to pay. The operations the gate covers declare this response. On /v1 the refusal is rendered in the OpenAI error format. Code: payment-required
- 403
The credential is valid but may not do this here; the request is refused by the request boundary before the handler runs, and `error.code` says which refusal. An operation may add codes of its own.
Weiterlesen
Codes: policy-denied (no role of the caller holds the permission the operation needs, or the credential class may not call it: a personal API key outside inference and MCP, a route that needs a signed-in person, the one-shot installation credential outside its three steps), tenant-mismatch (the organization a path, query, body or X-Tenant header names is not the caller's own), organization-provisioning, organization-suspended, organization-disabled, organization-deleted (the state of the caller's organization), user-disabled, residency-mismatch (the organization lives on another plane), organization-selection-required (a caller with more than one organization, or a platform operator, must name one in X-Organization-Id), organization-not-selectable, no-active-organization-membership, team-not-selectable (the X-Organization-Id or X-Team-Id the caller sent does not name an organization or team it may act in), identity-managed-by-provider (a person who is not a platform operator changes an organization's status, which belongs to the identity provider), support-session-required (a platform operator reads an organization's data without an open support session)
- 404
The requested resource or path was not found.
- 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 request conflicts with the current state of the resource or with an invariant it protects (a taken name, a role still in use, an organization that must not be deleted, an archived team, the last active root, a seat or service account limit).
- 500
Platform failure, rendered without internal cause details.
- 503
A dependency the operation needs is not configured on this plane or could not be reached, and nothing was changed. `error.code` names it; an operation lists the ones it can answer besides the boundary's. Retry later. Codes: support-audit-unavailable (the request boundary: an operator's read under an open support session could not be recorded, so nothing was served)
Erzeugt aus den Plattformverträgen beim Commit 5f833620.