Direct Access (OAuth 2.0 client-credentials)

When Do I Use Direct Access?

You can use Direct Access when you want to access your Paxful account using API.

How Do I Use Direct Access?

Direct Access mode relies on the OAuth 2.0 client-credentials 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 ships 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 OAuth 2.0 library provided by a third party, having an understanding of what happens behind the scenes will help you troubleshoot authentication issues.

Steps

The authentication flow will look this:

1. Requesting An Access Token (JWT)

Before you can call any of the endpoints that require authentication, you need to exchange an API key (client_id) + secret (client_secret) for an access token (JWT). Once you receive a JWT, you need to save it somewhere where only your application can access it.

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

If given client_id and client_secret are known to the authorization service, the response will include at least the following fields:

The most important parameter is the “access_token”, which will be covered in the next section.

It’s considered a best security practice that JWTs would allow you to only invoke API operations that your application truly needs. Before going to production, unselect operations that your application does not need. For more details please see Managing API Products & OAuth 2.0 Scopes.

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 Client Credentials Flow have a lifetime of 10 days. If you send an expired JWT, you will receive a 401 response code and need to get a fresh token using Step 1 to continue using APIs.

Managing API Products & OAuth 2.0 Scopes

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

Every API product contains a set of API operations. By adding a product to an API key, you make this product’s API operations available for invocation using JWTs that were issued by exchanging its API key + secret. In OAuth 2.0 lingo, an API operation that is allowed by a given JWT is called a scope.

In Direct Access mode, when a JWT is issued, access to all API operations (scopes) of products added to an API key will be enabled.