With OAuth 2.0, you first retrieve an access token for the API, then use that token to authenticate future requests. Access tokens are typically short-lived, but the authorization server can also provide a long-lived refresh token. A client application can use the refresh token to automatically refresh the access token.
Accessing data with OAuth 2.0 varies greatly between API service providers, but typically involves a few requests back and forth between client application, user, and API. An example OAuth 2.0 flow could run as follows:
To use OAuth 2.0, do the following:
In the Authorization tab for a collection or request, select OAuth 2.0 from the Type dropdown list. Specify if you want to pass the auth details in the request URL or headers.
By default Postman will append the access token to
Bearer
in the Authorization header for your request, but if your server implementation requires a different prefix, you can specify it in the Header Prefix field.
To request an access token, fill out the fields in the Configure New Token section, and select Get New Access Token. To use the token with your request or collection, select Proceed and then select Use token. The details you used to generate the token are saved with your request or collection. You can also share the token so that others with access to the collection can use the token.
Once you have a token value generated and added, it will appear in the request Headers.
Enter the details for your client application, and any auth details from the service provider. This allows you to replicate your application auth flow inside Postman to test authenticated requests.
You can share token credentials with your team. Turn on the Share token toggle and then select Sync Token. By default Postman won't sync your token in case you don't want to share it.
Postman will prompt you to supply specific details depending on the OAuth 2.0 Grant Type, which can be Authorization code, Implicit, Password credentials, or Client credentials.
Authorization code grant type requires the user to authenticate with the provider—an authorization code is then sent back to the client app, extracted, and exchanged with the provider for an access token to authenticate later requests.
To use authorization code grant type, enter a Callback URL for your client application (which needs to be registered with the API provider), together with various details provided by the API service including Auth URL, Access Token URL, Client ID, and Client Secret.
If you are using the Postman desktop app, you can enter your auth details in your web browser instead of in Postman by selecting Authorize using browser.
You can use PKCE (Proof Key for Code Exchange) with OAuth 2.0. When you select Authorization Code (With PKCE) two more fields will become available for Code Challenge Method and Code Verifier. You can opt to use SHA-256
or Plain
algorithms to generate the code challenge. The verifier is an optional 43-128 character string to connect the authorization request to the token request.
Authorization code (With PKCE) grant type coupled with Authorize using browser is recommended to prevent auth code interception attacks.
Implicit grant type returns an access token to the client without requiring the extra auth code step (and is therefore less secure).
To use implicit grant type with your requests in Postman, enter a Callback URL you have registered with the API provider, the provider Auth URL, and a Client ID for the app you have registered.
If you are using the Postman desktop app, you can enter your auth details in your web browser instead of in Postman by selecting Authorize using browser.
OAuth 2.0 Password grant type involves sending username and password directly from the client and is therefore not recommended if you're dealing with third-party data.
To use password grant type, enter your API provider's Access Token URL, together with the Username and Password. In some cases you will also need to provide a client ID and secret.
Client credentials grant type is typically not used to access user data but instead for data associated with the client application.
Enter the provider's Access Token URL, together with the Client ID and Client Secret for your registered application.
The full list of parameters to request a new access token is as follows, depending on your grant type.
Under Configure New Token, enter details about the token:
https://oauth.pstmn.io/v1/browser-callback
Select Advanced Options to customize the token:
When the configuration is complete, select Get New Access Token. The configuration information is saved along with the access token and will be used every time the token is refreshed.
When you use Authorization code or Implicit grant type, you will be prompted to supply your credentials to retrieve an access token to use in later requests. By default, Postman will display a pop-up window when you select Request Token. If you are using the Postman desktop app, you can instead choose to authenticate using your system's default web browser. Select Authorize using browser to set the Callback URL to return to Postman after you complete auth in the browser, so that your requests can use the token returned on successful authentication.
A token from the API includes its details, together with the expiration, and optionally a refresh token you can use to retrieve a new access token when your current one expires. Select Proceed and then select Use Token to use the returned token.
Any successfully retrieved tokens will be listed in the request Available Tokens dropdown list. Select one to send with your request. Select Manage Tokens in the dropdown list to view more details or delete your tokens.
If authentication fails or times out, Postman will display an error message. You can check the error details in the Postman Console, Retry to try authentication again, or edit your auth details before continuing.
Deleting a token in Postman doesn't revoke access. Only the server that issues the token can revoke it.
Before an OAuth 2.0 token generated in Postman expires, Postman automatically refreshes it in the background before you send a request that uses it. The refreshed access token is updated in any requests that it's used in. If you added any custom parameters when generating the token, those parameters will also be used for the refreshed token.
Auto-refreshing is the default behavior. To turn this feature off or on, select Auto-refresh access token. To manually refresh a token, select Refresh. The token's expiration time displays if the token expires within the next day.
Auto-refresh is available when a refresh token is present. If no refresh token is present, the Auto-refresh access token toggle and the manual Refresh option aren't available. To check if a refresh token is present, select Manage Tokens in the Token dropdown list. If a refresh token is not present, check with the authorization service. Postman can't refresh the access tokens without the refresh token.
You can use auto-refresh when manually sending the request. Auto-refresh isn't used for scheduled runs or monitors for the same collection.
To enable other Postman users to view and use an OAuth 2.0 access token, select Share access token.
To revoke other users' access to a synced token, do the following:
After you revoke access, other users with access to the request won't be able to see or use the token.
Postman supports using access tokens or ID tokens for OAuth 2.0 authorization. An access token enables an OAuth client to make calls to an API. An ID token contains information about the authenticated user. This information can be used by an OAuth client to customize their experience.
If an ID token is present, you can select the token type (Access token or ID token) in the Use Token Type dropdown list. If no ID token is present, this dropdown list isn't available. To check if an ID token is present, select Manage Tokens in the Token dropdown list.
Last modified: 2022/12/12
Additional resources
Videos
Blog posts
Case Studies