Using the API

🚧

Caution: Interacting with the API in this tool and testing endpoints involves live data. API calls in this sandbox environment will impact real data.

API Authentication

Authentication is required for the API.

The Ternary API supports two ways to authenticate to the API.

Short-Lived Access Token

Constraints

• Access tokens have a twenty-four (24) hour lifetime

Creation

This token depends on your session with the Ternary web app. You can view & copy this token in your browser's Dev Tools console. In Chrome, shown below, your token can be found at the following path Application - Storage - Cookies - https//my.ternary.app - TERNARY_ACCESS_TOKEN

TERNARY_ACCESS_TOKEN is the default cookie name; deployments can configure a different name.

Usage

Include the access token as a bearer token in the Authorization header. The access token bears all the privileges of its corresponding human user.

API Request

curl 'https://core-api.ternary.app/api/some_api_endpoint'
-H "Authorization: Bearer ${ACCESS_TOKEN}"

Long-Lived API Key

You can also authenticate by a long-lived API key. You can use the key anywhere you regularly use a personal access token.

Constraints

• API key expiration is optional. A key created without an expiration has no configured expiry; do not rely on an automatic 90-day expiration. Set an expiration when creating a key if you need a limited lifetime.
• API Keys belong to a specific human User (we do not yet support service accounts)

Creation
You can navigate to API key creation by clicking on the account dropdown in the top right -> "Settings" -> "API Keys" tab -> "Add API Key" button.

Usage

Include the API key as a bearer token in the Authorization header. The API key bears all the privileges of its corresponding human user.

API Request

curl 'https://core-api.ternary.app/api/some_api_endpoint'
-H "Authorization: Bearer ${API_KEY}"

Authentication and rate-limit errors

A 503 caused by an unavailable authentication dependency does not mean your credential is invalid. Diagnose it separately from 401 authentication failures and 403 permission denials. Where rate limiting is enabled, limits apply per user: additional API keys for the same user do not provide separate limits. Analytics may include Retry-After with a 429 response; when present, wait that long before retrying. Without a retry hint, use bounded exponential backoff instead of immediate repeated requests. Contact Ternary Support if throttling persists or you need the limit for your deployment.

Example Request

This sample workflow will guide you through using your TERNARY_ACCESS_TOKENto query the endpoint /me to see your current user attributes.

Log In to Ternary

• Navigate to Ternary

Locate and Copy TERNARY_ACCESS_TOKEN

Steps below are using Chrome

• Open Chrome DevTools

• Select Application Tab

  
  
  

• Filter TERNARY_ACCESS_TOKENand copy the Valueto your clipboard

  
  
  

Navigate to API Reference for /me

• Navigate to the endpoint to test the query.

• Paste TERNARY_ACCESS_TOKEN into Authorizationinput

  

• ClickTry It! to perform the request and observe the Response.

Selecting a Base URL

Choose the base URL for your API and tenant region. The table lists the documented Core regional bases and the US Analytics base. For an EU tenant, confirm the Analytics endpoint with Ternary Support before sending requests.

Use the base URL for the API you are calling and append the operation's path:

The Analytics Query and Fetch Metadata references use /query/load and /meta/focus relative to a base that already includes /analytics. Include the prefix only once, and do not combine an Analytics path with a Core base.

For Core requests, you can also select the region in the request example's Base URL dropdown:

Finding Your tenantID

Your tenant ID identifies your organization. You can find it in the Ternary browser URL as tenant_id=<YOUR_TENANT_ID>. Use the parameter name required by the endpoint: Core typically uses tenantID, while Analytics query and metadata use tenant_id.