CustomDomain Enterprise API

openapi: 3.2.0
info:
  title: Customdomain Ai Enterprise API
  version: '1.0'
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  description: 'Operations tagged Enterprise across 2 of this provider''s published API definitions: customdomain-ai-openapi-original.json, customdomain-ai-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.customdomain.ai/v1
  description: Hosted control-plane
- url: http://localhost:8080/v1
  description: Local control-plane
security:
- apiKey: []
tags:
- name: Enterprise
  description: RBAC reference matrix and the audit log.
paths:
  /rbac:
    get:
      operationId: getRbac
      summary: Role / permission matrix (static reference)
      tags:
      - Enterprise
      security: []
      responses:
        '200':
          description: Matrix
    servers:
    - url: https://api.customdomain.ai/v1
      description: Hosted control-plane
    - url: http://localhost:8080/v1
      description: Local control-plane
  /audit:
    get:
      operationId: getAudit
      summary: Audit log (tenant-scoped for tenant credentials; full log for the management…
      tags:
      - Enterprise
      security:
      - managementKey: []
      - apiKey: []
      - widgetJWT: []
      responses:
        '200':
          description: Events
        '401':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Error'
    post:
      operationId: recordAuditEvent
      summary: Record an audit event for a change made in the console
      tags:
      - Enterprise
      description: 'Ingest for the few mutations that happen in the customer console''s own database, so the control plane never sees them. Everything the control plane changes itself is recorded by its own handler and is not accepted here. The organization, actor, address and time are derived on the server; the body names only the action, an optional target and a small before and after summary. Requires an API key whose role may manage identity settings (admin or owner); a widget JWT is refused with `403`, and a `503` means the audit log is not configured on the deployment.


        The console''s server also records here what an operator did through its owner routes (disabling an account, signing it out, a verification resend, a password reset link, the workspace''s optional pages). It presents the provisioning secret in `X-Provision-Secret`, names the workspace in `tenant_id`, and may use only the `user.*` and `workspace.features_set` verbs, which a tenant key may not. The actor is recorded as `operator`, the reason in `after.reason` is required for all of them but `user.verification_resent`, and the answer is a `500` when the log did not take the event.'
      security:
      - apiKey: []
      - provisionSecret: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - action
              properties:
                action:
                  type: string
                  enum:
                  - whitelabel.configured
                  - api_key.default_revealed
                  - user.disabled
                  - user.enabled
                  - user.sessions_revoked
                  - user.verification_resent
                  - user.password_reset_link_issued
                  - workspace.features_set
                  description: The console-recordable verb. With an API key only `whitelabel.configured` and `api_key.default_revealed`; with the provisioning secret only the others. Any other value is refused with `400`.
                tenant_id:
                  type: string
                  description: 'Provisioning secret only, and required with it: the workspace the event is recorded on. An unknown one is a `404`.'
                target:
                  type: string
                  description: What the event is about. Defaults to the caller's own organization when empty.
                before:
                  type: object
                  additionalProperties: true
                  description: A small summary of the state before the change; at most 24 keys.
                after:
                  type: object
                  additionalProperties: true
                  description: A small summary of the state after the change; at most 24 keys.
      responses:
        '200':
          description: Recorded
          content:
            application/json:
              schema:
                type: object
                required:
                - recorded
                - action
                properties:
                  recorded:
                    type: boolean
                  action:
                    type: string
                    description: The verb that was recorded.
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Error'
    servers:
    - url: https://api.customdomain.ai/v1
      description: Hosted control-plane
    - url: http://localhost:8080/v1
      description: Local control-plane
components:
  responses:
    Error:
      description: 'Error envelope: {code, title, details}.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      required:
      - code
      - title
      properties:
        code:
          type: string
          description: stable machine code, e.g. invalid_request, unauthorized, not_found, service_unavailable, internal_error
        title:
          type: string
          description: human-readable summary
        details:
          type: string
          description: optional extra context
  securitySchemes:
    managementKey:
      type: http
      scheme: bearer
      description: Operator management key. Gates provisioning + reads across tenants.
    provisionSecret:
      type: apiKey
      in: header
      name: X-Provision-Secret
      description: Narrow secret held by the customer console's server, for signup provisioning and its other server to server calls (also accepted as a Bearer token, except on POST /audit, where a Bearer is always a tenant credential).
    apiKey:
      type: http
      scheme: bearer
      description: Long-lived tenant API key, cd_live_… (production) or cd_test_… (staging, development), stored hashed. Keys created before the switch to cd_ start with sk_live_… / sk_test_… and are still accepted. Scoped to the owning application's tenant.
    widgetJWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Short-lived widget JWT minted server-side via POST /v1/tokens. Scoped to one application (and optionally one domain).
    browserSession:
      type: http
      scheme: bearer
      description: The session token of one cloud browser sign in, returned by `POST /browser-sessions:redeem`. It binds one session, one connection and one workspace, lives at most as long as the session, and stops working the moment the session ends. It lives in the popup's memory only.
    agentToken:
      type: oauth2
      description: 'A delegated agent access token: an ES256 JWT that lives 15 minutes, sent as a bearer token. A person approves an agent in the console and the agent exchanges its authorization code (with PKCE) at the token endpoint. The token carries the workspace, the one application the grant is bound to, the grant, the approved scopes and its audience, and is verified against `/.well-known/jwks.json`. A route that accepts it lists the scope it needs; a token without the scope is refused with `403`, and a connection or order of another application answers `404`.'
      flows:
        authorizationCode:
          authorizationUrl: https://api.customdomain.ai/oauth/agent/authorize
          tokenUrl: https://api.customdomain.ai/oauth/agent/token
          refreshUrl: https://api.customdomain.ai/oauth/agent/token
          scopes:
            domains:read: Look at availability, connections, records, certificates, diagnoses, orders and the billing standing.
            domains:connect: Connect a domain, recheck it, reapply its records and start a one click setup.
            domains:disconnect: Remove a connected domain. The call must name the domain.
            domains:purchase: Buy a domain, up to the grant's monthly spend cap.
x-refined-from:
- customdomain-ai-openapi-original.json
- customdomain-ai-openapi.yml