API keys

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#

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 → Settings → API keys: a Manage or a Me key.
• Employee app → Connect AI → API keys: 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/manage or https://api.bizisy.com/mcp/me with 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.

1. Create a new key with the same name and a suffix ("Payroll sync 2").
2. Deploy it to your integration.
3. Watch Last used on the old key in Settings → 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 Settings → 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.

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.