Docs/Api Reference/Authentication

Authentication

Every request to the public API under https://<your-host>/api/public uses HTTP Basic auth with an API key pair:

Username: the public key, pk-ap-...
Password: the secret key, sk-ap-...

Create keys under API Keys. The SDKs use the same keys.

⚠

Keep the secret key on the server side. Do not put it in browser or mobile code, and do not commit it to source control.

Sending the header

Your HTTP client builds the header from the two parts:

code

Authorization: Basic base64(<public key>:<secret key>)

bash

curl https://<your-host>/api/public/traces \ -u "pk-ap-...:sk-ap-..."

python

response = requests.get( f"{os.environ['ANTS_PLATFORM_HOST']}/api/public/traces", auth=(os.environ["ANTS_PLATFORM_PUBLIC_KEY"], os.environ["ANTS_PLATFORM_SECRET_KEY"]), ) response.raise_for_status()

A request with only the public key, for example Authorization: Bearer <public key>, is not accepted by the public API endpoints. Always send the secret key.

Project keys and organization keys

Key	Created in	Works with
Project key	Project Settings > API Keys	Ingestion, OpenTelemetry, traces, observations, sessions, scores, datasets, prompts, models, LLM connections, annotation queues and the other project endpoints. `GET /api/public/projects` returns the key's project.
Organization key	Organization Settings > API Keys	Organization management endpoints only: projects, memberships, project API keys and SCIM.

Using the wrong kind of key returns an error. A project endpoint called with an organization key returns 401 with a message asking whether you are using an organization key, and prompt endpoints return 403. Organization endpoints called with a project key return 403.

Keys created for Discover AI agents only work with the Discover AI endpoints.

See API Reference for which endpoints need which key.

Key expiry

API keys created in the app expire six months after they are created. The API key list shows each key's expiry date. A request with an expired key returns 401 with the message API key has expired. Create a new key in project settings. Create a new key and update your clients before the old one expires.

Ingestion-only deployments

A self-hosted deployment can limit project keys to sending trace data. On such a deployment, project keys can still send traces, observations, scores and media, check their credentials, and fetch prompts. Reading trace data and managing project resources with a project key returns 403.

Errors

Status	Cause
`401`	Missing or malformed `Authorization` header, unknown key, wrong secret, expired key, or a key of the wrong kind for the endpoint.
`403`	The key is valid but not allowed to perform this operation.

The response body explains the reason in a message field, or an error field on some organization endpoints.

Using the SDKs

The SDKs read the keys from ANTS_PLATFORM_PUBLIC_KEY and ANTS_PLATFORM_SECRET_KEY, and the host from ANTS_PLATFORM_HOST (Python) or ANTS_PLATFORM_BASE_URL (JS/TS and Java), or take them as constructor arguments. See the Python, JS/TS and Java SDKs.

python

from ants_platform import AntsPlatform ants = AntsPlatform() print(ants.auth_check())

auth_check() returns True when the keys and host are valid, and raises an error when they are not.

Next steps

API Keys: create, note and delete keys.
API Reference: endpoints, errors and rate limits.