From 37b143021d492a602c8915f07f22da57211a9d04 Mon Sep 17 00:00:00 2001 From: Gregory Schier Date: Thu, 13 Aug 2026 21:35:59 -0700 Subject: [PATCH] Surface plugin auth strategies and OAuth 2.0 in the skill Authentication was only covered in references/requests.md, so an agent that never opened it had no reason to know the schema enumerates every installed strategy, including plugin-contributed ones. OAuth 2.0 was not mentioned in the always-loaded file at all. SKILL.md now shows how to list the strategies and dump one's shape, and calls out that the variant title is a display label rather than the authenticationType value ("NTLM Auth" is `windows`, "AWS Signature" is `awsv4`). Auth is in the frontmatter description too, so the skill triggers on requests to add auth to a request. requests.md gains a worked OAuth 2.0 payload, verified against the schema and round-tripped through the model. --- crates-cli/yaak-cli/skills/use-yaak/SKILL.md | 45 +++++++++++++++---- .../skills/use-yaak/references/requests.md | 44 ++++++++++++++++-- 2 files changed, 76 insertions(+), 13 deletions(-) diff --git a/crates-cli/yaak-cli/skills/use-yaak/SKILL.md b/crates-cli/yaak-cli/skills/use-yaak/SKILL.md index b26b7b54..2fa8b830 100644 --- a/crates-cli/yaak-cli/skills/use-yaak/SKILL.md +++ b/crates-cli/yaak-cli/skills/use-yaak/SKILL.md @@ -2,15 +2,16 @@ name: use-yaak description: > Build and run HTTP API requests with the Yaak CLI (`yaak`): create workspaces, - folders, environments and variables, author HTTP requests, send them - individually or a whole folder/workspace at once, chain one request's response - into the next, and import existing APIs from OpenAPI, Postman, Insomnia, or - cURL. Use this skill whenever the user mentions Yaak, a Yaak workspace, or the - `yaak` command, and also when they ask to try, hit, call, exercise, or smoke - test an HTTP or REST endpoint, to save or organize API requests for reuse, to - set up API requests for manual testing, to turn an OpenAPI or Postman - collection into runnable requests, or to run a saved request suite against - staging versus production. Prefer this over one-off `curl` commands whenever + folders, environments and variables, author HTTP requests, configure + authentication (OAuth 2.0, bearer tokens, API keys, basic, JWT, AWS SigV4), + send them individually or a whole folder/workspace at once, chain one + request's response into the next, and import existing APIs from OpenAPI, + Postman, Insomnia, or cURL. Use this skill whenever the user mentions Yaak, a + Yaak workspace, or the `yaak` command, and also when they ask to try, hit, + call, exercise, or smoke test an HTTP or REST endpoint, to save or organize + API requests for reuse, to set up API requests for manual testing, to add auth + to a saved request, to turn an OpenAPI or Postman collection into runnable + requests, or to run a saved request suite against staging versus production. Prefer this over one-off `curl` commands whenever the requests should be saved, reused, shared, or run as a set. allowed-tools: Bash(yaak:*), Bash(which:*), Bash(command:*), Bash(npm:*), Bash(npx:*) --- @@ -95,6 +96,32 @@ authentication variants: yaak request schema http --pretty ``` +That schema is also the authoritative list of **authentication strategies**, +including ones contributed by plugins. Each appears as a named variant under +`authentication`, with its own fields, required list, and enums, so there is +never a reason to guess auth config: + +```bash +# every installed strategy, with the value to use for authenticationType +yaak request schema http | jq -r '.properties.authentication.oneOf[] + | select(.title) | "\(.title): \(.description)"' + +# the full shape of one of them +yaak request schema http | jq '.properties.authentication.oneOf[] + | select(.title == "OAuth 2.0")' +``` + +The first prints lines like `OAuth 2.0: Authentication values for strategy +'oauth2'`. **The title is a display label, not the value** — `authenticationType` +takes the quoted strategy name, so NTLM Auth is `windows` and AWS Signature is +`awsv4`. + +The second prints the fields. OAuth 2.0 has fifteen of them plus an enum of valid +`grantType` values (`authorization_code`, `implicit`, `password`, +`client_credentials`), which is exactly the sort of thing that comes out wrong +when guessed. The command loads plugins, so it reflects what is actually +installed rather than a fixed list, and it returns in well under a second. + Rules that are easy to get wrong: - **Setting `bodyType` does not add a `Content-Type` header.** The app adds one diff --git a/crates-cli/yaak-cli/skills/use-yaak/references/requests.md b/crates-cli/yaak-cli/skills/use-yaak/references/requests.md index cc67223c..54d34426 100644 --- a/crates-cli/yaak-cli/skills/use-yaak/references/requests.md +++ b/crates-cli/yaak-cli/skills/use-yaak/references/requests.md @@ -130,10 +130,46 @@ strategy names are not always what you would guess — the built-ins are `basic` "authentication": {"location": "header", "key": "X-Api-Key", "value": "${[ api_key ]}"} ``` -The exact fields for each strategy, and which are required, are in the -`authentication` property of `yaak request schema http --pretty`, which -enumerates every installed strategy as a named variant. Read it rather than -guessing — `oauth2` has fifteen fields and `jwt` requires four. +OAuth 2.0 is the one to look up rather than attempt from memory. It has fifteen +fields, six of them required, and `grantType` is an enum: + +```json +"authenticationType": "oauth2", +"authentication": { + "grantType": "client_credentials", + "clientId": "${[ client_id ]}", + "clientSecret": "${[ client_secret ]}", + "accessTokenUrl": "https://auth.example.com/oauth/token", + "scope": "read:pets", + "credentials": "body", + "tokenName": "access_token", + "headerName": "Authorization", + "usePkce": false, + "useExternalBrowser": false +} +``` + +`grantType` accepts `authorization_code`, `implicit`, `password`, or +`client_credentials`, and which other fields matter depends on which you pick: +`authorization_code` also wants `authorizationUrl` and `redirectUri`, while +`client_credentials` does not. + +The exact fields for every strategy, and which are required, come from the +schema, which enumerates each installed strategy as a named variant under +`authentication`: + +```bash +# display name plus the value to use for authenticationType +yaak request schema http | jq -r '.properties.authentication.oneOf[] + | select(.title) | "\(.title): \(.description)"' + +# the full shape of one strategy +yaak request schema http | jq '.properties.authentication.oneOf[] + | select(.title == "OAuth 2.0")' +``` + +Because the list is built by loading plugins, it covers plugin-contributed +strategies too, not just the built-ins. Read it rather than guessing. Set `authenticationType` to `null` to send no auth and stop inheriting from the parent folder.