openapi: 3.1.0
info:
  title: dns-gate API
  version: "1"
  summary: Security gateway in front of DNS provider APIs (EuroDNS, Route53).
  description: |
    The gate's own API, the same whatever the DNS provider of a zone: zones and
    RRsets owned by teams, writes with content-hash preconditions, plans,
    adoption, transfers, audit, API keys and ACME DNS-01 endpoints. Send a bearer
    token: an OIDC token of an issuer of the gate configuration, a gate token or
    a gate API key ([Authentication](#tag/identity)). Guides:
    [API guide](https://kamorionlabs.github.io/dns-gate/docs/API/) and
    [API by example](https://kamorionlabs.github.io/dns-gate/docs/api/).
  license:
    name: MIT
    url: https://github.com/KamorionLabs/dns-gate/blob/main/LICENSE
externalDocs:
  description: Documentation
  url: https://kamorionlabs.github.io/dns-gate/docs/
servers:
  - url: https://{gate}
    variables:
      gate:
        default: dns-gate.example.com
        description: Host name of the gate.
security:
  - bearer: []
  - apiKey: []
  - virtualKey: []
    virtualKeyApp: []
  - session: []
tags:
  - name: discovery
    description: |
      Gate detection.

      **Errors** are `{"reason", "message", "details"}`; `reason` is stable and
      meant for programs.

      **EuroDNS-compatible API.** Every other path of the gate is the EuroDNS
      API, served under RBAC and ownership for the zones of EuroDNS providers
      (`404 zone_not_eurodns` for a zone of another provider), plus the zone
      profiles of the EuroDNS account (`/zone-profiles`, under
      `dns.zone.profile` on `*`, the provider named by `X-DNS-Gate-Provider`
      when there are several); it is documented by EuroDNS at
      <https://docapi.eurodns.com/> and not repeated here.
  - name: identity
    description: |
      Who is calling, how to connect, and gate-issued tokens.

      **Authentication.** A bearer token (JWT from an issuer declared in the gate
      configuration), a gate API key (`dgk_...`, as a bearer token, as the
      password of basic authentication with the key id as user name, or in
      `X-Api-Key`), a virtual key (`X-App-Id` + `X-Api-Key`), or the web UI
      session cookie. With the session cookie, every request other than GET must
      carry the `X-Gate-CSRF` header (equal to the `gate_csrf` cookie) and a
      same-origin `Origin` header; humans need a recent login for writes
      (`403 reauth_required` otherwise).

      **Gate tokens and OAuth.** With an issuer marked `self: true`, the gate
      signs its own tokens: `POST /api/v1/tokens` issues one to a web UI
      session, and its keys are served at `/.well-known/jwks.json`. The gate
      also runs an OAuth 2.0 authorization server for the Claude Desktop
      extension and the declared OAuth clients (tag `oauth`).

      **Token exchange.** `POST /api/v1/token-exchange` (RFC 8693) turns a
      token of an opted-in issuer (`token_exchange: true`) into a short-lived
      gate token with the same identity, for tools that need a credential
      longer than the CI or workload token lives.
  - name: zones
    description: Zones and their RRsets.
  - name: rrsets
    description: |
      Single RRset reads and writes, with content-hash preconditions.

      Every write goes through the gate engine: RBAC (zone, host pattern, record
      type), ownership by team, per-zone lock, protected records, blast-radius
      limits and audit. `GET` returns the content hash of the RRset as `ETag`;
      `If-Match` on `PUT` and `DELETE` acts only on that content, `If-None-Match: *`
      creates only (`412 precondition` otherwise).
  - name: forwards
    description: URL forwards (HTTP redirects), owned like RRsets, for providers with forwards (EuroDNS).
  - name: plans
    description: Dry runs persisted as single-use plans, then applied.
  - name: adoption
    description: Take over RRsets created outside the gate, and export them to Terraform.
  - name: teams
    description: |
      Teams, and ownership transfers between them with a second approver.

      RRsets are owned by teams. A caller acting for several teams writes for
      its default team (the first one, `default_team` of `/api/v1/me`) and may
      change the RRsets of any of them; the `X-DNS-Gate-Team` header (or the
      `team` field of plan and apply) makes it act for one of its teams only
      (`403 not_team_member` otherwise). The EuroDNS-compatible API always uses
      the default team.
  - name: audit
    description: Audit log.
  - name: delegation
    description: Policy delegation API, used by the Terraform provider to manage roles and bindings.
  - name: policy
    description: Policy editor of the web UI (managed layer, revisions, approvals).
  - name: api-keys
    description: Gate-issued API keys for third parties without OIDC (ACME clients, appliances).
  - name: acme
    description: |
      ACME DNS-01 endpoints compatible with lego httpreq and acme-dns.

      `/acme/httpreq/present` and `/cleanup` serve the lego `httpreq` DNS
      provider, `/acme/acme-dns/update` and `/register` the acme-dns API
      (acme.sh `dns_acmedns`, the certbot acme-dns hook, cert-manager, Caddy).
      They write `_acme-challenge` TXT RRsets through the engine, as the caller,
      whose role must have an `ephemeral_ttl`. Guide:
      [certificates](https://kamorionlabs.github.io/dns-gate/docs/ACME/).
  - name: zone-profiles
    description: Zone profiles of EuroDNS accounts, prepared before a domain transfer.
  - name: oauth
    description: |
      Gate authorization server (issuer with `self: true` and the UI login):
      authorization code with PKCE (S256) for the Claude Desktop extension and
      for the applications declared under `oauth.clients`, refresh token
      rotation, revocation (RFC 7009) and the connected applications of each
      user. `GET /oauth/authorize` (consent page) and the metadata documents
      (`/.well-known/oauth-authorization-server`,
      `/.well-known/openid-configuration`) are standard and not described
      here. Guide:
      [OAuth clients](https://kamorionlabs.github.io/dns-gate/docs/config/authentication/#oauth-clients).
paths:
  /.well-known/dns-gate:
    get:
      tags: [discovery]
      operationId: getGateInfo
      summary: Gate detection and features
      description: The only path clients use to detect a gate. No authentication.
      security: []
      responses:
        "200":
          description: Gate version and features.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/GateInfo" }

  /.well-known/jwks.json:
    get:
      tags: [discovery]
      operationId: getJWKS
      summary: Public keys of gate-issued tokens
      description: "Served when an issuer has `self: true` (404 otherwise). No authentication."
      security: []
      responses:
        "200":
          description: JSON Web Key Set.
          content:
            application/json:
              schema:
                type: object
                required: [keys]
                properties:
                  keys: { type: array, items: { type: object } }
        "404": { $ref: "#/components/responses/Error" }

  /api/v1/tokens:
    post:
      tags: [identity]
      operationId: issueToken
      summary: A gate token for the web UI session
      description: |
        Issues a bearer token signed by the gate issuer (`self: true`) for the
        signed-in UI user, with the identity of the session, to use with curl
        or the Terraform provider. Session cookie only (`403 session_required`
        for a bearer token or a virtual key), with `X-Gate-CSRF`; `404
        not_found` when no issuer has `self: true`. The lifetime is the
        issuer's `token_ttl`, capped by the session.
      security:
        - session: []
      responses:
        "200":
          description: Token.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/IssuedToken" }
        "401": { $ref: "#/components/responses/Error" }
        "403": { $ref: "#/components/responses/Error" }
        "404": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }

  /oauth/token:
    post:
      tags: [oauth]
      operationId: oauthToken
      summary: Redeem an authorization code or a refresh token
      description: |
        `authorization_code` (single use, 2 minutes, with `code_verifier` and
        the exact `redirect_uri`) or `refresh_token`. Declared clients
        authenticate with `client_secret_basic`, `client_secret_post` or
        `private_key_jwt` (RFC 7523: `iss` = `sub` = client id, `aud` this
        endpoint or the issuer, `exp` at most 5 minutes ahead, `jti` used
        once); public clients send `client_id` only. Every refresh returns a
        new refresh token: a used one revokes the grant
        (`oauth.refresh_reuse`), except within 30 seconds, where the same
        answer is returned again. Errors follow RFC 6749 (`invalid_client`
        401, `invalid_grant`, `invalid_scope`, `unsupported_grant_type`).
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [grant_type]
              properties:
                grant_type: { type: string, enum: [authorization_code, refresh_token] }
                code: { type: string }
                redirect_uri: { type: string }
                code_verifier: { type: string }
                refresh_token: { type: string }
                scope: { type: string, description: "Refresh only: a subset of the granted scopes." }
                client_id: { type: string }
                client_secret: { type: string }
                client_assertion_type: { type: string, enum: ["urn:ietf:params:oauth:client-assertion-type:jwt-bearer"] }
                client_assertion: { type: string }
      responses:
        "200":
          description: Tokens.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/OAuthTokenResponse" }
        "400":
          description: OAuth error.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/OAuthError" }
        "401":
          description: Client authentication failed (`invalid_client`).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/OAuthError" }

  /oauth/revoke:
    post:
      tags: [oauth]
      operationId: oauthRevoke
      summary: Revoke a refresh or access token (RFC 7009)
      description: |
        Revokes the grant of a refresh or access token of the authenticated
        client: every token of the grant stops working (access tokens within
        30 seconds on other replicas). Unknown tokens and tokens of other
        clients get 200 without effect, as do the stateless tokens of the
        Claude Desktop extension (`dns-gate-relay`).
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [token]
              properties:
                token: { type: string }
                token_type_hint: { type: string, enum: [refresh_token, access_token] }
                client_id: { type: string }
                client_secret: { type: string }
                client_assertion_type: { type: string }
                client_assertion: { type: string }
      responses:
        "200": { description: Revoked, or nothing to revoke. }
        "400":
          description: OAuth error.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/OAuthError" }
        "401":
          description: Client authentication failed (`invalid_client`).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/OAuthError" }

  /api/v1/oauth/grants:
    get:
      tags: [oauth]
      operationId: listOAuthGrants
      summary: Connected applications
      description: |
        The grants of the caller to the declared OAuth clients. With
        `gate.oauth.manage` (a person signed in directly, never a key or a
        delegated client), `client` or `subject` list the grants of a client
        or of a user (`403` otherwise).
      parameters:
        - { name: client, in: query, schema: { type: string } }
        - { name: subject, in: query, description: "issuer:id", schema: { type: string } }
      responses:
        "200":
          description: Grants, newest first.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/OAuthGrantList" }
        "403": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }
    delete:
      tags: [oauth]
      operationId: revokeOAuthGrants
      summary: Revoke every grant of a client or a user
      description: "`gate.oauth.manage` and `client` or `subject` required (a departing user, a compromised client)."
      parameters:
        - { name: client, in: query, schema: { type: string } }
        - { name: subject, in: query, description: "issuer:id", schema: { type: string } }
      responses:
        "200":
          description: Number of grants revoked.
          content:
            application/json:
              schema:
                type: object
                required: [revoked]
                properties:
                  revoked: { type: integer }
        "403": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/oauth/grants/{id}:
    delete:
      tags: [oauth]
      operationId: revokeOAuthGrant
      summary: Revoke a grant
      description: A grant of the caller, or any grant with `gate.oauth.manage` (404 otherwise).
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        "204": { description: Revoked. }
        "404": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/token-exchange:
    post:
      tags: [identity]
      operationId: exchangeToken
      summary: Exchange an OIDC token for a short-lived gate token (RFC 8693)
      description: |
        OAuth 2.0 token exchange. The subject token is validated exactly as a
        bearer token of its issuer (signature, audiences, `bound_claims`,
        bindings), and its issuer must have `token_exchange: true`. The
        answer is a token signed by the gate issuer (`self: true`) with the
        same identity (issuer, subject, name, category, teams and claims),
        plus the claim `gate_xchg` (the `jti` of the exchanged token).
        Gate tokens and API keys are never exchanged, and an exchanged token
        is refused once its issuer no longer opts in. The lifetime is 15
        minutes, or `expires_in` (a gate extension, seconds), capped by the
        issuer's `max_exchanged_ttl` (15m by default), the `token_ttl` of the
        gate issuer and the subject token expiry plus 5 minutes. Every exchange is audited
        (`gate.token.exchange`). `404 token_exchange_disabled` without a gate
        issuer or an opted-in issuer. Errors follow RFC 6749
        (`{"error", "error_description"}`).
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [grant_type, subject_token, subject_token_type]
              properties:
                grant_type: { type: string, enum: ["urn:ietf:params:oauth:grant-type:token-exchange"] }
                subject_token: { type: string, description: A JWT of an issuer with token_exchange. }
                subject_token_type:
                  type: string
                  enum:
                    - urn:ietf:params:oauth:token-type:jwt
                    - urn:ietf:params:oauth:token-type:id_token
                    - urn:ietf:params:oauth:token-type:access_token
                requested_token_type:
                  type: string
                  enum: [urn:ietf:params:oauth:token-type:access_token, urn:ietf:params:oauth:token-type:jwt]
                expires_in: { type: integer, minimum: 60, description: "Requested lifetime in seconds (default 900)." }
      responses:
        "200":
          description: Gate token.
          content:
            application/json:
              schema:
                type: object
                required: [access_token, issued_token_type, token_type, expires_in]
                properties:
                  access_token: { type: string }
                  issued_token_type: { type: string }
                  token_type: { type: string, enum: [Bearer] }
                  expires_in: { type: integer }
        "400": { $ref: "#/components/responses/OAuthError" }
        "404": { $ref: "#/components/responses/OAuthError" }

  /api/v1/me:
    get:
      tags: [identity]
      operationId: getMe
      summary: The authenticated subject and its effective permissions
      responses:
        "200":
          description: Subject.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Me" }
        "401": { $ref: "#/components/responses/Error" }

  /api/v1/connect:
    get:
      tags: [identity]
      operationId: getConnect
      summary: How clients reach the gate (base URL, MCP, issuer)
      description: Requires ui.read on at least one zone.
      responses:
        "200":
          description: Connection information.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Connect" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/connect/claude-desktop.mcpb:
    get:
      tags: [identity]
      operationId: getClaudeDesktopExtension
      summary: Claude Desktop extension of this gate
      description: Available when MCP and the UI login are enabled; 404 otherwise.
      responses:
        "200":
          description: MCP Bundle.
          content:
            application/zip:
              schema: { type: string, contentMediaType: application/zip }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/zones:
    get:
      tags: [zones]
      operationId: listZones
      summary: Zones the caller can read
      description: Managed zones, and zones discovered in the provider accounts but not managed (`unmanaged`, read-only), with the provider folder of each (EuroDNS). Requires ui.read.
      parameters:
        - name: folder
          in: query
          required: false
          description: Keep the zones whose folder matches this folder glob (`/ES` the folder ES, `/ES/**` every folder below it, `/` the zones in no folder).
          schema: { type: string, examples: ["/ES/**"] }
      responses:
        "200":
          description: Zones.
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/ZoneSummary" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/zones/{zone}/rrsets:
    parameters:
      - $ref: "#/components/parameters/Zone"
    get:
      tags: [zones]
      operationId: getZoneInventory
      summary: RRsets of a zone with their ownership
      description: Requires ui.read on the zone. The ETag is the gate version of the zone.
      responses:
        "200":
          description: Inventory.
          headers:
            ETag:
              description: Zone version, `"v<n>"`.
              schema: { type: string, examples: ['"v42"'] }
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ZoneInventory" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/zones/{zone}/rrsets/{host}/{type}:
    parameters:
      - $ref: "#/components/parameters/Zone"
      - $ref: "#/components/parameters/Host"
      - $ref: "#/components/parameters/Type"
      - $ref: "#/components/parameters/Team"
    get:
      tags: [rrsets]
      operationId: getRRset
      summary: One RRset
      description: Requires ui.read or dns.read on the zone.
      responses:
        "200":
          description: The RRset; the ETag is its content hash.
          headers:
            ETag: { $ref: "#/components/headers/RRsetETag" }
          content:
            application/json:
              schema: { $ref: "#/components/schemas/RRset" }
        default: { $ref: "#/components/responses/Error" }
    put:
      tags: [rrsets]
      operationId: putRRset
      summary: Create or replace an RRset
      description: |
        Sets the full desired state of the RRset: `ttl` and `values`, or `alias`
        (providers with alias records, such as Route53). The engine checks RBAC
        (dns.record.write on the zone, host and type), ownership (the RRset must
        be new or owned by the caller's team) and the preconditions under the
        zone lock, against a fresh read of the provider. `If-None-Match: *`
        creates only: `409 foreign_rrset` when an RRset created outside the
        gate exists, `412 precondition` when the gate owns one. `If-Match:
        "<hash>"` replaces only the RRset with that content hash. Writes to
        other RRsets of the zone in between do not refuse the request.

        Values are in zone file presentation format; TXT values are the text
        itself, unquoted, at any length (the gate or the provider splits them
        in 255-byte strings). Targets without a trailing dot are absolute; a
        single-label target is refused (`400 relative_target`).
      parameters:
        - $ref: "#/components/parameters/IfMatch"
        - $ref: "#/components/parameters/IfNoneMatch"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/RRsetPut" }
            examples:
              values:
                value: { ttl: 3600, values: ["192.0.2.10", "192.0.2.11"] }
              alias:
                value: { alias: { target: "d111111abcdef8.cloudfront.net.", hosted_zone_id: "Z2FDTNDATAQYW2", evaluate_target_health: false } }
      responses:
        "200":
          description: The RRset as written; the ETag is its new content hash.
          headers:
            ETag: { $ref: "#/components/headers/RRsetETag" }
          content:
            application/json:
              schema: { $ref: "#/components/schemas/RRset" }
        "400": { $ref: "#/components/responses/Error" }
        "403": { $ref: "#/components/responses/Error" }
        "404": { $ref: "#/components/responses/Error" }
        "409": { $ref: "#/components/responses/Error" }
        "412": { $ref: "#/components/responses/Error" }
        "423": { $ref: "#/components/responses/Locked" }
        "502": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }
    delete:
      tags: [rrsets]
      operationId: deleteRRset
      summary: Delete an RRset
      description: Deleting an RRset that does not exist succeeds. `If-Match` deletes only the RRset with that content hash.
      parameters:
        - $ref: "#/components/parameters/IfMatch"
      responses:
        "204":
          description: Deleted.
        "403": { $ref: "#/components/responses/Error" }
        "404": { $ref: "#/components/responses/Error" }
        "409": { $ref: "#/components/responses/Error" }
        "412": { $ref: "#/components/responses/Error" }
        "423": { $ref: "#/components/responses/Locked" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/zones/{zone}/forwards:
    parameters:
      - $ref: "#/components/parameters/Zone"
    get:
      tags: [forwards]
      operationId: listForwards
      summary: URL forwards of a zone with their ownership
      description: |
        Requires ui.read or dns.read on the zone. Served from the inventory
        cache, like the RRsets of the zone (a forward is the RRset of type
        URLFWD of its host). `https` tells whether the forwards answer HTTPS.
      responses:
        "200":
          description: Forwards.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ForwardList" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/zones/{zone}/forwards/{host}:
    parameters:
      - $ref: "#/components/parameters/Zone"
      - $ref: "#/components/parameters/Host"
      - $ref: "#/components/parameters/Team"
    get:
      tags: [forwards]
      operationId: getForward
      summary: One URL forward
      description: Requires ui.read or dns.read on the zone.
      responses:
        "200":
          description: The forward; the ETag is its content hash.
          headers:
            ETag: { $ref: "#/components/headers/RRsetETag" }
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ForwardView" }
        default: { $ref: "#/components/responses/Error" }
    put:
      tags: [forwards]
      operationId: putForward
      summary: Create or replace a URL forward
      description: |
        Sets the forward of the host: a 301 or 302 redirect to `url`, or a
        frame showing it. The engine checks RBAC (dns.forward.write on the zone
        and host; records.types does not apply), ownership (the forward must be
        new or owned by the caller's team, tombstones and transfers as for
        RRsets) and the preconditions under the zone lock, against a fresh read
        of the provider; `If-None-Match` and `If-Match` behave as on RRsets.
        `400 invalid` for a provider without forwards (Route53).

        `require_https: true` refuses the write with `409 https_unavailable`
        unless the forwards of the zone answer HTTPS (`https.status` active or
        no_forward; pending is refused). A forward is not created over A,
        AAAA, CNAME or APEX records of its host owned by another team or by
        nobody (`403 not_owner`, `409 foreign_rrset`). At EuroDNS that takes an HTTPS redirect
        subscription on the domain, a paid product ordered outside the gate;
        without it a forward answers plain HTTP only. The URL target may be
        https:// either way.
      parameters:
        - $ref: "#/components/parameters/IfMatch"
        - $ref: "#/components/parameters/IfNoneMatch"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ForwardPut" }
            examples:
              redirect:
                value: { type: "301", url: "https://www.example.com/" }
              frame:
                value: { type: frame, url: "https://shop.example.net/", title: "Shop" }
      responses:
        "200":
          description: The forward as written; the ETag is its new content hash.
          headers:
            ETag: { $ref: "#/components/headers/RRsetETag" }
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ForwardView" }
        "400": { $ref: "#/components/responses/Error" }
        "403": { $ref: "#/components/responses/Error" }
        "404": { $ref: "#/components/responses/Error" }
        "409": { $ref: "#/components/responses/Error" }
        "412": { $ref: "#/components/responses/Error" }
        "423": { $ref: "#/components/responses/Locked" }
        "502": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }
    delete:
      tags: [forwards]
      operationId: deleteForward
      summary: Delete a URL forward
      description: Deleting a forward that does not exist succeeds. `If-Match` deletes only the forward with that content hash.
      parameters:
        - $ref: "#/components/parameters/IfMatch"
      responses:
        "204":
          description: Deleted.
        "403": { $ref: "#/components/responses/Error" }
        "404": { $ref: "#/components/responses/Error" }
        "409": { $ref: "#/components/responses/Error" }
        "412": { $ref: "#/components/responses/Error" }
        "423": { $ref: "#/components/responses/Locked" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/zones/{zone}/rrsets/{host}/{type}/propagation:
    parameters:
      - $ref: "#/components/parameters/Zone"
      - $ref: "#/components/parameters/Host"
      - $ref: "#/components/parameters/Type"
      - $ref: "#/components/parameters/Team"
    get:
      tags: [rrsets]
      operationId: checkPropagation
      summary: DNS propagation of an RRset
      description: |
        Asks the authoritative name servers of the zone (its apex NS, without
        recursion) and the public resolvers of `propagation.resolvers` for the
        RRset, over UDP with EDNS0 and TCP when truncated, and compares each
        answer with the RRset as read from the provider: `match`, `stale`
        (other values, typically the previous content still cached), `missing`
        (NXDOMAIN or NODATA while the RRset exists) or `error` (timeout,
        SERVFAIL, REFUSED, a name server answering without authority). An
        RRset that does not exist matches an empty answer, so a deletion can be
        followed too. Alias RRsets (Route53) and EuroDNS APEX RRsets are
        compared on the addresses of their target: every address answered
        must be one of the target's (resolved by the gate for the
        authoritative servers, by the same resolver otherwise), else the
        answer is `indeterminate`, which never counts as up to date.
        Authoritative answers must also carry the expected TTL, and cached
        answers no more TTL left than it. `converged` needs a matching
        authoritative answer.

        Requires dns.read on the RRset, in a zone managed by the gate (never
        an arbitrary name). Results are cached for `propagation.cache_ttl`
        (default 10s) per RRset content; other checks are limited per caller
        (`propagation.requests_per_minute`, 429) and at most
        `propagation.max_in_flight` checks run at once (503 `busy`), per
        instance. Public resolvers answer from
        their cache until the TTL runs out: poll every few seconds, not in a
        tight loop. No audit event is written.
      parameters:
        - name: expect
          in: query
          required: false
          description: |
            Content hash just written (the ETag of a PUT or `new_hash` of an
            apply result, quoted or not), or `absent` after a deletion. The
            gate inventory is a cache of the instance answering: when it
            differs, the zone is read again from the provider (a few times a
            minute per caller at most), and `412 precondition` is returned if
            the RRset still differs.
          schema: { type: string }
      responses:
        "200":
          description: The answers of every server.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Propagation" }
        "400": { $ref: "#/components/responses/Error" }
        "403": { $ref: "#/components/responses/Error" }
        "404": { $ref: "#/components/responses/Error" }
        "412": { $ref: "#/components/responses/Error" }
        "429": { $ref: "#/components/responses/Error" }
        "501": { $ref: "#/components/responses/Error" }
        "502": { $ref: "#/components/responses/Error" }
        "503": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/zones/{zone}/plan:
    parameters:
      - $ref: "#/components/parameters/Zone"
      - $ref: "#/components/parameters/Team"
    post:
      tags: [plans]
      operationId: planRRsets
      summary: Dry run of RRset changes
      description: |
        Checks RBAC, ownership, preconditions and provider validation without
        writing. A refusal is `200` with `allowed: false`, `reason` and
        `message`. An allowed plan gets a `plan_id`, bound to the caller, the
        zone, the zone version and the team selected (`team` field or
        `X-DNS-Gate-Team`), valid for `mcp.plan_ttl` (10 minutes by default)
        and usable once, on any gate instance.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/PlanRequest" }
      responses:
        "200":
          description: Plan.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PlanResult" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/zones/{zone}/apply:
    parameters:
      - $ref: "#/components/parameters/Zone"
      - $ref: "#/components/parameters/Team"
    post:
      tags: [plans]
      operationId: applyPlan
      summary: Apply a plan, exactly as planned
      description: |
        Fails with `412 precondition` when the zone changed since the plan,
        `410 plan_expired` when the plan expired, `404 plan_not_found` for an
        unknown or already applied plan or the plan of another zone (plan
        again in these three cases), `403 forbidden` for the plan of
        another caller, and `400 team_mismatch` when the `team` field or
        `X-DNS-Gate-Team` names another team than the plan's. The plan is
        applied for its team.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ApplyRequest" }
      responses:
        "200":
          description: Applied changes.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PlanResult" }
        "403": { $ref: "#/components/responses/Error" }
        "404": { $ref: "#/components/responses/Error" }
        "410": { $ref: "#/components/responses/Error" }
        "412": { $ref: "#/components/responses/Error" }
        "423": { $ref: "#/components/responses/Locked" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/zones/{zone}/adopt/preview:
    parameters:
      - $ref: "#/components/parameters/Zone"
      - $ref: "#/components/parameters/Team"
    post:
      tags: [adoption]
      operationId: previewAdopt
      summary: Preview the adoption of foreign RRsets
      description: |
        Requires dns.record.adopt. The RRsets go to `owner`, the caller's
        team by default; another team than the caller's requires
        dns.ownership.approve on each RRset (`forbidden` candidates
        otherwise, `403 forbidden` without it anywhere in the zone). An RRset
        deleted recently by another team (tombstone) is never adoptable for
        another team (`reserved_for_other_team`): it moves through a
        transfer.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AdoptSelection" }
      responses:
        "200":
          description: Candidates and a preview token.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/AdoptPreview" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/zones/{zone}/adopt:
    parameters:
      - $ref: "#/components/parameters/Zone"
      - $ref: "#/components/parameters/Team"
    post:
      tags: [adoption]
      operationId: adopt
      summary: Adopt RRsets of a preview, all or nothing
      description: Requires dns.record.adopt and a comment. `409 adopt_conflict` when any RRset changed since the preview.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AdoptApply" }
      responses:
        "200":
          description: Adopted RRsets.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/AdoptResult" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/zones/{zone}/terraform:
    parameters:
      - $ref: "#/components/parameters/Zone"
    get:
      tags: [adoption]
      operationId: exportTerraform
      summary: Managed RRsets as Terraform/OpenTofu configuration
      description: |
        One resource and one `import` block (id `<zone>/<host>/<type>`) per
        managed RRset. `provider=dnsgate` (default) exports
        `dnsgate_record_set` of the `KamorionLabs/dnsgate` provider, for any DNS
        provider behind the gate; `provider=eurodns` exports
        `eurodns_record_set` of the `kamorionlabs/eurodns` provider (no alias
        RRsets). Requires ui.read.
      parameters:
        - name: provider
          in: query
          schema: { type: string, enum: [dnsgate, eurodns], default: dnsgate }
        - name: team
          in: query
          description: Owner team.
          schema: { type: string }
        - name: hosts
          in: query
          description: Host globs, comma-separated or repeated.
          schema: { type: array, items: { type: string } }
          style: form
          explode: true
        - name: types
          in: query
          description: Record types, comma-separated or repeated.
          schema: { type: array, items: { type: string } }
          style: form
          explode: true
        - name: rrsets
          in: query
          description: Exact selection `host/type`, comma-separated or repeated; takes precedence over hosts and types.
          schema: { type: array, items: { type: string, examples: ["www/A"] } }
          style: form
          explode: true
      responses:
        "200":
          description: HCL.
          content:
            text/plain:
              schema: { type: string }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/zones/{zone}/transfers:
    parameters:
      - $ref: "#/components/parameters/Zone"
      - $ref: "#/components/parameters/Team"
    post:
      tags: [teams]
      operationId: proposeTransfer
      summary: Request the transfer of RRsets to another team
      description: |
        The RRsets must be owned by one team (or reserved for it by a
        tombstone after a recent delete). The caller needs dns.record.write
        or dns.ownership.approve on the zone and, for every RRset, be allowed
        to write it through the bindings of the owner team or of the target
        team, or hold dns.ownership.approve on it (`403 not_owner`). The
        request waits for its approval (`ownership.transfer_ttl`, 7 days by
        default); with `"apply": true` its requester approves it at once,
        when `ownership.require_second_approver` is false (`400 invalid`
        otherwise).
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/TransferProposal" }
      responses:
        "201":
          description: Proposed transfer.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Transfer" }
        "400": { $ref: "#/components/responses/Error" }
        "403": { $ref: "#/components/responses/Error" }
        "404": { $ref: "#/components/responses/Error" }
        "409": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/transfers:
    get:
      tags: [teams]
      operationId: listTransfers
      summary: Transfer requests the caller can see, newest first
      description: |
        Requests of the zones the caller can read and of its teams; team
        renames for policy.read holders and the members of both teams.
        `can_decide` tells which ones the caller may approve (the inbox:
        `status=proposed`).
      parameters:
        - { name: zone, in: query, schema: { type: string } }
        - { name: status, in: query, schema: { type: string, enum: [proposed, applying, applied, rejected, expired, failed] } }
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 500, default: 50 } }
        - { name: cursor, in: query, schema: { type: string } }
      responses:
        "200":
          description: Page of transfers.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/TransferPage" }
        "400": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/transfers/{id}:
    parameters:
      - $ref: "#/components/parameters/TransferID"
    get:
      tags: [teams]
      operationId: getTransfer
      summary: One transfer request
      responses:
        "200":
          description: Transfer.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Transfer" }
        "404": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/transfers/{id}/approve:
    parameters:
      - $ref: "#/components/parameters/TransferID"
    post:
      tags: [teams]
      operationId: approveTransfer
      summary: Approve a transfer request, which applies it
      description: |
        By a human unless `ownership.machine_approvers`, after a recent
        login. With `ownership.require_second_approver` the approver is
        another person than the requester under any identity
        (`ownership.person_issuers`, `ownership.person_claims`, fail closed
        when either cannot be identified); without it the requester may
        approve its own request (`self_approved`). For every RRset, the
        approver must be allowed to write it through the bindings of the
        owner team, or hold dns.ownership.approve on it. A team rename needs
        policy.approve; it answers `applying` and is applied in the
        background, the approver needing dns.ownership.approve on every RRset
        of the team. The ownership entries change team
        in one store transaction, after checking under the zone lock that
        they still belong to the team with the content hash of the request,
        in the store and upstream; otherwise the transfer is `failed` and the
        answer is `412 precondition` with the transfer in `transfer`.
        `410 expired` when the request expired, `412 precondition` when it
        was already decided. When the zone is locked (`423`) or the store or
        the provider is unavailable (`502`), the transfer stays `applying`,
        returned in `transfer`, and the gate retries it for 24 hours (checking
        the rights of the approver again) before marking it `failed`.
      requestBody:
        content:
          application/json:
            schema: { $ref: "#/components/schemas/DecisionRequest" }
      responses:
        "200":
          description: Applied transfer.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Transfer" }
        "403": { $ref: "#/components/responses/Error" }
        "404": { $ref: "#/components/responses/Error" }
        "410": { $ref: "#/components/responses/Error" }
        "412": { $ref: "#/components/responses/Error" }
        "423": { $ref: "#/components/responses/Locked" }
        "502": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/transfers/{id}/reject:
    parameters:
      - $ref: "#/components/parameters/TransferID"
    post:
      tags: [teams]
      operationId: rejectTransfer
      summary: Reject a transfer request, or withdraw one's own
      requestBody:
        content:
          application/json:
            schema: { $ref: "#/components/schemas/DecisionRequest" }
      responses:
        "200":
          description: Rejected transfer.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Transfer" }
        "403": { $ref: "#/components/responses/Error" }
        "404": { $ref: "#/components/responses/Error" }
        "410": { $ref: "#/components/responses/Error" }
        "412": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/teams:
    get:
      tags: [teams]
      operationId: listTeams
      summary: Teams of the policy
      description: |
        Declared teams (base file and managed layer), teams referenced
        without a declaration (`auto`, during the migration to the teams
        block), team_from families and team_claim issuers, and the teams
        owning RRsets in the zones the caller can read that nothing else
        covers (`store`). Members are shown to policy.read holders only.
        Requires ui.read on a zone.
      responses:
        "200":
          description: Teams.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/TeamList" }
        "403": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/teams/{team}:
    parameters:
      - $ref: "#/components/parameters/TeamName"
    get:
      tags: [teams]
      operationId: getTeam
      summary: A team, what it owns and its pending transfers
      responses:
        "200":
          description: Team.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/TeamDetail" }
        "404": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/teams/{team}/rename:
    parameters:
      - $ref: "#/components/parameters/TeamName"
    post:
      tags: [teams]
      operationId: renameTeam
      summary: Request moving every RRset of a team to another team
      description: |
        Bulk transfer for migrations, in the managed zones and every other
        zone where the store holds RRsets or tombstones of the team, store
        only: proposed by a policy.propose holder and approved by a
        policy.approve holder (`/api/v1/transfers/{id}/approve`; another
        person with `ownership.require_second_approver`, otherwise
        `"apply": true` approves it at once), then applied in the background.
        The policy still names the old team: change the bindings in a policy
        revision too. Applied zone by zone; an interruption leaves the
        rename `applying` and the gate resumes it.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/TeamRenameRequest" }
      responses:
        "201":
          description: Proposed rename.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Transfer" }
        "400": { $ref: "#/components/responses/Error" }
        "403": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/audit:
    get:
      tags: [audit]
      operationId: listAudit
      summary: Audit events, newest first
      description: >-
        Events of zones the caller cannot read are filtered out; events without a zone
        (authentication failures) need read access to every managed zone. Pull-based
        collectors poll with `since` (a high-water mark minus a margin), follow
        `next_cursor` until it is absent and deduplicate on `event_id`
        (see docs/AUDIT.md).
      parameters:
        - { name: zone, in: query, schema: { type: string } }
        - { name: host, in: query, schema: { type: string } }
        - { name: type, in: query, schema: { type: string } }
        - { name: subject, in: query, description: "Case-insensitive substring of the subject or its name.", schema: { type: string } }
        - { name: category, in: query, schema: { type: string, enum: [human, pipeline, key] } }
        - { name: decision, in: query, schema: { type: string, enum: [allow, deny, error] } }
        - { name: since, in: query, description: "RFC 3339, fractional seconds accepted; inclusive.", schema: { type: string, format: date-time } }
        - { name: until, in: query, description: "RFC 3339, fractional seconds accepted; inclusive.", schema: { type: string, format: date-time } }
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 500, default: 50 } }
        - { name: cursor, in: query, schema: { type: string } }
      responses:
        "200":
          description: Page of events.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/AuditPage" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/policy/delegated:
    get:
      tags: [delegation]
      operationId: listDelegated
      summary: Delegations of the caller and their objects
      description: Every delegation for policy.read holders.
      responses:
        "200":
          description: Index.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/DelegatedIndex" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/policy/delegated/roles/{name}:
    parameters:
      - $ref: "#/components/parameters/DelegatedName"
    get:
      tags: [delegation]
      operationId: getDelegatedRole
      summary: A delegated role
      responses:
        "200":
          description: Role.
          headers:
            ETag: { $ref: "#/components/headers/ObjectETag" }
          content:
            application/json:
              schema: { $ref: "#/components/schemas/DelegatedObject" }
        default: { $ref: "#/components/responses/Error" }
    put:
      tags: [delegation]
      operationId: putDelegatedRole
      summary: Create or replace a delegated role
      description: Validated against the delegation limits, then activated as a new managed revision without approval.
      parameters:
        - $ref: "#/components/parameters/IfMatchObject"
        - $ref: "#/components/parameters/IfNoneMatch"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/DelegatedRoleRequest" }
      responses:
        "200":
          description: Result.
          headers:
            ETag: { $ref: "#/components/headers/ObjectETag" }
          content:
            application/json:
              schema: { $ref: "#/components/schemas/DelegatedResult" }
        default: { $ref: "#/components/responses/Error" }
    delete:
      tags: [delegation]
      operationId: deleteDelegatedRole
      summary: Delete a delegated role
      parameters:
        - $ref: "#/components/parameters/IfMatchObject"
        - $ref: "#/components/parameters/Delegation"
      responses:
        "200":
          description: Result.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/DelegatedResult" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/policy/delegated/bindings/{name}:
    parameters:
      - $ref: "#/components/parameters/DelegatedName"
    get:
      tags: [delegation]
      operationId: getDelegatedBinding
      summary: A delegated binding
      responses:
        "200":
          description: Binding.
          headers:
            ETag: { $ref: "#/components/headers/ObjectETag" }
          content:
            application/json:
              schema: { $ref: "#/components/schemas/DelegatedObject" }
        default: { $ref: "#/components/responses/Error" }
    put:
      tags: [delegation]
      operationId: putDelegatedBinding
      summary: Create or replace a delegated binding
      parameters:
        - $ref: "#/components/parameters/IfMatchObject"
        - $ref: "#/components/parameters/IfNoneMatch"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/DelegatedBindingRequest" }
      responses:
        "200":
          description: Result.
          headers:
            ETag: { $ref: "#/components/headers/ObjectETag" }
          content:
            application/json:
              schema: { $ref: "#/components/schemas/DelegatedResult" }
        default: { $ref: "#/components/responses/Error" }
    delete:
      tags: [delegation]
      operationId: deleteDelegatedBinding
      summary: Delete a delegated binding
      parameters:
        - $ref: "#/components/parameters/IfMatchObject"
        - $ref: "#/components/parameters/Delegation"
      responses:
        "200":
          description: Result.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/DelegatedResult" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/policy:
    get:
      tags: [policy]
      operationId: getEffectivePolicy
      summary: Effective policy (base file and active managed revision)
      description: |
        Requires policy.read. `load_error` tells why this replica does not
        serve the active managed revision (the health probes only say that it
        does not).
      responses:
        "200":
          description: Effective policy.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PolicyObject" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/policy/revisions:
    get:
      tags: [policy]
      operationId: listRevisions
      summary: Managed policy revisions, newest first
      parameters:
        - { name: status, in: query, schema: { type: string, enum: [proposed, approved, rejected, active, superseded] } }
        - { name: limit, in: query, schema: { type: integer } }
        - { name: cursor, in: query, schema: { type: string } }
      responses:
        "200":
          description: Page of revisions.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PolicyObject" }
        default: { $ref: "#/components/responses/Error" }
    post:
      tags: [policy]
      operationId: proposeRevision
      summary: Propose a managed policy revision
      description: Requires policy.propose.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/PolicyObject" }
      responses:
        "201":
          description: Proposed revision.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PolicyObject" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/policy/revisions/{id}:
    parameters:
      - $ref: "#/components/parameters/RevisionID"
    get:
      tags: [policy]
      operationId: getRevision
      summary: A revision with its document, diff and impact
      responses:
        "200":
          description: Revision.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PolicyObject" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/policy/revisions/{id}/export:
    parameters:
      - $ref: "#/components/parameters/RevisionID"
    get:
      tags: [policy]
      operationId: exportRevision
      summary: Managed document of a revision as YAML
      responses:
        "200":
          description: YAML.
          content:
            application/yaml:
              schema: { type: string }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/policy/revisions/{id}/approve:
    parameters:
      - $ref: "#/components/parameters/RevisionID"
    post:
      tags: [policy]
      operationId: approveRevision
      summary: Approve a revision (policy.approve, another approver than the author)
      requestBody:
        content:
          application/json:
            schema: { $ref: "#/components/schemas/DecisionRequest" }
      responses:
        "200":
          description: Revision.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PolicyObject" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/policy/revisions/{id}/reject:
    parameters:
      - $ref: "#/components/parameters/RevisionID"
    post:
      tags: [policy]
      operationId: rejectRevision
      summary: Reject a revision (policy.approve)
      requestBody:
        content:
          application/json:
            schema: { $ref: "#/components/schemas/DecisionRequest" }
      responses:
        "200":
          description: Revision.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PolicyObject" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/policy/revisions/{id}/activate:
    parameters:
      - $ref: "#/components/parameters/RevisionID"
    post:
      tags: [policy]
      operationId: activateRevision
      summary: Activate a revision
      responses:
        "200":
          description: Revision.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PolicyObject" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/policy/revisions/{id}/rollback:
    parameters:
      - $ref: "#/components/parameters/RevisionID"
    post:
      tags: [policy]
      operationId: rollbackRevision
      summary: Propose a new revision copying revision {id}
      responses:
        "201":
          description: Proposed revision.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PolicyObject" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/policy/explain:
    post:
      tags: [policy]
      operationId: explain
      summary: Simulate an authorization decision
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/PolicyObject" }
      responses:
        "200":
          description: Decision and its reasons.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PolicyObject" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/policy/who-can:
    get:
      tags: [policy]
      operationId: whoCan
      summary: Bindings and keys allowed to perform an action on an RRset
      parameters:
        - { name: zone, in: query, required: true, schema: { type: string } }
        - { name: host, in: query, schema: { type: string } }
        - { name: type, in: query, schema: { type: string } }
        - { name: action, in: query, schema: { type: string, default: dns.record.write } }
      responses:
        "200":
          description: Grants.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PolicyObject" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/policy/virtual-keys/generate:
    post:
      tags: [policy]
      operationId: generateVirtualKey
      summary: Generate a virtual key (shown once, only its hash goes in a proposal)
      responses:
        "200":
          description: Key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  app_id: { type: string }
                  key: { type: string }
                  key_sha256: { type: string }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/api-keys:
    get:
      tags: [api-keys]
      operationId: listAPIKeys
      summary: API keys the caller manages
      description: |
        Keys of the caller's teams (of every team for a holder of
        `gate.apikey.manage` on `*`) whose role zones it manages. Never the
        key itself. Needs `gate.apikey.manage`; keys cannot manage keys.
      parameters:
        - { name: team, in: query, schema: { type: string } }
        - { name: include_revoked, in: query, schema: { type: boolean } }
      responses:
        "200":
          description: Keys, oldest first.
          content:
            application/json:
              schema: { type: array, items: { $ref: "#/components/schemas/APIKey" } }
        "403": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }
    post:
      tags: [api-keys]
      operationId: createAPIKey
      summary: Create an API key (the key is returned once)
      description: |
        Binds a new key to one team of the caller and one role. The role
        must not grant `policy.*` nor `gate.*` actions, and the caller must
        hold `gate.apikey.manage` on every zone of the role and every action
        of the role on the same zones and records, with an ephemeral TTL and
        a change limit no looser than its own (`403 forbidden` otherwise).
        The grant of the role is recorded: if the role later grants more,
        the key is refused (`403 role_widened`). `acme_domains` creates one acme-dns registration per
        domain (the role must allow `_acme-challenge.<domain>` TXT and have
        an `ephemeral_ttl`); `acme_dns_accounts` in the answer is the storage
        file of acme-dns clients. Humans need a recent login.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/APIKeyRequest" }
      responses:
        "201":
          description: Key, with the secret (shown once).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/IssuedAPIKey" }
        "400": { $ref: "#/components/responses/Error" }
        "403": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/api-keys/{id}:
    parameters:
      - $ref: "#/components/parameters/APIKeyID"
    get:
      tags: [api-keys]
      operationId: getAPIKey
      summary: One API key (404 when the caller does not manage it)
      responses:
        "200":
          description: Key.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/APIKey" }
        "404": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }
    put:
      tags: [api-keys]
      operationId: replaceAPIKey
      summary: Replace the mutable fields of an API key
      description: |
        Replaces name, description, expires_at and allowed_cidrs (omitted
        fields are cleared). `acme_domains`, when present, syncs the
        registrations created through the API (kept domains keep their
        subdomain); when absent, registrations stay as they are; those of
        clients are never touched. Team and role cannot change
        (`409 immutable`); a revoked key cannot change (`409 revoked`).
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/APIKeyRequest" }
      responses:
        "200":
          description: Key.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/APIKey" }
        "400": { $ref: "#/components/responses/Error" }
        "404": { $ref: "#/components/responses/Error" }
        "409": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }
    delete:
      tags: [api-keys]
      operationId: revokeAPIKey
      summary: Revoke an API key
      description: The key stops working at once; it stays listed with `include_revoked=true`. Idempotent. Besides its managers, its creator and the members of its team holding `gate.apikey.manage` anywhere may revoke it.
      responses:
        "204": { description: Revoked. }
        "404": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/api-keys/{id}/rotate:
    parameters:
      - $ref: "#/components/parameters/APIKeyID"
    post:
      tags: [api-keys]
      operationId: rotateAPIKey
      summary: Rotate an API key (the new key is returned once)
      description: |
        Issues a new key for the same id; the previous key stays valid during
        `overlap` (default 24h, `0s` to stop it at once). Only one previous
        key is kept: rotating again ends the previous overlap.
      requestBody:
        content:
          application/json:
            schema: { $ref: "#/components/schemas/APIKeyRotate" }
      responses:
        "200":
          description: Key, with the new secret.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/IssuedAPIKey" }
        "404": { $ref: "#/components/responses/Error" }
        "409": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/providers/{provider}/zone-profiles:
    parameters:
      - $ref: "#/components/parameters/ProviderID"
    get:
      tags: [zone-profiles]
      operationId: listZoneProfiles
      summary: Zone profiles of a EuroDNS provider
      description: |
        Every zone profile (id and name) of the EuroDNS account of the
        provider. Zone profiles are account-wide templates (records, URL and
        mail forwards) that EuroDNS applies to a domain when it arrives on its
        nameservers (a transfer, a Premium DNS subscription); they name no
        domain. Every zone profile operation needs `dns.zone.profile` granted
        on `*` (`403 forbidden` otherwise), a provider with
        `eurodns.zone_profiles: true` (`403 zone_profiles_disabled`), and is
        audited; a provider of another kind answers `400 invalid_provider`.
        Writes need a recent login from humans (`403 reauth_required`);
        records of the protected list are refused on create, update and check
        (`403 protected`); 60 operations per subject and minute
        (`429 rate_limited`).
      responses:
        "200":
          description: Profiles, by id.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ZoneProfileList" }
        "403": { $ref: "#/components/responses/Error" }
        "404": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }
    post:
      tags: [zone-profiles]
      operationId: createZoneProfile
      summary: Create a zone profile
      description: |
        `name` is required; EuroDNS validates the content (`400 rejected`
        with its report or errors in `details`). The audit event holds the
        profile.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ZoneProfile" }
      responses:
        "201":
          description: Profile, with its id.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ZoneProfile" }
        "400": { $ref: "#/components/responses/Error" }
        "403": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/providers/{provider}/zone-profiles/check:
    parameters:
      - $ref: "#/components/parameters/ProviderID"
    post:
      tags: [zone-profiles]
      operationId: checkZoneProfile
      summary: Validate a zone profile without saving it
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ZoneProfile" }
      responses:
        "200":
          description: Profile as EuroDNS reads it, with its validation `report`.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ZoneProfile" }
        "403": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }

  /api/v1/providers/{provider}/zone-profiles/{id}:
    parameters:
      - $ref: "#/components/parameters/ProviderID"
      - $ref: "#/components/parameters/ZoneProfileID"
    get:
      tags: [zone-profiles]
      operationId: getZoneProfile
      summary: A zone profile
      responses:
        "200":
          description: Profile.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ZoneProfile" }
        "403": { $ref: "#/components/responses/Error" }
        "404": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }
    put:
      tags: [zone-profiles]
      operationId: updateZoneProfile
      summary: Replace a zone profile
      description: |
        The full profile; domains it was already applied to do not change.
        The audit event holds the previous and the new content.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ZoneProfile" }
      responses:
        "200":
          description: Profile.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ZoneProfile" }
        "400": { $ref: "#/components/responses/Error" }
        "403": { $ref: "#/components/responses/Error" }
        "404": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }
    delete:
      tags: [zone-profiles]
      operationId: deleteZoneProfile
      summary: Delete a zone profile
      description: The profile is read first; the audit event holds its content.
      responses:
        "204": { description: Deleted. }
        "403": { $ref: "#/components/responses/Error" }
        "404": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }

  /acme/httpreq/present:
    post:
      tags: [acme]
      operationId: httpreqPresent
      summary: Add a DNS-01 challenge value (lego httpreq)
      description: |
        lego `httpreq` provider with `HTTPREQ_ENDPOINT=https://<gate>/acme/httpreq`.
        Default mode: `fqdn` and `value`; RAW mode (`HTTPREQ_MODE=RAW`):
        `domain` and `keyAuth`, the value being base64url(SHA-256(keyAuth)).
        The value is added to the `_acme-challenge` TXT RRset (several
        challenges, a wildcard and its apex, coexist). Any credential of the
        gate; with an API key, basic authentication with the key id as user
        name (`HTTPREQ_USERNAME`) and the key as password
        (`HTTPREQ_PASSWORD`). The caller's role must have an `ephemeral_ttl`
        (`403 ephemeral_required`). Each value belongs to its author: cleanup
        removes only the caller's own values, and a value written by another
        caller cannot be presented again (`409 value_taken`). An RRset holds
        at most `acme.max_values` values, `acme.max_values_per_author` per
        caller (`409 too_many_values`).
      security:
        - apiKeyBasic: []
        - apiKey: []
        - bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/HTTPReqRequest" }
      responses:
        "200":
          description: Present.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/HTTPReqResult" }
        "400": { $ref: "#/components/responses/Error" }
        "401": { $ref: "#/components/responses/Error" }
        "403": { $ref: "#/components/responses/Error" }
        "409": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }

  /acme/httpreq/cleanup:
    post:
      tags: [acme]
      operationId: httpreqCleanup
      summary: Remove a DNS-01 challenge value (lego httpreq)
      description: Removes the value; the RRset is deleted with its last value. Same body and credentials as present.
      security:
        - apiKeyBasic: []
        - apiKey: []
        - bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/HTTPReqRequest" }
      responses:
        "200":
          description: Cleaned up (also when the value was absent).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/HTTPReqResult" }
        "400": { $ref: "#/components/responses/Error" }
        "401": { $ref: "#/components/responses/Error" }
        "403": { $ref: "#/components/responses/Error" }
        default: { $ref: "#/components/responses/Error" }

  /acme/acme-dns/update:
    post:
      tags: [acme]
      operationId: acmeDNSUpdate
      summary: Set a DNS-01 challenge value (acme-dns)
      description: |
        acme-dns `/update` with base URL `https://<gate>/acme/acme-dns`.
        `X-Api-User` is the key id and `X-Api-Key` the key; or `X-Api-Key` is
        a token (a gate token from the token exchange, or an OIDC token) and
        `X-Api-User` any non-empty value. These headers win over basic
        authentication taken from the URL; `Authorization: Bearer` also
        works. `subdomain` is a registration of the key (from
        `acme_dns_accounts` or `/register`) or a domain name
        (`www.example.com`, the only form with a token): the value is written to
        `_acme-challenge.<domain>` in its managed zone, no CNAME needed. As
        acme-dns, the two most recent values of a registration are kept;
        there is no cleanup call, the ephemeral TTL of the role removes the
        RRset. With a token, the two values are tracked per subject and
        domain. Errors are `{"error", "message"}`.
      security:
        - acmeDNSUser: []
          acmeDNSKey: []
        - apiKeyBasic: []
        - bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [subdomain, txt]
              properties:
                subdomain: { type: string, examples: ["8e5700ea-a4bf-41c7-8a77-e990661dcc6a", "www.example.com"] }
                txt: { type: string, pattern: "^[A-Za-z0-9_-]{43}$" }
      responses:
        "200":
          description: Written.
          content:
            application/json:
              schema:
                type: object
                properties:
                  txt: { type: string }
        "400": { $ref: "#/components/responses/ACMEDNSError" }
        "401": { $ref: "#/components/responses/ACMEDNSError" }
        "403": { $ref: "#/components/responses/ACMEDNSError" }
        default: { $ref: "#/components/responses/ACMEDNSError" }

  /acme/acme-dns/register:
    post:
      tags: [acme]
      operationId: acmeDNSRegister
      summary: Create an acme-dns registration of an API key
      description: |
        Unlike acme-dns, registration is not anonymous: without credentials
        the answer is `401 registration_requires_api_key`. With a key (basic
        authentication, e.g. from the user info of the base URL, or
        `X-Api-User` / `X-Api-Key`), the body names the domain (`domain`, a
        gate extension; `400 domain_required` otherwise) and the answer is an
        acme-dns account whose password is the presented key.
      security:
        - apiKeyBasic: []
        - acmeDNSUser: []
          acmeDNSKey: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                domain: { type: string, examples: ["www.example.com"] }
                allowfrom: { type: array, items: { type: string }, description: "CIDR prefixes allowed to call /update for this registration." }
      responses:
        "201":
          description: Account.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ACMEDNSAccount" }
        "400": { $ref: "#/components/responses/ACMEDNSError" }
        "401": { $ref: "#/components/responses/ACMEDNSError" }
        "403": { $ref: "#/components/responses/ACMEDNSError" }
        default: { $ref: "#/components/responses/ACMEDNSError" }

