Skip to main content

​
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

Anything defined in the Beekeeper API can be accessed through Serval.

​
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.
1

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.
2

Open Extensions, then Bot Accounts

In the left navigation, open the Extensions tab, then the Bot Accounts subtab.
3

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.
4

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.
5

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.
6

Note your tenant subdomain

This is the “company” part of company.beekeeper.io. You will enter it in Serval alongside the token. Serval uses it to build the base URL https://company.beekeeper.io/api/2/ for every API call.
Copy the token only - do not include any “Token ” or “Bearer ” prefix when you paste it into Serval. Serval adds the correct authorization scheme automatically.
Beekeeper bot access tokens do not expire. To revoke Serval’s access, delete or regenerate the token in the Beekeeper dashboard.
If a Beekeeper developer link opens on api.lumapps.com, that is expected - Beekeeper’s developer docs moved under LumApps after the acquisition, and the old links redirect there.

​
Connect in Serval

1

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”.
2

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.
3

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.
4

Save the connection

Health checks run automatically right after the connection is created (see Verifying the connection below).
When editing an existing Beekeeper connection, always 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 clear a pre-filled field, and do not save while the Access Token still shows only its masked value - re-enter both values any time you update the connection, including token rotations.

​
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 authenticated GET /api/2/status endpoint.
If “Get Beekeeper Status” passes but the Schedules or Forms checks fail, your token is valid - the bot account just lacks Shifts or Forms permissions in Beekeeper. Grant the bot those product permissions in the dashboard, or expect those two checks to fail if you do not use those areas.

​
Gotchas and troubleshooting

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.
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.
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.
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.
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.

​
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.