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 __Secure-accounts-session, which you can use for authentication in all the API requests.

Example request:

curl -i '' -X POST -d '{"email":"<your-email>","password":"<your-password>"}' -H 'Content-Type: application/json'

Successful response header includes the cookie:

Set-Cookie: __Secure-accounts-session=eyJhbGciOiJFZERTQSIsImtpZCI6IjIwMjMtMDctMjUiLCJ0eXAiOiJKV1QifQ.
clcifQo.MXtwBQx37PLm8t0rRlNbIkoe2n_xJFxmFWxV2RU0ii8c0fA0GYmzT2EK6FqSy1AcSN6ZyLM5McoSUvKl8nwmCA; 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:

curl --cookie __Secure-accounts-session=<cookie value> -X DELETE

Sign Up for an Account

curl -i '' -X POST -d '{"email":"<your email>","password":"<your password>","display_name":"<your name>","tos_accepted_for":"track", "remember_me":true, "timezone":"America/New_York"}' -H 'Content-Type: application/json'

Closing an account

curl --cookie __Secure-accounts-session=<cookie value> '' -X POST

Password Reset

Requesting a password reset code

curl -d '{"email": "<your email>"}' -H 'Content-Type: application/json'

Note: upon success a password reset code will be generated and sent to the specified email address.

Set new password

Reset the password using the obtained code like this:

curl -X POST -H 'Content-Type: application/json'<password reset code> -d '{"password":"<new password>"}' -i

Note: at this point you will receive a new __Secure-accounts-session cookie and the password for <email address> will be updated.

© 2024 Toggl. All rights reserved.