Create and manage vault secrets using Guided Auth

Use Guided Auth to add vault secrets to your Postman Vault, enabling you to store authentication credentials for public APIs that set up Guided Auth. You can use vault secrets added using Guided Auth in your local instance of Postman. Then you can reference vault secrets added using Guided Auth in new HTTP requests to the same public APIs. Only you can access and use values associated with your encrypted vault secrets, and vault secrets aren't synced to the Postman cloud.

Guided Auth enables you to set up authentication credentials for public APIs by following steps set up by API publishers. Once you set up your authentication credentials using Guided Auth, you can store them in your Postman Vault and reuse them throughout your workspaces.

Learn how to explore public APIs on the Postman API Network. If you're an API publisher, learn how to set up Guided Auth for your public APIs in Postman.

You can also add vault secrets without using Guided Auth. Learn how to add vault secrets to your Postman Vault.

Add authorization as vault secrets using Guided Auth

After you save your vault key, you can add your authentication credentials for public APIs to your Postman Vault as vault secrets. To do this, public APIs you're sending a request to must have Guided Auth set up. Then you can use authentication credentials added using Guided Auth in your local instance of Postman.

If you're using Guided Auth from the Postman web app, you must use the Postman Desktop Agent.

Guided Auth supports public APIs that require bearer, basic, API key, or OAuth 2.0 authentication credentials. If an API supports token refresh, Postman automatically refreshes OAuth 2.0 tokens that were stored in your Postman Vault using Guided Auth.

Vault secrets are deleted from your Postman Vault after signing out of Postman. Existing references to vault secrets will be empty when you sign in to Postman. You can add your vault secrets to your Postman Vault using Guided Auth after you sign in to Postman.

To add authentication credentials as vault secrets using Guided Auth, do the following:

1. Open an HTTP request, and enter the URL for a public API that has Guided Auth set up, such as https://api.getpostman.com/.

   Learn how to explore public APIs on the Postman API Network.

2. Select the Authorization tab, then select the Auth Type dropdown list.

   If the public API has only one API authentication configured, you can select Set up new authorization when you enter the URL. This takes you directly to the instructions for getting your credentials.

   

3. Select the Authorization tab, select the Auth Type dropdown list, then select the authentication option you'd like to use under Recommended setup.

   

4. Generate and enter your authentication credentials:

   • For APIs that require authentication credentials like tokens or API keys, follow the instructions to get your credentials. Then enter them in the field under Auth credentials.
   • For APIs that support OAuth 2.0, select Authorize to get your credentials and automatically enter the access token in the field under Auth credentials.

5. Select Store Auth in Vault.

   

   If you haven't entered your vault key since signing in to Postman, you'll be asked to enter it.

6. Enter the Auth method name for the authentication credentials. By default, the auth method name is the public API's name, such as "Postman API", but you can use a different name if you'd like.

   The auth method name is used to categorize the associated vault secret in your Postman Vault. The auth method name is also used to generate the vault secret's key. For example, if you enter Postman API Key as the auth method name for an API key, the vault secret's key will be postman-api-key:value.

   If you use an auth method name that already exists in your Postman Vault, the existing auth method will be overwritten.

7. Select Store. In the Auth Type dropdown list of the request, the auth method name will be selected under Stored in vault.

   

To view your authentication credentials in your Postman Vault, select the created auth method name as the auth type, then select View in vault. You can also select Vault from the Postman footer. Learn more about opening your Postman Vault.

In your Postman Vault, vault secrets added using Guided Auth are stored under Created with guided auth, and they're categorized by the auth method name. Each vault secret's key name is automatically appended with a suffix, which you shouldn't edit:

• For APIs that require authentication credentials like tokens or API keys, the suffix represents the authentication type, such as :token.
• For APIs that support OAuth 2.0, multiple vault secrets are added to your Postman Vault, including the access token and additional properties returned by the public API (like the token type). Each vault secret has a suffix that represents the value, such as :accessToken and :tokenType.

The allowed domains for the vault secret are autofilled with the domains and subdomains for the public API. This is a comma-separated list of domains and subdomains you're allowed to send requests to with the vault secret. This enables you to prevent unintentional disclosure of sensitive data in your vault secret. Postman uses this information to suggest using saved authorization in future HTTP requests to the domain or subdomain.

