Authentication
Tensile ingestion is authenticated with a single header: x-api-key. Learn where to get a key, how to send it, and how to keep it safe.
Watch the workflow: Inspect organization setup and evaluation controls · Authored dummy data
This recording uses an earlier Settings layout. It shows authored live-eval, key-metadata and stage-coverage examples; its section navigation is historical. In the current layout, open Settings → General for live evals and Settings → API keys for ingestion keys. The recording does not create or reveal a full key.
Read matching command examples
Read the walkthrough transcript
- 00:00 — This Tensile demo keeps live evaluations off. No model judging is running.
- 00:05 — Inspect an organization key label and prefix. The full key is hidden.
- 00:11 — Read the demo stage coverage. These authored events are tagged staging.
Every request to the Tensile ingestion API carries one header:
x-api-key: sk_1a2b3c...That is the whole model. A valid key authorizes writes for the organization that owns it. There is no separate account id to route on and no token exchange to perform.
Where keys come from
Organization owners and admins issue API keys in the Tensile dashboard under Settings → API Keys. Give each key a name that describes where it runs, for example production or staging, so you can revoke the right one later without guessing.
A key is a string that starts with sk_ followed by a hexadecimal secret:
sk_9f3c0d7e5b2a41c88e6f0a1b2c3d4e5f...Keys are scoped to your organization. Keys created in Settings have no expiry by default. A key with a configured expiry stops passing a fresh lookup after that time. Select Revoke to disable a key; Tensile keeps its audit record.
Sending the key
Send the key in the x-api-key header:
curl https://api.withtensile.com/api/v1/capture-event \
-H "x-api-key: sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{ "event_id": "...", "session_id": "...", "primitive_name": "support-bot", "args": "hi", "result": "hello" }'Endpoints
https://api.withtensile.com
http://localhost:8080
Use the matching base URL when you send the request. Production clients should use the HTTPS endpoint above.
Authentication failures and retries
A missing, unknown, revoked or expired key returns 401 after a fresh lookup. If the authentication database is temporarily unavailable, ingestion returns 503 with Retry-After. Retain the event and retry with backoff; a temporary database failure does not require replacing your key. A failed authentication check does not enqueue the event.
Keep keys out of source control
An sk_ key is a write credential. Anyone holding it can push events into your organization.
Sound practice:
- Load the key from an environment variable or a secrets manager, never a literal in code.
- Use separate keys per environment so you can revoke one without disturbing the others.
- Rotate a key by creating a new one, deploying it, then revoking the old one from Settings → API Keys.
- If a key is exposed, revoke it immediately. In the default ingestion service, a successful key lookup can be cached for up to 60 seconds. A revoked or newly expired key may still be accepted until that cached result expires.
Load the key from your runtime's secret store and interpolate it only into the server-side request header.