OAuth 2.0 Authentication Process

Security implementation is based on the final version of The OAuth 2.0 Authorization Framework. Every API request requires an access_token as part of the authentication header. This is a three-step process.

Before starting these steps, make sure API is available as part of your plan. If you don't have access to the Developer Dashboard, contact your Account Manager or Customer Support to get it enabled.

Steps

1. Setup an Application

• You need to have a valid and active PandaDoc account with a verified email address.
• Register your application at the Developer Dashboard. Please note, the application creation is only available with the production API access enabled, while you can test the public API with the Sandbox API key.

2. Authorize a User

• This is a one time browser-based request to associate a PandaDoc user with API requests.
• You can find client_id in the Developer Dashboard.
• Returns authorization code which is required to generate an access_token

Send the authenticating user to the PandaDoc OAuth2 request URL. We recommend a button or link titled "Connect to PandaDoc" if you are connecting users from a custom application. Users will see the "Authorize Application" screen. When the user clicks "Authorize", PandaDoc redirects the user back to your site with an authorization code inside the URL.

Authorization URL

https://app.pandadoc.com/oauth2/authorize?client_id={client_id}&redirect_uri={redirect_uri}&scope=read+write&response_type=code

Check your application settings here. client_id and redirect_uri values should match your application settings.

📘

Scope

If you're developing a server-side-only solution, you still need to perform the authentication process above to create an authorization code manually. Once associated with a user, access_token and refresh_token can be used by your application to automatically extend the validity of access tokens as needed. We suggest creating an API user in your PandaDoc workspace so that API methods create documents with this user.

3. Create an Access Token

• Authorization code is required to authorize a user. Returns access_token.
• Use this access token as a header in all API requests.

Learn more: Create an access_token.

4. Optionally, Refresh Access Token

• Eventually, access_token will expire, and accessing an API method will return 401 unauthorized. Your application needs to refresh the OAuth2 token with the stored refresh_token returned when initially creating an access token.
• Once refreshed, calls on behalf of the originally authorized user can resume immediately. Use the newly returned access_token for all future API requests.

📘

Access & Refresh Tokens

1. You are able to create as many pairs of access_token & refresh_token as you want. For each pair creation, you need a newly generated code.
2. Please use any GET request to verify the token validity.
3. To invalidate an access_token, just generate a new one and don't share or save it.

How to use OAuth 2.0 Authentication

If you’re using OAuth 2.0, use this header:

Authorization: Bearer {{oauth_key}}

Example:

Authorization: Bearer 3039ba033eb1410caa0a2227158d63c9d6502cd8