@whooshbang/contracts 1.0.0-rc.19 → 1.0.0-rc.21

package/openapi/whooshbang-v1.yaml

@@ -1,10 +1,10 @@
 openapi: 3.1.1
 jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema
 # whooshbang:public-origin production api https://api.whooshbang.com
-x-contract-version: 1.0.0-rc.19
+x-contract-version: 1.0.0-rc.21
 info:
   title: WhooshBang API
-  version: 1.0.0-rc.19
+  version: 1.0.0-rc.21
   description: |
     The V1 contract for human account/project administration, project-scoped
     subscription links, and asynchronous text messages. A Clerk session selects
@@ -41,6 +41,8 @@ tags:
     description: Account-scoped applications with transactionally bootstrapped test/live environments.
   - name: API credentials
     description: Human-administered, environment-scoped bearer credentials with one-time secret reveal.
+  - name: Account credentials
+    description: Human-administered, account-scoped bearer credentials that name their project and environment per call.
   - name: Subscription links
     description: Single-use, expiring Telegram authorization links.
   - name: Messages
@@ -97,6 +99,193 @@ paths:
           $ref: "#/components/responses/Forbidden"
         "429":
           $ref: "#/components/responses/RateLimited"
+  /v1/account/credentials:
+    get:
+      operationId: listAccountCredentials
+      summary: List safe account credential metadata
+      description: |
+        Returns only credentials owned by the account selected by the verified
+        Clerk organization session. Secrets and digest material are never
+        returned.
+      tags:
+        - Account credentials
+      security:
+        - clerkSession: []
+      x-account-membership: required
+      parameters:
+        - $ref: "#/components/parameters/ApiCredentialAfterCursor"
+        - $ref: "#/components/parameters/ApiCredentialPageLimit"
+        - $ref: "#/components/parameters/PageNumber"
+      responses:
+        "200":
+          description: A stable page of safe account credential metadata.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AccountCredentialCollection"
+              examples:
+                accountCredentials:
+                  externalValue: ../fixtures/core-v1/success/account-credential-collection.json
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+    post:
+      operationId: createAccountCredential
+      summary: Create an account-scoped API credential
+      description: |
+        Creates one credential against the whole account. It names no project
+        and no environment: a request names them in its path, and the
+        credential's authority on that path is the intersection of its scopes
+        with the project-credential vocabulary, so it is never wider than a
+        project credential would have been for the same project environment.
+        The complete bearer secret appears only in this creation response. It
+        cannot be read later and is never replayed from an idempotency cache.
+      tags:
+        - Account credentials
+      security:
+        - clerkSession: []
+      x-account-membership: required
+      x-secret-reveal:
+        responses: 1
+        replayable: false
+        later_reads: metadata_only
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateAccountCredentialRequest"
+            examples:
+              createAccountCredential:
+                externalValue: ../fixtures/core-v1/requests/create-account-credential.json
+      responses:
+        "201":
+          description: Creation-only secret reveal and safe credential metadata.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AccountCredentialSecretReveal"
+              examples:
+                createdAccountCredential:
+                  externalValue: ../fixtures/core-v1/success/account-credential-created.json
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/account/credentials/{account_credential_id}/rotate:
+    parameters:
+      - $ref: "#/components/parameters/AccountCredentialId"
+    post:
+      operationId: rotateAccountCredential
+      summary: Rotate an account-scoped API credential
+      description: |
+        Creates one replacement with the same label and scopes. The complete new
+        bearer secret appears only in this response. The replaced credential
+        remains active for the explicitly declared overlap, from zero through
+        86400 seconds, then becomes terminally revoked. A revoked credential
+        cannot be rotated. Missing and out-of-account credentials use the same
+        non-enumerating `404`.
+      tags:
+        - Account credentials
+      security:
+        - clerkSession: []
+      x-account-membership: required
+      x-secret-reveal:
+        responses: 1
+        replayable: false
+        later_reads: metadata_only
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RotateAccountCredentialRequest"
+            examples:
+              rotateAccountCredential:
+                externalValue: ../fixtures/core-v1/requests/rotate-account-credential.json
+      responses:
+        "201":
+          description: Creation-only replacement secret and safe metadata for both credentials.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AccountCredentialRotation"
+              examples:
+                rotatedAccountCredential:
+                  externalValue: ../fixtures/core-v1/success/account-credential-rotated.json
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/account/credentials/{account_credential_id}/revoke:
+    parameters:
+      - $ref: "#/components/parameters/AccountCredentialId"
+    post:
+      operationId: revokeAccountCredential
+      summary: Revoke an account-scoped API credential
+      description: |
+        Immediately and terminally revokes the selected credential. Repeating
+        the request for the same visible credential is safe and returns the
+        same revoked metadata without revealing secret or digest material.
+        Missing and out-of-account credentials use the same non-enumerating
+        `404`.
+      tags:
+        - Account credentials
+      security:
+        - clerkSession: []
+      x-account-membership: required
+      x-repeat-semantics:
+        same_target: idempotent
+        secret_returned: false
+      responses:
+        "200":
+          description: Safe terminal credential metadata.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AccountCredential"
+              examples:
+                revokedAccountCredential:
+                  externalValue: ../fixtures/core-v1/success/account-credential-revoked.json
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "429":
+          $ref: "#/components/responses/RateLimited"
   /v1/projects:
     get:
       operationId: listProjects