components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Token of an issuer declared in the gate configuration (Entra ID, GitHub Actions, GitLab, Azure DevOps, any OIDC issuer).
    virtualKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: Virtual key, with its application id in X-App-Id.
    virtualKeyApp:
      type: apiKey
      in: header
      name: X-App-Id
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: dgk
      description: Gate API key (`dgk_<id>_<secret>`) as a bearer token.
    apiKeyBasic:
      type: http
      scheme: basic
      description: Gate API key as the password, its id as the user name.
    acmeDNSUser:
      type: apiKey
      in: header
      name: X-Api-User
      description: Id of the gate API key (acme-dns user name).
    acmeDNSKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: Gate API key (acme-dns password), or a token on /update.
    session:
      type: apiKey
      in: cookie
      name: __Host-dns-gate-session
      description: Web UI session. Requests other than GET also need X-Gate-CSRF and a same-origin Origin.

  parameters:
    Zone:
      name: zone
      in: path
      required: true
      description: Zone name, e.g. `example.com`.
      schema: { type: string }
    Host:
      name: host
      in: path
      required: true
      description: Host relative to the zone, `@` for the apex; `*` is allowed as the first label (`*.app`).
      schema: { type: string, examples: ["www", "@", "*.app", "_acme-challenge.www"] }
    Type:
      name: type
      in: path
      required: true
      description: Record type, case-insensitive.
      schema: { type: string, examples: ["A", "CNAME", "TXT"] }
    IfMatch:
      name: If-Match
      in: header
      description: '`"<hash>"`: the RRset must have this content hash (`412 precondition` otherwise).'
      schema: { type: string }
    IfNoneMatch:
      name: If-None-Match
      in: header
      description: '`*`: create only (`412 precondition` if the object exists).'
      schema: { type: string, enum: ["*"] }
    IfMatchObject:
      name: If-Match
      in: header
      description: ETag of the delegated object (`412 precondition` otherwise).
      schema: { type: string }
    DelegatedName:
      name: name
      in: path
      required: true
      schema: { type: string, pattern: "^[a-z0-9]([a-z0-9._-]{0,62}[a-z0-9])?$" }
    Delegation:
      name: delegation
      in: query
      description: Delegation acting, when the caller matches several.
      schema: { type: string }
    APIKeyID:
      name: id
      in: path
      required: true
      schema: { type: string, pattern: "^[0-9a-f]{16}$" }
    ProviderID:
      name: provider
      in: path
      required: true
      description: Id of a provider of the gate configuration (`providers[].id`).
      schema: { type: string, examples: ["eurodns"] }
    ZoneProfileID:
      name: id
      in: path
      required: true
      description: EuroDNS zone profile id.
      schema: { type: integer, format: int32, minimum: 1 }
    RevisionID:
      name: id
      in: path
      required: true
      schema: { type: string, pattern: "^[a-z0-9-]{8,64}$" }
    TransferID:
      name: id
      in: path
      required: true
      schema: { type: string, examples: ["tr-1780000000000-0a1b2c3d4e"] }
    TeamName:
      name: team
      in: path
      required: true
      schema: { type: string, pattern: "^[a-z0-9]([a-z0-9._-]{0,62}[a-z0-9])?$" }
    Team:
      name: X-DNS-Gate-Team
      in: header
      description: |
        One of the caller's teams to act for: created and adopted RRsets go
        to it and only its RRsets may be changed (`403 not_team_member` when
        the caller is not a member). Default: the caller's first team, with
        write access to the RRsets of all its teams.
      schema: { type: string }

  headers:
    RRsetETag:
      description: Content hash of the RRset, `"<hash>"`, to send back in If-Match.
      schema: { type: string }
    ObjectETag:
      description: ETag of the delegated object.
      schema: { type: string }

  responses:
    Error:
      description: Error.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    OAuthError:
      description: OAuth 2.0 error (RFC 6749).
      content:
        application/json:
          schema:
            type: object
            required: [error]
            properties:
              error: { type: string, examples: [invalid_grant, invalid_request, unsupported_grant_type, token_exchange_disabled] }
              error_description: { type: string }
    ACMEDNSError:
      description: acme-dns error.
      content:
        application/json:
          schema:
            type: object
            required: [error]
            properties:
              error:
                type: string
                description: |
                  forbidden, registration_requires_api_key, domain_required,
                  bad_domain, bad_subdomain, bad_txt, invalid_allowfrom_cidr, too_many_values, too_many_registrations, value_taken,
                  malformed_json_payload, ephemeral_required, source_ip,
                  no_binding, unavailable, or a zone engine reason.
              message: { type: string }
    Locked:
      description: The zone is locked by another write; retry after Retry-After seconds.
      headers:
        Retry-After:
          schema: { type: integer }
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }

  schemas:
    Error:
      type: object
      required: [reason, message]
      properties:
        reason:
          type: string
          description: |
            Stable machine-readable reason; clients should treat an unknown
            value by its HTTP status. Status by reason:
            400 invalid, relative_target, bad_request, invalid_policy,
            delegation_required, team_mismatch;
            401 unauthenticated;
            403 forbidden, not_owner, too_many_changes, reauth_required, csrf,
            no_binding, bound_claims, source_ip, policy_not_editable,
            self_approval, delegated_object, session_required, not_team_member,
            not_delegable, scope_insufficient (with required_scope), unknown_client;
            404 not_found, plan_not_found, zone_not_eurodns;
            405 method_not_allowed;
            409 foreign_rrset, tainted, adopt_conflict, https_unavailable, not_owner (delegated
            object of another delegation), policy_busy, conflict, name_taken,
            stale_revision, approval_required, invalid_status, already_decided;
            410 plan_expired, expired; 412 precondition; 413 too_large; 415 bad_request;
            423 zone_locked; 429 rate_limited; 500 internal;
            501 not_implemented; 502 upstream; 503 store_unavailable,
            unavailable; 504 timeout. API keys and ACME add 403
            ephemeral_required, role_widened and 409 immutable, revoked,
            too_many_values, too_many_registrations, value_taken. Zone
            profiles add 400 rejected, invalid_provider and 403 protected,
            zone_profiles_disabled.
          enum:
            - invalid
            - relative_target
            - bad_request
            - invalid_policy
            - delegation_required
            - team_mismatch
            - unauthenticated
            - forbidden
            - not_owner
            - too_many_changes
            - reauth_required
            - csrf
            - no_binding
            - bound_claims
            - source_ip
            - policy_not_editable
            - self_approval
            - delegated_object
            - session_required
            - not_team_member
            - not_delegable
            - scope_insufficient
            - unknown_client
            - not_found
            - plan_not_found
            - zone_not_eurodns
            - method_not_allowed
            - foreign_rrset
            - tainted
            - adopt_conflict
            - https_unavailable
            - policy_busy
            - conflict
            - name_taken
            - stale_revision
            - approval_required
            - invalid_status
            - already_decided
            - plan_expired
            - expired
            - precondition
            - too_large
            - zone_locked
            - rate_limited
            - internal
            - not_implemented
            - upstream
            - store_unavailable
            - unavailable
            - timeout
            - ephemeral_required
            - immutable
            - revoked
            - role_widened
            - too_many_values
            - value_taken
            - too_many_registrations
            - rejected
            - invalid_provider
            - protected
            - zone_profiles_disabled
        message: { type: string }
        required_scope:
          type: string
          description: With scope_insufficient, a scope of the delegated client that would open the request.
          enum: [dns.read, dns.plan, dns.write, dns.adopt, dns.transfer, policy.read]
        details: {}
        transfer:
          $ref: "#/components/schemas/Transfer"
          description: The failed transfer, when its approval could not apply it.
        errors:
          type: array
          description: Validation errors of a policy document (reason invalid_policy).
          items:
            type: object
            properties:
              path: { type: string }
              message: { type: string }

    GateInfo:
      type: object
      required: [version, features]
      properties:
        version: { type: string }
        features:
          type: array
          description: |
            if-match, ownership, adopt (EuroDNS-compatible API extensions),
            policy-delegation (/api/v1/policy/delegated), plans
            (/api/v1/zones/{zone}/plan and apply), rrset-api
            (/api/v1/zones/{zone}/rrsets/{host}/{type}), forwards
            (/api/v1/zones/{zone}/forwards), api-keys
            (/api/v1/api-keys), acme-httpreq (/acme/httpreq), acme-dns
            (/acme/acme-dns), token-exchange (/api/v1/token-exchange).
          items: { type: string }

    Actor:
      type: object
      properties:
        subject: { type: string, description: "issuer:id" }
        name: { type: string }
        category: { type: string, enum: [human, pipeline, key, system] }

    Permission:
      type: object
      properties:
        role: { type: string }
        zones: { type: array, items: { type: string } }
        folders: { type: array, items: { type: string }, description: "Folder globs: the rule also applies to the zones whose provider folder matches one." }
        folder_zones: { type: array, items: { type: string }, description: "Zone globs a zone selected through folders must also match: policy.bounds.zones of a managed rule, allow.zones of a delegated one. Absent: no narrowing." }
        actions: { type: array, items: { type: string } }
        hosts: { type: array, items: { type: string } }
        types: { type: array, items: { type: string } }

    Me:
      type: object
      properties:
        subject: { type: string }
        name: { type: string }
        category: { type: string }
        email:
          type: string
          format: email
          description: >-
            Email address the issuer of the caller vouches for: the SAML email
            attribute or email-format NameID, the email claim of an OIDC issuer when
            verified (email_claim, email_verified_claim) or trusted (email_trusted),
            the email of the session a declared OAuth client was authorized with
            (within claims_max_age). Absent otherwise (API keys, virtual keys,
            unverified claims); never derived from name or subject.
        roles: { type: array, items: { type: string } }
        teams: { type: array, items: { type: string } }
        groups: { type: array, items: { type: string } }
        permissions: { type: array, items: { $ref: "#/components/schemas/Permission" } }
        default_team: { type: string, description: "Team the caller writes for unless it selects another of its teams." }
        client:
          type: object
          description: Delegated client the caller acts through (issuers[].delegated_clients); permissions are then clipped to its scopes and zones.
          properties:
            id: { type: string }
            name: { type: string }
            zones: { type: array, items: { type: string } }
            surfaces: { type: array, items: { type: string, enum: [api, mcp] } }
        scopes:
          type: array
          description: Scopes of the delegated client.
          items: { type: string, enum: [dns.read, dns.plan, dns.write, dns.adopt, dns.transfer, policy.read] }

    Connect:
      type: object
      properties:
        base_url: { type: string }
        mcp:
          type: object
          properties:
            enabled: { type: boolean }
            url: { type: string }
            allow_writes: { type: boolean }
        issuer:
          type: object
          properties:
            url: { type: string }
            kind: { type: string, enum: [entra, oidc, saml], description: "saml: url is the gate issuer, if any." }
            tenant_id: { type: string }
        client_id: { type: string }
        cli_scope: { type: string }
        claude_desktop_extension_url: { type: string }
        tokens_url: { type: string, description: "POST here for a gate token (UI session); absent without a gate issuer." }

    IssuedToken:
      type: object
      required: [access_token, token_type, expires_in, expires_at, issuer]
      properties:
        access_token: { type: string }
        token_type: { type: string, enum: [Bearer] }
        expires_in: { type: integer, description: "Seconds." }
        expires_at: { type: string, format: date-time }
        issuer: { type: string, description: "URL of the gate issuer." }

    ZoneSummary:
      type: object
      required: [zone, provider, rrsets, managed, tainted, pending, foreign]
      properties:
        zone: { type: string }
        provider: { type: string, description: "Provider instance id, e.g. eurodns or route53-prod." }
        folder: { type: string, description: 'Provider folder of the zone (EuroDNS), "/" for a zone in no folder; absent for providers without folders (Route53) or a zone not listed.', examples: ["/ES/Madrid"] }
        unmanaged: { type: boolean, description: "Discovered, not managed by the gate (read-only)." }
        rrsets: { type: integer }
        managed: { type: integer }
        tainted: { type: integer }
        pending: { type: integer }
        foreign: { type: integer }
        last_synced_at: { type: string, format: date-time }
        last_write_at: { type: string, format: date-time }

    Alias:
      type: object
      description: Provider alias target (Route53 alias records). An RRset with an alias has no values.
      required: [target, hosted_zone_id]
      properties:
        target: { type: string, examples: ["d111111abcdef8.cloudfront.net."] }
        hosted_zone_id: { type: string, examples: ["Z2FDTNDATAQYW2"] }
        evaluate_target_health: { type: boolean, default: false }

    Forward:
      type: object
      description: |
        URL forward of a host (RRset type URLFWD, TTL 0, no values). Its
        content hash is the RRset hash of TTL 0 and the single value
        `forward <type> <n>:<url> <n>:<title> <n>:<keywords> <n>:<description>`,
        n being the length in bytes of the field that follows.
      required: [type, url]
      properties:
        type: { type: string, enum: ["301", "302", frame], description: "301 or 302 redirect, or a frame showing the URL." }
        url: { type: string, examples: ["https://www.example.com/"], description: "Absolute http:// or https:// URL." }
        title: { type: string, description: "Frame forwards only." }
        keywords: { type: string, description: "Frame forwards only." }
        description: { type: string, description: "Frame forwards only." }

    HTTPSRedirect:
      type: object
      description: |
        Whether the forwards of a zone answer HTTPS requests. EuroDNS needs an
        HTTPS redirect subscription on the domain (read from
        /subscriptions and /https-redirect-subscriptions, cached 10 minutes);
        the gate never orders one.
      required: [status]
      properties:
        status: { type: string, enum: [active, pending, no_forward, inactive, unsupported, unknown], description: "inactive also covers a subscription past its expiration date; unknown is a failed read, kept 30 seconds." }
        subscription: { type: string, description: "Provider subscription id." }
        expires_at: { type: string }
        message: { type: string }

    ForwardView:
      allOf:
        - $ref: "#/components/schemas/RRset"
        - type: object
          properties:
            https: { $ref: "#/components/schemas/HTTPSRedirect" }

    ForwardList:
      type: object
      required: [zone, forwards]
      properties:
        zone: { type: string }
        https: { $ref: "#/components/schemas/HTTPSRedirect" }
        forwards: { type: array, items: { $ref: "#/components/schemas/RRset" } }

    ForwardPut:
      type: object
      additionalProperties: false
      required: [type, url]
      description: |
        `url` is an absolute http or https URL in canonical form, without user
        information, spaces, control characters nor unencoded `< > " ' ` \ { } | ^`.
        Frame fields are plain text without control characters nor `< > " ' ``.
      properties:
        type: { type: string, enum: ["301", "302", frame] }
        url: { type: string, maxLength: 2048 }
        title: { type: string, maxLength: 200 }
        keywords: { type: string, maxLength: 500 }
        description: { type: string, maxLength: 1000 }
        require_https: { type: boolean, description: "Refuse unless the forwards of the zone answer HTTPS (not stored)." }

    RRset:
      type: object
      required: [host, type, ttl, values, hash, status, protected, adopted]
      properties:
        host: { type: string, description: "Relative to the zone, @ for the apex." }
        type: { type: string }
        ttl: { type: integer }
        values: { type: array, items: { type: string } }
        alias: { $ref: "#/components/schemas/Alias" }
        forward: { $ref: "#/components/schemas/Forward" }
        read_only: { type: string, description: "Why the gate never writes this RRset (server_managed, routing_policy, relative_target, unsupported_forward, duplicate_forward, forward_record...)." }
        hash: { type: string, description: "Content hash (TTL and values, alias or forward), the ETag of the RRset." }
        status: { type: string, enum: [managed, tainted, pending, foreign, missing] }
        protected: { type: boolean }
        owner: { type: string, description: "Owner team." }
        created_by: { $ref: "#/components/schemas/Actor" }
        created_at: { type: string, format: date-time }
        updated_by: { $ref: "#/components/schemas/Actor" }
        updated_at: { type: string, format: date-time }
        adopted: { type: boolean }
        expires_at: { type: string, format: date-time }
        last_request_id: { type: string }

    ZoneInventory:
      type: object
      required: [zone, rrsets]
      properties:
        zone: { type: string }
        provider: { type: string, description: "Provider instance id serving the zone." }
        folder: { type: string, description: 'Provider folder of the zone (EuroDNS), "/" for a zone in no folder.' }
        unmanaged: { type: boolean }
        last_synced_at: { type: string, format: date-time }
        rrsets: { type: array, items: { $ref: "#/components/schemas/RRset" } }
        tombstones:
          type: array
          description: RRsets of a managed zone deleted recently through the gate, still reserved for their team.
          items: { $ref: "#/components/schemas/Tombstone" }

    Tombstone:
      type: object
      required: [host, type, team, deleted_at, expires_at]
      description: Until expires_at, only this team may create or adopt the RRset again; others ask for a transfer.
      properties:
        host: { type: string }
        type: { type: string }
        team: { type: string }
        deleted_by: { $ref: "#/components/schemas/Actor" }
        deleted_at: { type: string, format: date-time }
        expires_at: { type: string, format: date-time }

    RRsetPut:
      type: object
      additionalProperties: false
      description: "`values` (with `ttl`) or `alias`, not both. A missing ttl keeps the current one, or the provider default for a new RRset."
      properties:
        ttl: { type: integer, minimum: 1 }
        values: { type: array, minItems: 1, items: { type: string } }
        alias: { $ref: "#/components/schemas/Alias" }

    Propagation:
      type: object
      required: [zone, host, type, name, query_type, expected, checked_at, cached, summary, answers]
      properties:
        zone: { type: string }
        host: { type: string }
        type: { type: string }
        name: { type: string, description: "Absolute name asked, e.g. www.example.com." }
        query_type: { type: string, description: "Type asked: the RRset type, A for a EuroDNS APEX RRset." }
        expected:
          type: object
          required: [exists, values]
          properties:
            exists: { type: boolean, description: "False when the RRset does not exist (after a deletion)." }
            hash: { type: string }
            ttl: { type: integer }
            values: { type: array, items: { type: string }, description: "Comparison form: sorted, names absolute and lowercase, TXT as raw content." }
            alias_target: { type: string, description: "Target of an alias or APEX RRset, compared on its addresses." }
        checked_at: { type: string, format: date-time }
        cached: { type: boolean, description: "Served from the short cache of an identical check." }
        summary:
          type: object
          required: [total, match, stale, missing, error, indeterminate, converged, max_ttl_left]
          properties:
            total: { type: integer }
            match: { type: integer }
            stale: { type: integer }
            missing: { type: integer }
            error: { type: integer }
            indeterminate: { type: integer, description: "Alias answers whose addresses could not be tied to the target." }
            converged: { type: boolean, description: "Every server that answered has the expected content, with at least one authoritative match; indeterminate answers prevent it." }
            max_ttl_left: { type: integer, description: "Longest TTL left among the stale and missing answers, in seconds: when those caches expire at the latest." }
        answers: { type: array, items: { $ref: "#/components/schemas/PropagationAnswer" } }

    PropagationAnswer:
      type: object
      required: [kind, name, address, status, values, latency_ms]
      properties:
        kind: { type: string, enum: [authoritative, resolver] }
        name: { type: string, description: "Name server host name, or resolver name." }
        address: { type: string }
        location: { type: string }
        country: { type: string, description: "ISO 3166 code." }
        region: { type: string }
        status: { type: string, enum: [match, stale, missing, error, indeterminate] }
        values: { type: array, items: { type: string } }
        cnames: { type: array, items: { type: string }, description: "CNAME chain followed from the name." }
        ttl_left: { type: integer, description: "Remaining TTL of the answer, or of a negative answer (SOA minimum), in seconds." }
        rcode: { type: string }
        latency_ms: { type: integer }
        tcp: { type: boolean, description: "Answered over TCP after a truncated or failed UDP query." }
        error: { type: string }
        filtering: { type: boolean, description: "The resolver blocks some names by policy: its negative answers may be a filter decision." }
        truncated: { type: boolean, description: "Values left out (more than 32) or cut (over 512 bytes)." }

    RRsetChange:
      type: object
      required: [host, type]
      description: Desired state of one RRset; delete removes it.
      properties:
        host: { type: string }
        type: { type: string }
        ttl: { type: integer }
        values: { type: array, items: { type: string } }
        alias: { $ref: "#/components/schemas/Alias" }
        forward: { $ref: "#/components/schemas/Forward" }
        require_https: { type: boolean, description: "Forwards only: refuse unless the forwards of the zone answer HTTPS (409 https_unavailable)." }
        delete: { type: boolean }
        expected_hash: { type: string, description: "The RRset must have this content hash." }
        must_not_exist: { type: boolean, description: "The RRset must not exist." }

    Change:
      type: object
      properties:
        op: { type: string, enum: [create, update, delete, adopt, taint, expire, transfer] }
        host: { type: string }
        type: { type: string }
        old_ttl: { type: integer }
        old_values: { type: array, items: { type: string } }
        old_alias: { $ref: "#/components/schemas/Alias" }
        old_forward: { $ref: "#/components/schemas/Forward" }
        new_ttl: { type: integer }
        new_values: { type: array, items: { type: string } }
        new_alias: { $ref: "#/components/schemas/Alias" }
        new_forward: { $ref: "#/components/schemas/Forward" }
        new_hash: { type: string, description: "Apply results: content hash of the RRset after a create or update, the `expect` of a propagation check (omitted after a delete: expect `absent`)." }

    PlanRequest:
      type: object
      required: [changes]
      additionalProperties: false
      properties:
        changes:
          type: array
          minItems: 1
          maxItems: 100
          items: { $ref: "#/components/schemas/RRsetChange" }
        team: { type: string, description: "One of the caller's teams to act for (overrides X-DNS-Gate-Team)." }

    ApplyRequest:
      type: object
      required: [plan_id]
      additionalProperties: false
      properties:
        plan_id: { type: string }
        team: { type: string, description: "Must be the team of the plan, if the plan has one." }

    PlanResult:
      type: object
      required: [zone, allowed, changes, zone_version]
      properties:
        zone: { type: string }
        allowed: { type: boolean }
        reason: { type: string, description: "Engine reason when refused." }
        message: { type: string }
        changes: { type: array, items: { $ref: "#/components/schemas/Change" } }
        zone_version: { type: integer }
        plan_id: { type: string }
        team: { type: string, description: "Team selected for the plan or apply, empty for the default team." }

    RRsetRef:
      type: object
      required: [host, type]
      properties:
        host: { type: string }
        type: { type: string }

    AdoptSelection:
      type: object
      properties:
        rrsets: { type: array, items: { $ref: "#/components/schemas/RRsetRef" } }
        hosts: { type: array, items: { type: string }, description: "Host globs, combined with types." }
        types: { type: array, items: { type: string } }
        owner: { type: string, description: "Team; defaults to the caller's team. Another team requires dns.ownership.approve on each RRset." }

    AdoptPreview:
      type: object
      properties:
        zone: { type: string }
        owner: { type: string }
        candidates:
          type: array
          items:
            type: object
            properties:
              host: { type: string }
              type: { type: string }
              ttl: { type: integer }
              values: { type: array, items: { type: string } }
              forward: { $ref: "#/components/schemas/Forward" }
              status: { type: string }
              adoptable: { type: boolean }
              reason: { type: string, enum: [protected, server_managed, owned_by_other_team, reserved_for_other_team, already_owned, forbidden, relative_target, unsupported_forward, duplicate_forward, forward_record, invalid, invalid_forward, not_found] }
        preview_token: { type: string }

    AdoptApply:
      type: object
      required: [rrsets, comment, preview_token]
      properties:
        rrsets: { type: array, items: { $ref: "#/components/schemas/RRsetRef" } }
        owner: { type: string }
        comment: { type: string, maxLength: 2000 }
        preview_token: { type: string }

    AdoptResult:
      type: object
      properties:
        zone: { type: string }
        owner: { type: string }
        adopted: { type: array, items: { $ref: "#/components/schemas/RRsetRef" } }
        request_id: { type: string }

    AuditEntry:
      type: object
      properties:
        event_id: { type: string, description: "UUIDv7, the same as on the stdout audit line. Absent on events recorded before 0.9." }
        time: { type: string, format: date-time }
        request_id: { type: string }
        actor: { $ref: "#/components/schemas/Actor" }
        auth_method:
          type: string
          enum: [oidc, oidc-session, saml-session, gate-token, token-exchange, api-key, virtual-key, oauth-delegated]
        client:
          type: object
          description: Delegated client the actor acted through (issuers[].delegated_clients).
          properties:
            id: { type: string }
            name: { type: string }
        source_ip: { type: string, description: "Client address. Served to policy.read holders only." }
        user_agent: { type: string, maxLength: 256, description: "Client user agent. Served to policy.read holders only." }
        teams: { type: array, items: { type: string } }
        action: { type: string }
        zone: { type: string }
        decision: { type: string, enum: [allow, deny, error] }
        reason: { type: string }
        changes: { type: array, items: { $ref: "#/components/schemas/Change" } }
        provider: { type: string, description: "Provider instance id of the zone." }
        snapshot_id: { type: string, description: "Provider snapshot taken before the write (EuroDNS)." }

    AuditPage:
      type: object
      required: [entries]
      properties:
        entries: { type: array, items: { $ref: "#/components/schemas/AuditEntry" } }
        next_cursor: { type: string }

    SubjectMatcher:
      type: object
      required: [issuer]
      properties:
        issuer: { type: string }
        claims:
          type: object
          additionalProperties: { type: array, items: { type: string } }

    TeamFrom:
      type: object
      required: [claim, regex]
      properties:
        claim: { type: string }
        regex: { type: string, description: "Anchored, exactly one capture group." }
        prefix: { type: string }

    Rule:
      type: object
      description: A rule applies to the zones matching `zones` and to the zones whose provider folder matches `folders`; at least one of them is required.
      required: [zones, actions]
      properties:
        zones: { type: array, items: { type: string } }
        folders: { type: array, items: { type: string, examples: ["/ES", "/ES/**"] } }
        actions: { type: array, items: { type: string, examples: ["dns.read", "dns.record.write", "ui.read"] } }
        records:
          type: object
          properties:
            hosts: { type: array, items: { type: string } }
            types: { type: array, items: { type: string } }

    Role:
      type: object
      required: [rules]
      properties:
        description: { type: string }
        rules: { type: array, items: { $ref: "#/components/schemas/Rule" } }
        rebase_on_save: { type: boolean }
        ephemeral_ttl: { type: string, description: "Go duration." }
        max_changes_per_request: { type: integer }

    Binding:
      type: object
      required: [role]
      properties:
        role: { type: string }
        team: { type: string }
        team_from: { $ref: "#/components/schemas/TeamFrom" }
        groups: { type: array, items: { type: string } }
        subjects: { type: array, items: { $ref: "#/components/schemas/SubjectMatcher" } }

    DelegatedRoleRequest:
      allOf:
        - $ref: "#/components/schemas/Role"
        - type: object
          properties:
            delegation: { type: string, description: "Delegation acting, when the caller matches several." }
            managed_by: { type: string, description: 'Client label, e.g. "terraform".' }

    DelegatedBindingRequest:
      allOf:
        - $ref: "#/components/schemas/Binding"
        - type: object
          properties:
            delegation: { type: string }
            managed_by: { type: string }

    DelegatedOwner:
      type: object
      properties:
        delegation: { type: string }
        managed_by: { type: string }
        created_by: { type: string }
        created_at: { type: string, format: date-time }
        updated_by: { type: string }
        updated_at: { type: string, format: date-time }

    DelegatedObject:
      type: object
      required: [kind, name, owner, etag, revision_id]
      properties:
        kind: { type: string, enum: [role, binding] }
        name: { type: string }
        role: { $ref: "#/components/schemas/Role" }
        binding: { $ref: "#/components/schemas/Binding" }
        owner: { $ref: "#/components/schemas/DelegatedOwner" }
        etag: { type: string }
        revision_id: { type: string }

    ImpactItem:
      type: object
      properties:
        kind: { type: string, enum: [gain, loss, warning] }
        who: { type: string }
        role: { type: string }
        zones: { type: array, items: { type: string } }
        actions: { type: array, items: { type: string } }
        message: { type: string }

    DelegatedResult:
      type: object
      required: [changed, revision_id, impact]
      properties:
        object: { $ref: "#/components/schemas/DelegatedObject" }
        changed: { type: boolean, description: "false: nothing to do, no revision created." }
        revision_id: { type: string }
        impact: { type: array, items: { $ref: "#/components/schemas/ImpactItem" } }

    DelegatedIndex:
      type: object
      properties:
        delegations:
          type: array
          items:
            type: object
            properties:
              name: { type: string }
              description: { type: string }
              subjects: { type: array, items: { $ref: "#/components/schemas/SubjectMatcher" } }
              allow:
                type: object
                description: Limits of the delegation (zones, folders, actions, records, binding subjects, teams, roles, groups, max_objects).
        objects: { type: array, items: { $ref: "#/components/schemas/DelegatedObject" } }
        revision_id: { type: string }

    DecisionRequest:
      type: object
      properties:
        comment: { type: string }

    TeamMembers:
      type: object
      properties:
        groups: { type: array, items: { type: string } }
        subjects: { type: array, items: { $ref: "#/components/schemas/SubjectMatcher" } }

    TeamInfo:
      type: object
      required: [name, kind, roles]
      properties:
        name: { type: string, description: 'Team name; "<prefix>*" for a team_from family or the team_claim of an issuer (its team_claim_prefix).' }
        kind: { type: string, enum: [declared, auto, family, claim, store] }
        layer: { type: string, enum: [base, managed], description: "Layer declaring the team." }
        description: { type: string }
        members: { $ref: "#/components/schemas/TeamMembers" }
        roles: { type: array, items: { type: string }, description: "Roles of the bindings and virtual keys naming the team." }
        virtual_keys: { type: array, items: { type: string } }
        family: { $ref: "#/components/schemas/TeamFrom" }
        issuer: { type: string, description: "Issuer of a claim kind." }
        warning: { type: string }
        rrsets: { type: integer, description: "RRsets the team owns in the zones the caller can read." }

    TeamList:
      type: object
      required: [strict, teams, require_second_approver]
      properties:
        strict: { type: boolean, description: "Team references must be declared (the base file has a teams block)." }
        require_second_approver: { type: boolean, description: "Transfers and renames need the approval of another person (ownership.require_second_approver); otherwise their requester may approve them." }
        teams: { type: array, items: { $ref: "#/components/schemas/TeamInfo" } }

    TeamDetail:
      allOf:
        - $ref: "#/components/schemas/TeamInfo"
        - type: object
          required: [owned, transfers]
          properties:
            owned:
              type: array
              description: RRsets and tombstones of the team per zone the caller can read.
              items:
                type: object
                properties:
                  zone: { type: string }
                  rrsets: { type: integer }
                  tombstones: { type: integer }
            transfers: { type: array, items: { $ref: "#/components/schemas/Transfer" }, description: "Pending transfers from or to the team." }
            permissions:
              type: array
              description: Rules of the team's roles, per zone; for policy.read holders and the members of the team.
              items: { $ref: "#/components/schemas/Permission" }

    TransferProposal:
      type: object
      required: [rrsets, to_team, comment]
      additionalProperties: false
      properties:
        rrsets: { type: array, minItems: 1, maxItems: 100, items: { $ref: "#/components/schemas/RRsetRef" } }
        to_team: { type: string }
        comment: { type: string, maxLength: 2000 }
        apply: { type: boolean, description: "Approve at once, by the requester (ownership.require_second_approver false only); nothing is stored when the requester could not approve it." }

    TeamRenameRequest:
      type: object
      required: [to, comment]
      additionalProperties: false
      properties:
        to: { type: string }
        comment: { type: string, maxLength: 2000 }
        apply: { type: boolean, description: "Approve at once, by the requester (ownership.require_second_approver false only); nothing is stored when the requester could not approve it." }

    Transfer:
      type: object
      required: [id, kind, from_team, to_team, rrsets, status, requester, created_at, expires_at, can_decide]
      properties:
        id: { type: string }
        kind: { type: string, enum: [rrsets, rename] }
        zone: { type: string, description: "Empty for a rename." }
        from_team: { type: string }
        to_team: { type: string }
        rrsets:
          type: array
          items:
            type: object
            properties:
              host: { type: string }
              type: { type: string }
              hash: { type: string, description: "Content hash when the request was made." }
              tombstone: { type: boolean, description: "A recently deleted RRset still reserved for its team." }
        status: { type: string, enum: [proposed, applying, applied, rejected, expired, failed], description: "applying: approved, being applied or retried by the gate." }
        comment: { type: string }
        requester: { $ref: "#/components/schemas/Actor" }
        created_at: { type: string, format: date-time }
        expires_at: { type: string, format: date-time }
        decided_by: { $ref: "#/components/schemas/Actor" }
        decided_at: { type: string, format: date-time }
        decision_comment: { type: string }
        moved: { type: integer, description: "RRsets and tombstones moved." }
        error: { type: string, description: "Why a failed transfer was not applied." }
        can_decide: { type: boolean, description: "The caller may approve it; with ownership.require_second_approver false, the requester may approve its own request. The requester may always withdraw (reject) a proposed request." }
        self_approved: { type: boolean, description: "Approved by its requester (ownership.require_second_approver false)." }

    TransferPage:
      type: object
      required: [transfers]
      properties:
        transfers: { type: array, items: { $ref: "#/components/schemas/Transfer" } }
        next_cursor: { type: string }

    PolicyObject:
      type: object
      description: |
        Policy editor payload, consumed by the web UI. The exact shapes
        (EffectivePolicy, RevisionPage, RevisionDetail, ProposeRequest,
        ExplainRequest, ExplainResponse, WhoCanResponse) are documented in
        internal/uiapi/policy.go and may change before 1.0.

    OAuthTokenResponse:
      type: object
      required: [access_token, token_type, expires_in]
      properties:
        access_token: { type: string, description: "JWT (typ at+jwt) with client_id, act, scope, gate_grant, auth_time." }
        token_type: { type: string, enum: [Bearer] }
        expires_in: { type: integer }
        refresh_token: { type: string }
        scope: { type: string }
    OAuthError:
      type: object
      required: [error]
      properties:
        error: { type: string }
        error_description: { type: string }
    OAuthGrant:
      type: object
      required: [id, client_id, client_name, subject, scopes, status, created_at, consented_at, last_used_at, expires_at]
      properties:
        id: { type: string }
        client_id: { type: string }
        client_name: { type: string }
        subject: { type: string }
        subject_name: { type: string }
        scopes: { type: array, items: { type: string } }
        status: { type: string, enum: [active, expired, revoked] }
        created_at: { type: string, format: date-time }
        consented_at: { type: string, format: date-time }
        last_used_at: { type: string, format: date-time }
        expires_at: { type: string, format: date-time, description: "The earlier of the absolute and the idle expiry." }
        revoked_at: { type: string, format: date-time }
        revoked_by: { type: string }
    OAuthGrantList:
      type: object
      required: [grants, manage]
      properties:
        grants: { type: array, items: { $ref: "#/components/schemas/OAuthGrant" } }
        manage: { type: boolean, description: "The caller holds gate.oauth.manage." }
    APIKey:
      type: object
      required: [id, name, team, role, status, allowed_cidrs, acme_domains, acme_dns, created_at, created_by]
      properties:
        id: { type: string, pattern: "^[0-9a-f]{16}$", description: "Key id: user name of basic authentication and acme-dns, X-App-Id." }
        name: { type: string }
        description: { type: string }
        team: { type: string, description: Team owning the RRsets the key creates. }
        role: { type: string }
        status: { type: string, enum: [active, expired, revoked] }
        expires_at: { type: string, format: date-time }
        allowed_cidrs: { type: array, items: { type: string } }
        acme_domains: { type: array, items: { type: string } }
        acme_dns:
          type: array
          items:
            type: object
            properties:
              subdomain: { type: string }
              domain: { type: string }
              origin: { type: string, enum: [api, client], description: "api: from acme_domains, synced by PUT; client: /register or the domain name used as subdomain." }
              allowfrom: { type: array, items: { type: string } }
        created_at: { type: string, format: date-time }
        created_by: { type: string }
        created_by_name: { type: string }
        rotated_at: { type: string, format: date-time }
        previous_key_expires_at: { type: string, format: date-time, description: End of the overlap of the last rotation. }
        revoked_at: { type: string, format: date-time }
        revoked_by: { type: string }
        last_used_at: { type: string, format: date-time, description: "Last successful authentication (updated at most once a minute)." }
        last_used_ip: { type: string }

    IssuedAPIKey:
      allOf:
        - $ref: "#/components/schemas/APIKey"
        - type: object
          required: [key, acme_dns_accounts]
          properties:
            key: { type: string, description: "dgk_<id>_<secret>, shown once." }
            acme_dns_accounts:
              type: object
              description: |
                acme-dns accounts by domain: the storage file of the certbot
                acme-dns hook (acmedns.json), the registration file of
                certbot-dns-acmedns and the cert-manager acmeDNS secret.
              additionalProperties: { $ref: "#/components/schemas/ACMEDNSAccount" }

    ACMEDNSAccount:
      type: object
      required: [username, password, fulldomain, subdomain, allowfrom]
      properties:
        username: { type: string, description: Key id. }
        password: { type: string, description: The key. }
        fulldomain: { type: string, description: "_acme-challenge.<domain>, the RRset written (no CNAME needed)." }
        subdomain: { type: string }
        allowfrom: { type: array, items: { type: string } }

    APIKeyRequest:
      type: object
      required: [name]
      properties:
        name: { type: string, pattern: "^[A-Za-z0-9][A-Za-z0-9 ._@-]{0,63}$" }
        description: { type: string, maxLength: 512 }
        team: { type: string, description: Required on creation; on PUT empty or unchanged. }
        role: { type: string, description: Required on creation; on PUT empty or unchanged. }
        expires_at: { type: string, format: date-time }
        allowed_cidrs: { type: array, items: { type: string }, maxItems: 64 }
        acme_domains:
          type: array
          maxItems: 100
          items: { type: string, examples: ["www.example.com", "*.example.com"] }

    APIKeyRotate:
      type: object
      properties:
        overlap: { type: string, description: "Go duration, default 24h, at most 720h.", examples: ["24h", "0s"] }

    HTTPReqRequest:
      type: object
      properties:
        fqdn: { type: string, examples: ["_acme-challenge.www.example.com."] }
        value: { type: string }
        domain: { type: string, description: RAW mode. }
        token: { type: string, description: RAW mode. }
        keyAuth: { type: string, description: RAW mode. }

    HTTPReqResult:
      type: object
      properties:
        fqdn: { type: string }
        value: { type: string }

    ZoneProfileList:
      type: object
      required: [provider, profiles]
      properties:
        provider: { type: string }
        profiles:
          type: array
          items:
            type: object
            required: [id, name]
            properties:
              id: { type: integer }
              name: { type: string }

    ZoneProfile:
      type: object
      description: |
        EuroDNS `ZoneProfilePage`: hosts are relative to the domain the
        profile is applied to (`@` for the apex), targets are fully qualified
        with a trailing dot. `id`, `domainConnect` and `report` are read-only.
      required: [name]
      properties:
        id: { type: [integer, "null"], readOnly: true }
        name: { type: string, maxLength: 255 }
        domainConnect: { type: [boolean, "null"], readOnly: true }
        records:
          type: array
          items:
            type: object
            required: [type, host, ttl, rdata]
            properties:
              id: { type: [integer, "null"], readOnly: true }
              type: { type: string, examples: ["A", "CNAME", "MX", "TXT"] }
              host: { type: string, examples: ["@", "www"] }
              ttl: { type: integer, enum: [600, 900, 1800, 3600, 7200, 14400, 21600, 43200, 86400, 172800, 432000, 604800] }
              rdata: { type: string }
        urlForwards:
          type: array
          items:
            type: object
            properties:
              forwardType: { type: string, enum: [FRAME, HTTP301, HTTP302] }
              host: { type: string }
              url: { type: string }
              title: { type: string }
              keywords: { type: string }
              description: { type: string }
        mailForwards:
          type: array
          items:
            type: object
            properties:
              source: { type: string, description: "Left part of the address, `*` for a catch-all." }
              destination: { type: string }
        report:
          type: object
          readOnly: true
          description: EuroDNS validation report (check), as returned by EuroDNS.
