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
| Prefix | Mode | What it does |
|---|---|---|
ck_test_… | Test | Simulated provider with deterministic responses based on the file name. Free, livemode: false. See Test mode. |
ck_live_… | Live | Analyses documents for real and spends credits. livemode: true. |
pk_test_… / pk_live_… | Test / Live | Publishable 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_verifiederror. 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
| HTTP | code | When |
|---|---|---|
| 401 | missing_api_key | The Authorization: Bearer … header is missing or malformed. |
| 401 | invalid_api_key | The key does not match the ck_live_/ck_test_ (or pk_live_/pk_test_) format, does not exist or has been revoked. |
| 403 | secret_key_in_browser | A secret key (ck_…) used from a browser. |
| 403 | publishable_key_not_allowed | A publishable key (pk_…) on a route other than a session upload. |
| 403 | origin_not_allowed | A publishable key from a domain that is not on its list. |
| 403 | account_suspended | The account is suspended. |
{
"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/analyzewith a session'sclient_secret; any other route returns403 publishable_key_not_allowed. - The analysis options come from the session and its template: the browser cannot change
expectorchecks.
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.
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
LangChain and LlamaIndex
Wrap Constaia as a LangChain (JS and Python) and LlamaIndex tool so your agents validate documents and get a clear valid, invalid or review verdict.
POST /v1/analyze
Full reference for POST /v1/analyze: request formats, every option and check, the analysis object field by field, status codes and examples.