@@ -110,6 +299,7 @@ paths:
       security:
         - clerkSession: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - projects:read
       x-account-membership: required
@@ -211,6 +401,7 @@ paths:
       security:
         - clerkSession: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - projects:read
       x-account-membership: required
@@ -252,6 +443,7 @@ paths:
       security:
         - clerkSession: []
         - bearerGrant: []
+        - bearerCredential: []
       x-required-scopes:
         - projects:read
       x-account-membership: required
@@ -309,6 +501,7 @@ paths:
       security:
         - clerkSession: []
         - bearerGrant: []
+        - bearerCredential: []
       x-required-scopes:
         - projects:write
       x-account-membership: required
@@ -350,6 +543,7 @@ paths:
       security:
         - clerkSession: []
         - bearerGrant: []
+        - bearerCredential: []
       x-required-scopes:
         - projects:write
       x-account-membership: required
@@ -728,6 +922,7 @@ paths:
       security:
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - messages:write
       x-idempotency:
@@ -801,6 +996,7 @@ paths:
       security:
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - messages:write
       x-repeat-semantics:
@@ -1473,6 +1669,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - messages:read
       parameters:
@@ -1512,6 +1709,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - messages:write
       x-idempotency:
@@ -1586,6 +1784,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - messages:read
       responses:
@@ -1615,6 +1814,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - messages:write
       responses:
@@ -1648,6 +1848,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - messages:write
       x-idempotency:
@@ -1720,6 +1921,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - messages:write
       x-repeat-semantics:
@@ -1754,6 +1956,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - messages:read
       parameters:
@@ -1794,6 +1997,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - connections:read
       responses:
@@ -1830,6 +2034,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - connections:read
       parameters:
@@ -1921,6 +2126,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - connections:write
       x-idempotency:
@@ -2001,6 +2207,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - connections:read
       responses:
@@ -2033,6 +2240,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - connections:write
       requestBody:
@@ -2080,6 +2288,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - connections:write
       responses:
@@ -2139,6 +2348,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - connections:write
       responses:
@@ -2192,6 +2402,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - connections:write
       x-idempotency:
@@ -2233,14 +2444,30 @@ paths:
       - $ref: "#/components/parameters/ChannelConnectionId"
     post:
       operationId: restartChannelConnectionSetup
-      summary: Start a fresh managed setup on a connection that never finished one
+      summary: Start a fresh setup on a connection that never finished one
       description: |
