@sponson/adapters 0.4.0 → 0.6.0

package/recipes/honeycomb.yaml

@@ -0,0 +1,89 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Honeycomb API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: honeycomb
+title: Honeycomb
+category: observability
+verified_on: "2026-10-11"
+docs:
+  - title: Create a Marker
+    url: https://docs.honeycomb.io/api/markers/create-a-marker
+  - title: List All Markers
+    url: https://docs.honeycomb.io/api/markers
+  - title: Update a Marker
+    url: https://docs.honeycomb.io/api/markers/update-a-marker
+  - title: Delete a Marker
+    url: https://docs.honeycomb.io/api/markers/delete-a-marker
+api:
+  base_url: https://api.honeycomb.io
+  base_url_env: HONEYCOMB_API_URL
+  auth: { header: X-Honeycomb-Team, value_env: HONEYCOMB_API_KEY }
+detect:
+  deps: ["@honeycombio/"]
+  env: ["HONEYCOMB_*"]
+  starter:
+    - op: marker
+      values: { dataset: __all__, message: "deploy ${ctx.scope} ${ctx.git.sha}" }
+assumptions:
+  - id: HC1
+    verified: true
+    text: "`POST /1/markers/{datasetSlug}` creates a marker from `start_time`, `end_time` (Unix seconds), `message`, `type` and `url` (all optional; `start_time` defaults to the request's arrival), answering 201 with the marker and its `id`; `__all__` as the dataset slug makes an environment-wide marker. Requests carry a Configuration Key with the Manage Markers permission in `X-Honeycomb-Team`."
+    source: https://docs.honeycomb.io/api/markers/create-a-marker
+  - id: HC2
+    verified: true
+    text: "`GET /1/markers/{datasetSlug}` answers a bare array of the dataset's markers (`id`, `message`, `type`, `url`, `start_time`, `end_time`, `created_at`, `updated_at`, `color`)."
+    source: https://docs.honeycomb.io/api/markers
+  - id: HC3
+    verified: true
+    text: "`PUT /1/markers/{datasetSlug}/{markerId}` replaces the marker: a field left out of the body is erased."
+    source: https://docs.honeycomb.io/api/markers/update-a-marker
+  - id: HC4
+    verified: true
+    text: "`DELETE /1/markers/{datasetSlug}/{markerId}` removes the marker and answers it (200)."
+    source: https://docs.honeycomb.io/api/markers/delete-a-marker
+  - id: HC5
+    verified: true
+    text: "The API is served from `api.honeycomb.io` (US) and `api.eu1.honeycomb.io` (EU); EU teams set `base_url` in the provider block."
+    source: https://docs.honeycomb.io/api/markers/create-a-marker
+  - id: HC6
+    verified: false
+    text: "Message and type identify the marker this recipe created among the dataset's markers (Honeycomb does not require them to be unique: two equal ones make `find` refuse with PARAM_INVALID), and the list holds every marker of the dataset in one answer."
+  - id: HC7
+    verified: false
+    text: "An update (a changed `url`) re-sends message, type and url but not `start_time`, which Honeycomb then sets to the time of the update (HC3), moving the marker; markers are rarely edited."
+  - id: HC8
+    verified: false
+    text: "A deleted marker answers 404 to DELETE, which destroy treats as already gone."
+ops:
+  marker:
+    kind: resource
+    title: Deploy marker
+    summary: "A marker on an environment's dataset (or on every dataset of the environment with `__all__`) for a deploy, such as `deploy pr-42 0123abc`. Located by its message and type; a console edit of its URL is drift. Destroying the scope removes it; write `destroy: keep` to keep the deploy history."
+    covers: [honeycomb-marker]
+    params:
+      dataset:
+        type: string
+        required: true
+        description: The dataset's slug, or `__all__` for an environment-wide marker.
+        example: __all__
+      message:
+        type: string
+        required: true
+        description: The marker's text; with its type, its identity (HC6).
+        example: "deploy ${ctx.scope} ${ctx.git.sha}"
+      type:
+        type: string
+        default: deploy
+        description: The marker's type, which groups markers (and their color).
+      url:
+        type: string
+        description: The link opened from the marker (the preview or the build).
+        example: "https://${ctx.scope}.preview.example.com"
+    http:
+      find:
+        path: "/1/markers/{dataset}"
+        match: { message: { param: message }, type: { param: type } }
+      create: { path: "/1/markers/{dataset}" }
+      update: { method: PUT, path: "/1/markers/{dataset}/{id}" }
+      delete: { path: "/1/markers/{dataset}/{id}" }
+      fields:
+        url: { param: url }

