platform-openapi.yaml

components:
  schemas:
    Connector:
      additionalProperties: false
      properties:
        created_at:
          description: Timestamp when connector was first registered
          format: date-time
          type: string
        entitlement_slug:
          description: Slug of the BOOLEAN entitlement a license must grant for an organization to activate this connector. Absent means the connector is ungated.
          examples:
            - connector-attio
          type: string
        name:
          description: Stable connector identifier
          examples:
            - kaiten.integration.crm.attio
          type: string
        settings_schema:
          additionalProperties: {}
          description: JSON schema used to validate connector settings payloads
          type: object
        updated_at:
          description: Timestamp when connector registration was last updated
          format: date-time
          type: string
        version:
          description: Registered connector version
          examples:
            - 1.0.0
          type: string
      required:
        - name
        - version
        - settings_schema
        - created_at
        - updated_at
      type: object
    EnsureOrganizationBody:
      additionalProperties: false
      properties:
        externalId:
          description: The identity provider's id for the organization. The row's id is derived from this value, so the same external id always converges on the same organization.
          examples:
            - org_2abcDEF
          maxLength: 255
          minLength: 1
          type: string
        name:
          description: Display name for a newly created organization. Never replaces an existing one's name; omitted, a new organization is named after its external id.
          examples:
            - Kaiten
          maxLength: 255
          type: string
      required:
        - externalId
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
    MintOrganizationTokenBody:
      additionalProperties: false
      properties:
        name:
          description: Human-readable label for the credential
          examples:
            - ci-deploy
          maxLength: 255
          minLength: 1
          type: string
        scopes:
          description: Requested scopes, which must be a subset of the calling platform credential's. Omitted inherits all of them.
          examples:
            - - read:customers
          items:
            type: string
          type:
            - array
            - "null"
        ttl:
          description: Lifetime as a Go duration ("15m", "24h"). Omitted mints a non-expiring credential, whose bound is revocation -- including the cascade from the platform credential that minted it.
          examples:
            - 15m
          type: string
      required:
        - name
      type: object
    Organization:
      additionalProperties: false
      properties:
        external_id:
          description: External identifier for the organization, used for integration with external systems
          examples:
            - ext-123e4567-e89b-12d3-a456-426614174000
          type: string
        id:
          description: Unique identifier for the organization
          examples:
            - 123e4567-e89b-12d3-a456-426614174000
          type: string
        name:
          description: Display name of the organization
          examples:
            - My Organization
          type: string
      required:
        - id
        - external_id
        - name
      type: object
    PlainToken:
      additionalProperties: false
      properties:
        createdAt:
          format: date-time
          readOnly: true
          type: string
        createdBy:
          $ref: "#/components/schemas/User"
          readOnly: true
        expiresAt:
          format: date-time
          type: string
        id:
          readOnly: true
          type: string
        name:
          type: string
        revokedAt:
          format: date-time
          readOnly: true
          type: string
        revokedBy:
          $ref: "#/components/schemas/User"
          readOnly: true
        scopes:
          items:
            type: string
          type:
            - array
            - "null"
        serviceAccountId:
          readOnly: true
          type: string
        slug:
          description: Optional URL-friendly identifier, unique per service account. Auto-generated if not provided.
          maxLength: 100
          minLength: 2
          pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$
          type: string
        token:
          readOnly: true
          type: string
      required:
        - name
        - scopes
        - createdAt
        - createdBy
      type: object
    PlatformCredential:
      additionalProperties: false
      properties:
        createdAt:
          format: date-time
          readOnly: true
          type: string
        credentialKind:
          description: Credential class of the calling token
          examples:
            - platform
          type: string
        expiresAt:
          description: Absent when the credential does not expire
          format: date-time
          type: string
        id:
          readOnly: true
          type: string
        name:
          type: string
        scopes:
          items:
            type: string
          type:
            - array
            - "null"
        slug:
          type: string
        subject:
          description: External id of the platform identity this credential authenticates
          examples:
            - system:kaiten
          type: string
      required:
        - id
        - name
        - slug
        - subject
        - credentialKind
        - scopes
        - createdAt
      type: object
    Problem:
      additionalProperties: false
      properties:
        code:
          description: Stable, machine-readable error code.
          examples:
            - License.NotFound
          type: string
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          examples:
            - license not found
          type: string
        errorId:
          description: Correlation id for the server-side log entry describing the withheld cause.
          examples:
            - 3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31
          type: string
        errors:
          description: Optional list of individual error details
          items:
            $ref: "#/components/schemas/ErrorDetail"
          type:
            - array
            - "null"
        instance:
          description: A URI reference that identifies the specific occurrence of the problem.
          examples:
            - /api/licenses/enterprise
          type: string
        status:
          description: HTTP status code
          examples:
            - 404
          format: int64
          type: integer
        title:
          description: A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
          examples:
            - Not Found
          type: string
        type:
          default: about:blank
          description: A URI reference to human-readable documentation for the error.
          examples:
            - https://tools.ietf.org/html/rfc7231#section-6.5.4
          format: uri
          type: string
      type: object
    RegisterConnectorBody:
      additionalProperties: false
      properties:
        entitlement_slug:
          description: Slug of the BOOLEAN entitlement a license must grant for an organization to activate this connector. Absent means the connector is ungated.
          examples:
            - connector-attio
          type: string
        name:
          description: Stable connector identifier
          examples:
            - kaiten.integration.crm.attio
          type: string
        settings_schema:
          additionalProperties: {}
          description: JSON schema used to validate organization-level connector settings
          type: object
        version:
          description: Connector version
          examples:
            - 1.0.0
          type: string
      required:
        - name
        - version
        - settings_schema
      type: object
    Token:
      additionalProperties: false
      properties:
        createdAt:
          format: date-time
          readOnly: true
          type: string
        createdBy:
          $ref: "#/components/schemas/User"
          readOnly: true
        expiresAt:
          format: date-time
          type: string
        id:
          readOnly: true
          type: string
        name:
          type: string
        revokedAt:
          format: date-time
          readOnly: true
          type: string
        revokedBy:
          $ref: "#/components/schemas/User"
          readOnly: true
        scopes:
          items:
            type: string
          type:
            - array
            - "null"
        serviceAccountId:
          readOnly: true
          type: string
        slug:
          description: Optional URL-friendly identifier, unique per service account. Auto-generated if not provided.
          maxLength: 100
          minLength: 2
          pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$
          type: string
      required:
        - name
        - scopes
        - createdAt
        - createdBy
      type: object
    User:
      additionalProperties: false
      properties:
        id:
          description: ID of the user
          examples:
            - 123e4567-e89b-12d3-a456-426614174000
          type: string
        name:
          description: Name of the user
          examples:
            - John Doe
          type: string
      required:
        - id
      type: object
  securitySchemes:
    platformAuth:
      bearerFormat: Platform token
      description: A Kaiten platform token (`ksm_...`), which authenticates the platform identity `system:kaiten` and carries no organization context. Organization credentials — JWTs from the configured OIDC issuer and `ksh_...` access tokens — are rejected on this surface, and a platform token is rejected on the Core API. The scopes listed on each operation are the ones the token must carry.
      scheme: bearer
      type: http
