Delegated Access (OAuth 2.0 authorization code grant)

When Should I Use Delegated Access

You can use delegated access when you want to request and access other Paxful users accounts using API.

How Do I Use Delegated Access?

Delegated access mode relies on the OAuth 2.0 authorization code grant authentication flow. OAuth 2.0 is an industry standard, meaning you can use any of your favorite OAuth 2.0 libraries for authentication. A full list of Paxful OAuth 2.0 endpoints can be found at the end of this guide.

Paxful also provides SDKs for the most popular programming languages that you can use in your applications. For a list of available SDKs visit this page.

If you’re planning to use an SDK provided by Paxful or the OAuth 2.0 library provided by a third party, you’ll need to have an understanding of what happens behind the scenes to help troubleshoot authentication issues.

Prerequisites

• Create an application
• Add at least one product to your application (see Managing API Products & OAuth 2.0 Scopes below)

Steps

The authentication flow will look this:

1. Requesting An Access Token (JWT)

Compared to direct access mode (which uses the OAuth 2.0 client credentials flow), the OAuth 2.0 authorization grant flow requires additional work before you can get a JWT. By relying on delegated access, your application will gain access to a Paxful customer account to the extent that the user has authorized it.

In order to receive a JWT while using delegated access, there are a few sub-steps:

• Step 1 - your application generates a link that a user will need to click to trigger the authorization flow. When generating a link you are specifying client_id ( you receive it when you create an application in developers portal, see Prerequisites section), response_type - in this case it should stay “code”, redirect_uri - a URI that a user will be redirected back when s/he has authorized or declined scopes that you have requested (only URIs you have configured in the Authentication tab of Application settings in the developers portal are allowed) and scopes - a list of scopes (API operations) that your application would like to do on behalf of a user. For more information on “scopes” and how to manage them, please refer to Managing API Products & OAuth 2.0 Scopes.
• Step 3 - on this step a consent screen will be presented to a user. This is where the user can review what operations your application is requesting access to. All available scopes are divided into groups (see Managing API Products & OAuth 2.0 Scopes for more information). The consent screen doesn’t show all scopes your application has requested, but instead uses groups, meaning if you request at least one scope from a group, the whole group will be presented to a user.
• Step 4 - if the user on the consent screen grants your application the requested scopes, the user will be redirected back to the URI that was provided in the redirect_uri from step 1. Please pay attention to the code query parameter that is provided by the Authorization Server when redirect is being done.
• Step 5 - by now your application must be in possession of the code it has received after a redirect. Now, the application must exchange code to an access token. This is done by sending a request to https://accounts.paxful.com/oauth/token along with code that you have requested in the previous step as well as client_secret (you receive this when you create an application in the developers portal, see Prerequisites section for more information). If the authorization service can find a given code then it will return a JSON response that will include a JWT (access_token) and refresh_token:

curl --request POST \
    --url 'https://accounts.paxful.com/oauth2/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=authorization_code \
    --data client_id=CLIENT_ID \
    --data client_secret=CLIENT_SECRET \
    --data code=CODE

Please note that in the authentication flow above, client_secret is never shared to a user in a browser - client_secret is used only to exchange code for an actual JWT and nowhere else. Never share client_secret with anyone, it must be kept in a safe place where only your application can access it.

2. Calling API Endpoints

Every API request you want to authenticate needs to include an “Authorization” header with the JWT as its value:

curl --request POST \
    --url https://api.paxful.com/service/endpoint \
    --header 'Authorization: Bearer ABC'

If a JWT has a scope granted that is represented in this case by service/endpoint API endpoint, your request will be authenticated and you will receive a proper response. If JWT is not authorized to invoke an endpoint, you will receive a 403 HTTP error.

3. Refreshing An Access Token

Tokens that are received using Authorization Code Grant Flow have a lifetime of 1 hour. If you send an expired JWT, you will receive a 401 response code and need to get a fresh JWT using refresh_token that you have received in Step 5.

To get a new JWT using refresh_token, you need to send the following request:

curl --request POST \
  --url 'https://accounts.paxful.com/oauth2/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=refresh_token \
  --data refresh_token=REFRESH_TOKEN \
  --data client_id=CLIENT_ID \
  --data client_secret=CLIENT_SECRET

Please note that when you are refreshing a token, grant_type is set to refresh_token. If successful and authorization has found a provided REFRESH_TOKEN, you will receive the same response as in step 5.

Once you have exchanged a refresh_token for a new access token, the given refresh_token gets decommissioned and next time the access token expires you need to use a fresh refresh token.

Managing API Products & OAuth 2.0 Scopes

Once you create an application, you’ll need to add at least one API product to use it. If you already have an Application, you can visit the Products tab and add a product:

Every API product contains a set of API operations. When working with delegated access mode, before you can request access to an API operation, you need to have an API product that includes this operation added to your application. In OAuth 2.0 lingo, an API operation that is allowed to be invoked using a JWT that was received by exchanging client_id andclient_secret is called scope.

Contrary to direct access mode, when a JWT is issued through the authorization code grant flow, the JWT will only have access to scopes that a user has authorized. When working with delegated access mode, depending on the level of KYC that you as a developer have, you are able to request access to an additional set of API operations to perform on behalf of a user.

OAuth 2.0 Endpoints