Topics on this page

How do I get started?

In this quick guide, we will cover the following steps:

  1. Contacting the support team to obtain your client credentials (ID and Secret).
  2. Using your credentials to obtain a valid access key via OAuth 2.0 Client Credentials grant.

We will then use your credentials to:

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

We will also cover the following related topics:

  • Reviewing the status and error codes.
  • Discussing BriteAPI authentication and authorization.

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: Contact the Support team to obtain your API credentials

Figure 1: How to contact BriteCore Support.

If you do not have access to the link 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.

View code
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:

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

"expires_in": 3600,

"token_type": "Bearer"
}

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:

View code
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.

View code
{
"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.

How does authentication work?

BriteAPI uses BriteAuth for authentication. BriteAuth is a highly scalable system that offers best-in-class security features, including federated user identity, comprehensive multi-factor authentication (MFA) capabilities, and user directory integrations, such as Microsoft Active Directory Service.

BriteAuth leverages Cognito, Amazon Web Services’ authorization product, to meet HIPAA; PCI; and SOC 1, 2, and 3 authorization compliance.

For APIs, BriteAuth uses Lambda authorizers to apply authentication on APIs hosted on API Gateway. All requests must have Cognito User’s accessToken in the Authorization header to access secure endpoints.

Secured APIs require Cognito User’s accessToken value passed in the Authorization header.

How is security applied on endpoints?

OpenAPI uses the term security scheme for authentication and authorization.

How does authorization work? 

BriteAccess is responsible for active platform-wide access control. The main construct in the BriteAccess framework is the Access-Control Policy (ACP). An ACP defines whether or not to allow or deny a certain action to be performed, as well as under what circumstances. Once associated with a security role, an ACP can potentially affect users that operate under that security role.

At a high level, BriteAccess ACPs allow for access control through four different mechanisms:

  • Resource Protection: Allow/deny access to a platform resource.
  • Record Protection: Allow/deny access to a specific resource record/instance.
  • Action Control: Allow/deny a specific action/intention to be fulfilled.
  • Special Condition: Allow/deny access according to custom-defined conditions.

BriteAccess protects all interactive interfaces within BriteCore, including:

  • All HTTP API endpoints exposed by the platform.
  • All GraphQL data resolvers.
  • All BriteCore-UI navigational routes (coming soon).

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.