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

# Custom Integrations via GraphQL API

> Build custom integrations with Beebole using the GraphQL API. Read and write your account data programmatically to connect Beebole to any tool.

Beebole's GraphQL API lets you build custom integrations that connect Beebole to any tool or internal system your organization uses. When the built-in integrations don't cover your needs, the API gives you full programmatic access to read and write your Beebole account data.

This page is a starting point. For endpoints, authentication details, queries, and mutations, see the [API introduction](/help/api/introduction).

## What you can build

Beebole's GraphQL API supports both queries (reading data) and mutations (creating or updating data). Common custom integrations include:

| Use case                   | What it does                                                                      |
| -------------------------- | --------------------------------------------------------------------------------- |
| **HR system sync**         | Create and update people in Beebole when employees change in your HR platform.    |
| **Custom reporting**       | Pull time records, project data, and financial summaries into your own dashboard. |
| **Automated time entries** | Create time entries programmatically from data in other systems.                  |
| **Project provisioning**   | Create projects and subprojects in Beebole from your internal tools.              |
| **Payroll export**         | Extract approved time data in the format your payroll provider requires.          |

## Getting your API key

<Steps>
  <Step title="Access the API documentation">
    Review the full API reference in the [API documentation](/help/api/introduction) tab. It covers authentication, the schema explorer, available queries, and mutations.
  </Step>

  <Step title="Generate an API token">
    Go to **Settings** > **API** in your Beebole account to generate an API token. This token authenticates your requests.

    <Warning>
      Keep your API token secure. Do not share it in client-side code or public repositories.
    </Warning>
  </Step>

  <Step title="Explore the schema">
    Use the [schema explorer](/help/api/schema-explorer) to browse all available types, queries, and mutations. This helps you understand the data model before writing your integration.
  </Step>

  <Step title="Build and test your integration">
    Start with simple queries to read data, then move to mutations when you are ready to create or update records. Test thoroughly in a development environment before deploying to production.
  </Step>
</Steps>

Every person in Beebole has a personal **API Key** that authenticates their API requests. The key is created automatically and does not expire.

<Steps>
  <Step title="Open your API key">
    Click the button with your initials at the bottom of the sidebar, then choose **API Key**.
  </Step>

  <Step title="Copy the key">
    Click **Copy** to copy your **API Key** to the clipboard.
  </Step>

  <Step title="Authenticate your requests">
    Include the key in your API requests as described in the [API introduction](/help/api/introduction).
  </Step>
</Steps>

<Warning>
  Keep your API key secure. Don't include it in client-side code or commit it to public repositories — store it in an environment variable or a secrets manager. If a key is compromised, click **Reset** to revoke it and generate a new one.
</Warning>

## Best practices

<Tip>
  Start with a read-only integration (queries only) to validate your data mapping before writing data back to Beebole.
</Tip>

* **Use clear names** for projects and people created through the API so they are easy to recognize in Beebole.
* **Handle errors gracefully.** The API returns descriptive error messages — log and handle them in your code.
* **Keep your key secure.** Store it in an environment variable or a secrets manager, not in source code.

## Related content

<CardGroup cols={2}>
  <Card title="API introduction" icon="book" href="/help/api/introduction">
    Authenticate with the Beebole GraphQL API and send your first request.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/help/integrations/webhooks">
    Send real-time Beebole event notifications to your own services.
  </Card>

  <Card title="All integrations" icon="plug" href="/help/integrations/introduction">
    Browse the built-in Beebole integrations.
  </Card>
</CardGroup>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Where do I find my API key in Beebole?">
    Click the button with your initials at the bottom of the sidebar, then choose **API Key**. Your key is shown there with **Copy** and **Reset** actions. Beebole creates one key per person automatically, and it does not expire.
  </Accordion>

  <Accordion title="What programming languages can I use?">
    Any language with an HTTP client. The Beebole API uses standard GraphQL over HTTPS, so Python, JavaScript, Ruby, Go, Java, and others all work.
  </Accordion>

  <Accordion title="Can I create time entries through the API?">
    Yes. The Beebole API supports mutations for creating and updating time entries, projects, people, and other records. See the [API introduction](/help/api/introduction) for details.
  </Accordion>

  <Accordion title="What happens if I reset my API key?">
    Resetting revokes your current key and generates a new one. Any integration using the old key stops working until you update it with the new key, so reset only when you need to rotate a compromised key.
  </Accordion>
</AccordionGroup>