Authentication
API keys
On this page
An API key is a credential for one person in one company. It acts as that person, with their role, for one audience: Manage or Me. Send it as a bearer token:
Authorization: Bearer hrk_<id>_<secret>The key decides the company: there is no company id in requests.
Manage keys and Me keys#
| Manage key | Me key | |
|---|---|---|
| Acts like | The person in Manage, the HR app | The person in the employee app |
| Can use | Every Manage action their role allows: people, jobs, structure, invites, settings, webhooks | Their own profile, team, documents and tasks, the directory and the org chart |
| Who can create one | Owners, admins, HR and viewers | Everyone, including members |
| MCP server | /mcp/manage (HR Assistant) | /mcp/me (My Workplace) |
The API reference lists, for every action, which key may call it and with which roles. An action that isn't on the key's audience answers 404 not_found ("Unknown action"), as if it didn't exist.
Bizisy keys have no finer scopes than the audience: a key can do what its person can do there. For least privilege, create the key from a login whose role allows only what the integration needs, and prefer a Me key when the integration only acts for one person.
Create a key#
Keys are created only by a person signed in to Bizisy, never through the API or MCP, so a key can never mint another key.
- Manage → Integrations → API keys: a Manage or a Me key.
- Employee app → AI apps → API keys (the Connect AI button at the top, then Manage AI apps): a Me key.
Name it after the integration ("Payroll sync", "Claude Desktop"): the name shows in Activity next to everything the key does. The secret is shown once; Bizisy stores only a fingerprint (a SHA-256 hash) of it, so a lost key can't be recovered. Create a new one.
Use it#
- REST:
https://api.bizisy.com/v1/<module>/<action>. The API host accepts API keys only, never browser sessions. - MCP:
https://api.bizisy.com/mcp/manageorhttps://api.bizisy.com/mcp/mewith the same header (a Manage key on/mcp/manage, a Me key on/mcp/me). - Your company's address also accepts the key (
https://<company>.bizisy.com/mcp/manage), but only a key of that company.
Keep keys on servers. The API sends no CORS headers, so a page on another site can't call it, and a key in front-end code would be visible to anyone.
What follows the person#
A key is checked on every request against the person's current access:
- Role changes apply at once. If an admin becomes a viewer, their keys can do what a viewer can do from the next request. If they become a member, their Manage keys answer
403 forbidden(a member has no Manage access); their Me keys keep working. - Disabling a member stops their keys immediately, as do their sessions.
- Closing the company stops every key. If an owner reopens it, keys created before the closure stay refused: create new ones.
- Sign-in methods don't affect keys: turning off password or Google sign-in leaves keys working. Revoke them under API keys.
Keys don't expire.
Rotate a key#
There is no rotate button: rotate by overlap.
- Create a new key with the same name and a suffix ("Payroll sync 2").
- Deploy it to your integration.
- Watch Last used on the old key in Integrations → API keys (or
platform.api_keys.list,last_used_at, updated at most once a minute). When it stops moving, revoke it.
Revoke a key#
Revoke in Integrations → API keys (or Connect AI), or call platform.api_keys.revoke. It stops working at once. You can list and revoke only your own keys; an owner or admin who needs to stop someone else's keys disables that member or changes their role.
When the company switches API keys off#
Owners and admins can switch API keys off in Settings → Features, separately for Bizisy (HR, managers and admins) and for My workspace. Keys on a side that is off answer 403 api_disabled on REST and MCP, and no new key can be created there. The keys are kept: they work again as soon as the side is switched back on, unless the owner also chose to revoke them. People whose keys stop working get an email. When AI assistants are switched off for a side, that side's keys are refused over MCP with ai_disabled and keep working on REST.
Failed authentication#
A missing, malformed, revoked or unknown key answers 401 unauthenticated. On the API host, an address whose requests fail authentication 60 times within a minute gets 429 rate_limited for the rest of that minute, before any key is checked.
Something missing or wrong on this page? Write to hello@bizisy.com.