OAuth 2.0
With OAuth 2.0 you do not paste a password into every request. You get an access token from a provider such as Google, Azure AD, Auth0 or Keycloak, and requests carry that token. ApiWorkbench runs the sign-in, stores the token, adds it to requests and refreshes it when it expires.
Before you start
Register an app (a "client") with your provider. Its console or documentation gives you the values this page asks for:
- the client ID, and usually a client secret
- the authorization URL and the token URL
- the scopes your API needs
- a place to register a callback URL (also called redirect URI)
Which grant to choose
The grant type is the way the token is obtained. Your provider's documentation says which ones it supports.
| Grant type | How it works | Use it for |
|---|---|---|
| Authorization Code (With PKCE) | You sign in in a browser. The app trades the returned code for a token, protected by a one-time secret. | Signing in as a user. The current best practice. |
| Authorization Code | The same, without the one-time secret. Needs a client secret. | Providers without PKCE |
| Client Credentials | The client ID and secret alone get a token. No user is involved. | Machine-to-machine APIs |
| Password Credentials | A username and password are sent to the token URL. | Only first-party apps that still need it |
| Implicit | The token comes straight back in the redirect. | Legacy providers only. Prefer PKCE. |
Set up OAuth 2.0
Open the Auth tab and set Auth type to OAuth 2.0.
To share one token across many requests, do this on the collection instead: … menu, Auth, scripts and docs, Auth tab. Then set the requests to Inherit from parent. See Authorization.
Under Configure new token, choose the Grant type.
Fill in the fields for that grant. The tables below list them.
Select Get new access token.
Fields for every grant
| Field | What to enter |
|---|---|
| Token name | A name to tell tokens apart in the saved tokens list, such as Staging admin |
| Grant type | One of the five grants above |
| Client ID | The public identifier of the app you registered |
| Scope | Space-separated permissions, such as openid profile email |
Extra fields by grant
| Field | Auth Code | With PKCE | Implicit | Password | Client Creds |
|---|---|---|---|---|---|
| Callback URL | Yes | Yes | Yes | ||
| Auth URL | Yes | Yes | Yes | ||
| Access token URL | Yes | Yes | Yes | Yes | |
| Client secret | Yes | Optional | Yes | Yes | |
| Code challenge method, Code verifier | Yes | ||||
| Username, Password | Yes | ||||
| State | Yes | Yes | Yes | ||
| Client authentication | Yes | Yes | Yes | Yes |
What the less obvious fields mean:
| Field | Meaning |
|---|---|
| Callback URL | Where the provider sends the browser after sign-in. It must be registered with the provider. Example: http://localhost:8080/callback |
| Auth URL | The provider's authorization endpoint, opened in the browser |
| Access token URL | The provider's token endpoint |
| Client secret | The app's secret. Leave it empty for public clients such as PKCE apps. The client ID is then sent in the body. |
| Code challenge method | SHA-256 or Plain. Use SHA-256 unless the provider only supports plain. |
| Code verifier | Optional. Leave it empty to get a new random verifier for each sign-in. |
| State | Sent with the sign-in and checked when the browser comes back. Leave it empty for a random one each time. |
| Client authentication | Send as Basic Auth header or Send client credentials in body: how the token request says which app is asking |
Every field accepts {{variables}}, so the same setup can point at different providers per environment.
Advanced fields
Select Advanced to show optional settings. Leave them empty unless your provider needs them.
| Field | Meaning |
|---|---|
| Refresh token URL | Where refresh tokens are traded. Empty uses the access token URL. |
| Audience | Sent as audience= with the sign-in and token requests. Auth0 and Okta may need it to issue an API token. |
| Resource | Sent as resource=: the API the token is for. Azure AD v1 and ADFS use it. |
Get a token with browser sign-in
This applies to Authorization Code, Authorization Code (With PKCE) and Implicit.
On a desktop
Select Get new access token. A dialog opens and names the grant.
Select Sign in with the browser.
Your default browser opens the provider's sign-in page. ApiWorkbench waits, listening on your own computer for the redirect.
Sign in and approve the request in the browser.
Return to ApiWorkbench. The dialog closes and a message reads New access token saved.
The token appears under Current token, with its type, when it expires, and whether it came with a refresh token.
The callback URL and the local listener
After sign-in, the provider redirects the browser to the callback URL. ApiWorkbench catches that redirect by listening on a port of 127.0.0.1, your own computer, for as long as the sign-in takes.
| Callback URL you set | What happens |
|---|---|
http://localhost:8080/callback or http://127.0.0.1:8080/callback | The app listens on that port. Register exactly this URL with the provider. |
| A localhost address without a port | The app listens on a random port. |
| The port is already in use | The app listens on another port and tells you. |
An address that is not on your computer, such as https://app.example.com/cb | The app uses a local address instead. The provider must allow it, or use the paste method below. |
The dialog shows the address it is waiting on. It gives up after 10 minutes without an answer.
When the redirect cannot be caught
Use this when the callback URL must be a real website, when the browser is on another device, and on phones, where the app cannot listen for the redirect.
In the Get new access token dialog, find Paste the redirected URL.
Select Open in browser, or Copy link and open the link in any browser.
Sign in. The browser ends up on the callback address, which may show an error page. That is fine.
Copy the full address from the browser's address bar. It contains
code=(or, for the implicit grant,access_token=after a#).Paste it into Redirected URL and select Use this URL.
ApiWorkbench checks the state value, trades the code for a token and saves it.
Get a token without a browser
This applies to Client Credentials and Password Credentials.
You do not have to do anything. When you send a request and there is no token, or the token has expired, ApiWorkbench asks the token URL for one first and then sends your request.
To fetch one by hand, select Get new access token and then Request token.
How the token is sent
| Field | Meaning |
|---|---|
| Add token to | Header sends Authorization: Bearer <token>. Query param adds access_token=<token> to the URL. |
| Header prefix | The word before the token in the header. The default is Bearer. Leave it empty to send the token alone. |
Refresh and reuse tokens
Automatic refresh
When the current token has expired and it came with a refresh token, ApiWorkbench trades the refresh token for a new access token as part of the next send. You do not see a prompt.
If the refresh fails:
- with Client Credentials or Password Credentials, a fresh token is fetched instead
- with a browser grant, the request stops and asks you to use Get new access token
A token that came without an expiry time is never treated as expired. When the server starts rejecting it, get a new one yourself.
The Current token panel
| Control | What it does |
|---|---|
| Eye icon | Shows or hides the token text |
| Copy icon | Copies the token |
| Get new access token | Runs the selected grant |
| Refresh | Trades the refresh token for a new access token now |
| Clear | Stops using this token. It stays in the saved tokens. |
| Saved tokens | Lists tokens fetched earlier for this auth. Pick one to use it again. |
| Manage | Shows every saved token, with Delete token on each and Delete expired for all that have run out |
Each saved token is listed with its name, when it was obtained, and valid or expired. The list keeps the 20 most recent tokens.
Where tokens are kept
A token is saved with the request, folder or collection whose Auth tab fetched it. Put OAuth 2.0 on a collection and every request that inherits from it shares one token and one refresh.
WARNING
Tokens are stored on your device as plain text in the app's data files. Treat exports that contain them like passwords.
Troubleshooting
"No OAuth 2.0 access token yet"
The request was sent before a token existed, with a grant that needs a browser. Open the Auth tab and select Get new access token.
The provider shows "redirect_uri mismatch"
The callback URL sent by the app is not registered with the provider. Register the exact address, including the port and path. If the app had to switch to another port, the dialog says so: free the port or register the new address.
The browser signs in but ApiWorkbench keeps waiting
The provider redirected somewhere the app is not listening. Copy the address from the browser and use Paste the redirected URL.
The token request fails
Check the Access token URL, the client ID and secret, and Client authentication. Some providers accept the credentials only in the header, others only in the body. The Console shows the token request and the provider's answer.