Auth Tab

The Auth tab configures authentication for your request. Authentication proves your identity to the API server and grants access to protected resources. Atrahasis supports the most common authentication methods used by modern APIs.

Authentication Types

Select an authentication type from the dropdown. The interface adapts to show the required configuration fields for each type.

TypeWhen to Use
No AuthPublic endpoints that require no authentication
Bearer TokenJWT tokens, OAuth access tokens, session tokens
Basic AuthUsername/password credentials (legacy APIs, internal tools)
API KeySimple key-based authentication in header or query
OAuth 2.0Modern authorization with token flow (Google, GitHub, etc.)

No Auth

Select "No Auth" for public endpoints that do not require authentication. No Authorization header is added to the request.

Common Use Cases

  • Public read-only APIs
  • Health check endpoints
  • Status pages
  • Public documentation endpoints

Bearer Token

Bearer authentication sends a token in the Authorization header. This is the most common authentication method for modern APIs.

Configuration

TokenThe bearer token value (JWT, access token, etc.)

How It Works

Atrahasis adds this header to your request:

Authorization: Bearer <your-token>

Best Practices

  • Store tokens in environment variables: {{authToken}}
  • Use different tokens for different environments (dev, staging, production)
  • JWT tokens expire—refresh them when you get 401 errors
Security: Never commit tokens to version control. Use environment variables.

Basic Auth

Basic authentication sends username and password encoded in Base64. While simple, it is less secure than token-based methods and should only be used over HTTPS.

Configuration

UsernameThe username or email
PasswordThe password (masked by default)

How It Works

Atrahasis encodes credentials and adds this header:

Authorization: Basic <base64(username:password)>

For example, user "admin" with password "secret" becomes:

Authorization: Basic YWRtaW46c2VjcmV0

When to Use

  • Legacy APIs that only support Basic auth
  • Internal tools and admin interfaces
  • Service-to-service communication in secure networks
  • Quick testing before implementing proper auth
Warning: Basic auth credentials are only Base64 encoded, not encrypted. Always use HTTPS to prevent credentials from being intercepted.

API Key

API Key authentication sends a key-value pair either in a header or as a query parameter. Common for third-party APIs and services.

Configuration

KeyThe header or parameter name (e.g., X-API-Key, api_key).
ValueYour API key.
Add toWhere to send the key. The dropdown offers two options: Header (the default) and Query Param.

Header vs Query

Add to Header:X-API-Key: your-api-key-here
Add to Query:https://api.example.com/data?api_key=your-api-key-here

Headers are preferred for security—query parameters may be logged in server access logs.

Common Key Names

  • X-API-Key — Standard custom header
  • api_key — Common query parameter
  • apikey — Alternative query format
  • Authorization — When API expects key in auth header

OAuth 2.0

OAuth 2.0 is the industry standard for authorization. It allows you to access APIs on behalf of a user without handling their credentials directly.

Supported Flows

FlowUse Case
Authorization CodeMost secure. Opens your browser for user consent, then exchanges the returned code for a token. Best for user-facing applications. PKCE is always enabled for this flow.
Client CredentialsMachine-to-machine authentication. No user interaction — Atrahasis calls the Token URL directly with the Client ID and Client Secret. Best for server-side applications.
PasswordDirect username/password exchange. When selected, the form shows extra Username and Password fields for the end-user credentials (separate from the Client Secret). Use only for trusted first-party applications.
ImplicitLegacy flow for browser-based apps. When selected, the Client Secret field is hidden because the flow runs in a public context, and the form displays a deprecation warning panel recommending Authorization Code with PKCE instead. Use only for legacy API compatibility.

Configuration Fields

