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

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.

You can't set or access vault secrets in scripts.

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 aren't preserved in your Postman Vault after signing out of Postman. This means that references to the secret will be unresolved when you sign in to Postman. You can add your vault secrets back to your Postman Vault after you sign in.

You can't create an integration that links vault secrets created using Guided Auth with external vaults. Learn more about Postman Vault integrations.

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

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

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

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

   You can also select Set up new authorization when you enter a public API in the URL builder.
   
   

   

3. Under Guided setup, select the authentication option you'd like to use for the public API.

   

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 into the Auth credentials field.
   • For APIs that support OAuth 2.0, select Authorize to get your credentials and automatically enter the access token into the Auth credentials field.

5. Select Store Auth in Vault.

   

   If you haven't entered your vault key since signing in to Postman, Postman will ask you to enter it.

6. Enter the Auth method name for the authentication credentials.

   Postman remembers the domain name used to add authentication credentials as a vault secret. Postman uses this information to suggest using saved authorization in future HTTP requests to the domain. Enter an auth method name that helps you remember the domain name associated with the vault secret. The auth method name is also used to generate the vault secret's key.

   The auth method name must be unique. 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 auth in Vault. You can also select Vault from the Postman footer.

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.

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.

You can't set or access vault secrets in scripts.

If you're using the Postman web app to send requests with references to vault secrets added using Guided Auth, you must use the Postman Desktop Agent or the Postman Browser 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 authentication credentials you want to reference.

To reference vault secrets added using Guided Auth in your HTTP requests, you can also select Use Saved Authorization in the URL builder.

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 unresolved vault secrets, see Troubleshoot vault secrets.

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, delete vault secrets.

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, select Vault from the Postman footer. 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 the edit icon .

• To update the key or value for the vault secret, select the relevant cell.

  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 the delete icon .

• To delete all vault secrets associated with an auth method name, hover over the auth method name and select the delete icon .

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