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

To set up API authentication for your public APIs, go to the API authorization dashboard. Select Set up API authorization in the left sidebar.

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

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

  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.

    Enter grant type
  4. Select Generate Callback URL. Copy the URL and add it to the allow list in your application’s settings.

    Generate callback URL
  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 if client credentials should be sent as a Basic Auth header or in the request body.

  12. (Optional) Select Advanced settings to add a refresh token URL or parameters to different types of requests. If the refresh token URL is empty, the access token URL will be used.

  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.

    Describe steps for users to take

    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.

Set up API authentication

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

You must verify your domain for your API authentication configuration to share it with the Postman community.

  1. Select Generate TXT Record.

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

    Verify domain for API authentication
  3. Add the copied value to your domain as a DNS TXT record.

    Adding a TXT record
  4. Select Verify Domain in Postman to confirm. After your domain is verified, Postman will recognize newly created requests to your API and prompt users to authenticate through the steps you've provided.

Last modified: 2024/04/10