CustomDomain Tenancy API

openapi: 3.2.0
info:
  title: Customdomain Ai Tenancy API
  version: '1.0'
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  description: 'Operations tagged Tenancy 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: Tenancy
  description: 'Operator provisioning: tenants and one-call signup.'
paths:
  /tenants:
    post:
      operationId: createTenant
      summary: Create a tenant
      tags:
      - Tenancy
      description: Operator provisioning endpoint. Requires the management key in production.
      security:
      - managementKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
      responses:
        '201':
          description: Tenant created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tenant'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
    servers:
    - url: https://api.customdomain.ai/v1
      description: Hosted control-plane
    - url: http://localhost:8080/v1
      description: Local control-plane
  /tenants/{id}:
    get:
      operationId: getTenant
      summary: Get a tenant
      tags:
      - Tenancy
      security:
      - managementKey: []
      parameters:
      - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: Tenant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tenant'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
    patch:
      operationId: updateTenant
      summary: Rename your workspace
      tags:
      - Tenancy
      description: The caller's own tenant only (admin and above); any other id is a `404`.
      security:
      - apiKey: []
      parameters:
      - $ref: '#/components/parameters/Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  maxLength: 80
      responses:
        '200':
          description: Renamed
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
    servers:
    - url: https://api.customdomain.ai/v1
      description: Hosted control-plane
    - url: http://localhost:8080/v1
      description: Local control-plane
  /tenants:provision:
    post:
      operationId: provisionTenant
      summary: One-call signup provisioning (tenant + owner + app + API key)
      tags:
      - Tenancy
      description: Atomically creates a tenant, its first owner member, a default application, and a long-lived API key. `api_key` and `client_secret` are returned ONCE. Guarded by the dedicated provision secret (the `X-Provision-Secret` header or a Bearer token) so the customer console's server can hold this narrow secret instead of the operator management key. It also mints the workspace default key (see `POST /tenants/{tenant_id}/default-key`) and returns it ONCE as `default_api_key` with its id; both fields are absent if it could not be made, and the default key route makes it later.
      security:
      - provisionSecret: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - tenant_name
              properties:
                tenant_name:
                  type: string
                app_name:
                  type: string
                owner_email:
                  type: string
                environment:
                  $ref: '#/components/schemas/Environment'
      responses:
        '201':
          description: Provisioned (api_key + client_secret shown once)
          content:
            application/json:
              schema:
                type: object
                required:
                - tenant_id
                - application_id
                - api_key
                - client_secret
                properties:
                  tenant_id:
                    type: string
                  application_id:
                    type: string
                  api_key:
                    type: string
                    description: cd_live_… or cd_test_…; shown once
                  client_secret:
                    type: string
                    description: mints widget JWTs; shown once
                  default_api_key:
                    type: string
                    description: The workspace default key, cd_live_… or cd_test_…; shown once. Absent when it could not be made.
                  default_api_key_id:
                    type: string
                    description: The default key's id; present with default_api_key.
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $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
  /tenants/{tenant_id}/default-key:
    post:
      operationId: ensureDefaultApiKey
      summary: Ensure the workspace default key exists (secret returned only when created)
      tags:
      - Tenancy
      description: 'The workspace default key is an ordinary API key (`cd_live_…` in production) flagged `is_default`, at most one active per workspace, whose secret the customer console keeps sealed so the workspace''s owner can view it more than once. It acts with admin authority, never owner: it cannot make, unmake or remove an owner, delete the workspace, or create API keys (`403`). Server to server, guarded by the provision secret like `tenants:provision`; a missing and a wrong secret get the same `401`. With no active default key this creates one and answers `201` with the full secret ONCE in `api_key`. With one, it answers `200` with its id and prefix and no secret (a caller that lost its copy rotates instead). Not subject to the billing activation gate: the key adds no capability the workspace''s console key does not already hold.'
      security:
      - provisionSecret: []
      parameters:
      - name: tenant_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: An active default key exists; no secret
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultApiKey'
        '201':
          description: Created; api_key is the full secret, shown once
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultApiKey'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '409':
          $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
  /tenants/{tenant_id}/default-key:rotate:
    post:
      operationId: rotateDefaultApiKey
      summary: Rotate the workspace default key (new secret returned once)
      tags:
      - Tenancy
      description: 'Mints a new default key and revokes the old active one in one transaction: the old key stops authenticating at once, and there is never a moment with two active default keys or none. The workspace''s other keys are untouched. With no active default key it simply creates one. Same provision secret guard as `POST /tenants/{tenant_id}/default-key`.'
      security:
      - provisionSecret: []
      parameters:
      - name: tenant_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Rotated; api_key is the new full secret, shown once
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultApiKey'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '409':
          $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
  /stats:
    get:
      operationId: getStats
      summary: Aggregate counts across all tenants (operator)
      tags:
      - Tenancy
      description: 'How many tenants, accepted members and pending invites the control plane holds. An operator surface for the owner dashboard, gated by the management key: no tenant API key can reach it, and it carries no tenant data. `members` counts accepted members only (owners and teammates who signed up); an invite that was sent and never accepted counts under `pending_invites`, so the two add up to the members table.'
      security:
      - managementKey: []
      responses:
        '200':
          description: Counts
          content:
            application/json:
              schema:
                type: object
                required:
                - tenants
                - members
                - pending_invites
                properties:
                  tenants:
                    type: integer
                  members:
                    type: integer
                    description: Accepted members only.
                  pending_invites:
                    type: integer
                    description: Invites sent and not yet accepted.
        '401':
          $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:
  parameters:
    Id:
      name: id
      in: path
      required: true
      schema:
        type: string
  schemas:
    Environment:
      type: string
      enum:
      - production
      - staging
      - development
    Tenant:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
        name:
          type: string
        created_at:
          type: string
          format: date-time
    DefaultApiKey:
      type: object
      required:
      - key_id
      - prefix
      - created
      properties:
        key_id:
          type: string
        prefix:
          type: string
          description: The stored, non-secret prefix, for example cd_live_ab12cd34.
        created:
          type: boolean
          description: true when this call minted the key; api_key is present only then.
        api_key:
          type: string
          description: The full secret, cd_live_… or cd_test_…; shown once.
    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
  responses:
    Error:
      description: 'Error envelope: {code, title, details}.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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