Authentication

Status: stable Category: reference Added: 2026-04-20 Last reviewed: 2026-04-23

Summary

Every request to https://engine.tripod-health.com/api/... carries an API key in the apikey header. Keys are issued per consumer. A missing or invalid key is rejected with 401 before the request touches any business logic.

The only exception is GET /health, the unauthenticated liveness probe. Every other path in this directory requires an apikey header.

The apikey header

GET /api/health/check HTTP/1.1
Host: engine.tripod-health.com
apikey: <your-consumer-key>

Rules:

• The header name is exactly apikey, lowercase. Case-insensitive on the wire per RFC 7230, but clients should send it lowercase.
• The value is an opaque string. Treat it like a password: do not log it, do not embed it in URLs or query strings, do not commit it.
• One key per consumer. If your integration needs multiple parallel credentials (for example, separate staging and production keys), provision separate consumers.

How keys are issued and rotated

Keys are issued when a new consumer is provisioned. Provisioning is out of band — the API has no /keys endpoint. Reach out to your Tripod Health contact to request a key, list your active keys, or rotate.

Rotation works in two phases:

1. Provision a new key. Once issued, the new key is immediately valid. Both the old and the new key accept traffic during the overlap window.
2. Retire the old key. After the overlap window the old key is deactivated. From the moment of deactivation, any request bearing the old key fails with 401.

Rotate in your clients before the old key is deactivated. A cached key that survives past the deactivation boundary fails every request until it is refreshed.

What a 401 looks like

A 401 from a missing or unknown apikey uses a smaller envelope than the standard { timestamp, error, message, request_id } shape most other error responses carry, but it still includes a request_id:

{
  "message": "No API key found in request",
  "request_id": "cd27261422d41501f632143b590d7001"
}

Other forms you may see:

{ "message": "Invalid authentication credentials", "request_id": "..." }

{ "message": "Unauthorized", "request_id": "..." }

All carry HTTP status 401. The exact wording may change over time.

Clients should branch on the status code, not on the message string:

if (resp.status === 401) {
  // refresh / rotate the apikey, then retry
}

The request_id on a 401 is formatted as a hex string (typically 32 hex chars, no hyphens) rather than the UUID form that /api/* responses emit. Both are valid correlation IDs and both are accepted in support tickets — for a 401 it also helps to quote the UTC timestamp of the call and the consumer username you expected to be authenticating as.

Consumer identity in responses

Most endpoints do not echo your identity in their response — the response is the business payload. Two endpoints do surface consumer identity intentionally:

• GET /api/health/check — includes a consumer: { id, username } block so you can verify the key resolves to the consumer you expect.
• POST /api/debug/echo — echoes the consumer identity alongside the request details for integration testing.

For all other endpoints, your identity is resolved server-side (for logging and per-consumer metering), but the response body stays focused on the business result.

What we do not accept

• Authorization: Bearer <token>. Trinity does not use bearer tokens. Sending an Authorization header has no effect — only the apikey header is read.
• Query-string keys (?apikey=...). Query strings end up in logs, proxy caches, and browser history. The key must go in the header.
• Basic auth. Not supported.
• Cookies. The API is stateless and has no sessions. Cookies are ignored.

Security posture

• HTTPS only. In production, non-https requests are redirected with a 301 to the https form. Do not disable TLS verification in your client.
• No user sessions. Every request is authenticated on its own merits via the apikey header. There is nothing to log into or log out of.
• Per-consumer rate limits. See rate-limits.md.
• Keys belong in a secret store. Never embed in source, never commit to version control, never paste into shared chat. Cloud providers' secret-management services are the expected storage.

Debugging a 401

1. Check the header name. Must be exactly apikey. API-Key, X-API-Key, Authorization, and Api-Key are not accepted.
2. Check the value. Whole-string, no surrounding whitespace, no Bearer prefix.
3. Check the key is active. A rotated key stops working the moment the old credential is deactivated; a newly-provisioned key is active immediately.
4. Check the consumer. If you have multiple consumers, you may be sending the key for the wrong one. Call GET /api/health/check with each candidate key and compare the returned consumer.username against what you expect.
5. Check HTTPS. A curl -k against an HTTP URL hits the 301 redirect first; the subsequent HTTPS leg may drop the apikey header depending on your client. Always call the https:// URL directly.

Related

• errors.md — full error taxonomy for other status codes.
• rate-limits.md — per-consumer limits and headers.
• conventions.md — request-id, timestamp, and response-shape conventions.

Change history

Date	Change
2026-04-20	Initial publication.