-        Issues a new handoff for a `customer_managed` connection whose guided
-        setup expired, failed, or was simply abandoned, and returns the same
-        connection carrying a fresh `setup`. The connection is reused rather
-        than replaced because it is still `pending`: nothing was ever
+        Issues a new guided setup for a `customer_managed` connection whose
+        setup expired, failed, or was simply abandoned. Nothing was ever
         provisioned under it, no identity was claimed, and no subscriber ever
-        consented to anything through it.
+        consented to anything through it, so nothing is lost.
+
+        **Telegram reuses the connection and answers `200`.** A fresh `setup`
+        appears on the same resource.
+
+        **Customer-owned Slack replaces the connection and answers `201`.** The
+        abandoned connection is archived and a new one is returned, carrying a
+        new `app_setup` and a new creation link. The connection cannot be
+        reused, because Slack bakes this deployment's request URLs into the app
+        at the moment it is created and they are not ours to change afterwards:
+        a second setup on one connection would mean two Slack apps answering to
+        one address. **Read `id` on the response** — the connection you were
+        polling is now archived. A Slack app the previous attempt already
+        created is not withdrawn and cannot be; it is the customer's, and they
+        delete it in Slack when they are ready.
+
+        Entering the three app-specific values again is not a restart, and does
+        not need one. `rotate-credential` replaces them on the connection that
+        already exists.
 
         Restart takes no body. The suggested identity recorded when the
         connection was created is what the new attempt proposes again, so a
@@ -2279,6 +2506,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - connections:write
       x-repeat-semantics:
@@ -2297,6 +2525,21 @@ paths:
               examples:
                 setupRestarted:
                   externalValue: ../fixtures/core-v1/success/channel-connection-setup-restarted.json
+        "201":
+          description: |
+            A replacement connection carrying a fresh setup, for a
+            customer-owned Slack app whose request URLs cannot be re-pointed.
+            The connection named in the request is now archived.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ChannelConnection"
+              examples:
+                setupReplaced:
+                  externalValue: ../fixtures/core-v1/success/channel-connection-slack-customer-pending.json
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
@@ -2378,6 +2621,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - connections:write
       requestBody:
@@ -2456,6 +2700,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - connections:write
       responses:
@@ -2519,6 +2764,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - connections:write
       responses:
@@ -2544,6 +2790,262 @@ paths:
           $ref: "#/components/responses/ProviderOutcomeUnknown"
         "503":
           $ref: "#/components/responses/ProviderRetryable"
