Connect an AI Agent

An AI agent, such as a coding assistant or an automated script, can ask for its own PrefsDB key, and you approve it in your dashboard. You never have to copy a key into a chat or a config file.

How it works

1. The agent asks PrefsDB for a key. It shows you a short code, like WDJB-MJHT, and the address prefsdb.com/activate.
2. You open that address, sign in to your dashboard if you aren't already, and type the code.
3. You see which agent is asking and from where, and choose what its key may do. Then you press Approve (or Deny).
4. The agent picks up its key a few seconds later.

The code works for 10 minutes. Only an account's editors and admins can approve.

Only approve a code you started yourself

Whoever started a request gets the key if you approve it. If someone sends you a code and asks you to approve it, don't.

What the agent's key can do

You decide when you approve:

Choice	Default	What it means
Access	Read and write	Or read only: the agent can look at data but not change it.
Project	agent-state	The key only reaches data in this project. Clear it to let the agent reach every project.
Expires	Never	Or after 1 day, a week, 30 days, 90 days or a year.

The key appears in API Keys with an agent badge and its limits. Revoke it there whenever you want; the agent can also give it up itself. Approvals, denials and revocations appear in the activity log.

These are the same limits as Restricted API Keys, and they can't be changed later.

Turning it off

An admin can turn off Allow connecting agents in Settings. While it's off, nobody in the account can approve a request. Keys already given out keep working until you revoke them.

For agent developers

The flow is two calls, in the style of the OAuth device flow:

cURLJavaScript

# 1. Ask for a key (no credentials needed)
curl -s -X POST https://prefsdb.com/api/v1/pair/start/ \
  -H "Content-Type: application/json" -d '{"name": "My agent on build-box"}'
# {"device_code":"<secret>","user_code":"WDJB-MJHT","verification_uri":"https://prefsdb.com/activate/","interval":5,...}

# 2. Show the user the address and the code, then poll every `interval` seconds
curl -s -X POST https://prefsdb.com/api/v1/pair/poll/ \
  -H "Content-Type: application/json" -d '{"device_code": "<secret>"}'
# {"state":"pending",...}  ... later:  {"state":"approved","key":"<the key>","scope":{"project":"agent-state"},...}

const start = await (await fetch("https://prefsdb.com/api/v1/pair/start/", {
  method: "POST", headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "My agent on build-box" }),
})).json();
console.log(`Open ${start.verification_uri} and enter ${start.user_code}`);

let r;
do {
  await new Promise((ok) => setTimeout(ok, (r?.interval || start.interval) * 1000));
  r = await (await fetch("https://prefsdb.com/api/v1/pair/poll/", {
    method: "POST", headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ device_code: start.device_code }),
  })).json();
} while (r.state === "pending" || r.state === "slow_down");
if (r.state === "approved") { /* store r.key securely; send it as Authorization: Bearer <key> */ }

You can also send access: "read-only", a different project (or "" for none) and days to ask for an expiry. The person approving has the final say. The key comes back only once: keep it somewhere safe, and never print it. GET /api/v1/pair/self/ says what the key can do, and POST /api/v1/pair/revoke/ gives it up.