Agent keys for scripts and automations
Create an agent key, choose what it may do, see it once, rotate it before it expires and revoke it.
On this page
An agent key lets a script, an automation or a CI job talk to Verimly without a sign-in screen. The key acts as the person who created it, with at most that person's own rights. Anything that uses the key stops working the moment you revoke it.
If you use an app such as Claude or ChatGPT, you do not need a key: connect it as described in ai-connect.
Before you start
- Allow agents must be on in Settings › AI & agents. An owner controls it. If it is off, keys stop working.
- A key acts as you, so it can never see or change more than your role allows. A cashier who ticks Change the menu gets nothing extra, because the role cannot change the menu.
- If Read-only for everyone is on, every new key is read-only whatever you choose.
- Treat a key like a password: anyone who has it can act as you within its scopes.
Create a key
- Open Settings › AI & agents, find Agent keys and choose Create key.
- Enter a Name that says what it is for, such as Weekly report script.
- Under What it can do, keep Read-only on, or turn it off to allow changes and tick the scopes you need (see below). See your business is always included.
- Under Locations choose All locations, or Only these locations and pick at least one.
- Choose Expires: after 30, 90 or 365 days. Every key expires; there is no key that lives forever.
- Choose Create key.
- Copy your key now. It starts with
vk_live_and is shown only once. Store it in a password manager or your CI secrets, then choose I've copied it.
Send the key in the Authorization header as a bearer token: Authorization: Bearer vk_live_…. A key works on both the full and the Read-only server address shown on the same page. Keys cannot ask a person to approve more access, so they cannot go beyond the scopes you gave them.
Scopes
| Scope | What it allows |
|---|---|
| See your business | Sales, menu, stock, staff schedule, reservations and reports: what you can see yourself |
| Change the menu | Products, prices, categories and what is sold out |
| Manage reservations | Create, move and cancel bookings |
| Manage staff and shifts | Staff profiles, invitations and the schedule |
| Handle online orders | Accept online orders and update their status and notes. Never refunds or voids. No agent action uses this scope yet. |
Agents can never move money: no refunds, voids, payouts or payment settings.
See and manage keys
The list shows each key with its name, the first characters of the key, who it Acts as, Last used (or Not used yet), and Expires or Expired with the date. Owners see all keys of the business; everyone else sees their own.
Rotate a key before it expires
Choose Rotate on the key. You get a new secret with the same settings, and the old one stops working at once. The new key keeps the remaining days. Update your script straight away. An owner who rotates someone else's key takes it over: the new key acts as the owner.
Revoke a key
Choose Revoke and confirm. Anything using the key stops working at once. Do this if the key was pasted somewhere it should not be, a teammate leaves, or the script is retired.
When a person is removed from the business, their keys and connected apps are revoked as well.
Limits
- Calls are counted per month for the business: Starter 3000, Pro 10000 and Business 30000 per location, pooled. The page shows … of … agent calls and when it resets.
- Each key can make 60 calls a minute on Starter and Pro, 120 on Business. Over the limit the call is refused with a message to wait.
Common questions
I lost the key
It cannot be shown again. Create a new key (or rotate the old one) and revoke the lost one.
The key worked yesterday and now returns an error
It may be revoked (AGENT_KEY_REVOKED), expired, or Allow agents may be off (MCP_DISABLED). Check the key in the list and the switch on the page.
Why can the key read but not change anything?
Read-only is on for the key, or Read-only for everyone is on for the business, or the scope was not selected. See AGENT_READ_ONLY in agent-safety.
If something goes wrong
Look at Activity on the same page: it lists every action by agents, with result and time. For a leaked key, revoke it first and then check the audit log for what it did. Use contact-support if you need help.