+  /v1/projects/{project_id}/environments/{environment_id}/channel-connections/{connection_id}/app-manifest:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+      - $ref: "#/components/parameters/EnvironmentId"
+      - $ref: "#/components/parameters/ChannelConnectionId"
+    get:
+      operationId: getChannelConnectionAppManifest
+      summary: Read the generated app configuration a customer-owned setup will create
+      description: |
+        Returns the exact configuration WhooshBang generated for this
+        customer-owned Slack setup — the scopes it will ask for, the request
+        URLs it will point at, the literal manifest document, and the same
+        prefilled creation link the setup already carries.
+
+        It exists so the owner can read what they are about to approve, and a
+        reviewer can check it, without opening Slack or decoding a URL. It
+        carries configuration only: no account, project, or environment, no
+        credential, and no provider-native identifier.
+
+        Only a `customer_managed` Slack connection has one. Every other
+        provider and mode answers `404`, because a manifest they do not have is
+        not a manifest that is empty.
+      tags:
+        - Channel connections
+      security:
+        - clerkSession: []
+        - bearerCredential: []
+        - bearerGrant: []
+        - bearerAccountCredential: []
+      x-required-scopes:
+        - connections:read
+      responses:
+        "200":
+          description: The generated app configuration for exactly this setup.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CustomerOwnedSlackAppManifest"
+              examples:
+                manifest:
+                  externalValue: ../fixtures/core-v1/success/customer-owned-slack-app-manifest.json
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  /v1/projects/{project_id}/environments/{environment_id}/channel-connections/{connection_id}/tests:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+      - $ref: "#/components/parameters/EnvironmentId"
+      - $ref: "#/components/parameters/ChannelConnectionId"
+    get:
+      operationId: listConnectionTests
+      summary: List this connection's recent owner-triggered tests
+      description: |
+        Newest first. This is the audit-safe failure history for one
+        connection: what was tried, when, what came back, and what to do about
+        it. Every entry is safe to render, log, and paste into an issue.
+      tags:
+        - Channel connections
+      security:
+        - clerkSession: []
+        - bearerCredential: []
+        - bearerGrant: []
+        - bearerAccountCredential: []
+      x-required-scopes:
+        - connections:read
+      parameters:
+        - $ref: "#/components/parameters/ListAfterCursor"
+        - $ref: "#/components/parameters/ListPageLimit"
+        - $ref: "#/components/parameters/PageNumber"
+      responses:
+        "200":
+          description: Tests placed against exactly this connection.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ConnectionTestCollection"
+              examples:
+                tests:
+                  externalValue: ../fixtures/core-v1/success/connection-test-collection.json
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+    post:
+      operationId: createConnectionTest
+      summary: Prove this exact connection still works
+      description: |
+        Runs one test against one connection, on demand, and answers with what
+        it observed rather than with a claim.
+
+        Available on any Slack connection, whether the app is one the customer
+        owns or the one WhooshBang operates. Every other provider and mode is
+        refused rather than reporting a pass it never ran.
+
+        **A test addresses the workspace member who authorized this exact
+        connection, and nobody else.** For an app the customer owns that is the
+        person who installed it, once, for one connection. The
+        WhooshBang-operated app's installation is shared across tenants, so
+        "whoever installed the app" is not necessarily anybody the calling
+        tenant named; what is recorded instead is the member who approved this
+        environment's own connection, during its own authorization, and each
+        later authorization replaces it. One tenant therefore cannot cause a
+        message to somebody another tenant authorized.
+
+        `outbound_notification` sends one visible private message through this
+        exact identity to that member, and settles when the provider accepts
+        it. Nobody else can be addressed: a test cannot reach a channel, and it
+        cannot reach a subscriber who has not authorized anything.
+
+        `signed_interaction` sends that person a message with one button and
+        then waits. It settles when the provider calls this deployment's
+        interactivity URL and the signature over the untouched body verifies
+        against the secret this connection custodies — the only proof that the
+        signing secret, the request URL, and public reachability are all
+        correct at once. A window that closes with nothing arriving settles as
+        `expired`, which says nobody pressed it, and a request that arrives and
+        does not verify settles as `failed` with `unverified_request_received`.
+
+        The response is the placed test. An `outbound_notification` is usually
+        already settled when it returns; a `signed_interaction` is `pending`
+        until somebody presses the button, so read it again or list this
+        connection's tests.
+
+        **A provider failure is an answer, not a refusal.** If the connection
+        has not finished setup, or its grant is unavailable, or Slack refuses,
+        rate-limits, or cannot be reached, the test is **recorded** and answers
+        `201` carrying `status: failed`, a `failure_code` and a
+        `recovery_action`. There is no `502` or `503` on this operation, and
+        that is deliberate: a diagnostic that leaves no trace is the one thing
+        an audit-safe failure history cannot have, so the failure goes in the
+        history rather than into a problem document nobody keeps.
+
+        Three things are refused outright, because none describes a test that
+        ran: the connection is archived, it is not a Slack connection, or it is
+        a WhooshBang-operated Slack connection whose authorization has been
+        revoked — `idempotency_conflict` 409, `invalid_connection_transition`
+        at `/`. A connection that has never recorded who authorized it is not
+        refused: it is a recorded failure with
+        `verification_target_unknown`, because there is nobody a test could
+        honestly address.
+
+        A test never carries customer notification content, never counts as a
+        delivery to a subscriber, and never changes what any subscriber
+        receives.
+      tags:
+        - Channel connections
+      security:
+        - clerkSession: []
+        - bearerCredential: []
+        - bearerGrant: []
+        - bearerAccountCredential: []
+      x-required-scopes:
+        - connections:write
+      x-idempotency:
+        required: true
+        retention_seconds: 604800
+        scope:
+          - authenticated_environment
+          - operation_id
+          - key
+        equivalence: exact_request_body
+        replay_retention_extends: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateConnectionTestRequest"
+            examples:
+              signedInteraction:
+                externalValue: ../fixtures/core-v1/requests/create-connection-test.json
+      responses:
+        "201":
+          description: The placed test, settled if it could settle immediately.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ConnectionTest"
+              examples:
+                pending:
+                  externalValue: ../fixtures/core-v1/success/connection-test-pending.json
+        "200":
+          description: The equivalent test an idempotent replay already placed.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ConnectionTest"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
+  /v1/projects/{project_id}/environments/{environment_id}/channel-connections/{connection_id}/tests/{test_id}:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+      - $ref: "#/components/parameters/EnvironmentId"
+      - $ref: "#/components/parameters/ChannelConnectionId"
+      - $ref: "#/components/parameters/ConnectionTestId"
+    get:
+      operationId: getConnectionTest
+      summary: Read one owner-triggered connection test
+      description: |
+        The durable answer to one test. A `signed_interaction` is read again
+        here until it settles; a pending test whose window has closed reads as
+        `expired` on the way out rather than waiting for a sweep, so the status
+        the owner sees is the one they actually have.
+      tags:
+        - Channel connections
+      security:
+        - clerkSession: []
+        - bearerCredential: []
+        - bearerGrant: []
+        - bearerAccountCredential: []
+      x-required-scopes:
+        - connections:read
+      responses:
+        "200":
+          description: The exact test.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ConnectionTest"
+              examples:
+                succeeded:
+                  externalValue: ../fixtures/core-v1/success/connection-test-succeeded.json
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
   /v1/projects/{project_id}/environments/{environment_id}/notifier-connections:
     parameters:
       - $ref: "#/components/parameters/ProjectId"
