Skip to main content

Authentication

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.

info

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

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

ERROR

If authentication fails, HTTP status code 403 is returned.

HTTP Basic Auth with email and password​

Example request:

curl -u <email>:<password> https://api.track.toggl.com/api/v9/me

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 https://api.track.toggl.com/api/v9/me

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 'https://accounts.toggl.com/api/sessions' -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.
eyJhdWQiOlsidHJhY2siXSwiZXhwIjoxNzAxMDM4MDM1LCJpYXQiOjE2OTg2MTg4MzUsImlzcyI6Imh0dHBzOi8vYWNjb3VudHMudG9nZ2wuY29tIiwianRpIjoiZDkyYTQ2NGI3ZTY4MjQ4ZjA1YzY1NmE2ZWQzMTMxNGUiLCJuYmYiOjE2OTg2MTg1MzUsInN1YiI6ImE4WmtoMkh2YlB1azR4TXBXUXBn
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 https://accounts.toggl.com/api/sessions

Sign Up for an Account​

curl -i 'https://accounts.toggl.com/api/signup' -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> 'https://accounts.toggl.com/api/me/close_account/track' -X POST

Password Reset​

Requesting a password reset code​

curl https://accounts.toggl.com/api/me/password_reset/request -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' https://accounts.toggl.com/api/me/password_reset/confirm/<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.