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 standard OAuth2.0 token access endpoint described here. 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 are 30min for write oriented APIs and 4hours for read oriented APIs. Scope TTL can be changed using Scopes API.

API scopes are organised 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 application.

Where to start

First, outline the common use-cases for API consumption across your organization.
For example, some imaginary organization may use APIs as follows:

• Read-only APIs related to drivers and tasks for displaying operational dashboards.
• Task 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.

Create your apps in the Bringg Dashboard

1. Visit Bringg Web → User icon → Settings → Webhooks & API → select Add App

2. Give your app a name → select the scopes → press next.
   1. Selecting a scope group (i.e. Customer or Customer_write) will cover all scopes under this branch and any new scopes that may be added to this branch in the future. However, if you select specific scopes (i.e. Create_customer), any new scopes will not be included. In this case, you will need to create an additional app to cover any new scopes.

❗️

Once an app is created you can not add or remove scopes.

3. On the next screen you will be provided with client_id and client_secret for your newly created application.

   1. Client_secret will be displayed only upon app creation. Make sure to copy and save the client_secret in a secure location.
   2. Generating a new client_secret will block access to requests using the previous client_secret.

The application is disabled by default. You can activate it any time using the toggle switch.
Note: enabling an app will instantly stop unauthenticated access to any API endpoints covered by scopes included in your app.

4. Press Done

Alternatively, you can create and manage applications using Management API described in the section below.

Generate new client_secret for existing application

In case you lost your API credentials or want to change client_secret for security reasons, select Edit App → Generate New Secret. A confirmation screen will appear once you select Done.
Remember: generating a new client_secret will block access to requests using the previous client_secret.

📘

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 OAuth2.0 - it may be required to call your own server region's endpoints directly. In these cases, please substitute the domains as follows:

US1 (AWS): admin-api.bringg.com
US2 (GCP): us2-admin-api.bringg.com
EU1 (AWS): eu1-admin-api.bringg.com
EU2 (GCP): eu2-admin-api.bringg.com

List of Oauth2.0 API URLs

The structure of all API URLs is as follows: https://< domain >/services/< service name identifier >.

• < domain > : comes from above, depending on the relevant Bringg distributed server
• < service name identifier > : see list below

Example: https://us2-admin-api.bringg.com/services/create_task

Obtaining access tokens

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

Note: 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>'

2. You will receive the following response (example):

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

3. 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/ae25879e-c54a-405c-89ac-dfc746502884/9242e52f-2511-4c30-b6ad-cd9ec706aa67/' \
    --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.XXXXX.Pt6x7aUIA5afPGCgFJot0C8VVGihxDHxi3kFniXd2qvOuCQWpEVt2_X2s4Pww1zj1YK3ERQeYXcXCuzI83Fdhg'

4. Prior to reaching token expiration time (TTL) repeat operation described in point 1 to obtain a new token. You can always check current token status by calling 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
    }

Additional resources

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 authenticate using your Bringg username and password.

Applications management API
a) Get all applications defined for you organization:

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

b) Disable existing application:

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

c) Enable application:

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

d) Generate new application client_secret:

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

e) Delete 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>'