Skip to main content


To use the API, you need to authenticate yourself. This can be done via HTTP POST or HTTP Basic Auth. After successful authentication a session is created using a cookie.


In all the reference's snippet codes you will find <email> and <password> as fields to be replaced in order to authenticate with email and password.

The snippet codes already include required code to use email and password with the basic auth. In the following, we are going to explain all possible authentication mechanisms you can exploit to perform API requests.

In general, for HTTP Basic Auth, you have to add the Authorization header with the request. The Authorization header is constructed as follows:

  • In case email and password are used, they are combined into a email:password format
  • In case the api token is used, it is combined in xxxx:api_token format (xxxx indicating user's personal token)
  • The resulting string literal is then encoded using Base64
  • The authorization method and a space i.e. "Basic " is then put before the encoded string.

Aladdin:open sesame => Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==


If authentication fails, HTTP status code 403 is returned.

HTTP Basic Auth with email and password

Example request:

curl -u <email>:<password>

HTTP Basic Auth with API token

When using Basic Auth and API token, use the API token as email and string "api_token" as password.

Example request:

curl -u 1971800d4d82861d8f2c1651fea4d212:api_token

It's possible to create a session. The session creation request sets a cookie in the response header __Host-timer-session, which you can use for authentication in all the API requests.

Example request:

curl -u 1971800d4d82861d8f2c1651fea4d212:api_token -X POST

Successful response header includes the cookie:

Set-Cookie: __Host-timer-session=MTM2MzA4MJa8jA3OHxEdi1CQkFFQ180SUFBUkFCRUFBQVlQLUNBQUVHYzNSeWFXNW5EQXdBQ25ObGMzTnBiMjVmYVdRR2MzUnlhVzVuREQ0QVBIUnZaMmRzTFdGd2FTMXpaWE56YVc5dUxUSXRaalU1WmpaalpEUTVOV1ZsTVRoaE1UaGhaalpqWkRkbU5XWTJNV0psWVRnd09EWmlPVEV3WkE9PXweAkG7kI6NBG-iqvhNn1MSDhkz2Pz_UYTzdBvZjCaA==; Path=/; HttpOnly; Secure; SameSite=Lax

Destroy the session

Destroy the session manually by sending an according request to the API. You can use all the methods listed above. The example below uses the response from authentication with a session cookie.

Example request:

© 2022 Toggl. All rights reserved.