@rathnasgala2/schemas 3.3.0 → 3.5.0

package/openapi/openapi.yaml

@@ -1256,6 +1256,174 @@ components:
         - RECONCILING
         - INCONCLUSIVE
       type: string
+    DnsConnection:
+      additionalProperties: false
+      description: One attempt to add or remove a domain's DNS records at the person's DNS provider (SCHEMA-3.5.0). `outcome` is present when `phase` is `CANCELLED`, `FAILED` or `EXPIRED`; `plan` when `NEEDS_CONFIRMATION` or `APPLIED`; `applied` when `APPLIED`. The provider's access is used within one request chain (or held encrypted for at most `expiresAt` on `NEEDS_CONFIRMATION`) and revoked afterwards; Galascribe keeps none.
+      properties:
+        applied:
+          additionalProperties: false
+          properties:
+            at:
+              $ref: "#/components/schemas/PortableProblemRfc3339"
+            created:
+              minimum: 0
+              type: integer
+            deleted:
+              minimum: 0
+              type: integer
+            replaced:
+              minimum: 0
+              type: integer
+          required:
+            - at
+            - created
+            - replaced
+            - deleted
+          type: object
+        connectionId:
+          format: uuid
+          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+          type: string
+        createdAt:
+          $ref: "#/components/schemas/PortableProblemRfc3339"
+        expiresAt:
+          $ref: "#/components/schemas/PortableProblemRfc3339"
+        intent:
+          $ref: "#/components/schemas/DnsIntent"
+        outcome:
+          additionalProperties: false
+          properties:
+            code:
+              $ref: "#/components/schemas/DnsConnectionOutcomeCode"
+            detail:
+              maxLength: 500
+              minLength: 1
+              type: string
+          required:
+            - code
+            - detail
+          type: object
+        phase:
+          $ref: "#/components/schemas/DnsConnectionPhase"
+        plan:
+          items:
+            $ref: "#/components/schemas/DnsPlanEntry"
+          maxItems: 32
+          minItems: 0
+          type: array
+        provider:
+          $ref: "#/components/schemas/DnsProvider"
+        zone:
+          additionalProperties: false
+          properties:
+            accountName:
+              maxLength: 255
+              minLength: 1
+              type: string
+            name:
+              maxLength: 253
+              minLength: 1
+              type: string
+          required:
+            - name
+            - accountName
+          type: object
+      required:
+        - connectionId
+        - provider
+        - intent
+        - phase
+        - createdAt
+        - expiresAt
+      type: object
+    DnsConnectionOutcomeCode:
+      description: "Why a connection ended without success: `CANCELLED` (consent denied or plan discarded); `ZONE_NOT_FOUND` (the domain is not in the provider account chosen); `ZONE_AMBIGUOUS` (more than one active zone of that name across the accounts granted); `SCOPE_DECLINED` (the person did not grant what was needed); `PROVIDER_FAILED` (the provider failed or refused); `STATE_INVALID` (the return from the provider could not be matched to this connection); `EXPIRED`."
+      enum:
+        - CANCELLED
+        - ZONE_NOT_FOUND
+        - ZONE_AMBIGUOUS
+        - SCOPE_DECLINED
+        - PROVIDER_FAILED
+        - STATE_INVALID
+        - EXPIRED
+      type: string
+    DnsConnectionPhase:
+      description: "`STARTED` (waiting for the person at the provider); `NEEDS_CONFIRMATION` (something would be replaced, nothing touched yet); `APPLIED`; `CANCELLED` (the person declined, or discarded the plan); `FAILED`; `EXPIRED` (the person did not finish in time)."
+      enum:
+        - STARTED
+        - NEEDS_CONFIRMATION
+        - APPLIED
+        - CANCELLED
+        - FAILED
+        - EXPIRED
+      type: string
+    DnsIntent:
+      description: "`ADD` writes the domain's records at the provider; `REMOVE` deletes only the records whose values are Galascribe's targets, never anything else at that name."
+      enum:
+        - ADD
+        - REMOVE
+      type: string
+    DnsPlanAction:
+      description: "`CREATE` a record that is not there; `KEEP` one already identical; `REPLACE` one of the same type, or a CNAME where an A/AAAA must go (or the reverse), that differs; `DELETE` a record carrying a Galascribe target value (`REMOVE` only)."
+      enum:
+        - CREATE
+        - KEEP
+        - REPLACE
+        - DELETE
+      type: string
+    DnsPlanEntry:
+      additionalProperties: false
+      description: "One record in a connection's plan. `record` is what Galascribe wants at that name; `existing` is what the provider has there now (absent for `CREATE`). Records are always written DNS-only (`proxied: false`) so GitHub can issue the certificate."
+      properties:
+        action:
+          $ref: "#/components/schemas/DnsPlanAction"
+        existing:
+          additionalProperties: false
+          properties:
+            proxied:
+              type: boolean
+            type:
+              maxLength: 16
+              minLength: 1
+              pattern: ^[A-Z][A-Z0-9]*$
+              type: string
+            value:
+              maxLength: 4096
+              minLength: 1
+              type: string
+          required:
+            - type
+            - value
+            - proxied
+          type: object
+        record:
+          $ref: "#/components/schemas/DomainDnsRecord"
+      required:
+        - action
+        - record
+      type: object
+    DnsProvider:
+      description: Where a domain's DNS records live. `CLOUDFLARE` today; a further provider is an additive value.
+      enum:
+        - CLOUDFLARE
+      type: string
+    DnsProviderOffer:
+      additionalProperties: false
+      description: A provider this environment can connect to for this binding, and what it can do now.
+      properties:
+        intents:
+          items:
+            $ref: "#/components/schemas/DnsIntent"
+          maxItems: 2
+          minItems: 1
+          type: array
+          uniqueItems: true
+        provider:
+          $ref: "#/components/schemas/DnsProvider"
+      required:
+        - provider
+        - intents
+      type: object
     DomainBinding:
       additionalProperties: false
       description: A custom domain on GitHub Pages for one publication (SCHEMA-3.3.0). `dns.records` are exactly the records to add at the registrar (a CNAME to `<owner>.github.io` for a subdomain; GitHub's four A and four AAAA records for an apex). Galascribe checks DNS before it sets the Pages custom domain, then waits for GitHub's certificate and routing; `ACTIVE` proposes the change that moves `canonicalBase` to the domain, and the site moves at the next publish. `expiresAt` is set while `OWNERSHIP_PENDING` (7 days).
@@ -1271,6 +1439,13 @@ components:
           properties:
             observed:
               $ref: "#/components/schemas/DomainDnsObservation"
+            providers:
+              description: The DNS providers Galascribe can connect to for this binding right now (SCHEMA-3.5.0). Present only when the provider is configured in this environment and the binding's state has records to add, or (`REMOVE`) to remove. A client shows a connect button exactly when this names the provider and intent; it never decides from `nextStep`.
+              items:
+                $ref: "#/components/schemas/DnsProviderOffer"
+              maxItems: 4
+              minItems: 0
+              type: array
             records:
               items:
                 $ref: "#/components/schemas/DomainDnsRecord"
@@ -1587,6 +1762,58 @@ components:
       required:
         - status
       type: object
+    GetMembershipInvitationsByTokenResponse:
+      additionalProperties: false
+      allOf:
+        - else:
+            not:
+              required:
+                - publicationName
+          if:
+            properties:
+              scope:
+                pattern: ^PUBLICATION$
+                type: string
+                x-gala-const: PUBLICATION
+            required:
+              - scope
+          then:
+            required:
+              - publicationName
+      properties:
+        expiresAt:
+          $ref: "#/components/schemas/PortableProblemRfc3339"
+        invitedBy:
+          $ref: "#/components/schemas/SiteActor"
+        organizationName:
+          maxLength: 80
+          minLength: 1
+          type: string
+        publicationName:
+          maxLength: 80
+          minLength: 1
+          type: string
+        roleName:
+          maxLength: 80
+          minLength: 1
+          type: string
+        scope:
+          enum:
+            - ORGANIZATION
+            - PUBLICATION
+          type: string
+        state:
+          enum:
+            - PENDING
+          type: string
+      required:
+        - organizationName
+        - roleName
+        - scope
+        - invitedBy
+        - expiresAt
+        - state
+      type: object
     GetOrganizationsByOrganizationIdCapabilitiesResponse:
       additionalProperties: false
       properties:
@@ -1601,6 +1828,7 @@ components:
       type: object
     GetOrganizationsByOrganizationIdMembershipInvitationsByInvitationIdResponse:
       additionalProperties: false
+      description: "One pending or settled invitation, in exactly the shape the single-invitation read returns, so a client renders a row and its detail view from the same fields. SCHEMA-3.4.0 adds what a People page needs to show a pending row: `recipient` (the inviter's own unverified label, absent for older invitations), the invited role (`roleKey`, `roleName`), its publication when the invitation is publication-scoped (`publicationId`, `publicationName`), and who sent it (`invitedBy`)."
       properties:
         expiresAt:
           $ref: "#/components/schemas/PortableProblemRfc3339"
@@ -1608,10 +1836,34 @@ components:
           format: uuid
           pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
           type: string
+        invitedBy:
+          $ref: "#/components/schemas/SiteActor"
+        publicationId:
+          format: uuid
+          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+          type: string
+        publicationName:
+          maxLength: 80
+          minLength: 1
+          type: string
+        recipient:
+          description: "The label the inviter typed when creating the invitation (an email address), shown so the inviter recognises the row. It is not a verified identity: acceptance is possession-based and this value is never matched against whoever accepts (LOCAL-34 G6). Absent for invitations created before the label was stored."
+          maxLength: 320
+          minLength: 1
+          type: string
         roleId:
           format: uuid
           pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
           type: string
+        roleKey:
+          maxLength: 80
+          minLength: 1
+          pattern: ^[a-z][a-z0-9_]*$
+          type: string
+        roleName:
+          maxLength: 80
+          minLength: 1
+          type: string
         state:
           $ref: "#/components/schemas/MembershipInvitationState"
         version:
@@ -1624,6 +1876,9 @@ components:
         - state
         - roleId
         - expiresAt
+        - roleKey
+        - roleName
+        - invitedBy
       type: object
     GetOrganizationsByOrganizationIdMembershipInvitationsResponse:
       additionalProperties: false
@@ -2260,6 +2515,9 @@ components:
         - version
         - state
       type: object
+    GetOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsByConnectionIdResponse:
+      allOf:
+        - $ref: "#/components/schemas/DnsConnection"
     GetOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdResponse:
       allOf:
         - $ref: "#/components/schemas/DomainBinding"
@@ -4668,7 +4926,7 @@ components:
       type: string
     MembershipInvitationSummary:
       additionalProperties: false
-      description: One pending or settled invitation, in exactly the shape the single-invitation read returns, so a client renders a row and its detail view from the same fields. `recipient` is deliberately absent, as it is from the single read, because acceptance is possession-based and the label an inviter typed is never a verified identity (LOCAL-34 G6).
+      description: "One pending or settled invitation, in exactly the shape the single-invitation read returns, so a client renders a row and its detail view from the same fields. SCHEMA-3.4.0 adds what a People page needs to show a pending row: `recipient` (the inviter's own unverified label, absent for older invitations), the invited role (`roleKey`, `roleName`), its publication when the invitation is publication-scoped (`publicationId`, `publicationName`), and who sent it (`invitedBy`)."
       properties:
         expiresAt:
           $ref: "#/components/schemas/PortableProblemRfc3339"
@@ -4676,10 +4934,34 @@ components:
           format: uuid
           pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
           type: string
+        invitedBy:
+          $ref: "#/components/schemas/SiteActor"
+        publicationId:
+          format: uuid
+          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+          type: string
+        publicationName:
+          maxLength: 80
+          minLength: 1
+          type: string
+        recipient:
+          description: "The label the inviter typed when creating the invitation (an email address), shown so the inviter recognises the row. It is not a verified identity: acceptance is possession-based and this value is never matched against whoever accepts (LOCAL-34 G6). Absent for invitations created before the label was stored."
+          maxLength: 320
+          minLength: 1
+          type: string
         roleId:
           format: uuid
           pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
           type: string
+        roleKey:
+          maxLength: 80
+          minLength: 1
+          pattern: ^[a-z][a-z0-9_]*$
+          type: string
+        roleName:
+          maxLength: 80
+          minLength: 1
+          type: string
         state:
           $ref: "#/components/schemas/MembershipInvitationState"
         version:
@@ -4692,6 +4974,9 @@ components:
         - state
         - roleId
         - expiresAt
+        - roleKey
+        - roleName
+        - invitedBy
       type: object
     MembershipState:
       enum:
@@ -11834,7 +12119,7 @@ components:
             - string
             - "null"
         recipient:
-          description: Label recording who the inviter meant to invite. Acceptance is possession-based, so whoever presents the invitation token joins with the invited role, and this value is never matched against the accepting principal's verified identity. It exists so the inviter can recognize the invitation in a list; treat it as a note, not a binding (LOCAL-34 G6). Recipient binding is revisited when verified email exists.
+          description: An email address (at most 320 characters; anything else, a GitHub login included, is `400 VALIDATION_FAILED`). The server trims and lower-cases it. It records who the inviter meant to invite and is shown back on the invitation rows; acceptance is possession-based, so whoever presents the invitation token joins with the invited role and this value is never matched against the accepting principal's verified identity -- treat it as a note, not a binding (LOCAL-34 G6).
           format: email
           maxLength: 320
           type: string
@@ -12343,6 +12628,44 @@ components:
     PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDetachResponse:
       allOf:
         - $ref: "#/components/schemas/DomainBinding"
+    PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsByConnectionIdApplyResponse:
+      allOf:
+        - $ref: "#/components/schemas/DnsConnection"
+    PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsByConnectionIdDiscardResponse:
+      allOf:
+        - $ref: "#/components/schemas/DnsConnection"
+    PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsRequest:
+      additionalProperties: false
+      properties:
+        intent:
+          $ref: "#/components/schemas/DnsIntent"
+        provider:
+          $ref: "#/components/schemas/DnsProvider"
+      required:
+        - provider
+        - intent
+      type: object
+    PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsResponse:
+      additionalProperties: false
+      properties:
+        authorizationUrl:
+          description: The provider's consent address. A client navigates to it only when it is an `https` address on the provider's own host.
+          format: uri
+          maxLength: 4096
+          minLength: 1
+          pattern: ^https://[^\s]+$
+          type: string
+        connectionId:
+          format: uuid
+          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+          type: string
+        expiresAt:
+          $ref: "#/components/schemas/PortableProblemRfc3339"
+      required:
+        - connectionId
+        - authorizationUrl
+        - expiresAt
+      type: object
     PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsRequest:
       additionalProperties: false
       properties:
@@ -16684,33 +17007,104 @@ paths:
         - NONE
       x-gala-success-category: protocol
       x-gala-tenant-scope: NONE
-  /v2/callbacks/github/app:
-    post:
-      operationId: postCallbacksGithubApp
+  /v2/callbacks/cloudflare/oauth:
+    get:
+      description: |
+        The address Cloudflare sends the person back to after the consent screen. It never answers with a problem document for what the provider sends: every outcome, including a denied consent or an unknown `state`, is a `303` to the Domain page with `?dns=<connectionId>` (or without it when the connection cannot be identified), and `GET .../dns-connections/{connectionId}` says what happened. `code`, `state`, `error` and `iss` are never logged or echoed. Only a value longer than its limit is refused as `400 VALIDATION_FAILED`, before any connection is touched.
+      operationId: getCallbacksCloudflareOauth
       parameters:
         - $ref: "#/components/parameters/XCorrelationId"
-        - example: 018f0000-0000-7000-8000-000000000001
-          in: header
-          name: X-GitHub-Delivery
-          required: true
+        - example: example
+          in: query
+          name: code
+          required: false
           schema:
-            format: uuid
+            maxLength: 8192
+            minLength: 1
             type: string
-        - example: push
-          in: header
-          name: X-GitHub-Event
-          required: true
+        - example: example
+          in: query
+          name: state
+          required: false
           schema:
-            enum:
-              - installation
-              - installation_repositories
-              - push
-              - workflow_run
+            maxLength: 8192
+            minLength: 1
             type: string
-      requestBody:
-        content:
-          application/json:
-            examples:
+        - example: example
+          in: query
+          name: error
+          required: false
+          schema:
+            maxLength: 512
+            minLength: 1
+            type: string
+        - example: example
+          in: query
+          name: iss
+          required: false
+          schema:
+            maxLength: 2048
+            minLength: 1
+            type: string
+      responses:
+        "303":
+          description: consume the exact Cloudflare OAuth callback transaction succeeded
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            Location:
+              $ref: "#/components/headers/Location"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+        "400":
+          $ref: "#/components/responses/ValidationFailed"
+      security: []
+      summary: consume the exact Cloudflare OAuth callback transaction
+      tags:
+        - callbacks
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - NONE
+      x-gala-capability-key: null
+      x-gala-concurrency: single-use-transaction
+      x-gala-conditional-capabilities: []
+      x-gala-example-profile: NOMINAL_SUCCESS_AND_EACH_REACHABLE_PROBLEM
+      x-gala-nullability: required-and-nullable-are-explicit
+      x-gala-purpose: consume the exact Cloudflare OAuth callback transaction
+      x-gala-reachable-problems:
+        - VALIDATION_FAILED
+      x-gala-replay-identity: oauth-state
+      x-gala-state-guards:
+        - NONE
+      x-gala-success-category: oauth-callback
+      x-gala-tenant-scope: NONE
+  /v2/callbacks/github/app:
+    post:
+      operationId: postCallbacksGithubApp
+      parameters:
+        - $ref: "#/components/parameters/XCorrelationId"
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: header
+          name: X-GitHub-Delivery
+          required: true
+          schema:
+            format: uuid
+            type: string
+        - example: push
+          in: header
+          name: X-GitHub-Event
+          required: true
+          schema:
+            enum:
+              - installation
+              - installation_repositories
+              - push
+              - workflow_run
+            type: string
+      requestBody:
+        content:
+          application/json:
+            examples:
               nominal:
                 summary: Nominal valid request
                 value: {}
@@ -17782,6 +18176,126 @@ paths:
         - GithubRepository:name unclaimed on the resolved account
       x-gala-success-category: create
       x-gala-tenant-scope: NONE
+  /v2/membership-invitations/{token}:
+    get:
+      description: |
+        Lets the page an invitation link opens show what it offers before the
+        person signs in to accept it: the organization, the role, the
+        publication for a publication-scoped invitation, who sent it and when it
+        expires. No session is needed; the token is the capability. Any unknown,
+        expired, accepted or revoked token answers `404 RESOURCE_NOT_FOUND`
+        (non-enumerating). Accepting stays `POST
+        /v2/membership-invitations/{token}:accept` after sign-in.
+      operationId: getMembershipInvitationsByToken
+      parameters:
+        - $ref: "#/components/parameters/XCorrelationId"
+        - example: examplexxxxxxxxxxxxxxxxxxxxxxxxx
+          in: path
+          name: token
+          required: true
+          schema:
+            maxLength: 256
+            minLength: 32
+            type: string
+      responses:
+        "200":
+          content:
+            application/json:
+              examples:
+                nominal:
+                  summary: Nominal successful response
+                  value:
+                    expiresAt: "2026-10-16T12:00:00.000Z"
+                    invitedBy:
+                      displayName: Dev
+                    organizationName: Northwind Press
+                    publicationName: Maya's blog
+                    roleName: Editor
+                    scope: PUBLICATION
+                    state: PENDING
+              schema:
+                $ref: "#/components/schemas/GetMembershipInvitationsByTokenResponse"
+          description: read what an invitation link offers succeeded
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+        "400":
+          content:
+            application/problem+json:
+              examples:
+                VALIDATION_FAILED:
+                  summary: VALIDATION_FAILED
+                  value:
+                    code: VALIDATION_FAILED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 400
+                    title: VALIDATION_FAILED
+                    type: urn:gala:problem:validation-failed
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: VALIDATION_FAILED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - VALIDATION_FAILED
+        "404":
+          content:
+            application/problem+json:
+              examples:
+                RESOURCE_NOT_FOUND:
+                  summary: RESOURCE_NOT_FOUND
+                  value:
+                    code: RESOURCE_NOT_FOUND
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 404
+                    title: RESOURCE_NOT_FOUND
+                    type: urn:gala:problem:resource-not-found
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: RESOURCE_NOT_FOUND
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - RESOURCE_NOT_FOUND
+      security: []
+      summary: read what an invitation link offers
+      tags:
+        - membership-invitations
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - NONE
+      x-gala-capability-key: null
+      x-gala-concurrency: none
+      x-gala-conditional-capabilities: []
+      x-gala-example-profile: NOMINAL_SUCCESS_AND_EACH_REACHABLE_PROBLEM
+      x-gala-nullability: required-and-nullable-are-explicit
+      x-gala-purpose: read what an invitation link offers
+      x-gala-reachable-problems:
+        - RESOURCE_NOT_FOUND
+        - VALIDATION_FAILED
+      x-gala-replay-identity: safe-query
+      x-gala-state-guards:
+        - NONE
+      x-gala-success-category: query
+      x-gala-tenant-scope: NONE
   /v2/membership-invitations/{token}:accept:
     post:
       description: |
@@ -19605,7 +20119,14 @@ paths:
                   value:
                     expiresAt: "2026-09-06T00:00:00.000Z"
                     invitationId: 018f0000-0000-7000-8000-000000000001
+                    invitedBy:
+                      displayName: Dev
+                    publicationId: 018f0000-0000-7000-8000-000000000001
+                    publicationName: Maya's blog
+                    recipient: priya@example.com
                     roleId: 018f0000-0000-7000-8000-000000000001
+                    roleKey: editor
+                    roleName: Editor
                     state: PENDING
                     version: 0
               schema:
@@ -31888,6 +32409,1164 @@ paths:
         - NONE
       x-gala-success-category: query
       x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
+  /v2/organizations/{organizationId}/publications/{publicationId}/domains/{domainId}/dns-connections:
+    post:
+      description: |
+        Starts a connection to the person's DNS provider so Galascribe can add (`ADD`) or remove (`REMOVE`) the domain's DNS records there, and returns the provider's consent address (`authorizationUrl`); the App navigates the whole page to it. The provider sends the person back to the Domain page, where `GET .../dns-connections/{connectionId}` says what happened. Only offered when `dns.providers` on the binding lists the provider and the intent. `409 DNS_CONNECTION_NOT_APPLICABLE` when the binding's state has no records to add or remove; `503 DNS_PROVIDER_NOT_CONFIGURED` when this environment has no connection to that provider; `429 RATE_LIMITED` after one start per domain per minute. The connection is valid until `expiresAt`.
+      operationId: postOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnections
+      parameters:
+        - $ref: "#/components/parameters/XCorrelationId"
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: organizationId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: publicationId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: domainId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - $ref: "#/components/parameters/IdempotencyKey"
+        - $ref: "#/components/parameters/XCsrfToken"
+      requestBody:
+        content:
+          application/json:
+            examples:
+              nominal:
+                summary: Nominal valid request
+                value:
+                  intent: ADD
+                  provider: CLOUDFLARE
+            schema:
+              $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsRequest"
+        required: true
+      responses:
+        "201":
+          content:
+            application/json:
+              examples:
+                nominal:
+                  summary: Nominal successful response
+                  value:
+                    authorizationUrl: https://dash.cloudflare.com/oauth2/auth?client_id=example&response_type=code&state=example
+                    connectionId: 018f0000-0000-7000-8000-000000000001
+                    expiresAt: "2026-10-10T12:10:00.000Z"
+              schema:
+                $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsResponse"
+          description: start adding (or removing) a domain's DNS records at the person's DNS provider succeeded
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            Location:
+              $ref: "#/components/headers/Location"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+        "400":
+          content:
+            application/problem+json:
+              examples:
+                REQUEST_FIELD_UNKNOWN:
+                  summary: REQUEST_FIELD_UNKNOWN
+                  value:
+                    code: REQUEST_FIELD_UNKNOWN
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 400
+                    title: REQUEST_FIELD_UNKNOWN
+                    type: urn:gala:problem:request-field-unknown
+                VALIDATION_FAILED:
+                  summary: VALIDATION_FAILED
+                  value:
+                    code: VALIDATION_FAILED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 400
+                    title: VALIDATION_FAILED
+                    type: urn:gala:problem:validation-failed
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: REQUEST_FIELD_UNKNOWN, VALIDATION_FAILED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - REQUEST_FIELD_UNKNOWN
+            - VALIDATION_FAILED
+        "401":
+          content:
+            application/problem+json:
+              examples:
+                AUTHENTICATION_REQUIRED:
+                  summary: AUTHENTICATION_REQUIRED
+                  value:
+                    code: AUTHENTICATION_REQUIRED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 401
+                    title: AUTHENTICATION_REQUIRED
+                    type: urn:gala:problem:authentication-required
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHENTICATION_REQUIRED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHENTICATION_REQUIRED
+        "403":
+          content:
+            application/problem+json:
+              examples:
+                AUTHORIZATION_DENIED:
+                  summary: AUTHORIZATION_DENIED
+                  value:
+                    code: AUTHORIZATION_DENIED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 403
+                    title: AUTHORIZATION_DENIED
+                    type: urn:gala:problem:authorization-denied
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHORIZATION_DENIED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHORIZATION_DENIED
+        "404":
+          content:
+            application/problem+json:
+              examples:
+                RESOURCE_NOT_FOUND:
+                  summary: RESOURCE_NOT_FOUND
+                  value:
+                    code: RESOURCE_NOT_FOUND
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 404
+                    title: RESOURCE_NOT_FOUND
+                    type: urn:gala:problem:resource-not-found
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: RESOURCE_NOT_FOUND
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - RESOURCE_NOT_FOUND
+        "409":
+          content:
+            application/problem+json:
+              examples:
+                COMMAND_REPLAY_CONFLICT:
+                  summary: COMMAND_REPLAY_CONFLICT
+                  value:
+                    code: COMMAND_REPLAY_CONFLICT
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 409
+                    title: COMMAND_REPLAY_CONFLICT
+                    type: urn:gala:problem:command-replay-conflict
+                DNS_CONNECTION_NOT_APPLICABLE:
+                  summary: DNS_CONNECTION_NOT_APPLICABLE
+                  value:
+                    code: DNS_CONNECTION_NOT_APPLICABLE
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 409
+                    title: DNS_CONNECTION_NOT_APPLICABLE
+                    type: urn:gala:problem:dns-connection-not-applicable
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: COMMAND_REPLAY_CONFLICT, DNS_CONNECTION_NOT_APPLICABLE
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - COMMAND_REPLAY_CONFLICT
+            - DNS_CONNECTION_NOT_APPLICABLE
+        "429":
+          content:
+            application/problem+json:
+              examples:
+                RATE_LIMITED:
+                  summary: RATE_LIMITED
+                  value:
+                    code: RATE_LIMITED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: true
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 429
+                    title: RATE_LIMITED
+                    type: urn:gala:problem:rate-limited
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: RATE_LIMITED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            Retry-After:
+              $ref: "#/components/headers/RetryAfter"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - RATE_LIMITED
+        "503":
+          content:
+            application/problem+json:
+              examples:
+                DNS_PROVIDER_NOT_CONFIGURED:
+                  summary: DNS_PROVIDER_NOT_CONFIGURED
+                  value:
+                    code: DNS_PROVIDER_NOT_CONFIGURED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 503
+                    title: DNS_PROVIDER_NOT_CONFIGURED
+                    type: urn:gala:problem:dns-provider-not-configured
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: DNS_PROVIDER_NOT_CONFIGURED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - DNS_PROVIDER_NOT_CONFIGURED
+      security:
+        - browserSession: []
+      summary: start adding (or removing) a domain's DNS records at the person's DNS provider
+      tags:
+        - domains
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - NONE
+      x-gala-capability-key: publication.settings.manage
+      x-gala-concurrency: domain-binding-version
+      x-gala-conditional-capabilities: []
+      x-gala-example-profile: NOMINAL_SUCCESS_AND_EACH_REACHABLE_PROBLEM
+      x-gala-nullability: required-and-nullable-are-explicit
+      x-gala-purpose: start adding (or removing) a domain's DNS records at the person's DNS provider
+      x-gala-reachable-problems:
+        - AUTHENTICATION_REQUIRED
+        - AUTHORIZATION_DENIED
+        - COMMAND_REPLAY_CONFLICT
+        - DNS_CONNECTION_NOT_APPLICABLE
+        - DNS_PROVIDER_NOT_CONFIGURED
+        - RATE_LIMITED
+        - REQUEST_FIELD_UNKNOWN
+        - RESOURCE_NOT_FOUND
+        - VALIDATION_FAILED
+      x-gala-replay-identity: idempotency-key
+      x-gala-state-guards:
+        - NONE
+      x-gala-success-category: create
+      x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
+  /v2/organizations/{organizationId}/publications/{publicationId}/domains/{domainId}/dns-connections/{connectionId}:
+    get:
+      description: |
+        One DNS connection of this domain: where it stands (`phase`), what it will or did change (`plan`, `applied`) and, when it ended without success, why (`outcome`). `NEEDS_CONFIRMATION` means something at the provider would be replaced and nothing has been touched yet: `:apply` writes the plan, `:discard` leaves everything as it was. `404 DNS_CONNECTION_NOT_FOUND` for an unknown connection.
+      operationId: getOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsByConnectionId
+      parameters:
+        - $ref: "#/components/parameters/XCorrelationId"
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: organizationId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: publicationId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: domainId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: connectionId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+      responses:
+        "200":
+          content:
+            application/json:
+              examples:
+                nominal:
+                  summary: Nominal successful response
+                  value:
+                    connectionId: 018f0000-0000-7000-8000-000000000001
+                    createdAt: "2026-10-10T12:00:00.000Z"
+                    expiresAt: "2026-10-10T12:10:00.000Z"
+                    intent: ADD
+                    phase: NEEDS_CONFIRMATION
+                    plan:
+                      - action: REPLACE
+                        existing:
+                          proxied: true
+                          type: A
+                          value: 203.0.113.7
+                        record:
+                          name: "@"
+                          type: A
+                          value: 185.199.108.153
+                      - action: KEEP
+                        existing:
+                          proxied: false
+                          type: A
+                          value: 185.199.109.153
+                        record:
+                          name: "@"
+                          type: A
+                          value: 185.199.109.153
+                    provider: CLOUDFLARE
+                    zone:
+                      accountName: Maya Personal
+                      name: maya.dev
+              schema:
+                $ref: "#/components/schemas/GetOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsByConnectionIdResponse"
+          description: read a DNS connection succeeded
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+        "400":
+          content:
+            application/problem+json:
+              examples:
+                VALIDATION_FAILED:
+                  summary: VALIDATION_FAILED
+                  value:
+                    code: VALIDATION_FAILED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 400
+                    title: VALIDATION_FAILED
+                    type: urn:gala:problem:validation-failed
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: VALIDATION_FAILED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - VALIDATION_FAILED
+        "401":
+          content:
+            application/problem+json:
+              examples:
+                AUTHENTICATION_REQUIRED:
+                  summary: AUTHENTICATION_REQUIRED
+                  value:
+                    code: AUTHENTICATION_REQUIRED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 401
+                    title: AUTHENTICATION_REQUIRED
+                    type: urn:gala:problem:authentication-required
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHENTICATION_REQUIRED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHENTICATION_REQUIRED
+        "403":
+          content:
+            application/problem+json:
+              examples:
+                AUTHORIZATION_DENIED:
+                  summary: AUTHORIZATION_DENIED
+                  value:
+                    code: AUTHORIZATION_DENIED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 403
+                    title: AUTHORIZATION_DENIED
+                    type: urn:gala:problem:authorization-denied
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHORIZATION_DENIED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHORIZATION_DENIED
+        "404":
+          content:
+            application/problem+json:
+              examples:
+                DNS_CONNECTION_NOT_FOUND:
+                  summary: DNS_CONNECTION_NOT_FOUND
+                  value:
+                    code: DNS_CONNECTION_NOT_FOUND
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 404
+                    title: DNS_CONNECTION_NOT_FOUND
+                    type: urn:gala:problem:dns-connection-not-found
+                RESOURCE_NOT_FOUND:
+                  summary: RESOURCE_NOT_FOUND
+                  value:
+                    code: RESOURCE_NOT_FOUND
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 404
+                    title: RESOURCE_NOT_FOUND
+                    type: urn:gala:problem:resource-not-found
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: DNS_CONNECTION_NOT_FOUND, RESOURCE_NOT_FOUND
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - DNS_CONNECTION_NOT_FOUND
+            - RESOURCE_NOT_FOUND
+      security:
+        - browserSession: []
+      summary: read a DNS connection
+      tags:
+        - domains
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - NONE
+      x-gala-capability-key: publication.view
+      x-gala-concurrency: domain-binding-version
+      x-gala-conditional-capabilities: []
+      x-gala-example-profile: NOMINAL_SUCCESS_AND_EACH_REACHABLE_PROBLEM
+      x-gala-nullability: required-and-nullable-are-explicit
+      x-gala-purpose: read a DNS connection
+      x-gala-reachable-problems:
+        - AUTHENTICATION_REQUIRED
+        - AUTHORIZATION_DENIED
+        - DNS_CONNECTION_NOT_FOUND
+        - RESOURCE_NOT_FOUND
+        - VALIDATION_FAILED
+      x-gala-replay-identity: safe-query
+      x-gala-state-guards:
+        - NONE
+      x-gala-success-category: query
+      x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
+  /v2/organizations/{organizationId}/publications/{publicationId}/domains/{domainId}/dns-connections/{connectionId}:apply:
+    post:
+      description: |
+        Writes the records in the connection's `plan` at the provider, ends the provider's access, runs the domain's DNS check, and returns the connection as `APPLIED`. `409 DNS_CONNECTION_NOT_CONFIRMABLE` unless the connection is `NEEDS_CONFIRMATION`; `410 DNS_CONNECTION_EXPIRED` when the held access has lapsed (the connection is then `EXPIRED`); `502 DNS_PROVIDER_REJECTED` when the provider refused the change (nothing is half-applied).
+      operationId: postOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsByConnectionIdApply
+      parameters:
+        - $ref: "#/components/parameters/XCorrelationId"
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: organizationId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: publicationId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: domainId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: connectionId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - $ref: "#/components/parameters/IdempotencyKey"
+        - $ref: "#/components/parameters/XCsrfToken"
+      responses:
+        "200":
+          content:
+            application/json:
+              examples:
+                nominal:
+                  summary: Nominal successful response
+                  value:
+                    applied:
+                      at: "2026-10-10T12:03:00.000Z"
+                      created: 0
+                      deleted: 0
+                      replaced: 1
+                    connectionId: 018f0000-0000-7000-8000-000000000001
+                    createdAt: "2026-10-10T12:00:00.000Z"
+                    expiresAt: "2026-10-10T12:10:00.000Z"
+                    intent: ADD
+                    phase: APPLIED
+                    plan:
+                      - action: REPLACE
+                        existing:
+                          proxied: true
+                          type: A
+                          value: 203.0.113.7
+                        record:
+                          name: "@"
+                          type: A
+                          value: 185.199.108.153
+                      - action: KEEP
+                        existing:
+                          proxied: false
+                          type: A
+                          value: 185.199.109.153
+                        record:
+                          name: "@"
+                          type: A
+                          value: 185.199.109.153
+                    provider: CLOUDFLARE
+                    zone:
+                      accountName: Maya Personal
+                      name: maya.dev
+              schema:
+                $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsByConnectionIdApplyResponse"
+          description: apply the DNS changes a connection is waiting to make succeeded
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+        "400":
+          content:
+            application/problem+json:
+              examples:
+                VALIDATION_FAILED:
+                  summary: VALIDATION_FAILED
+                  value:
+                    code: VALIDATION_FAILED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 400
+                    title: VALIDATION_FAILED
+                    type: urn:gala:problem:validation-failed
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: VALIDATION_FAILED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - VALIDATION_FAILED
+        "401":
+          content:
+            application/problem+json:
+              examples:
+                AUTHENTICATION_REQUIRED:
+                  summary: AUTHENTICATION_REQUIRED
+                  value:
+                    code: AUTHENTICATION_REQUIRED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 401
+                    title: AUTHENTICATION_REQUIRED
+                    type: urn:gala:problem:authentication-required
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHENTICATION_REQUIRED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHENTICATION_REQUIRED
+        "403":
+          content:
+            application/problem+json:
+              examples:
+                AUTHORIZATION_DENIED:
+                  summary: AUTHORIZATION_DENIED
+                  value:
+                    code: AUTHORIZATION_DENIED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 403
+                    title: AUTHORIZATION_DENIED
+                    type: urn:gala:problem:authorization-denied
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHORIZATION_DENIED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHORIZATION_DENIED
+        "404":
+          content:
+            application/problem+json:
+              examples:
+                DNS_CONNECTION_NOT_FOUND:
+                  summary: DNS_CONNECTION_NOT_FOUND
+                  value:
+                    code: DNS_CONNECTION_NOT_FOUND
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 404
+                    title: DNS_CONNECTION_NOT_FOUND
+                    type: urn:gala:problem:dns-connection-not-found
+                RESOURCE_NOT_FOUND:
+                  summary: RESOURCE_NOT_FOUND
+                  value:
+                    code: RESOURCE_NOT_FOUND
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 404
+                    title: RESOURCE_NOT_FOUND
+                    type: urn:gala:problem:resource-not-found
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: DNS_CONNECTION_NOT_FOUND, RESOURCE_NOT_FOUND
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - DNS_CONNECTION_NOT_FOUND
+            - RESOURCE_NOT_FOUND
+        "409":
+          content:
+            application/problem+json:
+              examples:
+                COMMAND_REPLAY_CONFLICT:
+                  summary: COMMAND_REPLAY_CONFLICT
+                  value:
+                    code: COMMAND_REPLAY_CONFLICT
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 409
+                    title: COMMAND_REPLAY_CONFLICT
+                    type: urn:gala:problem:command-replay-conflict
+                DNS_CONNECTION_NOT_CONFIRMABLE:
+                  summary: DNS_CONNECTION_NOT_CONFIRMABLE
+                  value:
+                    code: DNS_CONNECTION_NOT_CONFIRMABLE
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 409
+                    title: DNS_CONNECTION_NOT_CONFIRMABLE
+                    type: urn:gala:problem:dns-connection-not-confirmable
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: COMMAND_REPLAY_CONFLICT, DNS_CONNECTION_NOT_CONFIRMABLE
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - COMMAND_REPLAY_CONFLICT
+            - DNS_CONNECTION_NOT_CONFIRMABLE
+        "410":
+          content:
+            application/problem+json:
+              examples:
+                DNS_CONNECTION_EXPIRED:
+                  summary: DNS_CONNECTION_EXPIRED
+                  value:
+                    code: DNS_CONNECTION_EXPIRED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 410
+                    title: DNS_CONNECTION_EXPIRED
+                    type: urn:gala:problem:dns-connection-expired
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: DNS_CONNECTION_EXPIRED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - DNS_CONNECTION_EXPIRED
+        "502":
+          content:
+            application/problem+json:
+              examples:
+                DNS_PROVIDER_REJECTED:
+                  summary: DNS_PROVIDER_REJECTED
+                  value:
+                    code: DNS_PROVIDER_REJECTED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: true
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 502
+                    title: DNS_PROVIDER_REJECTED
+                    type: urn:gala:problem:dns-provider-rejected
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: DNS_PROVIDER_REJECTED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - DNS_PROVIDER_REJECTED
+      security:
+        - browserSession: []
+      summary: apply the DNS changes a connection is waiting to make
+      tags:
+        - domains
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - NONE
+      x-gala-capability-key: publication.settings.manage
+      x-gala-concurrency: domain-binding-version
+      x-gala-conditional-capabilities: []
+      x-gala-example-profile: NOMINAL_SUCCESS_AND_EACH_REACHABLE_PROBLEM
+      x-gala-nullability: required-and-nullable-are-explicit
+      x-gala-purpose: apply the DNS changes a connection is waiting to make
+      x-gala-reachable-problems:
+        - AUTHENTICATION_REQUIRED
+        - AUTHORIZATION_DENIED
+        - COMMAND_REPLAY_CONFLICT
+        - DNS_CONNECTION_EXPIRED
+        - DNS_CONNECTION_NOT_CONFIRMABLE
+        - DNS_CONNECTION_NOT_FOUND
+        - DNS_PROVIDER_REJECTED
+        - RESOURCE_NOT_FOUND
+        - VALIDATION_FAILED
+      x-gala-replay-identity: idempotency-key
+      x-gala-state-guards:
+        - NONE
+      x-gala-success-category: protocol
+      x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
+  /v2/organizations/{organizationId}/publications/{publicationId}/domains/{domainId}/dns-connections/{connectionId}:discard:
+    post:
+      description: |
+        Ends a connection that is waiting for confirmation without changing anything at the provider, ends the provider's access, and returns the connection as `CANCELLED`. `409 DNS_CONNECTION_NOT_CONFIRMABLE` unless the connection is `NEEDS_CONFIRMATION`.
+      operationId: postOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsByConnectionIdDiscard
+      parameters:
+        - $ref: "#/components/parameters/XCorrelationId"
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: organizationId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: publicationId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: domainId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: connectionId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - $ref: "#/components/parameters/IdempotencyKey"
+        - $ref: "#/components/parameters/XCsrfToken"
+      responses:
+        "200":
+          content:
+            application/json:
+              examples:
+                nominal:
+                  summary: Nominal successful response
+                  value:
+                    connectionId: 018f0000-0000-7000-8000-000000000001
+                    createdAt: "2026-10-10T12:00:00.000Z"
+                    expiresAt: "2026-10-10T12:10:00.000Z"
+                    intent: ADD
+                    outcome:
+                      code: CANCELLED
+                      detail: The records were left as they were.
+                    phase: CANCELLED
+                    plan:
+                      - action: REPLACE
+                        existing:
+                          proxied: true
+                          type: A
+                          value: 203.0.113.7
+                        record:
+                          name: "@"
+                          type: A
+                          value: 185.199.108.153
+                      - action: KEEP
+                        existing:
+                          proxied: false
+                          type: A
+                          value: 185.199.109.153
+                        record:
+                          name: "@"
+                          type: A
+                          value: 185.199.109.153
+                    provider: CLOUDFLARE
+                    zone:
+                      accountName: Maya Personal
+                      name: maya.dev
+              schema:
+                $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdDomainsByDomainIdDnsConnectionsByConnectionIdDiscardResponse"
+          description: leave the provider's DNS records as they are and end a connection succeeded
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+        "400":
+          content:
+            application/problem+json:
+              examples:
+                VALIDATION_FAILED:
+                  summary: VALIDATION_FAILED
+                  value:
+                    code: VALIDATION_FAILED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 400
+                    title: VALIDATION_FAILED
+                    type: urn:gala:problem:validation-failed
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: VALIDATION_FAILED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - VALIDATION_FAILED
+        "401":
+          content:
+            application/problem+json:
+              examples:
+                AUTHENTICATION_REQUIRED:
+                  summary: AUTHENTICATION_REQUIRED
+                  value:
+                    code: AUTHENTICATION_REQUIRED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 401
+                    title: AUTHENTICATION_REQUIRED
+                    type: urn:gala:problem:authentication-required
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHENTICATION_REQUIRED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHENTICATION_REQUIRED
+        "403":
+          content:
+            application/problem+json:
+              examples:
+                AUTHORIZATION_DENIED:
+                  summary: AUTHORIZATION_DENIED
+                  value:
+                    code: AUTHORIZATION_DENIED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 403
+                    title: AUTHORIZATION_DENIED
+                    type: urn:gala:problem:authorization-denied
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHORIZATION_DENIED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHORIZATION_DENIED
+        "404":
+          content:
+            application/problem+json:
+              examples:
+                DNS_CONNECTION_NOT_FOUND:
+                  summary: DNS_CONNECTION_NOT_FOUND
+                  value:
+                    code: DNS_CONNECTION_NOT_FOUND
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 404
+                    title: DNS_CONNECTION_NOT_FOUND
+                    type: urn:gala:problem:dns-connection-not-found
+                RESOURCE_NOT_FOUND:
+                  summary: RESOURCE_NOT_FOUND
+                  value:
+                    code: RESOURCE_NOT_FOUND
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 404
+                    title: RESOURCE_NOT_FOUND
+                    type: urn:gala:problem:resource-not-found
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: DNS_CONNECTION_NOT_FOUND, RESOURCE_NOT_FOUND
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - DNS_CONNECTION_NOT_FOUND
+            - RESOURCE_NOT_FOUND
+        "409":
+          content:
+            application/problem+json:
+              examples:
+                COMMAND_REPLAY_CONFLICT:
+                  summary: COMMAND_REPLAY_CONFLICT
+                  value:
+                    code: COMMAND_REPLAY_CONFLICT
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 409
+                    title: COMMAND_REPLAY_CONFLICT
+                    type: urn:gala:problem:command-replay-conflict
+                DNS_CONNECTION_NOT_CONFIRMABLE:
+                  summary: DNS_CONNECTION_NOT_CONFIRMABLE
+                  value:
+                    code: DNS_CONNECTION_NOT_CONFIRMABLE
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 409
+                    title: DNS_CONNECTION_NOT_CONFIRMABLE
+                    type: urn:gala:problem:dns-connection-not-confirmable
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: COMMAND_REPLAY_CONFLICT, DNS_CONNECTION_NOT_CONFIRMABLE
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - COMMAND_REPLAY_CONFLICT
+            - DNS_CONNECTION_NOT_CONFIRMABLE
+      security:
+        - browserSession: []
+      summary: leave the provider's DNS records as they are and end a connection
+      tags:
+        - domains
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - NONE
+      x-gala-capability-key: publication.settings.manage
+      x-gala-concurrency: domain-binding-version
+      x-gala-conditional-capabilities: []
+      x-gala-example-profile: NOMINAL_SUCCESS_AND_EACH_REACHABLE_PROBLEM
+      x-gala-nullability: required-and-nullable-are-explicit
+      x-gala-purpose: leave the provider's DNS records as they are and end a connection
+      x-gala-reachable-problems:
+        - AUTHENTICATION_REQUIRED
+        - AUTHORIZATION_DENIED
+        - COMMAND_REPLAY_CONFLICT
+        - DNS_CONNECTION_NOT_CONFIRMABLE
+        - DNS_CONNECTION_NOT_FOUND
+        - RESOURCE_NOT_FOUND
+        - VALIDATION_FAILED
+      x-gala-replay-identity: idempotency-key
+      x-gala-state-guards:
+        - NONE
+      x-gala-success-category: protocol
+      x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
   /v2/organizations/{organizationId}/publications/{publicationId}/domains/{domainId}:check:
     post:
       description: |