> For the complete documentation index, see [llms.txt](https://docs.appmixer.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.appmixer.com/connector-configuration/toggl.md).

# Toggl

Get a Toggl API token and connect the Appmixer Toggl connector.

The Appmixer Toggl connector uses **API token** authentication. You do not need to register an app with Toggl. Each user generates an API token in their own Toggl profile and enters it when they connect Toggl in Appmixer.

The connector works with **Toggl** (the product formerly called Toggl 2.0 or Toggl Focus, at `focus.toggl.com`) and its API on `https://focus.toggl.com/api`. It does not work with the legacy **Toggl Track** API: a Toggl Track API token is a different credential and is rejected. New Toggl accounts are created in Toggl, not in Toggl Track.

***

## 1. Get the API token

1. Log in to [Toggl](https://focus.toggl.com).
2. Click your profile icon and open **Profile settings**.
3. Scroll to the **API token** section, pick an expiration and generate the token.
4. Copy the token right away. It starts with `toggl_sk_` and Toggl shows it only once.

Things to know about the token:

* A user has one active token. Generating a new token revokes the previous one, and every Appmixer account connected with the old token stops working until it is reconnected.
* The token expires after the period you picked. Reconnect the account in Appmixer with a new token before that date.
* The token acts as the Toggl user it belongs to, with that user's permissions in every organization and workspace. It has no scopes, so there is nothing else to select. Keep it secret.

***

## 2. Connect in Appmixer

When you add a Toggl component to a flow, Appmixer asks you to connect an account. The form has three fields:

* **API Token**: required. The token from step 1.
* **Organization ID** and **Workspace ID**: optional. Leave both empty to work in your default workspace. To work in another workspace, fill in both. They are the two numbers in the Toggl URL: `focus.toggl.com/<organization>/workspaces/<workspace>/...`.

One connected account works in one workspace. To use several workspaces, connect one account for each.

Appmixer sends the token as a Bearer token in the `Authorization` header, as described in the [Toggl authentication docs](https://engineering.toggl.com/docs/focus/start/authentication/). To check the token, it looks up your default workspace, or lists the projects of the workspace you entered. The connection is named after the workspace.

**Make API Call** accepts a path relative to `https://focus.toggl.com/api`, or a full URL on `https://focus.toggl.com`. Any other host is rejected so that the token is never sent elsewhere. Most Toggl endpoints are addressed by organization and workspace. Type `{organization_id}` and `{workspace_id}` in the path as they are, and Appmixer replaces them with the organization and workspace of the connected account, for example `/organizations/{organization_id}/workspaces/{workspace_id}/tasks`.

***

## 3. Triggers

The Toggl API has no webhooks, so every trigger polls. You do not need to set up anything in Toggl, and your Appmixer API does not need to be reachable from Toggl.

* **New Time Entry**: fires when the connected user creates a time entry, a started timer included.
* **Time Entry Updated**: fires when a time entry of the connected user is changed, a stopped timer included. Deleted time entries do not fire it.
* **New Project**: fires when a project is created in the workspace, by anyone.

How the polling works:

* Each trigger checks Toggl every 5 minutes, so an event can take up to 5 minutes to arrive.
* The first check after the flow starts only records where the account stands. It fires for nothing that already exists.
* The time entry triggers see only the time entries of the connected user, because that is all the Toggl API lists for a user. They watch entries that cover the last 30 days.

***

## Rate limits

Toggl limits API requests per hour by plan: Free 30, Starter 240, Premium 600 requests per hour (custom on Enterprise). See the [Toggl API announcement](https://community.toggl.com/t/toggl-2-0-public-api/4434).

* Each running trigger uses 12 requests per hour. On the Free plan, two triggers use most of the hourly quota.
* The connector queues requests at 1 request per second per Appmixer user and retries a 429 response.
* When Toggl answers 402 (the quota is used up, or the feature needs a paid plan), the component fails with a message that says so.
* The connector caches the project dropdown in the inspector and the default workspace of the account, to save requests.

***

## Backoffice configuration

Configuration ID: `appmixer:toggl`. For how to set connector configuration values, see [Connector Configuration](https://docs.appmixer.com/getting-started/services).

You do not need any Backoffice configuration to authenticate, because every user enters their own API token. There are two optional keys:

* `listCacheTTL`: optional. How long, in milliseconds, the list of projects shown in the inspector dropdowns is cached. The default is `120000` (2 minutes). A longer value saves requests from the hourly Toggl quota.
* `outputFilePrefix`: optional. A prefix for the names of CSV files created when **Find Time Entries**, **Find Report Time Entries** or **List Projects** runs with the **Store to CSV file** output type. Files are named `<prefix>-<component label in the flow>.csv`. The default is `toggl-objects-export`.

```bash
appmixer service-config set appmixer:toggl -u -d '{
  "listCacheTTL": 120000,
  "outputFilePrefix": "toggl-objects-export"
}'
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.appmixer.com/connector-configuration/toggl.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
