Authentication

Every request made to the API to perform an action or retrieve data is secured - to be able to do anything in the API you must identify yourself - this is called "authentication".

Authenticating with the Pushpay API is currently via OAuth2 bearer token only.

Each request made to the API must include an Authorization: Bearer ####### header, where ####### would be replaced with the contents of the access token. The access token is a JWT (JSON Web Token) that has been returned from the Pushpay authorization server https://auth.pushpay.com. These tokens contain claims which then determine what API methods can be invoked using that token.

To be able to request an access token from the Pushpay Authorization server you must first be issued with a client_id and client_secret, which can be achieved by contacting the API Support Team and asking them to set up an account for you.

Authorization Server

An authorization server is a server that you can contact, provide some identifying information to, and in return be given a piece of information (token) which you can include in each request to identify who is making the request.

Tokens include not only the client making the request, but may include other details like the pushpayer the access represents, or the subset of permissions that this integration requires - this is an important part of how we reduce risk.

To get an access token that you can use for accessing the API, you must first make a request to the Pushpay OAuth2 Authorization server. The URL of the authorization server is https://auth.pushpay.com. Instructions on how to make such a request are given further below, based on the OAuth2 flows relevant in different situations.

The authorization server is able to issue tokens for multiple applications. Currently there are just two applications available:

pushpay (production)
pushpay-sandbox (development sandbox)

There are 2 endpoints per application:

Where app-name is either 'pushpay' or 'pushpay-sandbox' as required.

OAuth 2.0 Authorization

Please see the Code Flow page for details on how to obtain tokens and refresh those.

Refreshing Tokens

Any tokens issued by the authorization server have a specified lifetime, after which the token will expire and you must then request a new token.

There is no way to stop the token expiring, but you can "refresh" the token, exchanging it for a new token which then allows you continue making requests to the API. To do so you must make a "refresh token" request, using the refresh_token value returned from the original request for access.

To perform a token refresh, you will need to make a request by:

Setting a "basic auth" header, using the client_id and client_secret as the username/password (basic auth combines the id and password separated by a colon, base64 encoded).
Setting the content type of the request to be application/x-www-form-urlencoded
Supplying a form-encoded body with the parameters:

grant_type = refresh_token
refresh_token = The refresh_token value from your original access token request

Making a POST request to https://auth.pushpay.com/pushpay/oauth/token

Upon success, you should receive a 200 OK response, with a JSON body as follows:

{
    "access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1N....",
    "token_type":"Bearer",
    "expires_in":3600,
    "refresh_token":"00e24c610e284598abadbee440407df9"
}

Authorization

Every request made to the API to perform an action or retrieve data is secured - to be able to do anything in the API you must be allowed access to that resource - this is called "authorization".

Permission & Scopes

In the Pushpay platform, access to the API is restricted in multiple ways:

Client ID
Scopes
Person Permissions
Addition Claims Each of these are described below.

Client ID

The API is accessed using an OAuth2 token. This token carries information about the token itself (how long it's valid for, etc.) and also includes in it information about the scopes the bearer of this token has, and the ID of the client itself.

In some circumstances, this client ID will be used to restrict what you can see - for example, when creating anticipated payments against a merchant and then when fetching the list of anticipated payments associated with the merchant, the client will only see those anticipated payments that it has created in the past.

Scopes

Scopes are permissions granted to the client represented in the bearer token. Most API methods will have one or more scopes that the token being used in the API request must have before they can make the request. If the token does not have those scopes, you will receive a 401 Unauthorized response.

When your API client is registered in the developer portal, it will be configured with one or more scopes that it can request.

When the client attempts to connect without already having an access token, it will use the authorization server to generate one, at which point it will specify which of the scopes it requires (it can be all or a subset of these scopes that are configured for the client). These scopes will be added to the generated access token which can then be used to make requests.

If using an OAuth2 flow which requires user consent (such as code flow), then the user will be shown what scopes (permissions) your application is requesting and be given the opportunity to allow or deny access.

The scopes themselves are part of the access token. This can mean that when the token is refreshed, if your client no longer has access to that scope, it will lose it. This also means you will need to request a new access token with the additional scopes where the Pushpay team has granted you additional scopes for your client.

Person Permissions

When using the following OAuth2 flows:

Resource Owner Password Flow
Code Flow

the bearer token will contain a subject "sub" claim, which identfies the Pushpay user that this token is on behalf of.

Some features in the Pushpay platform are restricted to Pushpay users only and, in some cases, also rely on those users having been granted roles (permissions) in the Pushpay platform.

In these cases, the API calls will be documented stating that they require the access token contain a "sub" claim.

Additional Claims

Accessing the API makes use of bearer token set in the "Authorize" header of each request. This token is actually JSON itself, encoded using the JWT (Json Web Token) standard.

The token includes a number of "claims", which are key/value pairs.

In addition to the standard set of claims in the specific, and "scope" (which is used to specify which scopes the token represents), there are also additional claims that some API methods will require.

Currently, there are two additional claims that may be included in an access token generated by the authorization server. These are:

Merchant: identifies a merchant that the bearer of the token will have permission to make changes to Organization: identifies an organization that the token bearer has permission to make changes to If a scope name is prefixed with the name of either of these additional claims, then that scope will require the claim in order to properly authorize the token it is applied to.

These additional claims are under the control of Pushpay and are set for certain types of integration - for example, where a third party developer requires access to a specific merchant's private data, and the merchant has agreed to allow this to take place (or are themselves the third party developer).

Additional Resources

Please see this article for more information about OAuth security.