Get API key

Documentation

Authentication and API key handling

Triguna authenticates with a custom ApiKey request header. How key scoping, test versus live keys, credit ceilings, rotation, and idempotency keys work in practice.

On this page

Every request carries a custom ApiKey header. There is no OAuth flow, no session, and no dashboard step between getting a key and making a call.

The ApiKey header

curl -H "ApiKey: $TRIGUNA_API_KEY" \
  "https://api.triguna.ai/v1/people/profile?profile_id=rokafor"

Key scope

PropertyValueNotes
Scope project + environment A key belongs to exactly one project and one environment.
Test keys tg_test_… Return shaped sample records and never spend credits.
Live keys tg_live_… Spend credits on every successful call.
Ceiling per key Set a monthly credit ceiling; requests past it return 402.

Because scope is per project and per environment, a staging key cannot quietly spend production credits, which is a common failure mode when one shared key is passed around.

Credit ceilings

A ceiling turns a runaway loop into a bounded, visible failure. Past the ceiling the API returns 402 with a documented body rather than silently spending:

HTTP 402
credit_ceiling_reached

Treat 402 as terminal. Retrying it wastes your own request budget and will not succeed until the ceiling resets or you raise it.

Handling keys

  • Keep keys server-side. A key in client code is a spend leak, not only a security issue. Anyone who reads your bundle can bill your account.
  • Rotate without downtime. Create a second key, move traffic to it, then revoke the first. Revocation takes effect immediately, so revoke last.
  • Send an idempotency key on retries. A retried call carrying Idempotency-Key is not billed twice, which matters because the retryable failure (429) is also the one you will hit most.
curl -H "ApiKey: $TRIGUNA_API_KEY" \
     -H "Idempotency-Key: 3f9c-1d77" \
  "https://api.triguna.ai/v1/people/profile?profile_id=rokafor"

What a rejected key looks like

StatusMeaningRetryable
401 Invalid or missing API key. No. Fix the header.
402 Out of credits, or a credit ceiling was reached. No. Raise the ceiling or top up.
403 Forbidden; usually a quota or billing rejection. No. Check the account.

All three return a plain-text body. See conventions, errors, and limits for the full table including 404 and 429.