Retrieving a Refresh and Access Token

The authentication process works by retrieving a Refresh and Access Token from the Bright Identity Provider (using OAuth 2). These tokens will allow your server side application to get and post data to the BrightPay API on behalf of the logged on user. This means your application will only be able to interact with data that the user has access to within BrightPay.

The scheme will work as below:

• Your application will publish a link pointing to the Bright Identity Provider (the link will include your Client Id)

• Your users will click on the link and their browser will be directed to the Bright Identity Provider

• The user will authenticate using their Bright ID username and password

• The Bright Identity Provider will redirect the user's browser back to your server-side application

• Your server-side application will catch the redirect and extract an authorisation code from the url

• Your server-side application will then pass the authorisation code along with your Client Secret to the Bright Identity Provider which will return a Refresh and Access Token

• Your server-side application will extract the Refresh and Access Token and store them server side

• The Access Token can be added to requests in order to authorise them (on behalf of the user).

• The Access Token will work for 5 minutes, shortly before the 5 minutes is complete you can use the Refresh token to request a new Access Token.

Creating the Initial Login UrI

Prerequisites - this step assumes you have a Bright Client Id and Secret for your application - please see Authentication for how to get these.

The first step in the process is to create a link (to be presented on your application) pointing to the Bright Identity Provider with the correct Scopes and Client Id.

https://login.brightsg.com/login.brightsg.com/B2C_1A_BPOL_SIGNIN_PROD/oauth2/v2.0/authorize? response_type=code&client_id=YOURCLIENTID&redirect_uri=YOURREDIRECTURL&state=YOURSTATE&scope=offline_access%20https%3A%2F%2Flogin.brightsg.com%2F456b7587-bc0e-4a1e-824e-756b078a2ade%2Fbrightpay.online.external.api

Item	Description
base URL	https://login.brightsg.com/login.brightsg.com/B2C_1A_BPOL_SIGNIN_PROD/oauth2/v2.0/authorize
response_type	Set to the value "code"
client_id	Set to your Client Id
redirect_uri	https%3A%2F%2Flocalhost%3A7467%2FLogin The redirect_uri is the end point that the Bright Identity Provider should redirect the browser to after generating an Authorization Code. Your application will listen at this specified end point and catch the request for further processing (as the request will include the Authorization Code). In this case the value has been set to "https://localhost:7467/Login" for testing purposes. In production this should be set to a production URL. Note the value specified for the redirect_uri must match one of the expected redirect_uri stored in the Bright Identity Provider. The redirect_uri(s) supported will be agreed when requesting the Client Id and Secret.
state	For example "7f4b7d0949c1457d8f108ad66c5b9fad_Home" The state represents the state of your application at the time of the request. The state will be passed back to your application when the Bright Identity Provider, after successful authentication, redirects the browser to the redirect uri with an Authorization Code. For example, the state could be used to track the page the login request was initially made from. Then when the browser arrives at the redirect uri (and the Authorisation Code has been extracted) your server-side application can redirect the browser back to the original page.
scope	offline_access%20https%3A%2F%2Flogin.brightsg.com%2F456b7587-bc0e-4a1e-824e-756b078a2ade%2Fbrightpay.online.external.api The scopes are the "permissions" or "abilities" your application is requesting to be added to the token. The scope has been set to offline_access https://login.brightsg.com/456b7587-bc0e-4a1e-824e-756b078a2ade/brightpay.online.external.api which are the scopes that are required to interact with the API.

Therefore, once the user has Authenticated with the Bright Identity Provider, the Bright Identity Provider will redirect the user’s browser to your applications redirect_uri, where your server-side application should listen for requests. Again, note the redirect_uri supplied must match a redirect_uri stored in the Bright Identity Provider.

Catching the response and extracting an Authorisation Code

The identity provider will redirect the user's browser to the redirect_uri with a response similar to belowhttps://localhost:7467/Login?state=7f4b7d0949c1457d8f108ad66c5b9fad_Home&code=eyJraWQiOiIwV1ZMal9IVDRtOH......48IUjfpxmypgpqjHMrOenoh0oQULSwtNfIlCDvt4MdOVnNQX1FUIVmeVVBM5LpxW0FKwRnB1HnVprvYhQqjWHDM4OV00rieHw.LzvGCz4XJMiVkvJJ1rBlC

