Authenticate with OAuth 2.0 authentication in Postman

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.

OAuth 2.0 overview

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:

• A client application makes a request for the user to authorize access to their data.
• If the user grants access, the application then requests an access token from the service provider, passing the access grant from the user and authentication details to identify the client.
• The service provider validates these details and returns a short-lived access token and a long-lived refresh token.
• The client uses the access token to request the user data with the service provider.
• When the access token expires, the client can use the refresh token to automatically request a new access token.

Scheduled runs, monitors, the Postman CLI, and Newman don't support OAuth 2.0 authentication grant types that require user interaction, such as authorization code, to manually generate an access token. These Postman features are automated on the Postman cloud, meaning it isn't possible to manually generate an access token and later refresh it. Check with your API provider whether user interaction is required to generate an access token for your grant type.

Using OAuth 2.0

To use OAuth 2.0, do the following:

1. In the Authorization tab for a collection or request, select OAuth 2.0 from the Auth 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.

2. 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.

3. 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.

4. Postman will prompt you to supply specific details depending on the OAuth 2.0 Grant Type, which can be an authorization code, PKCE, implicit, password credentials, or client credentials.

Specifying an authorization code

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.

Specifying an authorization code with PKCE

You can use Proof Key for Code Exchange (PKCE) 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.

Using implicit grant type

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.

Using password credentials

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.

Using client credentials

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.

Requesting an OAuth 2.0 token

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:

• Token Name - The name you want to use for the token.

• Grant type - A dropdown list of options. This will depend on the API service provider requirements.

• Callback URL - The client application callback URL to redirect to after auth. This must be registered with the API provider. If not provided, Postman will use a default empty URL and try to extract the code or access token from it. If this doesn't work for your API, you can use the following URL: https://oauth.pstmn.io/v1/browser-callback

  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. When using the Authorization Code or Implicit grant type, select this checkbox to set the Callback URL to return to Postman. If you opt to authorize using your browser, make sure pop-ups are deactivated for the callback URL, otherwise the option won't work.

• Auth URL - The endpoint for the API provider authorization server, to retrieve the auth code.

• Access Token URL - The provider's authentication server, to exchange an authorization code for an access token.

• Client ID - The ID for your client application registered with the API provider.

• Client Secret - The client secret given to you by the API provider.

• Scope - The scope of access you are requesting, which may include multiple space-separated values.

• State - An opaque value to prevent cross-site request forgery.

• Client Authentication - Send a Basic Auth request in the header, or client credentials in the request body. After upgrading to a new version, change the value here to avoid problems with client authentication.

To customize the token, select Advanced Options:

• Refresh Token URL - The endpoint for the refresh server, to exchange the refresh token for an access token. If empty, the refresh token URL will be the same as the access token URL.

• Auth Request, Token Request, and Refresh Request - Define any custom parameters you want to send with auth requests, token requests, or refresh requests. For each key-value pair you define, select an option to send the parameter in the request body, request URL, or request headers. Keep in mind the following considerations:

  • If you add multiple keys with same key name, they will be sent with the request as an array.
  • If you added resource or audience URIs in an earlier version of Postman, you can import them as custom parameters. Select the Audience and Resource tab to review the resources and audiences, then select Move Audience and Resource. For all grant types except implicit, the parameters are added to the token request. For implicit grant types, the parameters are added to the auth request.

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.

Refreshing an OAuth 2.0 token

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 supported for scheduled runs, monitors, the Postman CLI, or Newman.

Sharing an OAuth 2.0 access token

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:

1. Turn Share access token off.
2. Select Remove Synced Token.

After you revoke access, other users with access to the request won't be able to see or use the token.

Changing the OAuth 2.0 token type

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 has 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.