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 2A: Authorization Code with Proof Key for Code Exchange (PKCE)

Use this when: your application is a web app or native app where a real user needs to log in and a server is available to request the token using a secret. 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&code_challenge=<code_challenge>&code_challenge_method=S256

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>

Step 3: Exchange the code for an access token

Send a POST request from your client (web or native app) 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.

This is an example response (id_token is only included if the user requested the openid scope):

{
   "access_token":"eyJhbGJaXI...IHDdHVg",
   "refresh_token":"5Dj...Kil",
   "id_token":"eyJh...KuU7P4yQ",
   "scope":"openid profile email",
   "expires_in":86400,
   "token_type":"Bearer"
}

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>",
        "client_secret": "<client_secret>",
        "code": "<authorization_code>",
        "redirect_uri": "<redirect_uri>",
    },
)

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

Validate the hashing function

With the value: "secret_random_string_123secret_random_string_123", you should obtain the hash "eRbpJ69nrUtqXytMxxNm6SQt9xAKB_60KpTwHkVKDh0" after applying Base64URL.

Option 2B: Authorization Code with Client Secret

Use this when: your application is a web app or native app where a real user needs to log in and NO server is available to request the token using a secret. The token represents the authenticated user.

What you need from Open Cosmos: client_id and client_secret.

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>",
        "client_secret": "<client_secret>",
        "code": "<authorization_code>",
        "redirect_uri": "<redirect_uri>",
    },
)

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

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