This URI is constructed as below

Item	Description
base URL	https://localhost:7467/Login This is going to be a url to an endpoint on your application. Currently the site has been set to localhost for testing (with “Login” as the path). There will be some functionality at the "Login" end point to catch the request and process it. In production this should be set to a production URL. e.g. https://myproductionsite.com/Login.
state	7f4b7d0949c1457d8f108ad66c5b9fad_Home This is the state you provided in the Initial URI and will allow your application to navigate back to the calling page etc.
code	eyJraWQiOiIwV1ZMal9IVDRtOH......48IUjfpxmypgpqjHMrOenoh0oQULSwtNfIlCDvt4MdOVnNQX1FUIVmeVVBM5LpxW0FKwRnB1HnVprvYhQqjWHDM4OV00rieHw.LzvGCz4XJMiVkvJJ1rBlCQ This is the Authorisation Code that can be used to get a Refresh and Access Token.

Once your server-side application receives a request at the Redirect URI it should extract the "code" parameter which can later be exchanged for an Access Token.

Using the Authorisation Code to get a Refresh and Access Token

The next stage is to take the supplied Authorisation Code and ask the Bright Identity Provider to exchange it for an Access Token. To do this we need to POST data to the token end point below:

https://login.brightsg.com/login.brightsg.com/B2C_1A_BPOL_SIGNIN_PROD/oauth2/v2.0/token

with the following settings:

Setting	Value
Request Method	POST
Request Accept	application/json
Content Type	application/x-www-form-urlencoded

The request should include a body similar to below:

grant_type=authorization_code&code= eyJraWQiOiIwV1ZMal9IVDRtOH......48IUjfpxmypgpqjHMrOenoh0oQULSwtNfIlCDvt4MdOVnNQX1FUIVmeVVBM5LpxW0FKwRnB1HnVprvYhQqjWHDM4OV00rieHw.LzvGCz4XJMiVkvJJ1rBlCQ&client_id= 20ed300c-425be-4ca7-be38-3a523dfa2687&client_secret=45RtnwFe40Kgr...6edaaWgge334gHR&scope=offline_access%20https%3A%2F%2Flogin.brightsg.com%2F456b7587-bc0e-4a1e-824e-756b078a2ade%2Fbrightpay.online.external.api&redirect_uri=https%3A%2F%2Flocalhost%3A7467%2FLogin

Which is broken down as

Item	Description
grant_type	authorization_code Set the grant_type to the value above.
code	eyJraWQiOiIwV1ZMal9IVDRtOH......48IUjfpxmypgpqjHMrOenoh0oQULSwtNfIlCDvt4MdOVnNQX1FUIVmeVVBM5LpxW0FKwRnB1HnVprvYhQqjWHDM4OV00rieHw.LzvGCz4XJMiVkvJJ1rBlCQ This is the "Code" retrieved in the previous step.
client_id	20ed300c-45be-4ca7-be38-3a523dfa2687 This is your application's Client Id which has been supplied by Bright.
client_secret	45RtnwFe40Kgr...6edaaWgge334gHR This is your application's Client Secret which has been supplied by Bright.
scope	offline_access%20https%3A%2F%2Flogin.brightsg.com%2F456b7587-bc0e-4a1e-824e-756b078a2ade%2Fbrightpay.online.external.api Set the scopes to the value above.
redirect_uri	https%3A%2F%2Flocalhost%3A7467%2FLogin This is your redirect uri (in this case Localhost port 7476 for testing)

The provider will respond with the JSON similar to

{
"access_token":"reEseTEreseE…WRsHT5srtrtrsfd",
"token_type":"Bearer",
"not_before":1719399215,
"expires_in":300,
"expires_on":1719435215,
"resource":"456b7587-bc0e-4a1e-824e-756b078a2ade",
"profile_info":"ere12…wew33223221",
"scope":"https://login.brightsg.com/456b7587-bc0e-4a1e-824e-756b078a2ade/brightpay.online.external.api offline_access",
"refresh_token":"EyWEWA…RT_QEuttttW",
"refresh_token_expires_in":7776000
}

