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.

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

On this page