Licences and limits
A request with an API key passes two checks before it does anything: the licences, then the key's own permissions. This page says what each check refuses and lists the limits that apply. It states the rules plainly, so you can tell a customer what a key can and can't reach before they buy.
The rule
The API Licence works with the Manager Licence or the User App Licence. It does nothing on its own. A key reaches only what those licences cover.
- With a Manager Licence, a key reaches everything the API offers: locations, location state, commands, schedules and connection status.
- With only a User App Licence, a key reaches locations, location state, commands and connection status. There are no schedules by key or by MCP. Every schedule request is refused.
- With neither, a key reaches nothing, even with an API Licence.
- Without the API Licence, a key reaches nothing, whatever other licences the processor has.
Which licences a request needs
| API Licence | Manager Licence | User App Licence | What a key can do |
|---|---|---|---|
| Missing | Any | Any | Nothing. Every request is refused with 423, naming api. |
| Active | Active | Any | Locations, location state, commands, schedules and connection status, as far as the key's permissions go. |
| Active | Not active | Active | Locations, location state, commands and connection status. Every schedule request is refused with 423, naming rooms. |
| Active | Not active | Not active | Nothing. Every request is refused with 423, naming api. |
| Active | Read-only days | Not active | Reading only. Commands and schedule changes are refused with 423, naming rooms. Schedules can still be read. |
| Active | Read-only days | Active | Locations, location state, commands and connection status. Schedules can be read, but changing one is refused with 423, naming rooms. |
In a refusal, rooms is the Manager Licence and api is the API Licence. The Manager Licence's feature is named rooms for historical reasons.
Some details that decide a case:
- A Manager Licence trial counts as a Manager Licence. The API Licence has no trial: a processor with no API Licence key refuses every key, even while its Manager Licence is on trial.
- Demo mode doesn't count as an API Licence. While demo mode is on, a key is refused with 423 unless the processor has an API Licence.
- Read-only days are the 30 days after a Manager Licence ends. A key can read, as people can, but can't change schedules until a Manager Licence is added. Without a User App Licence it can't send commands either; with one it still can. See Licensing and editions.
- Making, changing and revoking keys doesn't need any licence. Keys you make before the API Licence is added are kept, and work as soon as it is.
- Staff aren't held to the API Licence. It only applies to requests that sign in with a key.
A refusal is always the same shape: 423, then a body with the feature that is missing and a sentence that stands by itself. These are the three sentences:
| Case | feature | errorDetails.title |
|---|---|---|
| No API Licence | api | This processor has no API Licence. Add one on the licence page to use the API. |
| An API Licence but neither of the other two | api | The API Licence works with a Manager Licence or a User App Licence, and this processor has neither. Add one on the licence page to use the API. |
| Schedules with no Manager Licence | rooms | This processor has no Manager Licence. Add one on the licence page to use locations and schedules. |
{
"success": false,
"errorDetails": {
"title": "This processor has no API Licence. Add one on the licence page to use the API.",
"messages": []
},
"feature": "api"
}
Over MCP the same rule applies tool by tool. Without the API Licence every request, tools/list included, is refused with 423. With only a User App Licence the schedule tools answer with a message that the processor has no Manager Licence. See MCP.
Permissions
The licences say what the processor offers. A key's permissions say what that key may do. A request the key isn't allowed to make is refused with 403; over MCP, the tool answers with a message saying which permission is missing.
Licences are checked first. A key with no permission to send commands, on a processor with no API Licence, is told about the licence with 423, not about the permission.
What a key cannot do
Keys cannot administer the processor. A key never reaches settings, the licence, upgrades, backup and restore, certificates, Administrators, other API keys, connections' own pages, touch screens, the User App or anything else an Administrator does. The processor answers a key on any of those routes as it would answer a stranger: 401. A key can't make, change or revoke another key.
Which routes a key can reach is fixed in the program and checked every time the processor is built, so a new page can't become reachable by a key by accident. The full list is on REST API.
The same key also works on the Stay API, if it has the stay permissions. The stay API is part of the API Licence.
Where keys are accepted
| Port | Default | Keys |
|---|---|---|
| HTTPS, the admin port | 8443 | Accepted. This is the only port that takes keys. |
| Plain HTTP | 8080 | Refused with 400: "Use HTTPS. Keys are not taken over plain HTTP." The request isn't redirected, because the key would already have been sent in the clear. |
| User App | 8180 | Refused with 400. |
| Connection | 8543 | Refused with 400. |
The plain HTTP port still serves the processor's certificate download to a request with no key. These are the defaults. If your ports are different, use your admin HTTPS port. See Ports and network.
Where it can be reached from
MCP is reachable on the site network only. So is the REST API. Your system has to reach the processor's admin HTTPS port directly, from the same network or one routed to it. A service that runs on the internet, such as a hosted AI assistant, can't call a processor on your site network.
Run the assistant on a computer on the site network.
Don't open the admin HTTPS port to the internet to get round this. A key only proves who is calling; it doesn't make the processor safe to expose.
Rate limits
| Limit | Value | When it's reached |
|---|---|---|
| Requests with one key | 300 a minute, REST and MCP together | 429 with Retry-After: 60. Other keys aren't affected. |
| Requests with a key the processor doesn't know, from one address | About 10 a minute | 429 to that address with Retry-After: 60. A key that is known still gets in from that address. |
A request that is refused still counts. If a program is retrying a refused request in a loop, fix the cause first. After a minute with no wrong keys, the address is free again.
Other limits
- 10 keys can be in use at once. Revoked and expired keys don't count.
- A schedule or a command is the same as one made on the processor's own pages. Its limits are the same.
- A request body on
/mcpcan be up to 256 KB; more is refused with 413. - A command status request can ask about up to 2,000 commands.
list_locationsreturns up to 500 locations in one call.- While demo mode is on, and the processor has an API Licence, a key sees the demo's locations, not the site's.