> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Beekeeper

> Connect Serval to Beekeeper, the frontline-workforce communication platform, so workflows can manage tasks, shifts, forms, chats, and more in your tenant.

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

Anything defined in the [Beekeeper API](https://developers.beekeeper.io/docs/beekeeper-api/a5a2c5e292428-beekeeper-rest-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](https://developers.beekeeper.io/docs/articles/ZG9jOjMyNzYwMDc5-1-set-up-a-bot-account-in-the-dashboard).

<Steps>
  <Step title="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.
  </Step>

  <Step title="Open Extensions, then Bot Accounts">
    In the left navigation, open the **Extensions** tab, then the **Bot Accounts** subtab.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

<Info>
  Beekeeper bot access tokens do not expire. To revoke Serval's access, delete or regenerate the token in the Beekeeper dashboard.
</Info>

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

## Connect in Serval

<Steps>
  <Step title="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".
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Save the connection">
    Health checks run automatically right after the connection is created (see Verifying the connection below).
  </Step>
</Steps>

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

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

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

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

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Paste the raw token only - no prefix">
    Beekeeper uses a "Token" authorization scheme rather than the more common "Bearer" (see [Beekeeper's authentication guide](https://developers.beekeeper.io/docs/articles/0e819f41aa404-authentication)). 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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Additional resources

For admin guides, including bot account management, see the [Beekeeper Help Center](https://help.beekeeper.io/). The full REST API reference is available in the [Beekeeper API documentation](https://developers.beekeeper.io/docs/beekeeper-api/a5a2c5e292428-beekeeper-rest-api).

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Beekeeper integration.