CustomDomain Providers API

openapi: 3.2.0
info:
  title: Customdomain Ai Providers API
  version: '1.0'
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  description: 'Operations tagged Providers 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: Providers
  description: The DNS-provider capability catalog and parity census.
paths:
  /providers:
    get:
      operationId: listProviders
      summary: List the DNS providers the Connect engine can detect and automate
      tags:
      - Providers
      security: []
      responses:
        '200':
          description: Provider capability catalog
          content:
            application/json:
              schema:
                type: object
                required:
                - providers
                - count
                properties:
                  providers:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProviderInfo'
                  count:
                    type: integer
    servers:
    - url: https://api.customdomain.ai/v1
      description: Hosted control-plane
    - url: http://localhost:8080/v1
      description: Local control-plane
  /providers/census:
    get:
      operationId: providerCensus
      summary: Full parity census (every target provider routed to its working mode)
      tags:
      - Providers
      security: []
      responses:
        '200':
          description: Census (each provider routed to dc / oauth / api / manual)
          content:
            application/json:
              schema:
                type: object
                required:
                - providers
                - count
                properties:
                  providers:
                    type: array
                    items:
                      type: object
                  count:
                    type: integer
    servers:
    - url: https://api.customdomain.ai/v1
      description: Hosted control-plane
    - url: http://localhost:8080/v1
      description: Local control-plane
  /providers/{provider}/zones:list:
    post:
      operationId: listProviderZones
      summary: Enumerate the connectable domains a provider credential controls
      tags:
      - Providers
      description: For the bulk-connect picker. The credential is used once to list zones and is never persisted here. `422` (`list_not_supported`) when the adapter can't enumerate zones; the console degrades to single-domain connect.
      security:
      - widgetJWT: []
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - credential
              properties:
                credential:
                  type: object
                  required:
                  - token
                  properties:
                    token:
                      type: string
                      description: Scoped provider API token; used once, never persisted.
      responses:
        '200':
          description: Zones
          content:
            application/json:
              schema:
                type: object
                properties:
                  provider:
                    type: string
                  zones:
                    type: array
                    items:
                      type: string
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '422':
          description: The provider can't enumerate zones
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    examples:
                    - list_not_supported
                  provider:
                    type: string
                  message:
                    type: string
        '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:
  schemas:
    ProviderInfo:
      type: object
      required:
      - id
      properties:
        id:
          type: string
        rail:
          type: string
          description: dc | oauth | api | manual
        oauth:
          type: boolean
        account_ways:
          type: array
          description: 'The ways to add this company''s account in Connected accounts, easiest first: `oauth` (the person signs in with the company and the account is made from the OAuth grant, kept with its refresh token; `POST /provider-accounts:oauth-start`, the console only), then `secure_sign_in` (the person signs in at the company and CustomDomain™ makes the key; `POST /provider-accounts:sign-in`, the console only), then `api_key` (the person pastes a key; `POST /provider-accounts`). Always present; `[]` for a company that only signs in and takes no key. `secure_sign_in` is listed only while the deployment runs it for the company (the feature on, its key page and its domain list in place); the workspace''s own gates are the sign in''s to apply. `oauth` is listed only while the deployment runs the company''s OAuth app, keeps what it hands back and the company''s sign-in needs no domain; a company that lists it lists no `secure_sign_in`.'
          items:
            type: string
            enum:
            - oauth
            - secure_sign_in
            - api_key
    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