blckbx: Authorization for Third-party Clients

blckbx-authorization-for-third-party-clients.md

Authorization for third-party clients

Prerequisites

• Request an application client credentials from blcbx team.

Steps

1. Request a token: From the authorized application, request an Access Token for blckbx.
2. Call blckbx API: Use the retrieved Access Token to call blckbx API.

Request Token

To access our API, you must request an Access Token for it. To do so, you will need to POST to the token URL, /oauth/token.

Example POST to token URL

curl --request POST \
  --url 'https://<YOUR_TENANT_SLUG>.auth.staging.blckbx.io/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials' \
  --data 'client_id=<YOUR_CLIENT_ID>' \
  --data 'client_secret=<YOUR_CLIENT_SECRET>' \
  --data 'audience=https://api.staging.blckbx.io/graphql'

Parameters

Parameter Name	Description
grant_type	Set this to client_credentials.
client_id	Your application's Client ID provided by blckbx team.
client_secret	Your application's Client Secret provied by blckbx team.
audience	Set this to https://api.staging.blckbx.io/graphql

Response

If all goes well, you'll receive an HTTP 200 response with a payload containing access_token, token_type, and expires_in values:

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 86400
}

and if not, you'll receive an HTTP 400, except for server error HTTP 500 and rate limit HTTP 429, response with a payload containing error, and error_description values:

{
  "error": "invalid_client",
  "error_description": "Invalid client: cannot retrieve client credentials"
}

Error Parameters

Error Parameter Name	Description
error	An error code. Error codes
error_description	(Optional) Additional information of the given error.

Error Codes

Error Code Name	Description
invalid_request	When the given parameters are invalid or missing.
invalid_client	When the given client parameters and audience are invalid.
invalid_grant	When grant type is not supported by the client.
unsupported_grant_type	When the blckbx API doesn't support the grant type.
rate_limit_exceeded	Rate limit error.
unknown_error	Usually a server error.

Authorization Server Rate Limit

Only 10 request per second per ip address.

Call blckbx API

To call blckbx API from your application, you must pass the retrieved Access Token as a Bearer token in the Authorization header of your HTTP request.

curl --request POST \
  --url https://api.staging.blckbx.io/graphql \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{"operationName": null, "variables": {}, "query":"{ devices { id } } "}'