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.

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

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

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.

18561856 18561856

📘

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

SERVICE NAME IDENTIFIER

NAME

RELATED API DOCUMENTATION

create_task

Create Order (Task)

https://developers.bringg.com/reference/create-task

update_task

Update Order (Task)

https://developers.bringg.com/reference/update-task-status

start_task

Start Order (Task)

https://developers.bringg.com/reference/start-order

end_task

End Order (Task)

https://developers.bringg.com/reference/end-order-task

cancel_task

Cancel Order (Task)

https://developers.bringg.com/reference/cancel-task

get_task

Get Order (Task)

https://developers.bringg.com/reference/get-order-task

get_open_tasks

Open Orders (Tasks)

https://developers.bringg.com/reference/opened-orders

create_note

Create Note

https://developers.bringg.com/reference/create-note

update_note

Update Note

https://developers.bringg.com/reference/update-note-1

checkin

Arrived to Location (Checkin)

https://developers.bringg.com/reference/arrived-to-location-checkin

checkout

Left Location (Checkout)

https://developers.bringg.com/reference/left-location-checkout

get_post_optimization_tasks

Post Optimization Orders (Tasks)

https://developers.bringg.com/reference/post-optimization-orders

create_customer

Create Customer

https://developers.bringg.com/reference/create-customer-1

update_customer

Update Customer

https://developers.bringg.com/reference/update-customer-1

create_user

Create User (i.e. Driver / Dispatcher/ Admin)

https://developers.bringg.com/reference/create-user-2

update_user

Update User (i.e. Driver / Dispatcher/ Admin)

https://developers.bringg.com/reference/update-user-1

get_user

Get User

https://developers.bringg.com/reference/get-user-1

delete_user

Delete User

https://developers.bringg.com/reference/delete-user-1

start_shift

Start Shift

https://developers.bringg.com/reference/start-shift

end_shift

End Shift

https://developers.bringg.com/reference/end-shift

driver_home_events

Driver Home Events

https://developers.bringg.com/reference/driver-home-events

create_team

Create Team

https://developers.bringg.com/reference/create-team-1

update_team

Update Team

https://developers.bringg.com/reference/update-team-1

team_index

Show All Teams

https://developers.bringg.com/reference/show-all-teams

get_team

Get Team Details

https://developers.bringg.com/reference/get-team-details

delete_team

Delete Team

https://developers.bringg.com/reference/delete-team-1

get_share

Get Share

https://developers.bringg.com/reference/get-share-1

get_quotes

Get Quote

https://developers.bringg.com/reference/get-quote

create_task_configuration

Create Task Configuration

https://developers.bringg.com/reference/create-task-configuration

get_realtime_availability

Get Driver Availability

https://developers.bringg.com/reference/get-realtime-driver-availability

generate_driver_qr_code

Generate Driver QR Code

https://developers.bringg.com/reference/generate-driver-qr-code

create_delivery_block

Create a Delivery Block

https://developers.bringg.com/reference/create-a-delivery-block

get_delivery_block

Get Delivery Block

https://developers.bringg.com/reference/get-delivery-block

assign_delivery_block

Assign a Driver to a Delivery Block

https://developers.bringg.com/reference/assign-a-driver-to-a-delivery-block

unassign_delivery_block

Unassign a Driver from a Delivery Block

https://developers.bringg.com/reference/unassign-a-driver-from-a-delivery-block

update_delivery_block

Update a Delivery Block

https://developers.bringg.com/reference/update-a-delivery-block

delete_delivery_block

Delete a Delivery Block

https://developers.bringg.com/reference/delete-a-delivery-block

users_delivery_blocks

Drivers Delivery Blocks

https://developers.bringg.com/reference/driver-delivery-blocks

team_delivery_blocks

Team Delivery Blocks

https://developers.bringg.com/reference/team-delivery-blocks

generate_pickup_qr_code

Generate Pickup QR Code

https://developers.bringg.com/reference/generate-pickup-qr-code

create_vehicle

Create Vehicle

https://developers.bringg.com/reference/create-vehicle

update_vehicle

Update Vehicle

https://developers.bringg.com/reference/update-vehicle

create_task_payment_history

Create Task Payment Details

https://developers.bringg.com/reference/payment-history

Create Planned Delivery Window

https://developers.bringg.com/reference/create-planned-delivery-window2

Update Planned Delivery Window

https://developers.bringg.com/reference/update-planned-delivery-window

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>'
  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 'https://admin-api.bringg.com/services/Qkdi30cw/ae25879e-c54a-405c-89ac-dfc746502884/9242e52f-2511-4c30-b6ad-cd9ec706aa67/' \
    --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": [
            "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>'