Breaking this down the fields you are interested in are:

Item	Description
access_token	This string is an access token that can be added as a "bearer" http request header, in order to interact with the BrightPay API on behalf of the user.
expires_in	How long in seconds before the access token expires (300 seconds = 5 minutes).
refresh_token	This string is a refresh token that can be used to retrieve another Access Token (just before the current Access Token has timed out).
refresh_token_expires_in	How long before the Refresh Token expires (7776000 seconds = 90 days).

Using the Access Token to request user information

To test the Access Token, request data from this end point (no parameters required)

https://external.brightpay.com/api/v1/Payroll/GetCurrentUserSummary

Setting	Value
Request Method	GET
Request Accept	application/json

With an HTTP Header as follows (the value is the Bearer plus the Access Token you received earlier):

Header Name	Value
Authorization	Bearer reEseTEreseE…WRsHT5srtrtrsfd

If successful, this end point should respond with JSON containing the logged on user's name and email similar to:

{
  "name": "John Doe",
  "emailAddress": "[email protected]",
  "isSuccess": true,
  "apiErrors": []
}

Using the Refresh Token to request a new Access Token

The Access Token will expire after 5 minutes. Your application can use the stored Refresh Token to request a new Access Token (perhaps 15 seconds before the original Access Token expires). To retrieve a new Access Token you need to POST data to the token end point below:

https://login.brightsg.com/login.brightsg.com/B2C_1A_BPOL_SIGNIN_PROD/oauth2/v2.0/token

with the following settings:

	Value
Request Method	POST
Request Accept	application/json
Content Type	application/x-www-form-urlencoded

The request should include a body similar to below:

grant_type=refresh_token&refresh_token=EyWEWA…RT_QEuttttW&client_id=2033200c-45be-4ca7-be38-3a523efd2687&client_secret=45RtnwFe40Kgr...6edaaWgge334gHR &scope=offline_access%20https%3A%2F%2Flogin.brightsg.com%2F456b7587-bc0e-4a1e-824e-756b078a2ade%2Fbrightpay.online.external.api

Which is broken down as

Item	Description
grant_type	refresh_token Set this value to "refresh_token".
refresh_token	e.g. EyWEWA…RT_QEuttttW This is your Refresh token retrieved earlier.
client_id	e.g. 2033200c-45be-4ca7-be38-3a523dfa2687 This is your Client Id which has been supplied by Bright.
client_secret	e.g. 45RtnwFe40Kgr...6edaaWgge334gHR This is your Client Secret which has been supplied by Bright.
scope	offline_access%20https%3A%2F%2Flogin.brightsg.com%2F456b7587-bc0e-4a1e-824e-756b078a2ade%2Fbrightpay.online.external.api Set the scope to the value above.

The Bright Identity Provider will respond with JSON similar to below:

{
"access_token":"tyT34Tethrhe…R4ereRErrbj4w",
"token_type":"Bearer",
"not_before":1719402949,
"expires_in":300,
"expires_on":1719438949,
"resource":"456b7587-bc0e-4a1e-824e-756b078a2ade",
"profile_info":" ere12…wew33223221",
"scope":"https://login.brightsg.com/456b7587-bc0e-4a1e-824e-756b078a2ade/brightpay.online.external.api offline_access",
"refresh_token":" EyWEWA…QwdfGIed2 ",
"refresh_token_expires_in":7776000
}

Which is broken down as

Item	Description
access_token	The Access token, this can be added as a http request header to interact with Bright APIs.
expires_in	How long in seconds before the access token expires (300 seconds = 5 minutes).
refresh_token	The Refresh token, this can be used to retrieve another Access token. Note this is a new value and should be stored as a replacement of the current Refresh token.
refresh_token_expires_in	How long before the Refresh token expires (7776000 seconds = 90 days)