Set up Guided Auth for public APIs in Postman

You can onboard your API consumers quickly and efficiently by setting up Guided Auth for your public APIs in Postman. This feature enables you to communicate the steps users need to take to successfully make their first request to your API, such as registering for a developer account or creating an app on your dashboard. When a user creates a request to your API, Postman will automatically recognize it requires authentication and prompt them with your provided steps to set it up.

Once users set up their authentication credentials, they can use Guided Auth to securely store them in their Postman Vault as encrypted vault secrets. Postman Vault enables users to reuse stored credentials throughout their local instance of Postman. Also, vault secrets aren't synced to the Postman cloud. Learn more about using Guided Auth to store credentials as vault secrets.

API authentication setup

Guided Auth enables Postman to recognize requests to your API's base URL and prompt your API's consumers with steps to set up authentication. Your API's consumers can use Guided Auth to set up authentication to your API whether they've forked your public collection or created a request to your API from scratch.

To set up authentication for your public APIs, go to the guided authorization dashboard. Select Team > Team Settings in the Postman header, then select Guided Auth in the left sidebar.

Postman supports Bearer Token, Basic Auth, API Key, and OAuth 2.0 authorization.

It's recommended that you configure OAuth 2.0 authorization for your public APIs because it requires less setup for your API consumers.

If you need separate authentication for different endpoints on the same base URL, you can set up multiple authentication schemes for your APIs by completing the Set up guided authorization form for each endpoint. It's recommended that you describe when each authentication scheme should be used, enabling your consumers to select the right option.

Set up OAuth 2.0 authentication

The following example shows you how to configure Guided Auth for an API that uses OAuth 2.0:

1. Enter the base URL of your API. You'll need to verify it later to enable authorization.

   Optionally, you can use variables in your base URL to represent values, such as a subdomain, the API consumer will replace with their own values. For example, you can add a variable that represents the region, product, or organization they must substitute in the URL to make a successful call to your API: https://{{org-name}}.example.com.

2. Select OAuth 2.0 as the authorization type.

3. Select Authorization code as the grant type. You can learn more about specifying an authorization code.

   

4. Select Generate Callback URL. Copy the URL and add it to the allow list in your application's settings.

   

5. Enter the API name. Use this field to help consumers make the right choice if you decide to set up multiple authentication schemes.

6. Enter the access token URL. This URL is the endpoint for your authentication server and will be used to obtain an access token.

7. Enter the authorization URL. This is where users will be sent to authenticate with your API.

8. Enter the application client ID for the application you created for this integration.

9. Enter the application client secret for the application you created for this integration. Secrets are stored encrypted at rest and in transit, and are never visible to consumers.

10. (Optional) Enter a comma-separated list of authentication scopes to restrict what Postman users can access. For example, read:public_key, write:org.

11. Select to send client credentials as a Basic Auth header or in the request body.

12. (Optional) Select Advanced settings to customize the authorization type:

    • Enter the refresh token URL. This is the endpoint for the refresh server that exchanges the refresh token for an access token. If the refresh token URL is empty, the access token URL will be used.
    • Enter custom parameters to send with auth requests, token requests, or refresh requests. For each key-value pair you define in token requests or refresh requests, choose whether you'd like to send the parameter in the request body, request URL, or request headers. Key-value pairs you define in auth requests are sent in the request URL. If you add multiple keys with same key name, they will be sent with the request as an array.
    

13. Add any prerequisite steps users must take to successfully make a request to your API. This could include steps like registering for a developer account, creating an integration, or copying a token. This will be shown to users when they create a request to your API and will guide them through setting up authentication.

    

    You can use basic Markdown syntax for bold, italics, underline, bullet points, and links to structure your content.

14. Verify your domain to complete adding authorization.

15. Select Save to save your API authorization settings.

Select Try it out to preview your configuration. You can test and validate your configuration by making an API call to this endpoint.

Verify your domain

Verify your domain to prove that you're the owner, enabling Postman to trust your team and its connection to your public API. This way, you'll prevent others from impersonating your API, ensuring the safety of your consumers. Postman requires that you verify the domain for your API authentication configuration before you can share it with the Postman community.

After your domain is verified, Postman will recognize newly created requests to your API and prompt your API consumers to authenticate using the steps you've provided.

To verify your domain, do the following:

1. Select Generate TXT Record.

2. Select the copy icon to copy the TXT Record.

   

3. Add the copied value to your domain as a DNS TXT record.

   

4. Select Verify Domain in Postman to confirm.