Pax8 Partner Authorization

This guide is intended for 3rd party applications that are looking to integrate with Pax8's public APIs on behalf of Pax8 partners. Pax8 partner's who have would like to use 3rd Party applications should review this page.

Delegated Authorization is the process of obtaining a Pax8 Partner's consent to call Pax8's Public APIs on their behalf. A Pax8 partner must provide consent before you may call the API on their behalf. This authorization is granted via OAuth2 Authorization Code Grant. The consent screen looks like this:

Initial Setup

1. Please send an email to [email protected] to discuss your use case, get sandbox credentials, vendor portal access, and API keys.
2. We will examine your use case and create an account in the Vendor Portal for you.

Getting Authorization from Pax8 Partners in Your Application

If you've used OAuth2 Delegated Authorization before, Pax8 adheres to the OAuth2 standard and you can likely re-use your existing knowledge. Keep in mind, however, we have a required audience parameter (described below) which is not in the OAuth2 specification. If you have not used OAuth2 before, we recommend you get a good basic understanding before using these steps.

Pax8 partners will be directed to your application to kick off the authorization and integration. You'll need to build a page in your application where they can learn more about your Pax8 integration and press a "Integrate with Pax8" button. This button should take the following actions:

1. Send an authorization request to https://login.pax8.com/authorize with the appropriate parameters:

• response_type - code
• clientId - <your clientId>
• scope - Manage:Pax8Data - see Supported Scopes for a full list
• state - See the Oauth2 Specification for full details
• redirect_uri - The redirect uri of your application. We'll ask you for this URL when you start your integration
• nonce - See the Oauth2 Specification for full details
• audience - https://api.pax8.com

https://login.pax8.com/authorize?
response_type=code&
client_id=<your clientId>&
scope=Manage:Pax8Data&
state=<your state>&
redirect_uri=<your redirect uri>&
nonce=<your nonce>&
audience=https://api.pax8.com

2. You'll receive a response to your callback url with a code parameter

https://<your-redirect-url>?code=<your code>

3. Exchange this code for an access token

• POST https://login.pax8.com/oauth/token

{
  "grant_type" : "authorization_code",
  "code" : "<code from prevous step>",
  "client_id" : "<your clientId>",
  "client_secret" : "<your clientSecret>",
  "redirect_uri" : "<your redirect url>"
}

• Response
  • id_token is optional. Only returned if you've requested the scope: openid
  • refresh_token is optional. Only returned if you've requested the scope: offline_access
    • Refresh tokens have an absolute lifetime of 31557600 seconds. Regardless of the interactions you take with the token, it will expire after this period.
    • Refresh tokens have an inactivity lifetime of 2592000 seconds. If the token has not been used for this period, it will expire. Each time you use the refresh token, the inactivity lifetime resets.

{
  "access_token": "<acces_token>",
  "id_token": "<id_token>",
  "refresh_token": "<refresh_token>",
  "scope": "<scopes>",
  "expires_in": 86400,
  "token_type": "Bearer"
}

4. Use the access token to call Pax8 APIs on a user's behalf. See the reference
   page for information on how to call the Pax8 API.

Testing Note

• Your Vendor Portal account is not suitable for testing the delegation flow described above. Only Pax8 Partner accounts will work.
• If you are currently logged into the Vendor Portal (https://integrations.pax8.com) you must test the login flow above in a new browser or incognito window. If you use the same browser session, you'll grant consent for your vendor account instead of a Partner Account and your calls to the Pax8 API will fail.

Supported Scopes

• Manage:Pax8Data: Access my Pax8 data (orders, subscriptions, contacts, products & invoices)
  • At this time we only support a single scope for Pax8 Data. Granular scopes are coming soon.
• email - The user's email address
• profile - Basic profile information
• openid - When requested, the response will contain an id_token containing the OpenId User identity
• offline_access - When requested, the response will contain a refresh_token which can be used to refresh the access_token after it expires.