package/recipes/inngest.yaml

@@ -0,0 +1,97 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Inngest recipes. Format and checklist: docs/adr/0020-recipes.md, docs/adr/0022-one-off-actions.md, CONTRIBUTING.md
+# "Adding a recipe". No API block: the sync is a request to the app's own serve endpoint, which registers itself
+# with Inngest using its own signing key, so Sponson sends no Inngest credential at all.
+provider: inngest
+title: Inngest
+category: queues
+verified_on: "2026-10-11"
+docs:
+  - title: Syncing an Inngest app (curl -X PUT on the serve endpoint), Inngest's integration guide
+    url: https://www.inngest.com/llm-context.md
+  - title: Apps in Inngest Cloud (sync methods, when to sync)
+    url: https://www.inngest.com/docs/apps/cloud
+  - title: Environments and branch environments
+    url: https://www.inngest.com/docs/platform/environments
+  - title: The TypeScript SDK's serve handler (InngestCommHandler, PUT = register)
+    url: https://github.com/inngest/inngest-js/blob/main/packages/inngest/src/components/InngestCommHandler.ts
+  - title: REST API v2 OpenAPI document (V2_SyncApp)
+    url: https://api-docs.inngest.com/api-specs/v2.json
+detect:
+  deps: [inngest]
+  env: ["INNGEST_*"]
+  starter:
+    - op: sync
+      preview_url: url
+      values: { revision: "${ctx.git.sha}" }
+assumptions:
+  - id: IN1
+    verified: true
+    text: "A `PUT` to the app's serve endpoint (by convention `/api/inngest`, `curl -X PUT https://your-app.com/api/inngest --fail-with-body`) makes the app's SDK register its functions with Inngest; the SDK authenticates that registration with the app's own `INNGEST_SIGNING_KEY`, so the caller sends no credential."
+    source: https://www.inngest.com/llm-context.md
+  - id: IN2
+    verified: true
+    text: "The app registers into the environment its SDK is configured for: `INNGEST_ENV` (or the client's `env` option) names the branch environment and always wins; Vercel's `VERCEL_GIT_COMMIT_REF` is detected automatically, while Netlify, Cloudflare Pages, Railway and Render must pass their branch variable. Sponson does not choose the environment: the app must be configured so."
+    source: https://www.inngest.com/docs/platform/environments
+  - id: IN3
+    verified: true
+    text: "A branch environment is created on demand the first time an app syncs with it (or events are sent to it), and every branch environment shares one signing key and one event key, so a preview needs no per-branch key."
+    source: https://www.inngest.com/docs/platform/environments
+  - id: IN4
+    verified: true
+    text: "Without `x-inngest-sync-kind: in-band` (which this recipe never sends) the serve handler syncs out of band: it calls Inngest's register endpoint itself and answers with that call's status and a JSON body `{ message, modified }`; a failed registration answers 500 (`Failed to register`)."
+    source: https://github.com/inngest/inngest-js/blob/main/packages/inngest/src/components/InngestCommHandler.ts
+  - id: IN5
+    verified: true
+    text: "Sync only once the new version of the code is live: some hosts roll a deploy out over seconds or minutes and an early sync registers the old functions. The recipe's trigger is the deployment's URL (a deploy line's external output, so the line waits for the deploy) and a revision."
+    source: https://www.inngest.com/docs/apps/cloud
+  - id: IN6
+    verified: true
+    text: "Branch environments are archived automatically three days after their latest deployment (archiving stops functions from triggering and keeps the data), and archiving cannot be undone per app; there is no request to undo a sync, so destroy sends nothing and forgets the record."
+    source: https://www.inngest.com/docs/platform/environments
+  - id: IN7
+    verified: true
+    text: "The REST API's `POST /v2/apps/{appId}/syncs` (marked beta, `x-beta: true`) takes `{ url }` and answers a sync with `status` pending, success, error or duplicate, but the operation declares no header or parameter that selects a branch environment; this recipe does not use it."
+    source: https://api-docs.inngest.com/api-specs/v2.json
+  - id: IN8
+    verified: false
+    text: "Syncing the same deployment again is harmless (the same functions registered again, `modified: false`), so the at-least-once delivery of an action (sent again after a crash before it was recorded) needs no idempotency key."
+  - id: IN9
+    verified: false
+    text: "A preview behind Vercel Deployment Protection answers the `PUT` with 401 unless it carries `x-vercel-protection-bypass` with the project's automation bypass secret; pass it with `headers`, as a `{ secret }`."
+ops:
+  sync:
+    kind: action
+    title: App sync into its branch environment
+    summary: Registers a preview deployment's Inngest functions by sending `PUT` to its serve endpoint, once per deployment URL and revision; the app's SDK picks the branch environment (`INNGEST_ENV`, IN2) and signs the registration with its own key (IN1), so no Inngest credential is needed.
+    covers: [inngest-sync]
+    params:
+      url:
+        type: string
+        description: "The deployment's base URL, without a trailing slash: usually `{ from: <deploy line>.preview_url }`, so the sync waits for the deploy (IN5)."
+        required: true
+        pattern: "^https?://\\S+[^/]$"
+        example: https://acme-git-feat-x-acme.vercel.app
+      path:
+        type: string
+        description: Where the app serves Inngest's `serve()` handler, appended to `url`.
+        default: /api/inngest
+        pattern: "^/\\S*$"
+      revision:
+        type: string
+        description: "What else makes it sync again when it changes, usually the commit: `\"${ctx.git.sha}\"`."
+        required: true
+        example: "${ctx.git.sha}"
+      headers:
+        type: map
+        description: "Extra request headers, such as `x-vercel-protection-bypass: { secret: env://VERCEL_AUTOMATION_BYPASS_SECRET }` for a protected preview (IN9)."
+    http:
+      trigger: { url: { param: url }, path: { param: path }, revision: { param: revision } }
+      request:
+        method: PUT
+        url: { join: [{ param: url }, { param: path }] }
+        headers: { param: headers }
+      outputs: { modified: /modified }
+    live:
+      # A deployed app with Inngest's serve handler and INNGEST_ENV set to a throwaway branch environment.
+      params: { url: SPONSON_LIVE_INNGEST_APP_URL }

