Authentication

curl https://app2.mavera.io/api/v1/usage -H "x-api-key: ***"

Keys look like mav_ followed by 48 hex characters. You can also send the key as a bearer token: Authorization: Bearer ***.

Connected guides

On docs2.mavera.io, the docs automatically ask the app for signed-in workspace context. The app validates its own cookie and returns only workspace identity, audience names and IDs, and API-key metadata. If automatic detection is unavailable, Connect account opens the secure app popup fallback.

• The app cookie never leaves app2.mavera.io; the docs cannot read it.
• Audience fields become live workspace selectors, and API consoles submit the real audience ID.
• The API-key dropdown lists active key names and prefixes, never hashes or plaintext values.
• Existing plaintext keys cannot be recovered. Select one and paste its full value into the current tab, or explicitly generate or rotate a dedicated docs-console key.
• Plaintext keys never appear in a URL. Generated keys return once through an exact-origin response and remain in that browser tab's sessionStorage.
• Every API console includes cURL, Python, Node.js, JavaScript, Go, and PHP examples that use environment-variable placeholders instead of printing the browser key.
• Copy page prompt, ChatGPT, Claude, Cursor, and Lovable actions package the current page as reusable AI context.
• Disconnecting clears the tab. Revoke a generated key from API Keys if the browser is no longer trusted.

What needs a key

Discovery is public so agents can introspect the catalog and schemas before authenticating.

Key security

• Only a SHA-256 hash of each key is stored. The plaintext is shown once at creation — store it then.
• A key carries a workspaceId; calls run scoped to that workspace's data and credits.
• Revoke instantly with DELETE /api/v1/keys?id=… (admin). Revoked keys return 401 immediately.
• lastUsedAt is updated on every authenticated call, so you can spot stale keys.

Errors

{ "ok": false, "error": { "code": "UNAUTHORIZED", "message": "missing API key (send x-api-key header)" } }   // 401
{ "ok": false, "error": { "code": "RATE_LIMITED", "message": "rate limit exceeded; retry in 42s" } }          // 429
{ "ok": false, "error": { "code": "PAYMENT_REQUIRED", "message": "out of credits (…)" } }                     // 402