About Beekeeper
Beekeeper is a mobile-first communication and operations platform for frontline workforces, now part of LumApps. It gives non-desk employees a single app for company news streams, chat, tasks, shift schedules, forms, and documents. Serval connects to your Beekeeper tenant using a bot access token plus your tenant subdomain, and attaches the token securely to every request it sends to Beekeeper on your behalf. Once connected, Serval workflows can reach frontline employees where they already work - sending messages, assigning tasks, managing shifts and events, and reading back submissions and profile data. Authentication: API key (bot access token + subdomain). No OAuth flow, and the bot token does not expire. Data sync: On-demand only. There is no background sync or data ingestion - Serval calls your Beekeeper tenant’s API at the moment a workflow runs.What the Beekeeper integration enables
| Capability | Description |
|---|---|
| People, posts, and groups | Look up users and profiles, and work with posts, streams, comments, files, groups, conversations, and surveys. |
| Tasks | Manage tasks, subtasks, approvals, task history, and exports. |
| Shifts | Work with schedules, shifts, and shift imports (including bulk shift imports). |
| Forms | Access forms, submissions, permissions, and surveys. |
| Company events | Manage company events, audiences, and invitees. |
| Chats | Work with group chats, chat members, and messages (Chats 2.0). |
| Artifacts | Manage files, folders, and their access control lists. |
| Beekeeper workflows | Read and manage Beekeeper’s own workflow definitions, executions, and inventory. |
| Webhook subscriptions | Manage your tenant’s Beekeeper webhook subscriptions. |
| Create Task (installable workflow) | Creates a new Beekeeper task in the To Do state, with a title, description, optional assignee, and optional due date. Requires installer approval by default. |
| Send Direct Message (installable workflow) | Sends a chat message to a Beekeeper user; the message body supports rich text. Requires installer approval by default. |
Get your credentials
Serval connects with a bot account created in your Beekeeper admin dashboard. You will need the bot’s API access token and your tenant subdomain. Beekeeper’s official guide is here: Set up a bot account in the dashboard.Sign in to your Beekeeper dashboard as an administrator
Go to your tenant’s dashboard (your-subdomain.beekeeper.io) and click the speedometer icon on the right-hand side of the top navigation bar to open the admin dashboard. Admin access is required to manage bot accounts.
Open Extensions, then Bot Accounts
In the left navigation, open the Extensions tab, then the Bot Accounts subtab.
Add a new bot account
Create a bot account and give it a recognizable name, for example “Serval”. The bot’s name and avatar are what employees see when Serval posts or messages on its behalf.
Copy the bot's API access token
Copy the token from the Bot Accounts list (a UUID-like value such as
fae00bbc-b0f6-4ace-8e13-7d53b58076e1) and keep it somewhere safe. You will paste it into Serval in the next section.Grant the bot the permissions it needs
Give the bot access to the surfaces you plan to use - for example, admin permission for posting, plus access to Tasks, Shifts, and Forms if you rely on those areas.
Beekeeper bot access tokens do not expire. To revoke Serval’s access, delete or regenerate the token in the Beekeeper dashboard.
Connect in Serval
Open the Beekeeper connect form
In Serval, add the Beekeeper integration to open the connect form. Both fields are required - leaving either blank shows “This field is required”.
Enter your Subdomain
Fill in Subdomain - “Your Beekeeper subdomain, e.g. ‘company’ for company.beekeeper.io”. The field is forgiving: pasting company, company.beekeeper.io, or a full URL all resolve to the bare lowercase subdomain. The subdomain also becomes the connection’s display name in Serval.
Enter your Access Token
Fill in Access Token - “Bot access token from your Beekeeper dashboard (Authorization: Token …). The token does not expire.” It is a password-style field, so the value is hidden as you type. Paste the raw token only. After saving, the token is shown masked - bullets with only the last 4 characters visible.
Verifying the connection
Health checks run once automatically after you create the connection, and you can re-run them anytime from the Health Checks section on the connection’s settings page. The status check calls Beekeeper’s authenticatedGET /api/2/status endpoint.
| Health check | What it verifies | On success | On failure |
|---|---|---|---|
| Get Beekeeper Status | The subdomain and access token are valid and Beekeeper is reachable. | ”Successfully reached the Beekeeper API." | "Unable to reach Beekeeper. Please verify the subdomain and access token are correct.” |
| List Beekeeper Schedules | The Shifts area is reachable with your token’s permissions; reports how many schedules came back. | ”Successfully listed schedules from Beekeeper (sample size: [number])." | "Unable to list schedules from Beekeeper. Please verify the access token has Shifts permissions.” |
| List Beekeeper Forms | The Forms area is reachable with your token’s permissions. | ”Successfully listed forms from Beekeeper." | "Unable to list forms from Beekeeper. Please verify the access token has Forms permissions.” |
Gotchas and troubleshooting
Editing the connection? Re-enter both fields
Editing the connection? Re-enter both fields
Any time you update this connection - rotating the token, fixing the subdomain, or anything else - re-enter both values before saving. Keep the Subdomain filled in, and click Replace next to the Access Token and paste the full token. Do not save while the Access Token still shows only its masked value, and do not clear a pre-filled field - the connection can stop working until both values are entered again.
Paste the raw token only - no prefix
Paste the raw token only - no prefix
Beekeeper uses a “Token” authorization scheme rather than the more common “Bearer” (see Beekeeper’s authentication guide). Serval handles this automatically, so paste only the raw token value into the Access Token field. Including a “Token ” or “Bearer ” prefix will break authentication.
Shifts or Forms health checks fail while Get Status passes
Shifts or Forms health checks fail while Get Status passes
These two checks exercise product-specific permissions. A failing Schedules or Forms check with a passing status check means the bot account needs Shifts or Forms access granted in the Beekeeper dashboard - the token itself is fine.
The Subdomain field accepts almost any format
The Subdomain field accepts almost any format
You can paste company, company.beekeeper.io, or a full URL with a trailing slash - Serval normalizes them all to the bare lowercase subdomain (everything before the first dot, with any protocol and trailing slash stripped). That normalized subdomain also becomes the connection’s display name in Serval.
The token never expires, but rotation is manual
The token never expires, but rotation is manual
There is no reconnect cadence to plan for. However, if you rotate or delete the bot account in Beekeeper, the connection breaks until you update it in Serval - and when you do, keep the Subdomain filled in and use Replace to paste the new token in full.
Beekeeper developer links redirect to LumApps
Beekeeper developer links redirect to LumApps
Following the LumApps acquisition, developers.beekeeper.io links - including the developer portal itself - redirect to api.lumapps.com. The links in this page were verified to resolve - if a provider link looks unfamiliar, that redirect is why.
Additional resources
For admin guides, including bot account management, see the Beekeeper Help Center. The full REST API reference is available in the Beekeeper API documentation.Need help? Contact support@serval.com for assistance with your Beekeeper integration.