Authentication

All Open Cosmos APIs require authentication using OAuth 2.0. This page explains the supported authentication flows and how to obtain access tokens for the DataCosmos API.

Open Cosmos uses Auth0 as its authentication provider. The Auth0 domain is login.open-cosmos.com.

Choosing the Right Flow

There are three supported authentication flows. Use the table below to decide which one applies to your situation:

Option 1: Client Credentials

Use this when: your application runs on a server or as a script, with no user present. The token represents your application, not an individual user.

What you need from Open Cosmos: client_id and client_secret.

This is the OAuth 2.0 Client Credentials flow. Your application exchanges its credentials directly for an access token, without any user interaction.

Request an access token

Send a POST request to the token endpoint:

POST https://login.open-cosmos.com/oauth/token
Content-Type: application/json

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

Save these credentials to data_cosmos_api_credentials.json in your working directory.

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: Authorization Code

Use this when: your application is a web app or native app where a real user needs to log in. The token represents the authenticated user.

What you need from Open Cosmos: client_id.

What you must provide to Open Cosmos: the redirect URI(s) your application uses after login.

This is the OAuth 2.0 Authorization Code flow. The user is redirected to Open Cosmos's login page, authenticates, and is then redirected back to your application with an authorization code. Your server exchanges the code for an access token.

For added security in public clients (e.g. single-page apps), use the Authorization Code flow with PKCE.

Step 1: Redirect the user to the authorization endpoint

GET https://login.open-cosmos.com/authorize

Example URL:

https://login.open-cosmos.com/authorize?response_type=code&client_id=<client_id>&redirect_uri=<redirect_uri>&audience=https%3A%2F%2Fbeeapp.open-cosmos.com&scope=openid%20profile%20email&state=<random_state>

Step 2: Handle the callback

After the user authenticates, they are redirected to your redirect_uri with a code parameter:

https://<redirect_uri>?code=<authorization_code>&state=<state>

Verify that the state matches the value you sent in Step 1.

Step 3: Exchange the code for an access token

Send a POST request from your server to the token endpoint:

POST https://login.open-cosmos.com/oauth/token
Content-Type: application/x-www-form-urlencoded

The response contains an access_token (and a refresh_token if you requested the offline_access scope) you can use as a bearer token in API requests.

Python example

import requests

# Step 3: Exchange code for token (run server-side)
response = requests.post(
    "https://login.open-cosmos.com/oauth/token",
    data={
        "grant_type": "authorization_code",
        "client_id": "<client_id>",
        "code": "<authorization_code>",
        "redirect_uri": "<redirect_uri>",
    },
)

token_data = response.json()
access_token = token_data["access_token"]

Option 3: Implicit (Legacy)

Use this when: you require obtaining a user token from a browser without involving a server.

What you need from Open Cosmos: client_id.

What you must provide to Open Cosmos: the redirect URI your application uses after login.

In this flow the access token is returned directly in the URL fragment after the user authenticates. No client secret is required, and no server-side token exchange takes place.

Authorization request

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 your redirect_uri with the token in the URL fragment:

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

Use the access_token value as the bearer token in API requests.

Using the Access Token

Regardless of which flow you use, include the access token as a bearer token in the Authorization header of every API request:

Authorization: Bearer <access_token>

Handling Token Expiration

Access tokens expire after a fixed period (typically 86400 seconds / 24 hours). When a token expires, the server responds with a 401 status code and a body like:

{
  "meta": null,
  "data": null,
  "errors": [
    {
      "message": "Token is not valid, err could not parse JWT token, err Token is expired",
      "source": "gateway-authservice"
    }
  ]
}

When you receive this response, you should request a new token:

• Client Credentials flow: repeat the token request to https://login.open-cosmos.com/oauth/token with your credentials.
• Authorization Code flow with offline_access: use your refresh token to obtain a new access token without requiring the user to log in again.

Where to Next