Authenticating with Piryx using OAuth 2.0

The Piryx API uses OAuth 2.0 for authorization and authentication of applications. OAuth allows users to give access to applications without handing out their user name, password or other sensitive information.

Note: when using the developer sandbox, authorization and authentication calls should be made to https://sandbox-api.piryx.com

Register your app

In order to use OAuth for authentication, you must register your application from your Piryx account. After you have filled out some basic information about the app, you will be given the client_id and client_secret used for authorization and authentication.

Web Application Flow

1. Redirect the user to the authorization end point. You must include your application's client_id as well as the URL (redirect_uri) you wish the user to be returned to after approving or denying access. A space separated list of permissions should be passed with the scope parameter. Currently, the only response type supported is code. You may also pass an optional state parameter that will be passed back to your callback URL after the user approves or denies access.

   https://api.piryx.com/oauth/authorize?
       response_type=code&
       client_id=...&
       redirect_uri=http://www.example.com/cb&
       scope=create_payment payment_details

   If there is a problem with the parameters passed, the user will be redirected back to your application using the redirect_uri sent with an additional error parameter. List of potential errors.

2. The user is taken to a page that lists the details of your app as well as the level of access being requested. The user is presented with the choice of allowing access to your application or denying access.

   If the user approves access, then the user will be redirected back to your callback URL with an additional code parameter. The authorization code will expire after a few minutes; you must exchange it for an access token within this time frame.

   https://www.example.com/cb?code=...

   If the user denies access, the user may be redirected back to your callback URL with the associated error code.

   https://www.example.com/cb?error=access_denied

3. You can exchange the authorization code for an access token by making a POST request to the access token end point. You must include your client_id, client_secret, the exact redirect_uri passed in the original authorization request, and the code returned after the user approved access.

   POST /oauth/access_token
   Host: api.piryx.com
   
   grant_type=authorization_code&client_id=...&client_secret=...&
   redirect_uri=http://www.example.com/cb&code=...

   The response will be returned in JSON format. If the access token has been granted, it will be returned along with the expiration time in seconds (if the token will expire). By default, an access token will expire within 1 hour from the time it was granted. However, if the original authorization request included the never_expire permission, the access token will not expire unless the user explicitly revokes access from the application.

   { "access_token": "...", "expires_in" : 3600 }

   If an error occurred when attempting to grant access, then the error will be returned in JSON format. List of possible errors.

   { "error": "invalid_request" }

4. You can make authenticated calls using the access token. This can be done by passing the OAuth token in the HTTP Authorization header:

   GET /api/accounts/me/campaigns HTTP/1.1
   Host: secure.piryx.com
   Authorization: OAuth 4us4qarUyuqa9uja

   You can also pass the access token using the oauth_token parameter.

   https://secure.piryx.com/api/accounts/me/campaigns?oauth_token=4us4qarUyuqa9uja

Permissions

In order to gain access to certain API features, you must specifically request permission from the user when authorizing the application. These permissions should be sent as a space-separated list in the scope parameter.

Authorization Errors

The following errors may occur during the authorization process. They will be passed back to your application contained in the error parameter to the redirect_uri callback URL specified during the authorization request.

Token Grant Errors

The following errors may occur when requesting an access token. The error code is returned in JSON format as in the following example:

{ "error": "invalid_grant" }