Skip to content

Authenticate

An API for retrieving your access token for authentication.

This guide will help you connect to our API using OAuth authentication. This document will guide you through setting up and using these authentication methods in your preferred programming language. For reference, you can also try out your authentication and the entire API in the OpenAPI Spec.

Prerequisites

Before you begin, ensure you have the following:

-A Blackbird AI account.

-Your client credentials (Client ID and Client Secret) for the Client Credentials flow.

-(Not reccommended in a production integration) Alternatively for trying out the API, your Compass Application username + password.

Download OpenAPI description
token.json
token.yaml
Languages
Servers
Mock server

https://docs.blackbird.ai/_mock/token/

https://api.blackbird.ai/

Get token

Request

Exchange client credentials for an access token.

Bodyapplication/x-www-form-urlencodedrequired
grant_typestring

The grant type. The only valid value right now is client_credentials

Value"client_credentials"
Example: "client_credentials"
client_idstring

Your application's client ID.

Example: "your_client_id"
client_secretstring

Your application's client secret.

Example: "your_client_secret"
curl -i -X POST \
  https://docs.blackbird.ai/_mock/token/auth/oauth2/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d grant_type=client_credentials \
  -d client_id=your_client_id \
  -d client_secret=your_client_secret

Responses

Access token returned successfully.

Bodyapplication/json
access_tokenstring

The access token to use for API requests.

Example: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
token_typestring

Token type, typically "Bearer".

Example: "Bearer"
expires_ininteger

Time in seconds until the access token expires.

Example: 3600
Response
application/json
{
  "access_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 3600
}

Get token via password grant

Request

Exchange username password via password OAuth grant for an access token.

Bodyapplication/x-www-form-urlencodedrequired
grant_typestring

The grant type. The only valid value right now is password

Value"password"
Example: "password"
usernamestring

Your compass username

Example: "myEmail@gmail.com"
passwordstring

Your compass password

Example: "myP@ssword123"
curl -i -X POST \
  https://docs.blackbird.ai/_mock/token/compass/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d grant_type=password \
  -d username=myEmail@gmail.com \
  -d password=myP@ssword123

Responses

Access token returned successfully.

Bodyapplication/json
access_tokenstring

The access token to use for API requests.

Example: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
token_typestring

Token type, typically "Bearer".

Example: "Bearer"
expires_ininteger

Time in seconds until the access token expires.

Example: 3600
Response
application/json
{
  "access_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 3600
}