If allowed domains or subdomains are specified for a vault secret, you can only reference it at the request level.

Use vault secrets added using Guided Auth

You can reference vault secrets that were added using Guided Auth from the Authorization tab of your HTTP requests. You can also use the Collection Runner to manually run collections that reference vault secrets added using Guided Auth. Scheduled collection runs, monitors, the Postman CLI, and Newman don't support vault secrets added using Guided Auth.

You can access vault secrets added using Guided Auth in scripts. Make sure you enable scripts to access your vault secrets. Otherwise, you'll receive an error in the Postman Console.

If you're using Guided Auth from the Postman web app, you must use the Postman Desktop Agent.

Select the Authorization tab of an HTTP request, and select the Auth Type dropdown list. Under Stored in vault, select the auth method name that has the stored authentication credentials you want to reference.

If the public API has only one API authentication configured, you can select Use Saved Authorization in the URL builder. This enables you to reference the vault secret with the authentication you generated using Guided Auth.

Vault secrets added using Guided Auth are inside double curly braces ({{ }}). The prefix vault: is appended to the vault secret's name, and a suffix is automatically appended with the authentication type. For example, a vault secret that stores an API key named "postman-api-key" uses the following syntax:

{{vault:postman-api-key:value}}

To learn how to troubleshoot empty or unresolved vault secrets, see Troubleshoot vault secrets.

From the variables pane, you can view vault secrets that are referenced in an HTTP request and available from a Postman element. Select Variables in the workbench to open the variables pane. Review the vault secrets referenced in a request under Variables used. Under All variables, you can view vault secrets that can be referenced and resolved in the Postman element that's open. For requests that reference a variable or vault secret, select All variables to display all vault secrets a request can access.

Vault secrets in your Postman Vault added using Guided Auth are masked by default when they're logged to the Postman Console. To edit whether vault secrets are masked in the Postman Console, select Settings, then turn the toggle on or off next to Mask vault secrets.

If you're using the Postman web app with Safari as your web browser, it deletes vault secrets from your local instance of Postman after seven days of inactivity. Use a different web browser if you want your vault secrets available for more than seven days without activity in the Postman web app. Learn about the browser requirements for the Postman web app.

Edit vault secrets added using Guided Auth

You can edit vault secrets stored in your Postman Vault that were added using Guided Auth. Update the auth method name, update allowed domains, make vault secrets unavailable, and delete vault secrets. You can also edit the value of vault secrets added using Guided Auth from requests that reference it or can access it.

Be careful when editing vault secrets added using Guided Auth. This might cause your authentication credentials stored as vault secrets to not work as expected. Learn how to troubleshoot vault secrets.

To edit vault secrets added using Guided Auth, open your Postman Vault. You can take the following actions:

• To filter the list of vault secrets by name, enter text in the Filter secrets box under Created with guided auth.

• To sort the list of vault secrets, select a column header. You can toggle between ascending and descending order.

• To edit an auth method name, hover over an auth method name, and select Edit.

• To update the key or value for the vault secret, select the relevant cell. Existing references to the vault secret will be empty, meaning they won't have a value. Learn how to add a value to an empty vault secret.

  Don't remove or change the suffix associated with each vault secret's key name.

• To delete a vault secret, hover over a secret and select Delete. This will remove the vault secret reference from requests that were using the auth method.

• To delete all vault secrets associated with an auth method name, hover over the auth method name and select Delete. This will remove the vault secret reference from requests that were using the auth method.

• To update the list of allowed domains, select the empty cell or list of domains.

• To make a vault secret unavailable without deleting it, clear the checkbox next to the secret. Any references to the secret will be unresolved. To make the secret available again, select the checkbox.

Changes are automatically saved to your Postman Vault.

You can also edit the value of a vault secret from the variables pane or the request builder. Select Variables in the workbench to open the variables pane. You can edit vault secrets referenced in an HTTP request under Variables used and vault secrets available from a Postman element under All variables. In the variables pane, delete the existing value next to a vault secret, then enter a new value. You can also hover over the reference to the vault secret in the request builder, delete the existing value, then enter a new value.