Topics on this page

How do I get started?

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

  1. 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: 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.

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.