Saltar al contenido principal
DocumentaciónIdentidad y acceso · console.latam.ccsio.ai

Service accounts

The service accounts an API key acts as.

Menú de la documentación

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

POST/identity/v1/service-accounts

Create a service account in the organization

Credencial
API key
Permiso
members.manage
Cuerpo de la solicitud
Cuerpo de hasta 1 MiB

Requires members.manage and authority to grant the chosen role. role is optional (default user): a built-in organization-level role other than root, or the id of one of the organization's custom roles; the caller must be able to grant it (anti-escalation: a custom-role holder can never grant organization_admin, and any role's permissions must be a subset of the caller's own).

Leer más

Creates the service account and its organization membership atomically. The server generates the stable principal reference; the caller supplies the organization, the display name and optionally the role. The new identity cannot receive human or platform-administrator authority through this operation. A service account is not a seat, but the plan limits how many an organization may have (a platform operator may set another limit): at the limit the request is refused and nothing can be bought.

curl
curl -X POST "https://console.latam.ccsio.ai/identity/v1/service-accounts" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "org_id": "acme",
  "display_name": "billing-app",
  "role": "user"
}'

Parámetros

NombreEnDescripción
X-Request-ID
opcional
headerstring

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

CreateServiceAccountRequest
  • org_idstringobligatorio

    pattern ^[a-z][a-z0-9._-]{0,63}$

  • display_namestringobligatorio

    Service-account display name, 1 to 128 bytes.

    1 to 128 characters

  • rolestringopcional

    Optional (default user): a built-in organization-level role other than root, or the id of one of the organization's custom roles. Subject to the anti-escalation rule: the caller must be able to grant it. root and team_admin are refused.

    pattern ^(organization_admin|user|role_[a-z0-9_]{1,59})$

Respuestas

  • 201

    The created service account, ready for API-key issuance.

    Esquema
    APIKeyPrincipal
    • principal_refstringobligatorio

      Stable service-account reference sent as principal_ref when issuing a key.

      pattern ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$

    • display_namestringobligatorio
    • kindstringobligatorio

      always "service_account"

  • 400

    Client refusal. Codes: invalid-request (the body is not valid JSON, has an unknown or trailing member, or lacks a required one), role-invalid (neither a built-in role nor one of the organization's custom roles), role-binding-invalid (a role that cannot be held at organization level), user-invalid (display_name longer than 128 bytes)

  • 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:

    Leer más

    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.

    Leer más

    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

    No role of the caller holds `members.manage` in the organization (policy-denied), or the organization the request names is not the caller's own (tenant-mismatch). Codes: policy-denied, tenant-mismatch, membership-forbidden (the role is root, the caller cannot grant it, or the caller cannot manage members)

  • 404

    The organization was deleted while the request ran. Codes: organization-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 organization has reached its service account limit. Codes: service-account-limit-reached

  • 500

    Platform failure, rendered without internal cause details.

Respuesta de ejemplo
{
  "principal_ref": "svc/01K7YP2C9W4X5E8H3J6M0N1Q2R",
  "display_name": "billing-app",
  "kind": "service_account"
}

Generado a partir de los contratos de la plataforma en el commit 5954fbc1.

Explora la plataforma

Obtén tu primera key API

El registro está abierto. Cuatro pasos hasta tu primera llamada: crea tu cuenta, crea tu organización, crea tu API key y empieza a usarla.

  1. 01Crea tu cuenta
  2. 02Crea tu organización
  3. 03Crea tu API key
  4. 04Empieza a usarla