API environments and authentication
5 minute read · API Client
Keep one request useful across environments without sending it to the wrong service. Name the environment clearly and check it before every consequential request.
- Reuse a base URL without sharing a secret
- Choose authorization at the right level
- Diagnose a wrong environment or rejected account
- Walk one request through two environments
- Variables window and authentication modes
- OAuth 2.0: every control
Reuse a base URL without sharing a secret
Add a cluster variable such as base_url and create local/staging environments as needed. Use {{base_url}}/api/articles in a saved request. Select the intended environment before sending and inspect the resolved destination. Local-only values remain distinct from values explicitly chosen for cloud sync; imports default variables to local-only.
Keep bearer tokens, cookies and private environment values local unless sharing them is intentional and supported by the selected visibility/access boundary. A public collection does not need the author's live credentials to explain its requests.
Choose authorization at the right level
A request can use no auth, bearer, basic or OAuth2 configuration and can inherit authorization from the cluster. Inspect inherited values when a request works in one cluster but fails after copying it. An Authorization header typed manually can conflict with a configured auth method; check the final request rather than assuming only one source exists.
OAuth operations contact the actual target service and use its own application/account rules. Cookie management likewise affects requests to the target. Vortex storing a configuration does not validate that an external provider has granted the requested access.
Diagnose a wrong environment or rejected account
For a 401/403, confirm the destination, chosen environment, auth inheritance and token validity without publishing the token. For a placeholder that does not resolve, inspect the variable name and scope. For unexpected data, check whether the request used local, staging or production before changing anything.
Setting a variable from a selected JSON response path is useful for a multi-step workflow, but the resulting value may be a secret. Review its persistence and sharing choice. Export only the collection content you intend to share and inspect the output. Continue with collection import/export.
Walk one request through two environments
Keep {{base_url}}/api/articles as the saved URL. In the local environment, set base_url to your local app; in staging, use the staging service. Switch environments and inspect the resolved URL before sending a read. A matching request name does not guarantee that the active environment is the same as yesterday.
Set a public default at collection level and override only what differs at request or environment level. Check inherited authentication after duplicating a request. For a login flow, inspect returned cookies or capture a chosen response field into an appropriate local variable; never export a live session along with a demonstration collection.
If an OAuth flow fails, check the target service's application settings and redirect/grant requirements. A Vortex account login is unrelated to authorization for your own API. See collection sharing before choosing which variables leave this device.
Related guides: your first request, safe collection sharing.
Variables window and authentication modes
Open the cluster's Variables window. No environment uses the base values; named environment pills select an environment. Use {{name}} in the URL, headers, body or supported authentication fields. Shared values sync to the cluster; personal values stay on this machine. Delete variable removes its definition, so requests still referencing it may become unresolved.
| Auth mode | Fields and behavior |
|---|---|
| Inherit | Uses the cluster's authorization. Available for a request, not as an endlessly inherited cluster configuration. |
| No Auth | Adds no configured authorization. Inspect manually entered headers separately. |
| Bearer Token | Sends the token with the Bearer authorization scheme. The token field can use a variable. |
| Basic Auth | Uses Username and Password for HTTP Basic authentication. Use HTTPS for remote services. |
| OAuth 2.0 | Obtains an access token from the configured service, then applies it to the request. It is separate from the provider account used by your coding agent. |
OAuth 2.0: every control
| Control | What it does / initial choice |
|---|---|
| Available tokens | Selects a stored token entry for this configuration. Inspect its name and expiry before using it. |
| Token name | Human-readable label for an acquired token. |
| Grant type | Client credentials by default; Password credentials is also offered. This form does not provide an authorization-code/PKCE browser flow. |
| Access token URL | The service endpoint receiving the token POST. Required; it must return JSON containing access_token. |
| Client ID / Client secret | Credentials issued by the target service for your API client. |
| Username / Password | Resource-owner credentials, shown for Password credentials. Only use this grant if the target service explicitly supports it. |
| Scope | Space-separated permissions expected by the service. A requested scope does not guarantee it is granted. |
| Client authentication | Sends client credentials in the request body by default, or as an HTTP Basic Auth header. Use the service's required method. |
| Add token to | Request headers by default, or Request URL. URL tokens can appear in logs and copied URLs. |
| Header prefix | Defaults to Bearer. Change it only when the service expects another prefix. |
| Auto-refresh expired token | On by default. Enables the supported refresh flow when expiry/refresh-token information is available. A token without a refresh token cannot be renewed by inventing one. |
| Share token with workspace | Off by default. Controls sharing of token credentials; review who can access the workspace before enabling it. |
| Advanced | Reveals refresh and additional token-request parameters. |
| Refresh token URL | Optional separate refresh endpoint; otherwise the access token URL is reused. |
| Token request parameters | Additional enabled key/value rows sent in the body, headers or query of the token request. |
| Refresh request parameters | Equivalent additional rows for refresh requests. |
| Get token | Contacts the configured token service and stores the returned access token. Non-2xx responses, invalid JSON or a missing access_token are errors. |
| Refresh now | Requests a replacement using the existing refresh token. Disabled when no refresh token is available. |
| Current access token / Expires | Shows the selected credential and computed expiry; “No expiry returned” means the service did not supply usable expiry information. |
Example: select OAuth 2.0 → Client credentials, enter your development token URL and client credentials, choose the service's client-authentication method, then get a token. Send one read-only API request and inspect its sent headers and response. A token successfully issued for one audience may still receive 401 from another API. See response inspection.