Authenticate Requests

OAuth

Delivery Hub's API uses the OAuth 2.0 Client Credentials Grant Flow to authorize communications between your external systems and Delivery Hub. It keeps your data secure and ensures no outside party can send malicious payloads to your Delivery Hub account.

OAuth works by generating a secret key that you then use to request a token. When you add this token to the header of your API payloads, Delivery Hub authorizes the sender to act on your behalf. You can think of this as adding a new user who signs in with a username and password (token) and has limited permissions.

The actions that APIs can take are limited by scopes, which determine the API endpoints each token can access. Learn more.

Create an OAuth client app to generate a secret key

Delivery Hub generates a unique Client ID and Client Secret Key for each app that you create in the settings.

The Client ID is the public identifier for the app and does not change, even when you regenerate the key. You can think of this as the app username.

The Client Secret Key is hidden from all users after you close the window, so be sure to copy it to add to the token request. You can think of this as the app password and the ID and token that replaces it in your other payloads as a password manager.

🚧

When you generate a new Secret Key, the previous key is disabled along with the token linked to it. Payloads using a disabled key are not authorized by Delivery Hub, and return an error.

📘

We recommend creating a separate app and corresponding token for each integration that you add. That way, if one of your apps is compromised, the rest of your integrations remain safe.
For example, you can create one app for your Order Management System (OMS), another for your Warehouse Management System (WMS), and another for billing.

1. Open Delivery Hub and go to Settings > Integrations, and select the API tab. Then, select Add App.

2. Enter an easily recognizable name for the app in the App name field. For example, if you are creating this app to connect with your OMS, include the name of your OMS in the title.

3. Note the list of scopes to understand the data that Delivery Hub APIs can access.

📘

All Order, Fulfillment, Shipment, and Return scopes are required for Delivery Hub APIs, including all scopes added to these groups in the future.

4. Select Save to generate the Client ID and Client Secret Key.

5. Copy the Client Secret Key so you don't lose access to it when you close the window.

Request an access token

Once you have generated the Client ID and Client Secret Key, send a request for a token to Bringg's authentication endpoint. You can send this payload using Postman [Authentication](ref:authentication# Request-a-token-using-Postman) or any other API testing client.

1. Add the app credentials (ID and Secret) that you just received to the call header.
   The URL for this call is https://eu2-admin-api.bringg.com/oauth/token or https://us2-admin-api.bringg.com/oauth/token, depending on the environment where your account is located.
2. Add the parameters to the request body, then send the call.

    curl --location --request POST 'https://admin-api.bringg.com/oauth/token' \
    -F 'grant_type=client_credentials' \
    -F 'client_id=kTKda4xsXRyFf9iZEK4skK.....3F0iZBl9WBQ_hV9Yk' \
    -F 'client_secret=yyTPn3TzJkfUkwQv.....VY-Xa22WTSUXxCiwWWENE' \
    -F 'ttl=<optional TTL in seconds>'

3. Bringg responds to a successful call with an access token:

    {
        "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.XXXXX.Pt6x7aUIA5afPGCgFJot0C8VVGihxDHxi3kFniXd2qvOuCQWpEVt2_X2s4Pww1zj1YK3ERQeg...",
        "token_type": "Bearer",
        "expires_in": 3600,
        "created_at": 1583192109
    }

Request a token using Postman

1. Open a new request by selecting File > New > HTTP Request or select the + icon in the tab bar.

2. Enter the URL for this call.
   Use https://eu2-admin-api.bringg.com/oauth/token for accounts using servers located in Europe, and https://us2-admin-api.bringg.com/oauth/token for accounts using servers in the US.

3. Change the call type from Get to Post.
4. Enter the parameters of the authorization request under the Params tab. Postman automatically formats the request to communicate with the server.

Add your token to your payloads

Pass this token to the header of your API requests. Using the header from the example below, replace the parentheses and their contents with the token.

{ curl --location --request POST 'https://api.bringg.com/v2/orders
-- header 'Authorization: Bearer (token)'

Request a new token

For continued access to the Bringg API endpoints, refresh your token before it expires (expires_at).

Repeat the steps above to receive a fresh token, then add it to your headers. You can automate this process by scheduling runs with Postman.

There is no need to generate a new key when refreshing your token.