info:
  contact:
    email: support@kaiten.sh
    name: Kaiten Team
  description: Platform-wide operations, authenticated by a Kaiten platform token (`ksm_...`) that identifies `system:kaiten` and carries no organization execution context. An operation that acts inside an organization names it in the path; it never inherits one from the credential.
  title: Kaiten Platform API
  version: 1.0.0
openapi: 3.1.0
paths:
  /platform/connectors:
    post:
      description: Registers or updates connector metadata and settings schema for this Kaiten deployment
      operationId: register-connector
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RegisterConnectorBody"
              description: Connector registration payload containing metadata and settings schema
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Connector"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - platformAuth:
            - write:organizations
      summary: Register connector manifest
      tags:
        - connectors
  /platform/me:
    get:
      description: Returns the name, scopes, expiry and creation time of the platform credential used to make the request, plus the platform identity it authenticates. The token value is never returned -- it is shown once, at creation.
      operationId: get-platform-me
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatformCredential"
          description: OK
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - platformAuth:
            - read:tokens
      summary: Describe the calling platform credential
      tags:
        - platform
  /platform/organizations:
    post:
      description: "Converges on the organization an external identity provider describes, creating it if it is not already there and returning it either way. The internal id is derived from the external id, so the operation is idempotent: a re-run returns the same organization instead of creating a second tenant, and an organization that already exists -- including one provisioned on a first login -- is returned unchanged apart from acquiring a name if it had none. Platform API: requires a Kaiten platform token (`ksm_...`) with write:organizations."
      operationId: ensure-organization
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EnsureOrganizationBody"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Organization"
          description: OK
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - platformAuth:
            - write:organizations
      summary: Create an organization if it does not already exist
      tags:
        - organizations
  /platform/organizations/{orgId}:
    delete:
      description: "Permanently deletes an organization and everything it owns — customers, licenses, feature flags, entitlements, instances, releases, memberships, service accounts and their tokens, and its audit trail. This cannot be undone, and the organization's usage history cannot be rebuilt. Platform API: requires a Kaiten platform token (`ksm_...`) with delete:organizations."
      operationId: delete-organization
      parameters:
        - description: Organization ID
          in: path
          name: orgId
          required: true
          schema:
            description: Organization ID
            format: uuid
            type: string
      responses:
        "204":
          description: No Content
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - platformAuth:
            - delete:organizations
      summary: Delete an organization
      tags:
        - organizations
    get:
      description: "Retrieve an organization by their unique identifier. Platform API: requires a Kaiten platform token (`ksm_...`)."
      operationId: get-organization
      parameters:
        - description: Organization ID
          in: path
          name: orgId
          required: true
          schema:
            description: Organization ID
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Organization"
          description: OK
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - platformAuth:
            - read:organizations
      summary: Get an organization by ID
      tags:
        - organizations
  /platform/organizations/{orgId}/memberships/{userId}:
    delete:
      description: "Soft-deletes a single membership. Platform API: requires a Kaiten platform token (`ksm_...`) with delete:memberships. The system:kaiten membership cannot be removed — the database refuses it, and this answers 403."
      operationId: delete-membership
      parameters:
        - description: Organization ID
          in: path
          name: orgId
          required: true
          schema:
            description: Organization ID
            format: uuid
            type: string
        - description: User ID
          in: path
          name: userId
          required: true
          schema:
            description: User ID
            format: uuid
            type: string
      responses:
        "204":
          description: No Content
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - platformAuth:
            - delete:memberships
      summary: Remove a user's membership on an organization
      tags:
        - organizations
  /platform/organizations/{orgId}/tokens:
    get:
      description: "Names the still-active credentials this platform credential minted in the named organization, so one can be addressed for revocation: revoke-organization-token takes a slug, and a slug is server-generated and cannot be derived from the name the caller chose. Only credentials issued by the calling platform credential, in the named organization, are listed. No credential value is returned -- these identify, they do not authenticate."
      operationId: list-organization-tokens
      parameters:
        - description: Organization the credential acts inside
          in: path
          name: orgId
          required: true
          schema:
            description: Organization the credential acts inside
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                description: Active credentials this platform credential holds in the named organization
                items:
                  $ref: "#/components/schemas/Token"
                type:
                  - array
                  - "null"
          description: OK
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - platformAuth:
            - read:tokens
      summary: List the organization credentials minted for the platform identity
      tags:
        - platform
    post:
      description: Issues an ordinary organization-scoped access token (`ksh_...`) owned by the system:kaiten platform identity inside the named organization, derived from its existing membership there. Requested scopes must be a subset of the calling platform credential's; omitting them inherits all of them. TTL is optional -- omitted mints a non-expiring credential. The token value is returned once, here, and can never be retrieved again. Revoking the platform credential that minted it also revokes this one.
      operationId: mint-organization-token
      parameters:
        - description: Organization to mint the credential inside
          in: path
          name: orgId
          required: true
          schema:
            description: Organization to mint the credential inside
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MintOrganizationTokenBody"
              description: Credential details
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlainToken"
                description: The minted credential, including its secret value (shown only once)
          description: Created
        "400":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Bad Request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "409":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Conflict
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - platformAuth:
            - write:tokens
      summary: Mint an organization credential for the platform identity
      tags:
        - platform
  /platform/organizations/{orgId}/tokens/{tokenSlug}:
    delete:
      description: Retires a credential this platform credential minted in the named organization, before the platform credential itself is retired. Only credentials issued by the calling platform credential, in the named organization, can be revoked here.
      operationId: revoke-organization-token
      parameters:
        - description: Organization the credential acts inside
          in: path
          name: orgId
          required: true
          schema:
            description: Organization the credential acts inside
            format: uuid
            type: string
        - description: Slug returned when the credential was minted
          in: path
          name: tokenSlug
          required: true
          schema:
            description: Slug returned when the credential was minted
            examples:
              - system-kaiten-a1b2c3
            format: text
            type: string
      responses:
        "204":
          description: No Content
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - platformAuth:
            - write:tokens
      summary: Revoke an organization credential minted for the platform identity
      tags:
        - platform
  /platform/users/{id}:
    delete:
      description: "Soft-deletes a user by ID. Platform API: requires a Kaiten platform token (`ksm_...`) with delete:users. The system:kaiten platform identity cannot be deleted — the database refuses it, and this answers 403."
      operationId: delete-user
      parameters:
        - description: User ID
          in: path
          name: id
          required: true
          schema:
            description: User ID
            format: uuid
            type: string
      responses:
        "204":
          description: No Content
        "401":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Not Found
        "422":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Unprocessable Entity
        "500":
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
          description: Internal Server Error
      security:
        - platformAuth:
            - delete:users
      summary: Delete a user
      tags:
        - users
security:
  - platformAuth: []
servers:
  - url: /api