Authentication. Keys, scopes and signatures.

API keys

One key shape, two environments, scopes per surface.

• Sandbox — keys start with flx_sk_sb_; hit api.sandbox.cogneris.ai; free quota, no real billing.
• Production — keys start with flx_sk_pr_; hit api.cogneris.ai; metered per the plan.
• Mint in the dashboard — Settings → API keys → Create; the secret is shown once.
• Per-key labels — name keys after their workload (etl-prod, support-readonly) for clean audit trails.

Scopes

Least-privilege is the default — keys must declare what they touch.

Wildcards are not supported — list scopes explicitly.

Sending the token

Bearer auth on every request. The SDKs read COGNERIS_KEY from the environment by default; you can also pass apiKey directly to the client.

Authorization: Bearer flx_sk_pr_…

curl https://api.cogneris.ai/v1/templates \
  -H "Authorization: Bearer $COGNERIS_KEY"

Rotation & revocation

• Rotate without downtime — create a second key, deploy it, then revoke the old one. Two active keys per label are allowed during the cutover.
• Revocation is instant — revoked keys return 401 on the next request; there is no propagation delay.
• Recommended cadence — rotate prod keys every 90 days; rotate immediately on suspected exposure.
• Leak detection — keys leaked to public GitHub are auto-revoked within 1 business day and a notice is sent to security@ on file.

Webhook signatures

We sign every webhook delivery with HMAC-SHA256 over the raw body, using a per-tenant signing secret. Verify before you trust the payload — the timestamp guards against replay.

Cogneris-Signature: t=1747654200,v1=9c8f…7e2a
Cogneris-Event:     extract.completed
Cogneris-Delivery:  evt_01J9PZQ2…

import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const [t, v1] = header.split(",").map(p => p.split("=")[1]);
  const expected = crypto.createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Reject deliveries where now() - t > 300s. Retries follow exponential backoff for up to 24 hours.

OAuth for partners

Building an app that acts on behalf of a Cogneris tenant? Use the OAuth 2.0 / OpenID Connect flow with PKCE. Tokens are tenant-scoped and inherit the scopes the user granted at consent. See the API reference for the endpoints and consent screen contract.

Storage & secrets

• Never check keys into source — use a secrets manager or your CI's encrypted variables.
• Don't share keys across services — one labelled key per service makes audit and revocation surgical.
• Don't put keys in browsers — Cogneris APIs are server-side; for client apps, proxy through your backend.

Auth errors