Get started with BriteCore APIs

To obtain your client credentials (ID and Secret), complete one of the following:

• Use your credentials to obtain a valid access key via OAuth 2.0 Client Credentials grant.
• Configure Postman to obtain a token.

Once you obtain your credentials, you can:

1. Make a test request to BriteAPI.
2. Evaluate the response.

Note: For security reasons, your API access key is valid for an hour. You can set up Postman (or similar tools) to request the authorization code automatically.

Step 1: Obtain your API credentials

1. Go to the BriteCore menu.
2. Select Users.
3. Select Generate API Key.
4. Type an App Client Name in the text box. This is mainly used as an identifier for the system. 
5. Select New API Key. A dialog box displays the following:
   1. App Client Name
   2. App Client ID
   3. App Client Secret
6. Copy down the Client and ID and Client Secret.
7. Select the checkbox next to I acknowledge that I have copied the details and will not be able to view them again.
8. Select Close.

Note: If you don't have access to the BriteCore UI and are going through an active implementation, please contact your Consulting Project Manager. Otherwise, you can submit a Zendesk ticket to contact Support.

Step 2: Use your credentials to obtain a valid access token

Call the token endpoint auth (<client url>/api/auth/oauth2/token) with the following parameters:

• Authorization: Basic ${authorization_code}
• grant_type: client_credentials
• Scope: <client url>.britecore.com/api
• Where authorization_code is composed of the client ID and client secret concatenated with a colon and encoded in Base 64.

Note: Blocks of code are hidden by default to make the page more navigable. Select View code and Hide code to view or hide these sections as needed.

curl --location --request POST '{url}/api/auth/oauth2/token' \
--header 'Authorization: Basic {authorization_code}' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope={url}/api'

The response should look like this:

{
"access_token": "eyJra...krcg",

"expires_in": 3600,

"token_type": "Bearer"
}

Step 3: Configure Postman to obtain a token

If you are using Postman, configure the Authorization tab with the following fields:

• Type: OAuth 2.0
• Add auth data to: Request Headers

Under Configure New Token tab:

• Token Name: Type any identifier
• Grant Type: Select Client Credentials from the dropdown. 
• Access Token URL: <client_url>/api/auth/oauth2/token
• Client ID: <client id>from Step 1. 
• Client Secret: <client secret> from Step 1
• Client URL: <client_url>/api 
• Scope: <client_url>/api
• Client Authentication: Send as Basic Auth Header in the dropdown.

Select the Get New Access Token button to retrieve a token. 

Now that you have your credentials, let's make a test call.

Optional step: Make a test request to BriteAPI

To use an access key, pass it along to every call in the Authorization header. Example:

curl --location --request GET 'https://<client url>/api/lines/lines/?page=1' \
--header 'Authorization: Bearer {access_token}' \

Evaluate your response

A successful JSON response from the above request—a successful request will return status code 200.

{
"count": 40,

"next": null,

"previous": null,

"results": [

{
"id": "142fef34-05a7-4926-8fd2-782f49111240",

"label": "Training Line",

"name": "training",

"description": "Training only"

},
{

"id": "14d13532-27b1-4ec6-ad32-81035a63ea82",

"label": "General Auto Laura",

"name": "generalAutoLaura",

"description": "General Auto Laura Description"

},
{

"id": "208d8d06-8353-4628-a9a1-e73f4866dd3c",

"label": "General Auto",

"name": "generalAuto",

"description": "BriteRules sandbox - PLEASE DO NOT EDIT"

}

Status and error codes

BriteAPI uses standard HTTP response codes to indicate the success or failure of an API request and conforms to JSON: API standard error codes. The HTTPS status error codes include:

• 200: The API request was successfully processed.
• 300: The API request was successfully processed.
• 400: Indicates a client-side error such as a bad request, unauthorized request, resource not found, etc.
• 500: Internal server error.

In addition, as part of our error handling protocol, BriteAPI returns a helpful error message if arguments aren't provided, records aren't found, processes don't complete, etc.

Validation error format

All validation errors contain a message and code. Validation errors can also contain a meta attribute. This allows the validation error to provide additional context surrounding the error.

What are the token expiration times? 

For security reasons, tokens are set to expire in an hour. You can use your dedicated Client ID and Secret ID to generate a new token via tools like Postman.