OAuth2 and how to use with BGL’s API (including how to test with Postman)

A large number of questions are received about our API from developers about how does OAuth2 work and how do I use it with your API.

What is OAuth 2.0?

OAuth was created as a response to the direct authentication pattern such as HTTP Basic Authentication, where the user is prompted for a username and password.

The OAuth 2.0 authorization framework enables a third-party
application to obtain limited access to an HTTP service, either on
behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service, or by allowing the
third-party application to obtain access on its own behalf.

Authorization Code Grant

The Authorization Code Grant Type is grant type which BGL uses and probably the most common of the OAuth 2.0 grant types.

The authorization code is a temporary code that the client will exchange for an access token. The code itself is obtained from the authorization server where the user gets a chance to see what information the client is requesting, and approve or deny the request. The Access Token’s purpose is to inform the API that the bearer of the token has been authorized to access the API and perform a predetermined set of actions (which is specified by the scopes granted).

The flow includes the following steps:

Step 1. Initiate request

You will need to create a link to the authorization server which the user will open in a browser. The link includes information that allows the authorization server to identify and respond to the client.

The URL can put inserted into an <a href=""> tag or attached to a button. Example:<a href="https://api.bgl360.com.au/oauth/authorize?response_type=code&client_id=0ce526e5-1475-4eda-b272-2c45455171&scope=audit&redirect_uri=https://exampleapp.com/bglcallback"> Connect Your BGL Account</a>

Step 2. The user approves the request

The user enters their credentials on the login page which opens. If the user is logged in this step will be skipped.

Step 3. API redirects the user back to your app/website.

Once the user is authenticated, the Authorization Server sends a redirect header redirecting the user’s browser back to the app that made the request. The redirect will include a “code” in the URL (and the original “state” if used).

e.g.

https://exampleapp.com/bglcallback?code=Yzk5ZD&state=5ca75bd30

Step 4. You exchange the auth code for an access token

The client uses the auth code to get an access token by making a POST request to the authorization server.

e.g.

curl –location –request POST ‘https://api.staging.bgl360.com.au/oauth/token?grant_type=authorization_code&scope=audit&redirect_uri=www.yourwebsite.com.au/bgl&code=Yzk5ZD’
–header ‘Authorization: Basic YzhkYWQ5MzYtMDU3Ny00N2FmLThhZTMtZjIyNWQzMDhlNDNhOmFkN2Y3OGEyLTllNDAtNGViNy1hMzRkLWU4OTNiZDlkYjA4MQ==’

The authorization server will validate the request and respond with an access token and optional refresh token if the access token will expire.

Example Response:

{ access_token: “df2f0e40-606f-4311-8066-590732fd126b” token_type: “bearer” refresh_token: “c50a429f-9a6d-449d-8d82-4899998fe27b” expires_in: 581977 scope: “audit” }

How do I test this with Postman?

On BGL’s API site, create a new application if you do not already have one. You can use https://app.getpostman.com/oauth2/callback as the Redirect URL.

Copy the details from BGL’s API Client Details Page into the Postman Access Token Details:

If all details are correct, when you click Request Token you will be prompted for your BGL Login details and confirm Postman can access your account.

A token will then be generated which can be used to test requests.