Authentication

Tech Discussions Getting Started With API
, ,
1

To access the API, you must authenticate yourself. This can be done using either HTTP POST or HTTP Basic Auth. Once authentication is successful, a session is established through the use of a cookie.

:grey_exclamation: 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.

:bulb: EXAMPLE

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

:fire: 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

Authentication with a session cookie​

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

2

I remain confused about how session cookies are used for api authentication.

Is a session cookie always issued regardless of which auth method is used initially? In other words, do both Basic options (email:pw, or apitoken:api-token) set a session cookie?
If so, does that mean the session cookie is sufficient for all subsequent API requests? Or does every request need the Authorization header (in which case, what does the session cookie actually do?)

3

@slhenty

Thanks for the question! I’ll try to explain below. Feel free to comment if there’s further confusion. :slight_smile:

When is the session cookie created?
A session cookie (__Secure-accounts-session) is created when you authenticate using either email:password or API token via the appropriate login endpoint.

How is the session cookie used?
Once issued, the session cookie is automatically sent with each subsequent API request as part of the request headers. This means you don’t need to include the Authorization header after the session cookie is set—it serves as your authentication for all API requests.

What about ending the session?
You’ll need to manually destroy the session by making a logout request to the API when you’re done. Otherwise, the session will persist until it times out or is invalidated on the server side.

Why you might be confused:
The confusion likely arises from mixing session cookies with Authorization headers. To clarify:

  • Use the Authorization header (Basic auth or API token) once to log in.
  • After that, the session cookie takes over for all subsequent requests.

Let me know if it helped in the comment below, please :slight_smile:

4

I remain confused about how session cookies are used for api authentication.
Is a session cookie always issued regardless of which auth method is used initially? In other words, do both Basic options (email:pw, or apitoken:api-token) set a session cookie?

No, the __Secure-accounts-session is only created when providing your email & password in the request payload to the /sessions endpoints as described here.

If so, does that mean the session cookie is sufficient for all subsequent API requests? Or does every request need the Authorization header (in which case, what does the session cookie actually do?)

To interact with the Toggl Track API services, you may find it easier to authenticate with your personal Track API token. For every request you need to provide the token as described in here.
You may also, alternatively, authenticate with the __Secure-accounts-session cookie which involves creating it as described here and then providing it in subsequent requests. Example:

curl --cookie __Secure-accounts-session={cookie value} https://track.toggl.com/api/v9/me

1 Like