Skip to content

Authentication

Auth lives on each request and inherits from the parent collection by default — set it once on the folder, every request below uses it. Schemes whose signature depends on the final URL or body bytes (AWS SigV4, OAuth 1.0a, WSSE) are signed at the wire (Cloudflare Worker on web, Electron main process on desktop), so the signature matches the exact bytes the upstream receives. Header-shaped schemes (Bearer, Basic, API Key, OAuth 2.0) are applied before dispatch — in the main process when the secret is a desktop keychain handle.

The simplest case: Authorization: Bearer <token>. Reads variables: {{token}}.

Username + password, UTF-8 encoded and then base64-encoded (the same encoder in the app, desktop main process and CLI, so ü or emoji work). An empty username with a password is sent as :password (the common :token shape) in the app and the CLI; with neither, no header is sent. Stored as a SecretRef (handle, never plaintext in the renderer) on desktop.

Choose where the key lives — a header or a query parameter — and its name.

Four grants. PKCE (S256) is always sent on the authorization-code grant and is not sent on the other three. There is no PKCE toggle:

  • Authorization code — on the web, Get token opens the authorization URL in a popup and reads the redirect. The desktop app denies renderer popups, so the button is disabled with a notice there: use client credentials, password or device code, or paste a token. Desktop loopback support is a planned follow-up; the system-browser flow in the desktop app is MCP OAuth (ADR 0031).
  • Client credentials — service-to-service.
  • Resource owner password — when you must.
  • Device code — for CLIs and headless clients.

Get token saves the issued access token, plus refresh_token and the expiry from expires_in when the server returns them, in the request’s auth settings. When the token is expired or about to expire and a refresh token is present, an HTTP send refreshes it and saves the newly issued token back to the request.

Token requests — Get token, the device-code request and auto-refresh — go through the app’s own HTTP transport (the Worker’s /api/proxy on web and self-hosted, the HTTP IPC channel on desktop), not a direct browser fetch. So:

  • The SSRF guard applies to the token endpoint like any request you send: on the hosted web app an IdP on localhost or a private network is refused unless the server allows private upstreams (local dev, or ALLOW_PRIVATE_IPS on a self-hosted server).
  • Redirects from the token endpoint are not followed, so the client secret is never re-posted to wherever a redirect points.
  • IdPs that send no CORS headers work, and on desktop a http://localhost IdP is no longer blocked by the renderer’s content-security policy.

A client secret or password stored in the desktop keychain or an external secret store can’t be read by the renderer, so Get token refuses with a message saying so (enter the value directly or paste an access token), and auto-refresh is skipped — the expired token then gets the upstream’s 401.

HMAC-SHA1 (the default), HMAC-SHA256, or PLAINTEXT, per request — useful for legacy APIs (Twitter v1, Magento, Etsy, Tumblr). Nonce and timestamp generated per send.

For AWS APIs (S3, DynamoDB, EC2, etc.). Pick the region and service; Restura computes the canonical request and signs at the wire. Works for HTTP. SSE refuses AWS SigV4 (and OAuth 1.0a, WSSE, Digest, and NTLM) instead of connecting unsigned. gRPC isn’t signed yet, so a gRPC call using it is blocked (see gRPC authentication).

X-WSSE UsernameToken header with PasswordDigest (default — fresh nonce and timestamp per send) or PasswordText. Common for SOAP-y APIs. Signed at the wire for HTTP requests (not yet for gRPC).

HTTP Digest (RFC 7616) works on web, self-hosted, desktop, and the CLI. The first request goes out without credentials; when the server answers 401 with a WWW-Authenticate: Digest … challenge, Restura retries exactly once with an Authorization: Digest … header. Only a hash goes on the wire — never the password.

  • Algorithms: MD5, MD5-sess, SHA-256, SHA-256-sess (the strongest offered is picked), with qop=auth or the legacy no-qop form. auth-int and SHA-512-256 are not supported.
  • The retry replays the same method and body, and the digest uri is the exact request-target that was sent.
  • A 401 that isn’t a Digest challenge is returned as-is. If any redirect along the way left the original origin, even one that comes back, the challenge is never answered.
  • The retry counts against the same redirect limit as the first request; it doesn’t get a fresh one. Digest and redirects also work through a SOCKS proxy on desktop.
  • Over plain http:, an attacker on the network can strip a stronger challenge and force MD5, and can see the exchange anyway. Use https: for Digest-protected APIs.
  • Desktop keychain passwords are resolved in the main process at send time. Web can’t use keychain-stored passwords.
  • Digest applies to HTTP (and GraphQL over HTTP) requests. It isn’t used for SSE, WebSocket, gRPC, or GraphQL subscriptions.

desktop only Enter a username and password, plus an optional domain and workstation. DOMAIN\user in the username field also works when the domain field is empty. The desktop app performs the NTLMv2 handshake when sending: a negotiate message, the server’s 401 challenge, then the authenticate message. All three happen on the same connection.

  • The first request carries no credentials. Only an HMAC proof is sent after the challenge; the password never goes on the wire.
  • The handshake stays on one HTTP/1.1 connection. If the server closes it after the challenge, the request fails with an error instead of retrying on a new connection. A request set to HTTP/2 fails, because NTLM can’t run over HTTP/2.
  • Credentials go only to the origin you requested. A redirect to another origin drops Authorization, Cookie, Proxy-Authorization, credential-named headers and headers your auth added. Other headers keep following.
  • Works direct, through an HTTP/HTTPS proxy (always tunnelled with CONNECT) and through SOCKS. Keychain passwords are resolved in the main process at send time.
  • Over plain http: the NTLM exchange can be captured and cracked offline. Use https: for NTLM-protected APIs.
  • Web and self-hosted don’t send NTLM: the request goes out without an Authorization header and the editor warns about it. The CLI refuses NTLM requests. NTLM isn’t used for SSE, WebSocket, gRPC or GraphQL subscriptions.

mTLS (client certificates) desktop only

Section titled “mTLS (client certificates) ”

Upload a .pem / .p12 / .pfx with passphrase; the cert is presented during the TLS handshake.

Secret-bearing auth fields (tokens, passwords, client secrets, private keys) use a handle-based pattern: the encrypted value lives in the Electron main process keychain-protected store, and the renderer only sees a SecretRef handle. The plaintext is resolved at the wire, never touches the Zustand store, never lands in an exported collection, never appears in crash logs.

If a keychain secret can’t be resolved at send time (for example a collection opened on another machine), the desktop app fails the request with ”… is unavailable on this device” rather than sending it without Authorization or signing with an empty secret. A pre-request script also can’t add a secret variable’s value to a header that didn’t already reference it in the saved request — the send is refused.

Auth on a collection cascades to every child folder and request unless overridden. Use the Inherit auth from parent option (default) on new requests.

Imported Postman “No Auth” is the exception: Restura’s none means inherit, so an imported explicit noauth request below a configured ancestor, or any request below an unsupported-auth folder, is not sent and the Auth tab shows a “Not sent” banner. See Postman import.

The guard holds while the collection stays in Restura’s own store (and in Postman export), but OpenCollection and git-folder saves do not preserve it until #1232 adds an explicit no-auth to the model: they write none as omitted, which means inherit, so the request inherits the ancestor credential again after the round trip. Set the auth explicitly on those requests before saving to those formats.

  • Store API keys as environment variables rather than inline on the request — they survive auth-type changes and are easy to swap.
  • Use OAuth 2.0 client credentials for CI runs — paste the client ID / secret into the CLI and your collection runs without browser prompts.
  • For AWS endpoints, set AWS_REGION and the service name once on the collection and reuse across requests.