Using OAuth Client Credentials Grant will allow for all server-to-server communications, whereas the Authorization Grant will also allow for acting on behalf of a customer. In order to use OAuth, a basic understanding of the topic is assumed. Please read up on the subject if you have never used OAuth.

Creating an OAuth Client

To start using OAuth, go to the Business Dashboard, and create an OAuth Client under Integrations.


You'll use the Client ID and Client Secret from the Client you have created to initiate the OAuth handshake between Piggy and your integration. With the created Client you wil be able to perform server-to-server actions as well as manage actions for a Piggy Customer, but only if that the Customer has granted access to your integration. Please note that there is a distinction between a Customer and a Member. An end-user can be represented by either or both. To learn more, click here.

Server-to-Server (Client Credentials Grant)

If you only wish to perform server-to-server actions and do not want to perform actions on behalf of a piggy customer, you will not have to update the client with a redirect-url.

Requesting an Access Token

To request an access token, perform a call to when on the Production environment, with the following payload:

1 2 3 4 5 { "grant_type": "client_credentials", "client_id": "your-client-id", "client_secret": "your-client-secret" }

The returned access_token will be the token that you need to add to your subsequent requests.

Using OAuth 2.0 Access Tokens

OAuth 2.0 access tokens are provided as a bearer token in the Authorization http header.

The header format is:

Authorization: Bearer {{ access_token }}

Manage Token Expiration

Your application needs to manage access token expiration. Access tokens offered with Client Credentials Grant expire in certain time. Also, the authorization server does not support refresh requests. So your application needs to obtain a new access token before or after expiration. You can use one of the two methods below:

  1. Calculate expiration time: Use the expires_in field of token response. You can calculate expiration time by using the field which represents the lifetime of the access token and the time you have received it. Let your application calculate and manage the expiration time of access token so that it can make a token request before the token expires.
  2. Detect invalid_token error: Utilize invalid_token error responses. Piggy verifies each access token and will return an invalid_token error response (with status code 401) when the access token has expired. So, when your application detects the error, let it make a token request to obtain a new access token.