Authentication & Generating Credentials

The Cranium Public REST API uses OAuth 2.0 client credentials authentication. To make authenticated requests, you generate a Client ID and Client Secret in the Cranium platform, exchange them for a bearer token at the token endpoint, and include the token in the Authorization header of subsequent API requests.

Authentication Flow

1. Generate credentials in the Cranium portal under Settings → API Manager. You will receive a Client ID, Client Secret, and Scope.

2. Request a token by calling POST /oauth2/v2.0/token with your credentials.

3. Call the API by including the token in the Authorization header on every data endpoint request.

4. Refresh the token before it expires. Do not call the token endpoint on every API request.

Generating Credentials

API credentials are generated in the API Management section under Settings.

1. In Cranium, open Settings and select API Management.

2. Click Generate Credentials.

3. Cranium displays the Client ID, Client Secret, and Scope. Copy each value immediately. The Client Secret is shown only once at creation and cannot be retrieved later. If the secret is lost, generate a new credential set.

4. Store the Client Secret in a secure secrets manager. Do not commit secrets to source control or share them outside your organization.

Each set of credentials is scoped to a single tenant. The values you need to request a token are summarized below.

Client ID: Displayed on the API Manager page after creation.
Client Secret: Displayed once at creation time. Copy and store securely.
Scope: Displayed on the API Manager page alongside the Client ID.

If the API Management section does not appear under Settings, your tenant is not licensed for the Public API. Contact your Customer Success Manager to enable the API.

Requesting a Token

Exchange your Client ID, Client Secret, and Scope for a bearer token at the token endpoint.

Token endpoint: POST /oauth2/v2.0/token

Content-Type: application/x-www-form-urlencoded

Request parameters:

Example request:

curl -X POST https://api.cranium.ai/oauth2/v2.0/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" \
	-d "scope=https://id.cranium.ai/api/.default"

Response:

json

{
	"access_token": "eyJ...",
	"token_type": "Bearer",
	"expires_in": 3600
}

The access_token value is the bearer token used to authenticate subsequent API requests. The expires_in value is the token lifetime in seconds. Tokens are valid for approximately one hour.

Authenticating API Requests

Pass the access_token value as a bearer token in the Authorization header on all subsequent API calls.

Header format:

Authorization: Bearer {access_token}

Example request:

curl -X GET
https://api.cranium.ai/api/public/v1/billofmaterials \
	-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

The token must be included on every request to the data endpoints. Requests without a valid token receive a 401 Unauthorized response.

Alternative: Basic Authentication Header

The token endpoint also accepts client credentials via HTTP Basic authentication. Use whichever pattern your OAuth library defaults to.

Header format:

Authorization: Basic {base64(client_id:client_secret)}

Example request:

curl -X POST https://api.cranium.ai/oauth2/v2.0/token \
	-H "Content-Type: application/x-www-form-urlencoded" \
	-u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
	-d "grant_type=client_credentials" \
	-d "scope=https://id.cranium.ai/api/.default"

Both methods are equivalent. The Basic auth method is the default for many OAuth client libraries, while the form-body method is sometimes easier to construct manually with curl or in scripts.

Token Lifetime & Caching

Tokens expire after expires_in seconds, typically 3600 seconds (one hour). Cache the token in your client and track its expiry time. Request a new token when the current one is close to expiring. Avoid calling the token endpoint on every API request, as this adds unnecessary latency and may result in rate limiting.

A simple caching strategy:

1. On startup, request a token and store it along with the expiration time.

2. Before each API request, check whether the cached token is still valid.

3. If the token is valid, use it. If the token has expired or is about to expire (within a 60-second buffer is a safe margin), request a new token.

4. If a request returns 401, request a new token and retry the request once.

Security Notes

Treat the Client Secret as a password. Store it in a secrets manager and never commit it to source control.
All Public API traffic is over HTTPS. Requests over HTTP are rejected.
Bearer tokens carry the same access as the Client ID and Secret used to obtain them. Treat tokens as sensitive.
401 responses do not consume your rate limit quota. See the Rate Limits & Error Handling article for details.

Did this answer your question?