Authentication

All Open Cosmos APIs require authentication in order to access them. This page provides information on how to obtain client credentials and access tokens for accessing the API.

Credentials

To get client credentials required for accessing the DataCosmos API you can contact the DataCosmos team.

Access Token

When using any of the DataCosmos APIs you will need to set a bearer token in your HTTP request headers.

There are two supported login options:

1. Client credentials (service-to-service)
2. Implicit (browser-based, for user based authentication)

Each customer will have only one of these options configured for their tenant. Use the option assigned to your account.

Option 1: Client Credentials

This bearer token can be retrieved by sending a request to the auth endpoint with your client credentials.

An example of how to use the client credentials to authenticate and receive a bearer token is provided below in different programming languages.

For these examples you will need to save your credentials to data_cosmos_api_credentials.json in the same directory using the following format:

{
  "client_id": "<client_id>",
  "client_secret": "<client_secret>",
  "audience": "https://beeapp.open-cosmos.com",
  "grant_type": "client_credentials"
}

Bash

DATACOSMOS_ACCESS_TOKEN=$(curl --request POST "https://login.open-cosmos.com/oauth/token" --header "Content-Type: application/json" -d @data_cosmos_api_credentials.json | jq -r ".access_token")

echo $DATACOSMOS_ACCESS_TOKEN

Python

Requests example

import json

import requests

with open("data_cosmos_api_credentials.json") as fp:
    oauth_body = json.load(fp)

session = requests.Session()
req = session.post(
    "https://login.open-cosmos.com/oauth/token",
    data=oauth_body
).json()

session.headers.update(
    {"Authorization": f'{req["token_type"]} {req["access_token"]}'}
)

print(req["access_token"])

Oauthlib example

Requires installation of the Requests OAuthlib package.

import json

from oauthlib.oauth2 import BackendApplicationClient
from requests_oauthlib import OAuth2Session

with open("data_cosmos_api_credentials.json") as fp:
    credentials = json.load(fp)

client = BackendApplicationClient(client_id=credentials["client_id"])
session = OAuth2Session(client=client)
session.fetch_token(
    token_url="https://login.open-cosmos.com/oauth/token",
    client_id=credentials["client_id"],
    client_secret=credentials["client_secret"],
    audience=credentials["audience"],
)

Option 2: Implicit

The implicit option is used for browser-based login flows. In this case, the access token is returned directly in the URL fragment after a user successfully authenticates, and no client secret is used in the browser.

The token obtained represents the user that completed the flow, not the application itself.

Use your configured Auth0 custom domain in the authorize URL. Example (replace placeholders):

https://login.open-cosmos.com/authorize?response_type=token&client_id=<client_id>&redirect_uri=<redirect_uri>&audience=https%3A%2F%2Fbeeapp.open-cosmos.com

After login, the browser is redirected to redirect_uri with the access token in the URL fragment, for example:

https://<redirect_uri>#access_token=<token>&token_type=Bearer&expires_in=86400

Use the returned access_token as the bearer token for API requests.

Where to Next