Authentication

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 formatCopy Anchor Link

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 keysCopy Anchor Link

Keys are managed in the dashboard, under 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 errorsCopy Anchor Link

{
  "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 serverCopy Anchor Link

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 key in a browser, and the widget rejects any attribute that looks like a key. Publishable browser keys do not exist yet.

CONSTAIA_API_KEY environment variableCopy Anchor Link

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 examplesCopy Anchor Link

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 stepsCopy Anchor Link