Agents

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 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. 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.

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 https://bynefit.com/dash/api/v1/agent \
  -H "Authorization: Bearer $BYNEFIT_API_KEY"

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);

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.

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.

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.

Permission names

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

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 -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."}'

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());

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

Errors an agent can get

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: the docs as Markdown and llms.txt.
• Keys and review: every kind of key side by side.
• Support: quote the request id.