# Agent keys

Give an AI agent its own key to your Space. It reads only what you tick, the key runs out on its own, and you can stop it in one click. Every call it makes is listed for you.

## What the agent gets

- **Reading, nothing else.** You choose from: Activity, Tasks, Member profiles, Forms and answers, Payments.
- **No changes, no member emails.** It cannot change your Space, see member email addresses, make keys or sign in as you. It can ask for member emails and manage your directory and read your site files and change your site files and create and manage your forms and read your engagement types and create and manage your engagement types, and you decide.
- **A key that runs out.** 30 days unless you pick otherwise, never more than 90.
- **Test mode first.** A small daily ceiling until you move it to live. Calls cost units.

## Make one

1. **Open Agent keys** A manager or admin of the Space opens [/dash/integrations/agent-keys](https://bynefit.com/dash/integrations/agent-keys) and chooses *Create agent key*. Admins can also choose *Let an AI agent use your Space* in the *Create key* window on [/dash/integrations/api-tokens](https://bynefit.com/dash/integrations/api-tokens). Whoever makes it is its owner.
2. **Say which agent and what it is for** Name the agent and write a line about the job. Tick what it may read, pick when it expires, and add IP addresses if it always calls from the same place.
3. **Hand it over once** The key starts with `bapi_ag_` and is shown once, with a hand-off you paste into the agent: where to call, the key as `BYNEFIT_API_KEY`, these docs, its limits, and how to ask you for more. Bynefit keeps only a scrambled copy.

> **Send it only as a bearer header.** An agent key in a web address, or in any header other than `Authorization: Bearer`, is refused with `agent_key_header_only`. Refusing it cannot stop the address from reaching server and proxy access logs on the way in, so treat a key that was sent in an address as leaked: take a new key or revoke it.

## Check what it may do

The agent can ask the API about its own key at any time: what it may read, what it may ask for, its units and daily ceiling left and the answer to anything it asked for.

**cURL**

```bash
curl https://bynefit.com/dash/api/v1/agent \
  -H "Authorization: Bearer $BYNEFIT_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch('https://bynefit.com/dash/api/v1/agent', {
  headers: { Authorization: `Bearer ${process.env.BYNEFIT_API_KEY}` },
});
const me = await res.json();
console.log(me.mode, me.limits.remaining_today, me.can_request);
```

**Python**

```python
import os
import requests

me = requests.get(
    'https://bynefit.com/dash/api/v1/agent',
    headers={'Authorization': f"Bearer {os.environ['BYNEFIT_API_KEY']}"},
).json()
print(me['mode'], me['limits']['remaining_today'], me['can_request'])
```

## Test mode, then live

A new agent key is in test mode: it works on every endpoint it is allowed, with a smaller daily ceiling. When you are happy with what it does, the owner chooses *Move to live* on the key page. A confirmation lists exactly what changes (the daily ceiling) and what does not (its permissions, its expiry, your controls). Space admins are emailed.

> **An agent key's test mode reads your real information.** It limits how much the agent can do, not what it sees. It is not the sandbox. For sample data, give the agent a [test key](https://bynefit.com/docs/test-mode) while you build, then make it an agent key.

## Limits and units

Agent calls are counted in **units**, not as a fixed number of calls. A plain read is 1 unit and a change is 5. Each started 64 KB sent or received adds a unit, and member contact data and site files count double and secrets-adjacent data triple. Failed calls cost nothing, except a `403` or `429`, which costs one unit so probing is never free. Every answered call carries `X-Bynefit-Units` (what that call cost) and `X-Bynefit-Units-Remaining` (included units plus pack credit left).

A Space gets a monthly allowance of included units, and an admin can add more at any time: packs of units that last 12 months, automatic top ups, or extra usage billed on the monthly invoice. Agents spend included units first, then pack credit that expires soonest, then extra usage if the admin turned it on. Used credit is not refunded in cash.

| Pack | Price |
| --- | --- |
| 10,000 units | $17.50 |
| 100,000 units | $175.00 |
| 1,000,000 units | $1,750.00 |

Extra usage is off unless an admin turns it on. When it is on, units beyond included units and packs are added to the monthly invoice, up to a monthly limit the admin sets.

When a Space has no units left and has not turned on extra usage or automatic top ups, every call answers `402` with the code `usage_exhausted`, a `top_up_url` for the owner and no data. The agent should stop and tell its owner.

Separate from units, each agent key keeps a short burst limit and a daily safety ceiling against a runaway agent. Past either, the agent gets a `429` with a `Retry-After` header. The daily ceiling comes back at midnight, server time, and the key's owner can raise it on the key page. Every reply, refusals included, carries `X-Agent-Budget-Limit`, `X-Agent-Budget-Remaining`, `X-Bynefit-Agent-Mode` and an `X-Request-Id` to quote to support.

| Limit | Test mode | Live |
| --- | --- | --- |
| Calls a minute | 30 | 30 |
| Calls a day, safety ceiling | 200 | 20,000, up to 200,000 |

## Permission names

These are the exact names to use when you create or request an agent key.

| Permission | What it allows | Access |
| --- | --- | --- |
| `read:events` | Activity. See what happened in your Space, like a task created or a form submitted. Newest first. | Open |
| `read:tasks` | Tasks. Look up a single task by its id. | Open |
| `read:users` | Member profiles. Look up a member's public profile. No email address. | Open |
| `read:forms` | Forms and answers. Read your forms and what people sent in. Answers can include personal details. The respondent email field is left out unless the key also has Member emails, but an email a person typed into an answer is still included. | Open |
| `read:payments` | Payments. Read the payment records for your Space. | Open |
| `read:users:pii` | Member emails. Adds each member's email address to profile lookups, and the respondent email address to form submissions. | Sensitive, by approval |
| `write:resources` | Manage your directory. Add, change or delete your directory entries from a spreadsheet or another system. | By approval |
| `read:site-files` | Read your site files. List your hosted sites, read their files and see the saved versions of a file. | Partner Spaces |
| `write:site-files` | Change your site files. Create, replace and delete files on your hosted site. Every change is versioned, scanned for secrets and logged, and deleted files go to the trash. | Partner Spaces |
| `write:forms` | Create and manage your forms. Create forms, change their settings, add, change, reorder and delete their fields, and pause or delete a form that has no submissions. Registration forms stay with the owner, and no submission is read or changed. | Partner Spaces |
| `read:engagement-types` | Read your engagement types. List and read the engagement types of your Space: their stages, the form and booking type they link to, and their default items. No engagement or client is read. | Partner Spaces |
| `write:engagement-types` | Create and manage your engagement types. Create engagement types, change their stages, linked form, booking type and default items, switch them off, and delete a type no engagement uses. No engagement or client is read or changed. | Partner Spaces |

## When the agent needs more

The agent asks with a reason. You get an email, see its reason on the key page, and approve or decline. Approving shows what the permission lets the agent do before anything changes. Member emails then go to Bynefit for review, usually within one business day. If your Space does not have directory management yet, approving it also asks Bynefit to turn it on for the Space; the key gets it as soon as that is approved.

**cURL**

```bash
curl -X POST https://bynefit.com/dash/api/v1/agent/access-requests \
  -H "Authorization: Bearer $BYNEFIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"permission": "NAME_FROM_CAN_REQUEST", "reason": "Add the pantry hours we collect from partners to the directory."}'
```

**JavaScript**

```javascript
const res = await fetch('https://bynefit.com/dash/api/v1/agent/access-requests', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BYNEFIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    permission: 'NAME_FROM_CAN_REQUEST',
    reason: 'Add the pantry hours we collect from partners to the directory.',
  }),
});
console.log(res.status, await res.json());
```

**Python**

```python
import os
import requests

res = requests.post(
    'https://bynefit.com/dash/api/v1/agent/access-requests',
    headers={'Authorization': f"Bearer {os.environ['BYNEFIT_API_KEY']}"},
    json={
        'permission': 'NAME_FROM_CAN_REQUEST',
        'reason': 'Add the pantry hours we collect from partners to the directory.',
    },
)
print(res.status_code, res.json())
```

Use a `permission` from `can_request`. The reason must be 20 to 500 characters. A new request answers `201`. The same permission twice answers `409 already_requested`, and a key can have 3 requests waiting at once. After the owner declines a permission, asking for it again within 24 hours answers `429 recently_declined`.

## What you can see

Each key has its own page with five tabs. *Overview* shows its state, today's calls, units and what it can do, with the next step. *Access* holds its permissions, the requests waiting for an answer and the addresses it may connect from. *Activity* is the call log and the saved copies. *Usage and billing* shows the Space's unit balance and the key's use by day. *Settings* holds notifications, limits and the danger zone. The address ends in the tab name, so you can link straight to one.

The Activity tab lists every call: when, the method and path, the result, the permission it used, how long it took, how much data went each way and the request id, with a usage table by day (calls, failures, data, typical and slow response times). The log keeps 30 days, up to the last 5,000 calls per key. The caller's network address is kept only as a one-way code, used to spot one source driving several keys.

A private, encrypted copy of what the agent sent and what came back is kept for up to 365 days (the owner can choose a shorter time, from 30 days, or delete it at any time): the first 4,096 bytes of each, after passwords, keys, member emails, phone numbers and names are removed. The contents of site files are never kept, only their size and a fingerprint. The owner can read and download them from the key page. Bynefit staff can read them only to look into abuse or a security problem, or at the owner's request, and each time is recorded.

The key page also flags unusual activity: a burst of failed calls, many calls refused for a missing permission, many different endpoints in a minute, a burst of changes, or the same network address driving several keys. A flag blocks nothing; the owner is emailed once a day at most, when activity emails are on.

The owner is emailed on the agent's first call, when it uses up a day's ceiling and when many of its calls fail in an hour. Space admins are emailed when units reach 80% and 100%, 30 days before pack credit expires, and when a purchase, automatic top up or extra usage is billed. Those three can be switched off per key. Pauses, expiry, going live and access requests are always emailed.

## Expiry and renewal

The owner and the Space's admins and managers are emailed 7 days and 1 day before the key expires. The owner renews it for another 30 days with one click, and the agent keeps the same key. After the date the agent gets `401 token_expired` until it is renewed.

## Stop it

*Pause* works straight away: every call gets `403 agent_key_paused` until the owner resumes it. *Revoke* ends the key for good with `401 token_revoked`. The owner and any admin of the Space can do either, from the key page or from the API keys list. Bynefit staff can also pause or revoke any agent key, and the owner is emailed when they do; only the owner can resume it. If the owner stops being an active manager or admin of the Space, including while the Space is waiting to be deleted or is under moderation, the key stops too. A Bynefit staff account gets no exception.

## Who can do what

| Person | Can |
| --- | --- |
| The owner (the manager or admin who made it) | Everything: pause, resume, renew, move to live, a new key, IP addresses, emails, and approving or declining requests. |
| Any other admin of the Space | Pause and revoke, and see its activity. |
| Bynefit staff | Pause and revoke any agent key. Never resume, renew, move to live or approve access for the owner. |
| Any other manager of the Space | See it and its activity. |

## Errors an agent can get

| Status | Code | What to do |
| --- | --- | --- |
| 401 | `agent_key_header_only` | Send the key as Authorization: Bearer, never in the address. |
| 401 | `token_expired` | Stop and tell the owner. They can renew it. |
| 401 | `token_revoked` | Stop. The key is gone for good. |
| 403 | `agent_key_paused` | Stop and tell the owner. |
| 403 | `agent_owner_inactive` | The owner is no longer a manager or admin. Someone else must make a new key. |
| 403 | `ip_not_allowed` | Call from an address on the key, or ask the owner to add yours. |
| 403 | `insufficient_scope` | Ask for the permission instead of retrying. |
| 429 | `agent_rate_limited` | Wait for Retry-After. |
| 402 | `usage_exhausted` | The Space is out of units. Stop and tell the owner; the answer carries a top_up_url for them. |
| 429 | `agent_budget_spent` | Wait for Retry-After, or ask the owner to move the key to live or raise its ceiling. |
| 429 | `agent_limits_unavailable` | The limits could not be checked, so nothing ran. Wait for Retry-After. |

Agent refusals and `insufficient_scope` answers carry a `request_id` and a `docs_url` back to this page.

## Next steps

- [Building with an AI agent](https://bynefit.com/docs/ai-agents): the docs as Markdown and `llms.txt`.
- [Keys and review](https://bynefit.com/docs/keys): every kind of key side by side.
- [Support](https://bynefit.com/docs/support): quote the request id.

---

Source: https://bynefit.com/docs/agent-keys
Checked against the live API on October 10, 2026.