FieldDescription
Grant TypeWhich OAuth 2.0 flow to use. Selecting a grant type shows only the fields that flow needs; switching the grant type hides irrelevant inputs automatically.
Client IDYour application's identifier, issued by the OAuth provider. Always shown, required for every flow.
Client SecretYour application's secret key. Shown for Authorization Code, Client Credentials, and Password grants. Hidden entirely for Implicit flow since it runs in a public context.
Auth URLWhere users are sent to grant access. Shown for Authorization Code and Implicit flows, hidden for the other two.
Token URLWhere the access token is obtained. Shown for every flow except Implicit (Implicit receives the token directly from the Auth URL).
ScopesPermissions your app requests (e.g., "read:user", "write:data"). Separate multiple scopes with spaces or commas.
AudienceOptional target identifier used by providers such as Auth0 and Okta. Leave empty if your provider does not require it.
Callback URLRead-only field shown for Authorization Code and Implicit flows. Atrahasis always listens on http://127.0.0.1:9876/callback. A Copy button is provided so you can paste the value into your provider's allowed redirect URIs. Port 9876 must not be used by another application while you authenticate.
Username / PasswordShown only when the Password grant type is selected. The credentials are kept in memory and are never persisted to saved requests or project files.
PKCE: Proof Key for Code Exchange is automatically enabled whenever you select the Authorization Code flow. It cannot be toggled off — there is no separate "Use PKCE" option in the form.

Token Management

Once you have obtained a token, Atrahasis manages it for you:

  • The access token and, when provided, the refresh token are stored with the tab.
  • On every request the token is automatically attached as an Authorization: Bearer <token> header (or the token type returned by the provider).
  • Before each request Atrahasis checks whether the token is about to expire. If a refresh token is available, it is used silently to obtain a new access token — no manual action needed.
  • If the token has already expired and cannot be refreshed, the request fails and you are prompted to re-authenticate.
Token Status Panel

While a token is present, a status panel appears at the bottom of the OAuth 2.0 form:

  • Status — Valid (fresh), Expiring soon (close to expiry), or Expired (past expiry).
  • Type — the token type returned by the provider, usually Bearer.
  • Expires — a relative countdown such as in 2h 15m, or Expired.
  • Scopes — the scopes the provider actually granted (may differ from what you requested).
  • Refresh Token — shows whether a refresh token was returned, so you know if silent renewal is possible.
Action Buttons
  • Authenticate — shown when there is no token yet. Runs the selected flow to obtain a fresh token.
  • Re-authenticate — replaces the "Authenticate" button once a token exists. Runs the flow again from scratch, discarding the current token state.
  • Clear Token — removes the stored token from the tab without running any flow. Useful when testing the "no token" state.
  • Cancel — appears while a flow is in progress (for example while waiting for the browser callback). Stops the callback listener and clears the loading state.

Authorization Code Flow Steps

  1. Click Authenticate (or Re-authenticate if a token already exists).
  2. Atrahasis starts a local callback listener on port 9876 and opens your default browser at the provider's Auth URL.
  3. Log in with your account and grant the requested scopes.
  4. The provider redirects the browser to http://127.0.0.1:9876/callback, where Atrahasis captures the authorization code.
  5. Atrahasis exchanges the code for an access token (and refresh token, if the provider returns one) using the configured Token URL.
  6. The Token Status panel updates, and the access token is attached to every subsequent request from this tab.

Project Security Schemes

When working with OpenAPI projects, the Auth dropdown also shows security schemes defined in the project's specification.

How It Works

  1. Import an OpenAPI specification that defines security schemes
  2. Project schemes appear under "Project Schemes" in the Auth dropdown
  3. Select a scheme to use its pre-configured settings
  4. Fill in the required credentials (token, username/password, etc.)

This ensures your requests use authentication exactly as defined in the API specification.

Security Alternatives

Some API endpoints support multiple authentication methods. When this is the case, Atrahasis shows a "Security" dropdown above the auth type selector.

Example

An endpoint might accept either:

  • OAuth 2.0 with "read:user" scope
  • API Key in header

Use the Security dropdown to choose which method to use for this specific endpoint.

Best Practices

Use Environment Variables

Store all credentials in environment variables, not directly in the request. This keeps secrets out of saved requests and allows different credentials per environment.

Let Atrahasis Handle OAuth Refreshes

Atrahasis automatically refreshes OAuth 2.0 access tokens before each request when a refresh token is available — you do not need to manually refresh. If you still receive a 401 Unauthorized error, the refresh has failed or there is no refresh token; in that case use the Re-authenticate button to start the flow again.

Minimize Scope

For OAuth 2.0, request only the scopes you need. This follows the principle of least privilege and improves security.

Test Without Auth First

When debugging, try setting auth to "No Auth" to confirm whether authentication is the issue or if the problem lies elsewhere.

HeadersProcessors