@@ -2566,6 +3068,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - connections:read
       parameters:
@@ -2630,6 +3133,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - connections:write
       requestBody:
@@ -2692,6 +3196,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - connections:write
       responses:
@@ -2724,6 +3229,7 @@ paths:
       security:
         - clerkSession: []
         - bearerGrant: []
+        - bearerCredential: []
       x-required-scopes:
         - projects:read
       x-account-membership: required
@@ -2751,6 +3257,7 @@ paths:
       security:
         - clerkSession: []
         - bearerGrant: []
+        - bearerCredential: []
       x-required-scopes:
         - projects:write
       x-account-membership: required
@@ -2795,6 +3302,7 @@ paths:
       security:
         - clerkSession: []
         - bearerGrant: []
+        - bearerCredential: []
       x-required-scopes:
         - projects:write
       x-account-membership: required
@@ -2842,6 +3350,11 @@ paths:
         - Recipient experience
       security:
         - clerkSession: []
+        - bearerGrant: []
+        - bearerCredential: []
+        - bearerAccountCredential: []
+      x-required-scopes:
+        - projects:read
       x-account-membership: required
       responses:
         "200":
@@ -2863,14 +3376,21 @@ paths:
       operationId: updateEnvironmentRecipientExperience
       summary: Replace one environment's enabled channels and exact browser policy
       description: |
-        Origins are exact scheme/host/port values. Return destinations are
-        registered developer keys resolving to exact URLs. Wildcards,
-        templates, arbitrary recipient-time URLs, and channels not backed by
-        an offered compatible connection are refused.
+        Origins are exact scheme/host/port values, written in any spelling that
+        means that same origin: a trailing slash, an uppercase host, and an
+        explicitly written default port are accepted and stored in canonical
+        form. Return destinations are registered developer keys resolving to
+        exact URLs. Wildcards, templates, arbitrary recipient-time URLs, and
+        channels not backed by an offered compatible connection are refused.
       tags:
         - Recipient experience
       security:
         - clerkSession: []
+        - bearerGrant: []
+        - bearerCredential: []
+        - bearerAccountCredential: []
+      x-required-scopes:
+        - projects:write
       x-account-membership: required
       requestBody:
         required: true
