Bringg API Access Management

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.


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:

  |__<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

  1. 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.

  1. 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.

  1. 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:

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):
US2 (GCP):
EU1 (AWS):
EU2 (GCP):

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


create_taskCreate Order (Task)
update_taskUpdate Order
start_taskStart Order
end_taskEnd Order (Task)
cancel_taskCancel Order (Task)
get_taskGet Order
get_open_tasksGet Open Orders (Tasks)
create_noteCreate Note
update_noteUpdate Note
checkinArrived to Destination (Check in)
checkoutLeft Destination (Checkout)
get_post_optimization_tasksGet Post Optimization Orders (Tasks)
create_customerCreate Customer
update_customerUpdate Customer
create_userCreate User
(i.e. Driver / Dispatcher/ Admin)
update_userUpdate User
(i.e. Driver / Dispatcher/ Admin)
get_userGet User
delete_userDelete User
start_shiftStart Shift
end_shiftEnd Shift
driver_home_eventsDriver Home Events
create_teamCreate Team
update_teamUpdate Team
team_indexShow All Teams
get_teamGet Team Details
delete_teamDelete Team
get_shareGet Share
get_quotesGet Quotes
create_task_configurationCreate Order Configuration
get_realtime_availabilityGet Driver Availability
generate_driver_qr_codeGenerate Driver QR Code
create_delivery_blockCreate Delivery Block
get_delivery_blockGet Delivery Block
assign_delivery_blockAssign Delivery Block to Driver
unassign_delivery_blockUnassign Delivery Block from Driver
update_delivery_blockUpdate Delivery Block
delete_delivery_blockDelete Delivery Block
users_delivery_blocksGet Drivers' Delivery Blocks
team_delivery_blocksTeam Delivery Blocks
generate_pickup_qr_codeGenerate Pickup QR Code
create_parking_spotCreate Parking Spot
update_parking_spotUpdate Parking Spot
get_parking_spotGet All Parking Spots
get_by_id_parking_spotGet Parking Spot by ID
delete_parking_spotDelete Parking Spot
create_vehicleCreate Vehicle
update_vehicleUpdate Vehicle
get_vehicle_by_idGet Vehicle by ID
get_all_vehiclesGet All Vehicles
delete_vehicleDelete Vehicle by ID
create_task_payment_historyCreate Order Payment Details
Create Delivery Slot
Update Delivery Slot

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 '' \
    -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 (example):
        "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.XXXXX.Pt6x7aUIA5afPGCgFJot0C8VVGihxDHxi3kFniXd2qvOuCQWpEVt2_X2s4Pww1zj1YK3ERQeYXcXCuzI83Fdhg",
        "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 '' \
    --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.XXXXX.Pt6x7aUIA5afPGCgFJot0C8VVGihxDHxi3kFniXd2qvOuCQWpEVt2_X2s4Pww1zj1YK3ERQeYXcXCuzI83Fdhg'
  1. 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": [
        "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 '' \
    --header 'Authorization: Basic xxxyyy...'

b) Disable existing application:

    curl --location --request POST \
    '<app_id>' \
    --header 'Authorization: Basic xxxyyy...'

c) Enable application:

    curl --location --request POST \
    '<app_id>' \
    --header 'Authorization: Basic xxxyyy...'

d) Generate new application client_secret:

    curl --location --request POST \
    '<app_id>' \
    --header 'Authorization: Basic xxxyyy...'

e) Delete application:

    curl --location --request DELETE \
    '<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 '' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic xxxyyy... \

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

     curl --location --request POST '' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic xxxyyy... \
    --data-raw '{
      "teams_write": 1000 

Token introspection API
a) Get token info:

    curl --location --request POST '' \
    -H 'Authorization: Bearer <another valid token>' \
    -F 'token=<token to check>'


    curl --location --request POST '' \
    -F 'client_id=<client_id>' \
    -F 'client_secret=<client_secret>' \
    -F 'token=<token to check>'