domainee-dev Origin secret API

openapi: 3.2.0
info:
  title: Domainee Origin secret API
  version: 1.0.0
  summary: Custom domains, domain registration, and DNS diagnostics for SaaS products.
  description: 'Domainee lets your product attach your customers'' own domains to their accounts:

    one call to connect a hostname, automatic SSL issuance and renewal, DNS health

    monitoring, webhooks, and domain registration across 500+ TLDs.


    ## Authentication


    Every `/v1` endpoint except `/v1/tools/*` takes a Bearer token in the

    `Authorization` header. Two kinds work interchangeably:


    - **API keys** (`sk_live_…`), created at https://domainee.dev/developers

    - **OAuth access tokens** (`dmn_oat_…`), issued by the flow described in

    the `/.well-known/oauth-authorization-server` document.


    Both are workspace-scoped: a token only ever sees its own workspace''s data.


    ## Rate limits


    Authenticated endpoints allow 60 requests per minute per key and answer `429`

    with `{"error":"rate_limited"}` beyond that. The free tools are limited per IP

    at 30/minute and 500/day.


    ## Idempotency


    Send an `Idempotency-Key` header on any POST to make a retry safe: the first

    response for a given key is replayed instead of performing the work twice.


    ## Errors


    Failures return the same envelope at every status code:

    `{ "error": "not_found", "message": "Domain not found" }`.


    Full guides: https://domainee.dev/docs. Machine-readable index: https://domainee.dev/llms.txt.'
  termsOfService: https://domainee.dev/terms
  contact:
    name: Domainee support
    email: hello@domainee.dev
    url: https://domainee.dev/contact
servers:
- url: https://api.domainee.dev
  description: Production
security:
- bearerAuth: []
tags:
- name: Origin secret
  description: Prove to your origin that a request came through Domainee.
paths:
  /v1/origin-secret:
    get:
      operationId: getOriginSecret
      summary: Check whether the origin secret is on
      description: Never returns the secret itself. It is shown only when you turn it on or rotate it.
      tags:
      - Origin secret
      responses:
        '200':
          description: Whether the workspace sends an origin secret.
          content:
            application/json:
              schema:
                type: object
                properties:
                  enabled:
                    type: boolean
                required:
                - enabled
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: rotateOriginSecret
      summary: Turn on or rotate the origin secret
      description: Generates a new secret for the workspace, replacing any existing one. From then on every proxied request carries it in `x-domainee-origin-secret`. The edge picks up the new value within about a minute. The secret is returned only in this response.
      tags:
      - Origin secret
      responses:
        '200':
          description: The new secret.
          content:
            application/json:
              schema:
                type: object
                properties:
                  enabled:
                    type: boolean
                  originSecret:
                    type: string
                    description: The secret (dos_...). Shown only in this response.
                required:
                - enabled
                - originSecret
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: disableOriginSecret
      summary: Turn off the origin secret
      description: Proxied requests stop carrying `x-domainee-origin-secret` within about a minute.
      tags:
      - Origin secret
      responses:
        '200':
          description: The origin secret is off.
          content:
            application/json:
              schema:
                type: object
                properties:
                  enabled:
                    type: boolean
                required:
                - enabled
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Missing, malformed, revoked, or expired Bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      description: The error envelope used by every authenticated endpoint.
      properties:
        error:
          type: string
          description: Stable machine-readable code.
          example: not_found
        message:
          type: string
          description: Human-readable explanation.
      required:
      - error
      - message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key (`sk_live_…`) from https://domainee.dev/developers or an OAuth access token (`dmn_oat_…`). Both are workspace-scoped.
externalDocs:
  description: Domainee documentation
  url: https://domainee.dev/docs