Auth, environments and secrets
Authenticate requests, keep values in environments, and keep secrets in your system's credential store.
This page covers how Studio authenticates requests, and where tokens and other values are kept.
The short version: put credentials in an environment as secret variables, and refer to them as
{{name}}.
Environments
An environment in Studio is a named set of variables, such as baseUrl, token or
customerId. Use a variable as {{name}} in the base URL, parameters, headers, auth and body.
- Pick the active environment in the top bar. Manage them with
⌘E(Ctrl+E). - Switching environment switches every value at once, so staging and production are two environments, not two setups.
- A variable can be marked secret. The environment file then records that the variable exists and is secret, but not its value, so the file is safe to commit.
Two things share the word "environment". A Studio environment is your own set of variables and never leaves your computer. A Spec0 environment is a place your API is deployed, shown as a target in the address bar. You'll often use both at once: one says where the request goes, the other fills in the blanks.
Auth
The Auth section is always there, whether or not the spec declares securitySchemes. Besides
the schemes the spec defines, you can choose:
- Bearer token
- Basic (
user:password) - API key header, with a header name you choose
- OAuth 2.0 (below)
Headers takes any other rows.
Auth values aren't stored with the API. Put the value in an environment as a secret variable and
enter {{token}} in the Auth field. A value typed straight into the field works, but it's kept only
until Studio quits.
OAuth 2.0
Choose OAuth 2.0 and Studio gets the token for you. Two grants are supported:
| Grant | Use it for |
|---|---|
| Client credentials | Service-to-service APIs. |
| Authorization code with PKCE | Signing in as a user. Studio opens your browser and catches the redirect. |
If the spec declares its oauth2 flows, the token URL, authorize URL and scopes are filled in.
- The client secret is a reference. Enter
{{clientSecret}}and keep the secret itself in an environment. Each environment then has its own credentials and its own token. - Tokens refresh themselves shortly before they expire. They're cached per API and environment, and never written into the spec, the library or a collection.
- Errors say what's wrong: a rejected client id or secret, a scope the client isn't allowed, a token URL that can't be reached, or a URL that answered with an HTML sign-in page (usually the wrong URL).
Where secrets are kept
Secret values go into your operating system's credential store, where it already keeps passwords:
| System | Credential store |
|---|---|
| macOS | Keychain |
| Windows | Credential Manager |
| Linux | Secret Service (a keyring such as GNOME Keyring or KWallet) |
Studio can only read and write its own entries there, under the name io.spec0.studio.
Secret values are also kept out of everything Studio writes down: History, error messages, saved
unsent changes, collection files, run logs, the console, and exported reports all show {{name}}
instead. Copy as curl is the exception: it shows the real values, because you asked for a
command to paste.
If there's no credential store
If the credential store can't be reached, Studio keeps secret values in a local file that is not encrypted, and the Environments dialog says so. This mostly happens on Linux with no keyring running, or a locked one. Install or unlock a keyring and restart Studio: the values then move into the credential store. See Troubleshooting.
Windows limits how long a stored credential can be. A very long token can go over that limit; only that value then stays in the local file, and the Environments dialog says how many are affected.