Code Flow

Code Flow

The OAuth2 code flow provides a secure way to request an access token on behalf of a Pushpay user. That is, where the application requesting the token does not get exposed to the user's login or password, and where the Pushpay user is given the opportunity to consent to giving the client access to their information.

The OAuth2 code flow uses HTTP redirects to complete the request for an access token. The process involves first redirecting to an "authorization" endpoint, which is appended with details of the client the token will be issued for, along with the scopes that are required and the URL to redirect back to when the authorization is complete.

Step 1 - Getting Consent

To initiate this flow, first you must direct the user's browser to go to the authorization server endpoint at:

https://auth.pushpay.com/pushpay/oauth/authorize

This URL must have a number of query parameters appended to it:

• client_id = client ID
• response_type = code
• redirect_uri = Absolute URL to redirect back to
• scope = space-separated list of scopes

Note:

• The Absolute URL to redirect to must be on the whitelist of allowable redirect URLs - the Pushpay platform does not allow for open redirects.
• In order to whitelist your redirect URL, please send an email to [email protected]
• Redirect URLs must be using HTTPS

Upon receiving the request, the authorization server will:

1. Redirect to the Pushpay website, where the Pushpay user can login.
2. Once the Pushpay user has authenticated, they will be redirected to the authorization server's consent page. The consent page will let the Pushpay user know the name of your application, along with what scopes (permissions) being requested. Additionally, the user will be asked to specify how long they are going to grant permission for - which may be from one day to one year, or even indefinitely (by select the "forever" option).
3. The user either allows or denies access to the client. Note that the user can uncheck any (or even all) of the scopes you have requested while still being able to click "Allow" on the consent page, therefore your application must be able to handle these scenarios.
4. The consent page redirects to the redirect_url included in the initial request to the authorization server. The redirect URL will have a code appended to it, like this example: http://my-payment-app.com/callback?code=b12d5abc34567bbca8cc9012f634b56f

Step 2 - Retrieving Access Token

Once your application has received a request to the redirect_url, you can then proceed to make a request to the authorization server to generate an access token, by:

1. 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).
2. Setting the content type of the request to be application/x-www-form-urlencoded
3. Supplying a form-encoded body with the parameters:

• grant_type = authorization_code
• code = code query parameter that was appended to the redirect_url
• redirect_uri = The redirect URL used in the original authorization endpoint request

4. 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":"652a15ee623b4f4cada11d4c4b3c2a6f"}
}

The access_token property contains the token you must use for all subsequent API requests.