@@ -3719,6 +4239,7 @@ paths:
         - Subscription links
       security:
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - subscriptions:write
       x-idempotency:
@@ -3778,6 +4299,7 @@ paths:
         - Subscription links
       security:
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - subscriptions:read
       responses:
@@ -3817,6 +4339,7 @@ paths:
         - Messages
       security:
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - messages:write
       x-idempotency:
@@ -3881,6 +4404,7 @@ paths:
         - Messages
       security:
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - messages:read
       responses:
@@ -3923,6 +4447,7 @@ paths:
         - Messages
       security:
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - messages:read
       responses:
@@ -3962,6 +4487,7 @@ paths:
         - Machine clients
       security:
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - machine-clients:write
       x-idempotency:
@@ -4008,6 +4534,74 @@ paths:
           $ref: "#/components/responses/Unprocessable"
         "429":
           $ref: "#/components/responses/RateLimited"
+  /v1/projects/{project_id}/environments/{environment_id}/machine-clients/{machine_client_id}/credentials:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+      - $ref: "#/components/parameters/EnvironmentId"
+      - $ref: "#/components/parameters/MachineClientId"
+    post:
+      operationId: registerMachineCredentialInEnvironment
+      summary: Register a machine-credential digest in a named project environment
+      description: |
+        The environment-scoped form of `registerMachineCredential`. Registers
+        only the credential ID and SHA-256 digest; the path only names where the
+        owning machine client lives. Request and response shapes are that
+        operation's exactly, including its published examples.
+      tags:
+        - Machine clients
+      security:
+        - bearerGrant: []
+        - bearerAccountCredential: []
+      x-required-scopes:
+        - machine-clients:write
+      x-idempotency:
+        required: true
+        retention_seconds: 604800
+        scope:
+          - authenticated_environment
+          - operation_id
+          - key
+        equivalence: validated_request_after_documented_defaults
+        replay_retention_extends: false
+      parameters:
+        - $ref: "#/components/parameters/IdempotencyKey"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RegisterMachineCredentialRequest"
+      responses:
+        "200":
+          description: Existing safe credential metadata on an equivalent registration replay; never secret or digest.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MachineCredential"
+        "201":
+          description: Newly registered safe credential metadata; never secret or digest.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MachineCredential"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
+        "429":
+          $ref: "#/components/responses/RateLimited"
   /v1/projects/{project_id}/environments/{environment_id}/capabilities:
     parameters:
       - $ref: "#/components/parameters/ProjectId"
@@ -4023,6 +4617,7 @@ paths:
         - Capabilities
       security:
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - capabilities:read
       responses:
@@ -4065,6 +4660,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - subscriptions:write
       x-idempotency:
@@ -4128,6 +4724,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - subscriptions:read
       responses:
@@ -4160,6 +4757,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - subscriptions:read
       parameters:
@@ -4205,6 +4803,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - subscriptions:write
       x-idempotency:
@@ -4269,6 +4868,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - subscriptions:read
       responses:
@@ -4296,6 +4896,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - subscriptions:write
       requestBody:
@@ -4334,6 +4935,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - subscriptions:write
       responses:
@@ -4374,6 +4976,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - subscriptions:read
       parameters:
@@ -4441,6 +5044,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - subscriptions:write
       responses:
@@ -4474,6 +5078,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - subscriptions:write
       responses:
@@ -4513,6 +5118,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - messages:write
       x-idempotency:
@@ -4577,6 +5183,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: []
+        - bearerAccountCredential: []
       x-required-scopes:
         - messages:read
       responses:
@@ -4615,8 +5222,28 @@ components:
         consenting account member. It selects exactly one account and carries
         the scopes that member consented to, and never a project: an operation
         names its project and environment in the path, and the service checks
