Guides

Bringg API Access Management

Suggest Edits

Bringg supports OAuth2.0 Client Credentials Grant flow for increased security and convenience in Bringg API consumption.

Benefits of fine-grained API access management

  • Compliance with modern security standards.
  • Precise and confident control over your APIs.
  • Tailored API access for your business use-case.

Overview

In Bringg, API access management is organised using applications, scopes and access tokens.

Each application applies to a particular business use-case, covering one or more scopes. Each application has its own credentials (client_id and client_secret). The credentials can be exchanged for a security token utilizing a standard OAuth2.0 token access endpoint. All tokens conform to JWT standard.

In Bringg, scopes refer to specific API endpoints or API endpoint group(s). Each scope may have its own access rules, particularly access token eviction time (time to live -TTL).

The default TTL is 30 minutes for write-oriented APIs and 4 hours for read-oriented APIs. A scope TTL can be changed using Scopes API.

API scopes are organized in the following hierarchical structure:

<root>
  |__<logical group>
     |__<logical group read>  
     |    |__<endpoint 1>        
     |    |__<endpoint 2>        
     |__<logical group write>  
          |__<endpoint 3>        
          |__<endpoint 4>

The full API hierarchy is displayed in the Bringg Platform under Platform Integtegrations > OAuth2.

Before You Begin

  • Outline the common use cases for API consumption across your organization.
    For example, some organizations may use APIs as follows:
    • Read-only APIs related to drivers and tasks for displaying operational dashboards.
    • Order creation and update APIs for an integration with a server back-end.
    • Teams and users management APIs as part of custom web application developed in house.
      Each of these use cases should be represented by a single app with its own credentials, tokens, and TTLs.
  • Make sure you have the Admin user type in Bringg.

📘

API Domains and Regional Endpoints

Each Bringg merchant (and its associated data) is hosted and managed on one of Bringg's distributed server regions. Each server region is geographically and physically separated from the others, but for most purposes, public access is via a common, security gateway: app.bringg.com.

For some API purposes however - such as for OAuth 2.0 - it may be required to call your own server region's endpoints directly. In these cases, please substitute the domains as follows:

US2: https://us2-admin-api.bringg.com
US3: https://us3-api.bringg.com
EU2: https://eu2-admin-api.bringg.com
EU3: https://eu3-admin-api.bringg.com

Configure OAuth 2.0 Applications

Configure OAuth 2.0 applications to define your authentication method's scopes and receive the codes required for a token request.

Create an OAuth 2.0 app in the Bringg platform


  1. In the Bringg platform, select your user icon, then go to Settings > Platform Integrations > OAuth2 API and select Add App.
  2. Enter a recognizable name for your authentication app.
  3. Select application scopes. These tell Bringg which data can be read (accessed) or written (changed) in response to the API requests that use this authentication method.

    🚧

    Note:

    • Selecting all scopes limits the app's functionality. Choose only the parameters that are required for this app's purposes.
    • Selecting a scope group includes all nested parameters, along with any that are added in the future.
    • Once an app is created, it cannot be edited. You can create new apps with additional functionality as needed.
  4. Select Next to continue.
  5. Copy the Client ID and Client Secret Key to use in your token request.

    🚧

    Note:

    The The Client Secret Key is encrypted after you select Done and can't be accessed again.

  6. Activate the application by selecting the toggle.
  7. Select Done to finalize and hide the Client Secret ID.
  8. Request an access token to begin sending API requests to Bringg.

❗️

Critical Notes:

Activating an app instantly stops unauthenticated access to any API endpoints covered by the scopes included in your app.

If you lose your Client Secret Key, you can select Generate New Secret Key to create a new one. This automatically blocks access to requests using the previous Client Secret key.

Configure an OAuth 2.0 app using Bringg's Management API

You can utilize APIs to manage apps, scopes, and tokens. All these methods require you to be an admin user in Bringg and to authenticate using your Bringg username and password.

Applications Management API

a) Get all applications defined for your organization:

    curl --location --request GET 'https://admin-api.bringg.com/oauth/applications' \
    --header 'Authorization: Basic xxxyyy...'

b) Deactivate an existing application:

    curl --location --request POST \
    'http://admin-api.bringg.com/oauth/applications/disable/<app_id>' \
    --header 'Authorization: Basic xxxyyy...'

c) Activate an application:

    curl --location --request POST \
    'http://admin-api.bringg.com/oauth/applications/enable/<app_id>' \
    --header 'Authorization: Basic xxxyyy...'

d) Generate a new application client_secret:

    curl --location --request POST \
    'http://admin-api.bringg.com/oauth/applications/renew/<app_id>' \
    --header 'Authorization: Basic xxxyyy...'

e) Delete an application:

    curl --location --request DELETE \
    'http://admin-api.bringg.com/oauth/applications/<app_id>' \
    --header 'Authorization: Basic xxxyyy...'

Scopes API

a) See all scopes configured for your organization with their description and TTLs:

     curl --location --request GET 'https://admin-api.bringg.com/oauth/scopes' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic xxxyyy... \

b) Set custom expiration time on some of the scopes:

     curl --location --request POST 'https://admin-api.bringg.com/oauth/scopes' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic xxxyyy... \
    --data-raw '{
      "users":3600,
      "teams_write": 1000 
    }

Token introspection API

a) Get token info:

    curl --location --request POST 'https://admin-api.bringg.com/oauth/introspect' \
    -H 'Authorization: Bearer <another valid token>' \
    -F 'token=<token to check>'

or

    curl --location --request POST 'https://admin-api.bringg.com/oauth/introspect' \
    -F 'client_id=<client_id>' \
    -F 'client_secret=<client_secret>' \
    -F 'token=<token to check>'

Request access tokens

  1. Call OAuth2.0 token endpoint using your app credentials (client_id and client_secret).

    📘

    Note

    The token TTL can be changed, but the updated TTL must be shorter than the TTL indicated on scopes level.

    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 'scope=<any space separated list of scopes that covered by app or blank to include all scopes>' \
    -F 'ttl=<optional TTL in seconds>'
  1. You will receive the following response, with a unique access token:
    {
        "access_token": "ey...",
        "token_type": "Bearer",
        "expires_in": 3600,
        "created_at": 1583192109
    }
  1. Use the access_token obtained from the previous call to access API of your choice (example of calling get_open_tasks API):
curl --location --request POST 'https://admin-api.bringg.com/services/Qkdi30cw/xxxx-yyyy-zzzz-1111/aaaa-bbbb-cccc-2222/' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.XXXXX.Pt6x7aUIA5afPGCgFJot0C8VVGihxDHxi3kFniXd2qvOuCQWpEVt2_X2s4Pww1zj1YK3ERQeYXcXCuzI83Fdhg'
  1. Prior to reaching token expiration time (TTL), repeat the process to obtain a new token.

Check the status of a token

You can always check the status of your current token by calling the token info API:

    curl --location --request GET 'http://localhost:3000/oauth/token/info' \
    -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.XXXXX.Pt6x7aUIA5afPGCgFJot0C8VVGihxDHxi3kFniXd2qvOuCQWpEVt2_X2s4Pww1zj1YK3ERQeYXcXCuzI83Fdhg'

Should your token be valid, you will get a response like this:

    {
        "resource_owner_id": "Merchant:1",
        "scope": [
            "services"
        ],
        "expires_in": 1779,
        "application": {
            "uid": "KjBYkBNQEIxjhDZ_3kNtM28oBvvJEq0yUJKDIiYCCDg"
        },
        "created_at": 1582558663
    }

Updated 4 months ago