OAuth 2.0 tokens in .http files (VS Code, Cursor, CI)

Most APIs want an OAuth 2.0 access token: you sign in, get a token from the token endpoint, put it in Authorization: Bearer …, and do it all again when it expires an hour later. Since 0.10, Plainwire does this for you. Describe the provider once in http-client.env.json, write {{$auth.token("my-api")}} where the token goes, and the token is fetched before the request, cached, and refreshed when it expires. It uses the JetBrains HTTP Client's format, so the same files work in IntelliJ IDEA and WebStorm.

Plainwire's request editor with the Auth tab set to OAuth 2: a Configuration dropdown showing orders-api, an option to send the ID token, an Acquire token now button, and the saved header Authorization: Bearer {{$auth.token("orders-api")}}.
The request editor’s Auth tab: pick a configuration from the current environment, or acquire a token now.

Quick start: Client Credentials

Machine-to-machine APIs use the Client Credentials grant: a client ID and secret, no browser. In http-client.env.json:

{
  "dev": {
    "baseUrl": "https://api.example.com",
    "Security": {
      "Auth": {
        "my-api": {
          "Type": "OAuth2",
          "Grant Type": "Client Credentials",
          "Token URL": "https://login.example.com/oauth/token",
          "Client ID": "my-client-id",
          "Scope": "orders:read"
        }
      }
    }
  }
}

Put the secret in http-client.private.env.json (add it to .gitignore). Plainwire merges the two files key by key, so the private file only needs the part that is secret:

{
  "dev": { "Security": { "Auth": { "my-api": { "Client Secret": "s3cr3t" } } } }
}

Then use the token in any request:

### My orders
# @assert status == 200
GET {{baseUrl}}/orders
Authorization: Bearer {{$auth.token("my-api")}}

Select the dev environment in the status bar and press Send. The first request fetches a token; later requests reuse it until it expires.

Try it against a real server

Duende's public IdentityServer demo has a test client. With the two files below, plainwire run --env demo gets a token and calls the demo's protected API:

http-client.env.json

{ "demo": { "Security": { "Auth": { "duende": {
  "Type": "OAuth2", "Grant Type": "Client Credentials",
  "Token URL": "https://demo.duendesoftware.com/connect/token",
  "Client ID": "m2m", "Scope": "api" } } } } }

http-client.private.env.json

{ "demo": { "Security": { "Auth": { "duende": { "Client Secret": "secret" } } } } }

api.http

### Demo API with a client-credentials token
# @assert status == 200
GET https://demo.duendesoftware.com/api/test
Authorization: Bearer {{$auth.token("duende")}}
$ plainwire run --env demo
plainwire 0.10.0 · 1 request in 1 file · environment demo from http-client.env.json, http-client.private.env.json

api.http
  ✓ GET Demo API with a client-credentials token 200 · 456 ms · 1/1 checks

1 passed, 0 failed (1 requests, 1049 ms)

That is a real run (20 November 2026). Without the private file the secret is missing, and the run stops with the provider’s answer instead of sending the request unauthenticated:

  ✗ GET Demo API with a client-credentials token
      Auth "duende": token request failed: invalid_client (HTTP 400)
      at api.http:3

Signing in with a browser: Authorization Code + PKCE

For APIs that act for a user, use the Authorization Code grant. Plainwire opens the provider's sign-in page in your browser and listens on a loopback address for the redirect (RFC 8252, the way desktop apps do it), then exchanges the code for tokens:

"my-app": {
  "Type": "OAuth2",
  "Grant Type": "Authorization Code",
  "Auth URL": "https://login.example.com/authorize",
  "Token URL": "https://login.example.com/oauth/token",
  "Redirect URL": "http://127.0.0.1:8765/callback",
  "Client ID": "my-public-client",
  "Scope": "openid profile offline_access",
  "PKCE": true
}

We tested this end to end against Duende's demo (client interactive.public.short, PKCE): sign-in in a real browser, the redirect back to Plainwire, a token the demo API accepted, and after the 75-second token expired, a refresh that the API accepted too.

All grant types and settings

Grant TypeNeedsUse it for
Client CredentialsToken URL, Client ID, Client SecretService-to-service APIs and CI.
PasswordToken URL, Client ID, Username, PasswordOlder APIs and test users (deprecated by OAuth 2.1, still common).
Authorization CodeAuth URL, Token URL, Client ID; PKCE recommendedSigning in as a user in the browser.
Device AuthorizationDevice Auth URL, Token URL, Client IDProviders that show a code to enter on another device; Plainwire shows the code, copies it, opens the page and polls.
ImplicitAuth URL, Client IDLegacy single-page-app clients (no refresh).
"Type": "Mock""Token" (and optional "ID Token")A fixed token for local development and tests.

Other keys: "Client Credentials" = "basic" (default, HTTP Basic), "in body" or "none" for public clients; "Custom Request Parameters" and "Custom Request Headers" such as {"audience": {"Value": "https://api", "Use": "In Token Request"}} (Use: Everywhere, In Auth Request, In Token Request); "Acquire Automatically": false to sign in only when you run Plainwire: Acquire OAuth 2 Token…; "Open Complete URI": true for device codes. Any value can use {{variables}}, for example "Password": "{{password}}" from the private file. The extension gives completions and checks for all of these keys while you edit http-client.env.json.

In the editor and in CI

Compared with other clients

REST Client has no OAuth 2 support; fetching a token by hand with a chained login request is the usual workaround (its most-reacted OAuth issue, #302, is open). The JetBrains HTTP Client defines this format, and Plainwire reads the same keys (all except Start Polling After Browser), so a team can mix IntelliJ and VS Code. Postman and Thunder Client have OAuth 2 in a GUI form; their settings live in the app or its cloud, while here they are a JSON file in your repository, with the secret in a git-ignored file next to it.

FAQ

Where are my tokens stored?

In memory only, for the VS Code window or the CLI run. Nothing is written to disk, history, or anywhere else, and Plainwire has no telemetry. Source: GitHub (MIT).

My provider only allows https redirect URLs.

Plainwire can only receive a sign-in on a loopback http address. Most providers allow http://localhost or http://127.0.0.1 for native and development clients; register one of those. Otherwise use the Device Authorization grant if the provider supports it.

Does it work in Cursor, Windsurf and VSCodium?

Yes, it is the same extension. Install the .vsix from the latest release; see installing in Cursor and VSCodium.