Constaia

Authentication

Authenticate Constaia API calls with ck_live_ and ck_test_ Bearer keys, where to create and revoke them, and why they never go in the browser.

Cette page n'est pas encore traduite dans votre langue. Voici la version anglaise.

Every call to https://api.constaia.com/v1 (except the public document type catalogue and the signed export downloads) is authenticated with a secret key in the Authorization header:

curl https://api.constaia.com/v1/balance \
  -H "Authorization: Bearer $CONSTAIA_API_KEY"

Key format

PrefixModeWhat it does
ck_test_…TestSimulated provider with deterministic responses based on the file name. Free, livemode: false. See Test mode.
ck_live_…LiveAnalyses documents for real and spends credits. livemode: true.
pk_test_… / pk_live_…Test / LivePublishable key for the browser: it only uploads documents to a session your server creates, and only from the domains you allow.

The prefix is followed by 24 to 64 alphanumeric characters. The key decides the mode, not a request parameter: the same code runs in test and live by changing only the environment variable.

Creating and revoking keys

Keys are managed in the dashboard, under Developers → API keys:

  • A test key is created when you sign up so you can start without any setup.
  • To create a live key you must have confirmed your email. Otherwise the dashboard answers with the email_not_verified error. If you signed up with Google or GitHub, your email is already verified.
  • Each key is shown only once, when it is created. Copy it to your secret manager at that moment.
  • Constaia stores only a SHA-256 hash of the key: we cannot recover it or show it again. If you lose it, create a new one and revoke the old one.
  • A revoked key stops working immediately and returns 401 invalid_api_key.

To rotate keys without downtime (create the new one, deploy, revoke the old one) follow the steps in Security.

Authentication errors

HTTPcodeWhen
401missing_api_keyThe Authorization: Bearer … header is missing or malformed.
401invalid_api_keyThe key does not match the ck_live_/ck_test_ (or pk_live_/pk_test_) format, does not exist or has been revoked.
403secret_key_in_browserA secret key (ck_…) used from a browser.
403publishable_key_not_allowedA publishable key (pk_…) on a route other than a session upload.
403origin_not_allowedA publishable key from a domain that is not on its list.
403account_suspendedThe account is suspended.
401 response
{
  "error": {
    "type": "authentication",
    "code": "missing_api_key",
    "message": "Falta la cabecera Authorization: Bearer <api_key>.",
    "request_id": "req_01M3PD48ARCDHXGT0XECMARCPD"
  }
}

Every error follows this shape. See Errors.

The key lives on your server

Never in the browser or a mobile app

A ck_live_ or ck_test_ key gives access to your account and your credits. Do not put it in frontend code, a mobile app, a repository or NEXT_PUBLIC_*/VITE_* variables. Your frontend or app sends the file to your backend, and your backend calls Constaia.

The API has open CORS on /v1, but that does not change the rule: the JavaScript SDK throws secret_key_in_browser if it detects a secret key in a browser, the API rejects it with 403 secret_key_in_browser when it comes from a page on another origin, and the widget rejects any attribute that looks like a secret key.

Publishable keys (pk_…)

If you want the browser to upload the document straight to Constaia, without going through your server, use a publishable key. That one can ship in your website's code, because it only allows one thing: uploading documents to a session your backend creates with the secret key (POST /v1/sessions), from the domains you allow (1–20, app.yoursite.com, *.yoursite.com and, in test, localhost:3000).

  • Create them under Developers → API keys, with the Publishable type. They are shown only once.
  • They only work on POST /v1/analyze with a session's client_secret; any other route returns 403 publishable_key_not_allowed.
  • The analysis options come from the session and its template: the browser cannot change expect or checks.

Reference in Sessions and publishable keys and guide in Frontend-only integration.

CONSTAIA_API_KEY environment variable

Store the key in CONSTAIA_API_KEY. The JavaScript, PHP and Python SDKs and the MCP server read it automatically when you do not pass a key.

.env
CONSTAIA_API_KEY=ck_test_...

Minimal examples

They all call GET /v1/balance, which spends no credits.

curl https://api.constaia.com/v1/balance \
  -H "Authorization: Bearer $CONSTAIA_API_KEY"

Every response carries an X-Request-Id: req_… header. Keep it in your logs and include it if you contact us about a problem.

Next steps

Sur cette page