Pular para o conteúdo principal

API Authentication

Your systems authenticate to the Cogneris API with an API key. There is no token exchange, session or cookie to manage: send the key on every request.

Send the key​

Put the key in the standard Authorization header as a Bearer token:

Authorization: Bearer <your API key>
curl -X POST "https://api-eu.cogneris.ai/Document/extraction" \
  -H "Authorization: Bearer $COGNERIS_API_KEY" \
  -F "file=@./invoice.pdf"
  • The key identifies your tenant. There is no x-tenant header to send.
  • Read the key from an environment variable such as COGNERIS_API_KEY or from a secrets manager. Never put it in source code, in a URL, or in a browser application.
  • Every request is HTTPS-only.

Production and sandbox keys​

When you create a key you choose its Environment, and the prefix tells you which one it is:

PrefixEnvironmentWhat it can call
xtkt_live_ProductionEvery route, including the synchronous /Document/* endpoints. Consumes credits.
xtkt_test_SandboxOnly the asynchronous job flow: POST /api/v1/artifacts, GET /api/v1/artifacts/content, POST/GET /api/v1/document-jobs, GET /api/v1/document-jobs/{jobId} and POST /api/v1/document-jobs/{jobId}/cancel. Does not consume credits.

A sandbox key on any other route — the synchronous /Document/* endpoints included — is refused with 403 and the code environment.sandbox_route_unavailable. On POST /api/v1/document-jobs a sandbox key runs only Extraction without a templateId, Classification, ZeroShot, Crop and Split.

Either prefix only gets the key looked up: the key must also be valid and active, or the answer is 401.

Region​

A tenant lives in one region, chosen when it is created, and its key works only on that region's host:

RegionAPI host
Europe (default for new tenants)https://api-eu.cogneris.ai
United Stateshttps://api-us.cogneris.ai

A key does not work on the other region's host.

Create, store and revoke keys​

Keys are created in the Cogneris platform under Vision → Developers → API Keys — see Generate an API key.

  • The plaintext key is shown once, when it is created. The platform keeps only a hash.
  • Use one key per integration and environment, with the smallest access it needs and an expiry.
  • Revoke a key from the same page when it is no longer used or may have leaked. A revoked key returns 401.

Rate limit​

Each key may send 50 requests per fixed 1-minute window. Requests over the limit receive 429; wait for the Retry-After interval before retrying.