Authentication

Ironcall supports four authentication schemes, configured per request (or inherited from a folder) in the Auth tab: Bearer token, Basic auth, API Key, and OAuth 2.0.

Bearer token

In the Auth tab, select Bearer and enter your token. Ironcall automatically adds the Authorization: Bearer <token> header to the request.

Use a variable to keep the token out of the request definition and reference it from your environment:

{{auth_token}}

Basic auth

Select Basic and enter a username and password. Ironcall Base64-encodes the credentials and injects the Authorization header automatically. The password field supports secret variables.

API Key

Select API Key. Enter a key name and value, then choose whether to send it as a header or a query parameter. Ironcall injects it into every request automatically.

Example: API key sent as a header:

Key Value
X-API-Key {{api_key}}

OAuth 2.0

Select OAuth 2.0 and pick a grant type:

  • Authorization Code (with PKCE), for user-facing APIs. Fill in the Authorization URL, Token URL, Client ID, Client Secret, and Scope. Click Get New Access Token: Ironcall opens your system browser to the provider's consent page and listens on a temporary loopback address to capture the redirect, then exchanges the code for a token.
  • Client Credentials, for machine-to-machine APIs. Fill in the Token URL, Client ID, Client Secret, and Scope. The token is fetched directly, with no browser step.

Once a token is obtained, Ironcall sends it as Authorization: <Header Prefix> <token> (the prefix defaults to Bearer). Expired tokens are refreshed automatically when the provider returned a refresh token. All config fields accept {{variables}}.

The token stays on your device

The obtained access and refresh tokens are stored locally on this device only. They never enter the synced document, so they are not shared with other members of a shared workspace, and they are not pushed to the cloud. Each device obtains its own token with Get New Access Token. The OAuth configuration itself (URLs, client id, client secret, scope) is encrypted end-to-end and synced like other request auth.

For Authorization Code, save the request before fetching a token (the token cache is keyed to the saved request).

Redirect URL

By default the loopback redirect uses an ephemeral port, so the URL is http://127.0.0.1:<port>/callback with a different port each time. This works with providers that accept a loopback host on any port (Google "Desktop app" clients, per RFC 8252).

Many providers (GitHub, Auth0, Azure AD) instead require an exact redirect URL, port included. For those, set the optional Redirect URL field to the exact loopback URL you registered with the provider, for example http://localhost:8080/callback. Ironcall binds that exact host and port and sends the URL unchanged. The field accepts only 127.0.0.1 or localhost http URLs (the app has to bind the address to catch the redirect). Leave it empty to use the automatic ephemeral port.

CLI

The Ironcall CLI supports Client Credentials only (it fetches the token at run time). Authorization Code requires the interactive browser flow and is not available in the CLI; run those requests from the desktop app.

Fallback: fetch a token in a script

For grant types Ironcall does not implement, you can still fetch a token in a pre-script and reference it with Bearer auth:

// Folder pre-script: obtain a token once and reuse it across requests
if (!ic.env.get("access_token")) {
  // Run a dedicated "login" request earlier in the collection that stores
  // the token via ic.env.set("access_token", ...), then read it here.
  throw new Error("access_token is not set; run the login request first");
}
ic.request.headers["Authorization"] = "Bearer " + ic.env.get("access_token");

A common pattern is a first request in the collection that calls your token endpoint and saves the result with ic.env.set("access_token", ic.response.json().access_token) in its post-script.

Environments & VariablesScripts