package/recipes/kinde.yaml

@@ -0,0 +1,120 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Kinde Management API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: kinde
+title: Kinde
+category: auth
+verified_on: "2026-10-11"
+docs:
+  - title: Kinde Management API (OpenAPI specification)
+    url: https://api-spec.kinde.com/kinde-management-api-spec.yaml
+  - title: Access the Kinde Management API
+    url: https://docs.kinde.com/developer-tools/kinde-api/connect-to-kinde-api/
+  - title: Kinde Management API JS SDK (conventional variable names)
+    url: https://github.com/kinde-oss/management-api-js
+api:
+  base_url_env: KINDE_API_URL
+  auth:
+    oauth2_client_credentials:
+      token_url: /oauth2/token
+      token_url_env: KINDE_TOKEN_URL
+      client_id_env: KINDE_MANAGEMENT_CLIENT_ID
+      client_secret_env: KINDE_MANAGEMENT_CLIENT_SECRET
+      audience: /api
+base_url_example: https://acme.kinde.com/api/v1
+detect:
+  deps: ["@kinde-oss/"]
+  env: ["KINDE_*"]
+  starter:
+    - op: callback_url
+    - op: logout_url
+      preview_url: url
+  where:
+    base_url: "`https://<business>.kinde.com/api/v1`: Kinde → Settings → Details → Domain"
+    app_id: "Kinde → Settings → Applications → your application → Details → Client ID"
+    url: "the exact callback URL the SDK sends on a preview: its URL plus the callback path (a `{ from }` reference cannot carry a path)"
+assumptions:
+  - id: KI1
+    verified: true
+    text: "A machine-to-machine application authorized for the Management API gets a token from `POST https://<business>.kinde.com/oauth2/token` (form-encoded `grant_type=client_credentials`, `client_id`, `client_secret`, `audience=https://<business>.kinde.com/api`); API calls go to `https://<business>.kinde.com/api/v1/…`. The recipe writes the token URL and audience as paths, so a plan's `base_url: https://<business>.kinde.com/api/v1` names the business once."
+    source: https://docs.kinde.com/developer-tools/kinde-api/connect-to-kinde-api/
+  - id: KI2
+    verified: true
+    text: "`GET /api/v1/applications/{app_id}/auth_redirect_urls` (scope `read:applications_redirect_uris`) answers `{ redirect_urls: [...] }`; `PUT` on the same path (scope `update:applications_redirect_uris`) replaces all of an application's callback URLs with the body's `urls` array. (`POST` adds and `DELETE ?urls=` removes; the recipe replaces the list it read, under a lock, so that one apply is one idempotent write.)"
+    source: https://api-spec.kinde.com/kinde-management-api-spec.yaml
+  - id: KI3
+    verified: true
+    text: "`GET /api/v1/applications/{app_id}/auth_logout_urls` answers `{ logout_urls: [...] }` and `PUT` replaces them with the body's `urls` array, as for callback URLs."
+    source: https://api-spec.kinde.com/kinde-management-api-spec.yaml
+  - id: KI4
+    verified: true
+    text: "The audience is always the business's kinde.com subdomain (`https://<business>.kinde.com/api`), even when a custom domain serves sign-in, so `base_url` names the kinde.com subdomain."
+    source: https://docs.kinde.com/developer-tools/kinde-api/connect-to-kinde-api/
+  - id: KI5
+    verified: true
+    text: "`KINDE_MANAGEMENT_CLIENT_ID` and `KINDE_MANAGEMENT_CLIENT_SECRET` are the variables Kinde's Management API SDK reads for the machine-to-machine client."
+    source: https://github.com/kinde-oss/management-api-js
+  - id: KI6
+    verified: false
+    text: "A `PUT` with an empty `urls` list is accepted and leaves the application with no URLs of that kind (destroying the last preview URL of an application that has no others)."
+  - id: KI7
+    verified: false
+    text: "URLs are read back exactly as written (no normalisation), and the replace has no precondition: the line locks the list (`lockOn`) against other Sponson runs; a console edit made between the read and the write can still be lost."
+ops:
+  callback_url:
+    kind: list_item
+    title: Application callback URL
+    summary: "One URL in a Kinde application's Allowed callback URLs, such as the preview's `/api/auth/kinde_callback`. Read-modify-write: the list is read (`redirect_urls`) and replaced (`urls`) with the URL added, under a lock on the list; removed on destroy; every other URL is left as it is."
+    covers: [kinde-callbacks]
+    params:
+      app_id:
+        type: string
+        required: true
+        description: The application's id (its Client ID in the Kinde dashboard).
+        example: 3b0b5c6c8fcc464fab397f4969b5f482
+      url:
+        type: string
+        required: true
+        pattern: "^https?://\\S+$"
+        description: "The callback URL, exactly as the SDK sends it (`KINDE_REDIRECT_URL` / `KINDE_SITE_URL` + the callback path)."
+        example: "https://${ctx.scope}.preview.example.app/api/auth/kinde_callback"
+    http:
+      parent:
+        path: "/applications/{app_id}/auth_redirect_urls"
+        method: PUT
+        write_list_path: /urls
+      list_path: /redirect_urls
+      item: { param: url }
+    sim:
+      objects:
+        "/applications/{app_id}/auth_redirect_urls": { redirect_urls: [https://app.example.com/api/auth/kinde_callback] }
+    live:
+      params: { app_id: SPONSON_LIVE_KINDE_APP_ID }
+  logout_url:
+    kind: list_item
+    title: Application allowed logout redirect URL
+    summary: "One URL in a Kinde application's Allowed logout redirect URLs, such as the preview's home page. Read (`logout_urls`) and replaced (`urls`) with the URL added, under a lock on the list; removed on destroy; every other URL is left as it is."
+    covers: [kinde-callbacks]
+    params:
+      app_id:
+        type: string
+        required: true
+        description: The application's id (its Client ID in the Kinde dashboard).
+        example: 3b0b5c6c8fcc464fab397f4969b5f482
+      url:
+        type: string
+        required: true
+        pattern: "^https?://\\S+$"
+        description: "The URL the SDK redirects to after logout (`KINDE_POST_LOGOUT_REDIRECT_URL`)."
+        example: "https://${ctx.scope}.preview.example.app"
+    http:
+      parent:
+        path: "/applications/{app_id}/auth_logout_urls"
+        method: PUT
+        write_list_path: /urls
+      list_path: /logout_urls
+      item: { param: url }
+    sim:
+      objects:
+        "/applications/{app_id}/auth_logout_urls": { logout_urls: [https://app.example.com] }
+    live:
+      params: { app_id: SPONSON_LIVE_KINDE_APP_ID }

package/recipes/mongodb_atlas.yaml

@@ -0,0 +1,119 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# MongoDB Atlas Administration API v2 recipes (programmatic API keys, HTTP Digest). Format and checklist:
+# docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: mongodb_atlas
+title: MongoDB Atlas
+category: databases
+verified_on: "2026-10-11"
+docs:
+  - title: Atlas Administration API v2 (OpenAPI document)
+    url: https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2.json
+  - title: Create One Database User in One Project
+    url: https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-creategroupdatabaseuser
+  - title: Configure Atlas API access (API keys use HTTP Digest)
+    url: https://www.mongodb.com/docs/atlas/configure-api-access/
+  - title: Atlas CLI environment variables
+    url: https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-env-variables/
+api:
+  base_url: https://cloud.mongodb.com/api/atlas/v2
+  base_url_env: MONGODB_ATLAS_API_URL
+  media_type: application/vnd.atlas.2023-01-01+json
+  auth: { digest: { user_env: MONGODB_ATLAS_PUBLIC_API_KEY, password_env: MONGODB_ATLAS_PRIVATE_API_KEY } }
+detect:
+  env: ["MONGODB_ATLAS_*"]
+  db_hosts: [.mongodb.net]
+  starter:
+    - op: database_user
+      values: { username: "app-${ctx.scope}", roles: [{ databaseName: "app_${ctx.scope}", roleName: readWrite }] }
+  where:
+    group_id: "Atlas → Project Settings → Project ID, or `atlas projects list`"
+    password: "a reference, never a value: `{ secret: \"env://PREVIEW_DB_PASSWORD\" }`"
+assumptions:
+  - id: MA1
+    verified: true
+    text: "Programmatic API keys authenticate with HTTP Digest (the public key as the user name, the private key as the password); service accounts take an OAuth2 client-credentials token instead (`https://cloud.mongodb.com/api/oauth/token`)."
+    source: https://www.mongodb.com/docs/atlas/configure-api-access/
+  - id: MA2
+    verified: true
+    text: "The Atlas CLI keeps the key pair in `MONGODB_ATLAS_PUBLIC_API_KEY` and `MONGODB_ATLAS_PRIVATE_API_KEY`."
+    source: https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-env-variables/
+  - id: MA3
+    verified: true
+    text: "Requests and answers use the versioned media type `application/vnd.atlas.2023-01-01+json` (in `Accept` and `Content-Type`); the database-user operations are published under that version."
+    source: https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2.json
+  - id: MA4
+    verified: true
+    text: "`POST /groups/{groupId}/databaseUsers` creates a user from `databaseName`, `groupId`, `roles` and `username` (required), with `password` for SCRAM users (write-only, never answered), optional `scopes` (absent: every cluster of the project) and `deleteAfterDate` (Atlas deletes the user then; within one week of the request). It answers 201 with the user."
+    source: https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2.json
+  - id: MA5
+    verified: true
+    text: "`GET`, `PATCH` and `DELETE /groups/{groupId}/databaseUsers/{databaseName}/{username}` read, update and delete one user; SCRAM users authenticate against `databaseName` `admin`."
+    source: https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2.json
+  - id: MA6
+    verified: true
+    text: "A project supports 100 database users by default (900 at most)."
+    source: https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-creategroupdatabaseuser
+  - id: MA7
+    verified: false
+    text: "A GET of a user that does not exist answers 404; a second create of the same user answers 409."
+  - id: MA8
+    verified: false
+    text: "`roles` (each `{ databaseName, roleName, collectionName? }`) and `scopes` (each `{ name, type }`) are answered in the order they were sent, so they compare without drift."
+  - id: MA9
+    verified: false
+    text: "`PATCH` takes the user's identifying fields (`databaseName`, `groupId`, `username`) with the changed ones and keeps the password when none is sent."
+ops:
+  database_user:
+    kind: resource
+    title: Database user
+    summary: "A SCRAM database user per scope on a shared Atlas cluster, such as `app-pr-42` with `readWrite` on the database `app_pr_42`, instead of a cluster per preview. The password is an input: a `{ secret: … }` reference (a value per environment in a secret manager) or a sensitive output of another line, sent on create only and never compared. Located by its user name; a console edit of its roles or scopes is drift; destroy deletes the user (not the database's data)."
+    covers: [mongodb-atlas-user]
+    params:
+      group_id:
+        type: string
+        required: true
+        pattern: "^[0-9a-f]{24}$"
+        description: The project (group) id, 24 hexadecimal digits.
+        example: 32b6e34b3d91647abb20e7b8
+      username:
+        type: string
+        required: true
+        description: The user name, unique in the project; its identity.
+        example: "app-${ctx.scope}"
+      password:
+        type: string
+        required: true
+        description: "The user's password, as a reference (`{ secret: env://… }`, or `{ from: <line>.<output> }` of a sensitive output); sent on create only (MA4)."
+        example: { secret: "env://PREVIEW_DB_PASSWORD" }
+      roles:
+        type: list
+        required: true
+        description: "The roles, each `{ databaseName, roleName }` (`readWrite`, `read`, `dbAdmin`, …)."
+        example: [{ databaseName: "app_${ctx.scope}", roleName: readWrite }]
+      scopes:
+        type: list
+        description: "The clusters it may reach, each `{ name, type: CLUSTER }`; absent: every cluster of the project (not compared then)."
+      delete_after:
+        type: string
+        description: "An ISO 8601 time, within a week, at which Atlas deletes the user by itself (sent on create only)."
+    http:
+      read: { path: "/groups/{group_id}/databaseUsers/admin/{username}" }
+      create:
+        path: "/groups/{group_id}/databaseUsers"
+        body:
+          databaseName: admin
+          groupId: { param: group_id }
+          username: { param: username }
+          password: { param: password }
+          deleteAfterDate: { param: delete_after }
+      update:
+        method: PATCH
+        body: { databaseName: admin, groupId: { param: group_id }, username: { param: username } }
+      id_path: /username
+      fields:
+        roles: { param: roles }
+        scopes: { param: scopes }
+    sim:
+      id_from: username
+    live:
+      params: { group_id: SPONSON_LIVE_ATLAS_GROUP_ID }

package/recipes/okta.yaml

@@ -0,0 +1,177 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Okta Management API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: okta
+title: Okta
+category: auth
+verified_on: "2026-10-11"
+docs:
+  - title: Okta Management API (OpenAPI specification, management-minimal.yaml)
+    url: https://raw.githubusercontent.com/okta/okta-management-openapi-spec/master/dist/current/management-minimal.yaml
+  - title: Applications API, replace an application
+    url: https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Application/#tag/Application/operation/replaceApplication
+  - title: Trusted Origins API
+    url: https://developer.okta.com/docs/api/openapi/okta-management/management/tag/TrustedOrigin/
+  - title: Okta Terraform provider, configuration (conventional variable names)
+    url: https://raw.githubusercontent.com/okta/terraform-provider-okta/master/docs/index.md
+api:
+  base_url_env: OKTA_API_URL
+  auth: { header: Authorization, value_env: OKTA_API_TOKEN, prefix: "SSWS " }
+base_url_example: https://acme.okta.com/api/v1
+detect:
+  deps: ["@okta/"]
+  env: ["OKTA_*"]
+  starter:
+    - op: redirect_uri
+    - op: trusted_origin
+      preview_url: origin
+      values: { name: "sponson-${ctx.scope}" }
+  where:
+    base_url: "`https://<org>.okta.com/api/v1`: your Okta org's domain"
+    app_id: "Okta Admin Console → Applications → your application: the `0oa…` id in its URL"
+    url: "the exact redirect URI the app sends on a preview: its URL plus the callback path (a `{ from }` reference cannot carry a path)"
+assumptions:
+  - id: OK1
+    verified: true
+    text: "An API token is sent as `Authorization: SSWS <token>` (the `apiToken` security scheme; Okta recommends scoped OAuth tokens, which need `private_key_jwt` and are not supported here). Every path is under `https://<org>.okta.com/api/v1`."
+    source: https://raw.githubusercontent.com/okta/okta-management-openapi-spec/master/dist/current/management-minimal.yaml
+  - id: OK2
+    verified: true
+    text: "`PUT /api/v1/apps/{appId}` replaces an application: all required properties must be in the body (no partial update), and system-assigned properties (`id`, `name`, `status`, `created`, `lastUpdated`) in the body are ignored. So the recipe sends the whole application read with `GET /api/v1/apps/{appId}` back, with one URI added or removed (`parent.send: parent`)."
+    source: https://raw.githubusercontent.com/okta/okta-management-openapi-spec/master/dist/current/management-minimal.yaml
+  - id: OK3
+    verified: true
+    text: "An OIDC application keeps its redirect URIs in `settings.oauthClient.redirect_uris` and its sign-out redirect URIs in `settings.oauthClient.post_logout_redirect_uris`, both arrays of strings."
+    source: https://raw.githubusercontent.com/okta/okta-management-openapi-spec/master/dist/current/management-minimal.yaml
+  - id: OK4
+    verified: false
+    text: "The read-only members of the GET answer that the replace documentation does not list (`_links`, `_embedded`, `credentials.oauthClient.client_id`) are ignored when sent back, as the listed system-assigned ones are."
+  - id: OK5
+    verified: false
+    text: "The application replace has no precondition: the line locks the application (`lockOn`, shared by both URI ops) against other Sponson runs; a console edit made between the read and the write can still be lost (the next apply reports it as drift)."
+  - id: OK6
+    verified: true
+    text: "`POST /api/v1/trustedOrigins` creates a trusted origin from `name`, `origin` and `scopes` (`[{ type: CORS }, { type: REDIRECT }]`, or `IFRAME_EMBED`); `GET /api/v1/trustedOrigins` lists them as a bare array, `q` prefix-matching `name` and `origin`, `limit` up to 200; `PUT /api/v1/trustedOrigins/{id}` replaces one; `DELETE /api/v1/trustedOrigins/{id}` answers 204. `name` and `origin` are each unique."
+    source: https://raw.githubusercontent.com/okta/okta-management-openapi-spec/master/dist/current/management-minimal.yaml
+  - id: OK7
+    verified: false
+    text: "A trusted origin is found among the first 200 that `q=<origin>` matches (pagination follows a `Link` header, which the http adapter does not read); an org with more than 200 origins starting with the same text may not find it and would see the create refused as a duplicate."
+  - id: OK8
+    verified: false
+    text: "Scopes are read back as written (`[{ type: CORS }, { type: REDIRECT }]`, no added members), so they can be compared as drift."
+  - id: OK9
+    verified: true
+    text: "`OKTA_API_TOKEN` is the variable the Okta Terraform provider reads for an API token."
+    source: https://raw.githubusercontent.com/okta/terraform-provider-okta/master/docs/index.md
+ops:
+  redirect_uri:
+    kind: list_item
+    title: OIDC application sign-in redirect URI
+    summary: "One URI in an Okta OIDC application's sign-in redirect URIs (`settings.oauthClient.redirect_uris`), such as the preview's `/login/callback`. The application is read, and written back whole with the URI added (Okta replaces applications only as a whole), under a lock on the application; removed on destroy; every other URI and setting is sent back as read."
+    covers: [okta-redirect]
+    params:
+      app_id:
+        type: string
+        required: true
+        description: The application's id (`0oa…`).
+        example: 0oa1gjh63g214q0Hq0g4
+      url:
+        type: string
+        required: true
+        pattern: "^\\S+://\\S+$"
+        description: "The redirect URI, exactly as the application sends it as `redirect_uri`."
+        example: "https://${ctx.scope}.preview.example.app/login/callback"
+    http:
+      parent: { path: "/apps/{app_id}", method: PUT, send: parent }
+      list_path: /settings/oauthClient/redirect_uris
+      item: { param: url }
+    sim:
+      objects:
+        "/apps/{app_id}":
+          id: 0oa1gjh63g214q0Hq0g4
+          name: oidc_client
+          label: Web app
+          status: ACTIVE
+          signOnMode: OPENID_CONNECT
+          credentials: { oauthClient: { client_id: 0oa1gjh63g214q0Hq0g4, token_endpoint_auth_method: client_secret_basic } }
+          settings:
+            oauthClient:
+              application_type: web
+              grant_types: [authorization_code]
+              response_types: [code]
+              redirect_uris: [https://app.example.com/login/callback]
+              post_logout_redirect_uris: [https://app.example.com]
+    live:
+      params: { app_id: SPONSON_LIVE_OKTA_APP_ID }
+  post_logout_redirect_uri:
+    kind: list_item
+    title: OIDC application sign-out redirect URI
+    summary: "One URI in an Okta OIDC application's sign-out redirect URIs (`settings.oauthClient.post_logout_redirect_uris`), such as the preview's home page. Written back with the whole application, under the application's lock; removed on destroy; every other URI and setting is sent back as read."
+    covers: [okta-redirect]
+    params:
+      app_id:
+        type: string
+        required: true
+        description: The application's id (`0oa…`).
+        example: 0oa1gjh63g214q0Hq0g4
+      url:
+        type: string
+        required: true
+        pattern: "^\\S+://\\S+$"
+        description: "The URI the application passes as `post_logout_redirect_uri`."
+        example: "https://${ctx.scope}.preview.example.app"
+    http:
+      parent: { path: "/apps/{app_id}", method: PUT, send: parent }
+      list_path: /settings/oauthClient/post_logout_redirect_uris
+      item: { param: url }
+    sim:
+      objects:
+        "/apps/{app_id}":
+          id: 0oa1gjh63g214q0Hq0g4
+          name: oidc_client
+          label: Web app
+          status: ACTIVE
+          signOnMode: OPENID_CONNECT
+          credentials: { oauthClient: { client_id: 0oa1gjh63g214q0Hq0g4, token_endpoint_auth_method: client_secret_basic } }
+          settings:
+            oauthClient:
+              application_type: web
+              grant_types: [authorization_code]
+              response_types: [code]
+              redirect_uris: [https://app.example.com/login/callback]
+              post_logout_redirect_uris: [https://app.example.com]
+    live:
+      params: { app_id: SPONSON_LIVE_OKTA_APP_ID }
+  trusted_origin:
+    kind: resource
+    title: Trusted origin (CORS and redirect)
+    summary: "A trusted origin for the preview, so the Okta Sign-In Widget and Auth JS may call Okta from it (CORS) and Okta may redirect to it after sign-in or sign-out (REDIRECT). Found by its origin; its name and scopes are compared as drift and replaced with `PUT`; deleted on destroy."
+    covers: [okta-redirect]
+    params:
+      name:
+        type: string
+        required: true
+        description: "The trusted origin's name, unique in the org."
+        example: "sponson-${ctx.scope}"
+      origin:
+        type: string
+        required: true
+        pattern: "^\\S+://[^/\\s]+$"
+        description: "The origin, scheme and host without a path (`https://pr-42.preview.example.app`); unique in the org."
+        example: "https://${ctx.scope}.preview.example.app"
+      scopes:
+        type: list
+        default: [{ type: CORS }, { type: REDIRECT }]
+        description: "What the origin is trusted for: `[{ type: CORS }]`, `[{ type: REDIRECT }]`, both (the default), or `IFRAME_EMBED`."
+    http:
+      find:
+        path: "/trustedOrigins?q={origin}&limit=200"
+        list_path: ""
+        match: { origin: { param: origin } }
+      create: { path: /trustedOrigins }
+      update: { method: PUT, path: "/trustedOrigins/{id}" }
+      delete: { path: "/trustedOrigins/{id}" }
+      item_path: ""
+      fields:
+        name: { param: name }
+        origin: { param: origin }
+        scopes: { param: scopes }