CustomDomain Power API

openapi: 3.2.0
info:
  title: Customdomain Ai Power API
  version: '1.0'
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  description: 'Operations tagged Power 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: Power
  description: 'The edge reverse-proxy for a connection: origin, apex↔www redirect, and root-path serving.'
paths:
  /connections/{id}/power:
    get:
      operationId: getConnectionPower
      summary: Read a connection's Power (edge reverse-proxy) configuration
      tags:
      - Power
      description: 'A widget token must be the connection''s end user: a connection that names another end user than the token''s `end_user_ref`, or names one while the token names none, answers `403` `token_wrong_end_user` before anything is read or changed, and a connection that names none is any token''s. An API key, an app-scoped token and a delegated agent token are not limited by it.'
      security:
      - widgetJWT: []
      - apiKey: []
      parameters:
      - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: Power configuration
          content:
            application/json:
              schema:
                type: object
                properties:
                  power:
                    $ref: '#/components/schemas/PowerConfig'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/ForbiddenOrWrongEndUser'
        '404':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Error'
    post:
      operationId: enableConnectionPower
      summary: Enable Power (register the origin + redirect/root-path config)
      tags:
      - Power
      description: Registers the origin the edge reverse-proxies to (SSRF-validated) plus the redirect / root-path config the ask answer carries. `application_url` is required to enable.
      security:
      - widgetJWT: []
      - apiKey: []
      parameters:
      - $ref: '#/components/parameters/Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PowerConfigInput'
      responses:
        '201':
          description: Power enabled
          content:
            application/json:
              schema:
                type: object
                properties:
                  power:
                    $ref: '#/components/schemas/PowerConfig'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '409':
          description: '`conflict`: the call changes a redirect or the root path access of a domain that is being removed.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: '`redirect_target_not_allowed` or `redirect_loop` for `redirect_to` or `www_redirect`: the same checks as `PATCH /connections/{id}`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/RedirectsBusy'
    delete:
      operationId: disableConnectionPower
      summary: Remove Power (drop the origin, clear config, tear down the cert)
      tags:
      - Power
      security:
      - widgetJWT: []
      - apiKey: []
      parameters:
      - $ref: '#/components/parameters/Id'
      description: 'Clears the forward and the root path access, drops the origin and tears down the certificate. Clearing a forward is checked like any redirect change: on a domain whose `www` redirect is on, the visit that went to the forward now goes to the `www` name, and when that would come back (`www` forwards to the root) the call is refused with `422` `redirect_loop` and nothing is changed, the origin included. The `www` redirect itself is not cleared here (`PATCH /connections/{id}` turns it off).'
      responses:
        '204':
          description: Power removed
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '409':
          description: '`conflict`: the domain''s forward or root path access is set and the domain is being removed.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: '`redirect_loop`: taking the forward off would send a visit round a circle through the `www` redirect.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/RedirectsBusy'
    servers:
    - url: https://api.customdomain.ai/v1
      description: Hosted control-plane
    - url: http://localhost:8080/v1
      description: Local control-plane
  /applications/{id}/power:default:
    get:
      operationId: getApplicationDefaultOrigin
      summary: The application-wide default origin
      tags:
      - Power
      description: 'The origin the edge proxies to for any of this application''s connections that have no origin of their own. Resolution order is: the connection''s own origin, then this default, then none (the edge answers 421).


        This exists because a per-connection origin is the wrong grain for the common case: one application serving thousands of customer domains, all proxying to the same place and dispatching on `X-Forwarded-Host`.'
      security:
      - widgetJWT: []
      - apiKey: []
      parameters:
      - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: The current default
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationDefaultOrigin'
        '401':
          $ref: '#/components/responses/Error'
        '402':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Error'
    put:
      operationId: setApplicationDefaultOrigin
      summary: Set or clear the application-wide default origin
      tags:
      - Power
      description: 'Send `default_origin: ""` to clear it. The value is validated by the same guard a per-connection origin gets, and the edge re-validates the RESOLVED address at dial time: a hostname that passes here and is later repointed at a private address is refused when the edge connects.'
      security:
      - widgetJWT: []
      - apiKey: []
      parameters:
      - $ref: '#/components/parameters/Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - default_origin
              properties:
                default_origin:
                  type: string
                  description: Absolute http(s) URL, or "" to clear.
                  example: https://app.yourcompany.com
      responses:
        '200':
          description: The stored default
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationDefaultOrigin'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '402':
          $ref: '#/components/responses/Error'
        '404':
          $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
  /connections/{id}/power:eligibility:
    get:
      operationId: getConnectionPowerEligibility
      summary: Whether Power can be enabled for this connection yet
      tags:
      - Power
      description: 'Power needs the domain pointing at the edge (connection `live` or `propagating`) so the reverse proxy receives its traffic.


        A widget token must be the connection''s end user: a connection that names another end user than the token''s `end_user_ref`, or names one while the token names none, answers `403` `token_wrong_end_user` before anything is read or changed, and a connection that names none is any token''s. An API key, an app-scoped token and a delegated agent token are not limited by it.'
      security:
      - widgetJWT: []
      - apiKey: []
      parameters:
      - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: Eligibility
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Eligibility'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/ForbiddenOrWrongEndUser'
        '404':
          $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
  /connections/{id}/power:repower:
    post:
      operationId: repowerConnection
      summary: Update an existing Power configuration
      tags:
      - Power
      description: Update the origin and/or config. Omitting `application_url` keeps the current origin (unlike enable, which requires it).
      security:
      - widgetJWT: []
      - apiKey: []
      parameters:
      - $ref: '#/components/parameters/Id'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PowerConfigInput'
      responses:
        '200':
          description: Power updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  power:
                    $ref: '#/components/schemas/PowerConfig'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '409':
          description: '`conflict`: the call changes a redirect or the root path access of a domain that is being removed.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: '`redirect_target_not_allowed` or `redirect_loop` for `redirect_to` or `www_redirect`: the same checks as `PATCH /connections/{id}`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/RedirectsBusy'
    servers:
    - url: https://api.customdomain.ai/v1
      description: Hosted control-plane
    - url: http://localhost:8080/v1
      description: Local control-plane
  /power:
    get:
      operationId: listPoweredConnections
      summary: List the caller app's powered connections
      tags:
      - Power
      security:
      - widgetJWT: []
      - apiKey: []
      responses:
        '200':
          description: Powered connections
          content:
            application/json:
              schema:
                type: object
                properties:
                  power:
                    type: array
                    items:
                      $ref: '#/components/schemas/PowerConfig'
        '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
