Deliverr API Guide - Authentication

Note: This guide is meant to be accompanied with Deliverr's API spec: https://api.deliverr.com/documentation/v1/spec

Deliverr’s API uses a custom implementation of the OAuth 2.0 Authorization Code flow to authenticate users.

1. To start the authentication process, please go to the following link:

   <https://api.deliverr.com/oauth/v1/authorize>?
   	scopes={scopes}&
   	redirect_uri={redirect_uri}
   
   example:
   <https://api.deliverr.com/oauth/v1/authorize>?
   	scopes=api/products+api/orders+api/reports&
   	redirect_uri=https://deliverr.com
   

   • Replace {scopes} with the scope(s) you would like access to. To request multiple scopes, you can join them with + as the separator between scopes. For the respective API end points, the allowed scopes are:
   • api/products - access to products endpoints
   • api/inbounds - access to inbounds endpoints (in  beta; please request it via channels@deliverr.com) 
   • api/orders - access to orders endpoints
   • api/webhooks - access to webhooks endpoints
   • api/reports - access to reports endpoints
   • api/returns - access to returns endpoints (in beta; please request it via channels@deliverr.com)
   • api/parcels - access to parcel endpoints (in beta; please request it via channels@deliverr.com)
   • Replace {redirect_uri} with your service URL where you would like to receive the authorization code

   It will redirect you to the following consent screen:
   
   
   
   

2. Login with the same credentials as your Deliverr account (Note: this login is case-sensitive); you will be redirected to the redirect_uri you specified (in step #1 above), along with the code query parameter:

   • For the example above in step #1, it can be [<https://deliverr.com?code=e4869c3e-f532-4068-b732-4a186a9a08c0>](<https://deliverr.com?code=e4869c3e-f532-4068-b732-4a186a9a08c0>) 
     
     

3. Use the code parameter value to make the following request to the OAuth token endpoint in the API with the authorization_code grant type:

   curl --location --request POST '<https://api.deliverr.com/oauth/v1/token>' \\
   --header 'Content-Type: application/x-www-form-urlencoded' \\
   --data-urlencode 'code={received_code_value}' \\
   --data-urlencode 'grant_type=authorization_code'
   

   • Note that the request body must be in the application/x-www-form-urlencoded format

   You will receive a response like this:

   {
       "access_token": {valid access token},   -- 1 hour expiration
       "refresh_token": {valid refresh token}, -- 10 year expiration
       "expires_in": 3600,
       "token_type": "Bearer"
   }
   

   The refresh token does not expire. Pass in the access_token value as a Bearer token in the Authorization header to authenticate your requests to the public API.
   
   

4. Access tokens have a 1 hour lifetime. To generate new access tokens as needed, make the following request to the OAuth token endpoint

    

   curl --location --request POST '<https://api.deliverr.com/oauth/v1/token>' \\
   --header 'Content-Type: application/x-www-form-urlencoded' \\
   --data-urlencode 'refresh_token={received_refresh_token}' \\
   --data-urlencode 'grant_type=refresh_token'
   

   You will receive a response like this:

   {
       "access_token": {valid access token},
       "expires_in": 3600,
       "token_type": "Bearer"
   }
   

   The access token has a 1 hour life time from when it was generated.