Authorization

You can set authorization on a request, a folder or a collection. Postguy applies it when you send the request.

The generated header or query parameter shows in the request's header table. It is never saved into the collection file.

To edit auth, open the Authorization tab of a request or of a collection or folder. Every text field accepts {{variables}} (see Variables), except the OAuth 2.0 block (see OAuth 2.0).

Inheritance

Postguy picks the auth in this order:

1. The request's own auth.
2. Each folder, from the innermost to the outermost.
3. The collection.

The first level that is not Inherit wins. No Auth counts as a result: it stops the search and sends nothing. The Inherit view shows the kind it inherits.

Auth kinds

The kind is the tag stored in the collection file.

Algorithm and method values:

{{variable}} expansion on send covers Basic, Bearer, API Key, Digest, JWT, OAuth 1.0, AWS v4 and Hawk.

If the file names an auth kind this build does not know, Postguy keeps it as is. Resolving to it adds nothing to the request.

The selected kind is also exported and imported with Postman and OpenAPI documents. OpenAPI security schemes map to Basic, Bearer, API Key and OAuth 2.0.

Digest

• With a nonce filled in: Postguy answers directly from the stored challenge values.
• With an empty nonce: Postguy first sends the request without credentials. If the server replies 401 with a WWW-Authenticate header, Postguy computes the answer from that challenge and retries once. The console shows the warning Digest challenge accepted; request retried once.

Turn on disableRetryRequest to send only the first request and see the 401 yourself. An empty clientNonce generates a random one.

OAuth 2.0

Grants

Get a token

Fill in the fields, then press Get New Access Token.

Client credentials and password grants send one request to the token URL.

The two code grants work like this:

1. Postguy starts a listener on 127.0.0.1 with an ephemeral port and builds the redirect URI http://127.0.0.1:<port>/callback.
2. It opens the authorization URL in your system browser with response_type=code and the state. For PKCE it also sends code_challenge and code_challenge_method (S256, or Plain).
3. The listener waits up to five minutes for the redirect, checks state and takes the code. It reads at most an 8 KiB request line, then closes.
4. Postguy exchanges the code at the token URL (with the PKCE verifier for the PKCE grant).

The app shows progress and errors in its status text.

Authorize using browser is stored in the file as useBrowser. The app does not read it, so the code grants always use the browser.

Client authentication is Client secret in Basic header (default) or Client secret in body. The token request is a form POST with a 30 second timeout, a 4 MiB response cap and the global proxy and TLS settings.

Use the token

A send fails in two cases:

• No token: no access token; run the authorization flow first.
• The stored expiry has passed and no refresh was possible: the access token has expired; refresh it first.

Refresh and storage

• The Refresh button is enabled when a refresh token exists. expires in <n>s shows next to it when the server reported an expiry.
• Before a send, Postguy refreshes a token that is past its expiry, if there is a refresh token. The console warns OAuth 2.0 access token refreshed. The new refresh token and scope replace the old ones when the server returns them.
• Access and refresh tokens live in the workspace secrets file, not in the collection file, like secret variables. The UI masks them. Exports that strip secrets blank them. See Workspace and Import and export.
• The OAuth 2.0 block is not variable-expanded on send. Type literal values for URLs, client ID and secret.

Headless