Authentication

Information on How We Handle Authentication

The CBBB Service API requires authentication with valid, pre-registered credentials. In order to use the API, the consumer must first authenticate their username and password. Every request made after the consumer login credentials are authenticated must include an "Authorization" header key with a Bearer token in the format of "Authorization": "Bearer <token>".

If you are interested in using the CBBB API, please contact us to register and get your user credentials.

How to Register a Token

Workflow Overview:

  1. Register your account with Council.
  2. Make the first call to the API to get an authorization token.
  3. After a 10 second delay, the desired endpoint may be called using that token.
  4. Tokens are reusable - subsequent calls to the API are made using the same token issued in step #1. There is no need to wait (assuming you don’t exceed the 100 request per minute rate limit, which can be adjusted per partner if necessary).
  5. If the calls made in step #3 fail because of a 401 – unauthorized error, discard your current token and return to step #1.

 

Authenticating the consumer username and password to obtain an authorization token:

URL to obtain token

https://api.bbb.org/token

HTTP method

POST

Header values

Content-Type: application/x-www-form-urlencoded

Request body

grant_type=password&username=<username>&password=<password>

Example: grant_type=password&username=someuser&password=abc123

Once successfully authenticated, the service will respond with an object that contains the following attributes:

.expires - what date/time the token will expire
.issued - date/time when the token was issued
access_token - the full token that will be used
expires_in - seconds until the token expires
token_type - will always be 'bearer'
username - the username (email address) used for authentication

Sample Authorization Token Request:

request to: https://api.bbb.org/token

header: content-type: application/x-www-form-url-encoded

request body: grant_type=password&username=username&password=abc123

Sample Authorization Response Body:

{
 "access_token": "VOIxCyANd9dJxQ4nsAxw-93-...",
 "token_type": "bearer",
 "expires_in": 86313599,
 "userName": "user@address.com",
 ".issued": "Mon, 29 Sep 2014 17:54:00 GMT",
 ".expires": "Sat, 24 Jun 2017 17:54:00 GMT"
}
Making Requests with the Token:

Every request after the consumer login credentials are authenticated must include an "Authorization" header key with a Bearer token in the format of "Authorization": "Bearer <token>"

Delay for initial token request

Upon receiving a newly issued token, you must wait 10 seconds before attempting the first use.

Authorization header:

All requests will need to include an "Authorization" bearer header in the following format:

Authorization: Bearer VOIxCyANd9dJxQ4nsAxw-93-hViJ123ezt1xH... (shortened for readability)

Once the request is made, the API will decrypt the token and determine if it is valid. If the token is valid, the incoming request is mapped to the appropriate user, including that user's roles and attributes.

Expired Tokens:

Users should be aware that a token can expire after a specific amount of time or it can be revoked manually by Council. In these cases, the user must request another token. It is useful to build the possibility of expired tokens into your authentication process.

Unauthorized Responses:

The user will receive a 401 - Unauthorized exception if one of the following conditions occurs:

  • The user's credentials are invalid when requesting a token.
  • The user's token is invalid, has expired or has been revoked.
  • The user's credentials and token are valid, but the user is not authorized to access a specific endpoint.

 

User Login/Access Token API Call (HTML Code is below form)

The token generated with a successful login will be used in the subsequent calls.
Username:
Password:
Access Token:

 

 Sample Login/Access Token API Call Code

Process Flow Diagram

Authentication Flow Diagram