components:
  parameters:
    Id:
      name: id
      in: path
      required: true
      schema:
        type: string
  schemas:
    Eligibility:
      type: object
      required:
      - domain
      - eligible
      properties:
        domain:
          type: string
        eligible:
          type: boolean
        reason:
          type: string
          description: why not, when ineligible; empty when eligible.
    PowerConfigInput:
      type: object
      properties:
        application_url:
          type: string
          format: uri
          description: origin the edge proxies to; required to enable, optional to re-power (kept if omitted).
        www_redirect:
          type: boolean
        redirect_to:
          type: string
          description: set to a URL to 301 the host there; "" clears it.
        root_path_access:
          type: array
          items:
            type: string
    ApplicationDefaultOrigin:
      type: object
      properties:
        application_id:
          type: string
        default_origin:
          type: string
          description: Absent when no default is set.
        configured:
          type: boolean
          description: Whether a default is set. Distinguishes "no default" from an empty value.
    PowerConfig:
      type: object
      required:
      - connection_id
      - domain
      - powered
      - www_redirect
      properties:
        connection_id:
          type: string
        domain:
          type: string
        origin:
          type: string
          description: the URL the edge reverse-proxies to.
        powered:
          type: boolean
          description: true when an origin is registered.
        www_redirect:
          type: boolean
          description: serve an apex↔www redirect.
        redirect_to:
          type: string
          description: when set, the edge 301s the host here.
        root_path_access:
          type: array
          items:
            type: string
    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:
    RedirectsBusy:
      description: '`redirects_busy`: another change to this workspace''s forwarding is still being saved (redirect changes of one workspace are made one at a time), and this one waited for it in vain. Nothing was changed; send it again after the `Retry-After` seconds. `service_unavailable`: edge serving is off in this deployment, so a forward cannot be set.'
      headers:
        Retry-After:
          description: Seconds to wait before sending the call again (on `redirects_busy`).
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error:
      description: 'Error envelope: {code, title, details}.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ForbiddenOrWrongEndUser:
      description: '`forbidden`: the credential may not do this. `token_wrong_end_user`: a widget token that is not this connection''s end user (the connection names another end user than the token''s `end_user_ref`, or names one while the token names none); nothing is read or changed, and the answer shows nothing of the connection. Mint the token with the end user''s `end_user_ref`.'
      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