FutureSmart Developer Docs
Open Database Agent

API keys and permissions

How Database Agent API keys are issued, what each key may do, and how to store, rotate and revoke them.

Sending the key

Every request carries your key in the X-API-Key header. The header name is case-insensitive.

Shell
curl -sS "https://futuresmart.ai/database-agent/api/v1/agents/$DATABASE_AGENT_ID" \
  -H "X-API-Key: $DATABASE_AGENT_API_KEY"

One key, one agent

A key is issued for a single agent, from that agent's Share → API panel in the app. Each person gets one active key per agent; generating again shows the key you already have.

RequestResult
Any route under /v1/agents/{your agent}Allowed, except the four below
The same route on a different agent403 — This API key is not valid for this agent
A route with no agent in the path (for example GET /v1/agents)401 — This API key is agent-scoped and cannot be used on this endpoint
An unknown or revoked key401 — Not authenticated: valid session or API key required

What a key can and cannot do

On its own agent, a key can do everything the API reference lists:

  • Ask questions and follow-ups, and rate answers.
  • Read every saved conversation on the agent — including ones other people started in the app or the widget — and rename, delete or export them.
  • Configure the agent: its name, greeting, model settings, connected databases, which tables are visible, table and column descriptions, and example questions.

A key can never:

  • issue, list or revoke API keys;
  • invite collaborators or change their roles;
  • read or change the database connection's password;
  • delete the agent.

Those need a signed-in owner in the app and return 403 to a key.

Keeping keys safe

  • Server side only. Call the API from your backend, a job or a CLI — never from browser JavaScript or a mobile app, where anyone can read the key. For a chat box on a public website use the app's Share → Chat bubble on your website instead, which needs no key.
  • Environment variables or a secret store. Don't commit keys to source control. The examples in these docs read DATABASE_AGENT_API_KEY from the environment for that reason.
  • Read-only database account. The agent is built to answer questions, not to change data. Connecting it with a database user that can only read makes that a guarantee enforced by your database rather than a property of the agent.
  • Limit the tables. Tables you hide from the agent in the app are never queried, whatever the question.

Rotating and revoking

To rotate a key, revoke it in Share → API (each key in Your API keys has a revoke action), then generate a new one and deploy it. Revocation takes effect on the next request; calls with the old key return 401.

Self-hosted installations

The open-source project uses the same per-agent keys. It also has an operator key (FASTAPI_SECRET_KEY) that reaches every agent and can issue agent keys:

Shell
curl -sS -X POST "http://127.0.0.1:18000/nl2sql/api/v1/agents/$AGENT_ID/api-keys" \
  -H "X-API-Key: $FASTAPI_SECRET_KEY" -H "Content-Type: application/json" \
  -d '{"user_id": "integration@example.com"}'

Use the operator key only to administer your own installation. Give applications per-agent keys.