-        both against the granting person's membership before acting. It can
-        hold account-level scopes, which no credential can.
+        both against the granting person's membership before acting. A project
+        credential can name no project but its own; an account credential names
+        one per call the same way this does.
+    bearerAccountCredential:
+      type: http
+      scheme: bearer
+      bearerFormat: wb_ac1.acred_<16-byte-base64url>.<32-byte-base64url-secret>
+      description: |
+        Selects exactly one account and nothing below it. It names no project
+        and no environment, so it authenticates only operations whose path does,
+        and its authority there is the intersection of its scopes with the
+        project-credential vocabulary — never wider than a project credential
+        would have been for the same project environment. A path naming a
+        project outside its account is refused with `credential_account_mismatch`
+        rather than a bare scope failure. `account:read` is the one scope it can
+        hold that a project credential cannot, and it authorizes only the
+        account's project directory: listing the account's projects and reading
+        one, which is the account-wide question a project credential cannot ask
+        and the reason a `--project <slug>` selector can work at all. It is
+        required *in addition to* each of those operations' own
+        `x-required-scopes`, never instead of them.
+        Credentials cannot be read after creation.
     bearerCredential:
       type: http
       scheme: bearer
@@ -4685,6 +5312,13 @@ components:
       description: Canonical opaque project credential identity; never a readable secret.
       schema:
         $ref: "#/components/schemas/ApiCredentialId"
+    AccountCredentialId:
+      name: account_credential_id
+      in: path
+      required: true
+      description: Canonical opaque account credential identity; never a readable secret.
+      schema:
+        $ref: "#/components/schemas/AccountCredentialId"
     ApiCredentialAfterCursor:
       name: after
       in: query
@@ -4812,6 +5446,13 @@ components:
       description: Opaque connection identity; never authorization.
       schema:
         $ref: "#/components/schemas/OpaqueIdentifier"
+    ConnectionTestId:
+      name: test_id
+      in: path
+      required: true
+      description: Opaque identity of one owner-triggered connection test; never authorization.
+      schema:
+        $ref: "#/components/schemas/OpaqueIdentifier"
     NotifierId:
       name: notifier_id
       in: path
@@ -4906,6 +5547,24 @@ components:
       $ref: ../schemas/whooshbang-v1.schema.json#/$defs/UpdateChannelConnectionRequest
     RotateChannelConnectionCredentialRequest:
       $ref: ../schemas/whooshbang-v1.schema.json#/$defs/RotateChannelConnectionCredentialRequest
+    ConnectionTestKind:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/ConnectionTestKind
+    ConnectionTestRecoveryAction:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/ConnectionTestRecoveryAction
+    ConnectionTestStatus:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/ConnectionTestStatus
+    ConnectionTestFailureCode:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/ConnectionTestFailureCode
+    ConnectionTestEvidence:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/ConnectionTestEvidence
+    ConnectionTest:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/ConnectionTest
+    ConnectionTestCollection:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/ConnectionTestCollection
+    CreateConnectionTestRequest:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/CreateConnectionTestRequest
+    CustomerOwnedSlackAppManifest:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/CustomerOwnedSlackAppManifest
     NotifierConnectionRoute:
       $ref: ../schemas/whooshbang-v1.schema.json#/$defs/NotifierConnectionRoute
     NotifierConnectionCollection:
@@ -4940,6 +5599,20 @@ components:
       $ref: ../schemas/whooshbang-v1.schema.json#/$defs/UpdateRecipientCopyOverrideRequest
     CreateApiCredentialRequest:
       $ref: ../schemas/whooshbang-v1.schema.json#/$defs/CreateApiCredentialRequest
+    CreateAccountCredentialRequest:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/CreateAccountCredentialRequest
+    RotateAccountCredentialRequest:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/RotateAccountCredentialRequest
+    AccountCredentialId:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/AccountCredentialId
+    AccountCredential:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/AccountCredential
+    AccountCredentialCollection:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/AccountCredentialCollection
+    AccountCredentialSecretReveal:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/AccountCredentialSecretReveal
+    AccountCredentialRotation:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/AccountCredentialRotation
     RotateApiCredentialRequest:
       $ref: ../schemas/whooshbang-v1.schema.json#/$defs/RotateApiCredentialRequest
     ApiCredentialId: