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
<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
- In case the api token is used, it is combined in
xxxx:api_tokenformat (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
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.
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
__Host-timer-session, which you can use for authentication in all the API requests.
curl -u 1971800d4d82861d8f2c1651fea4d212:api_token -X POST https://api.track.toggl.com/api/v9/me/sessions
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.
curl --cookie __Host-timer-session=MTM2MzA4MJa8jA3OHxEdi1CQkFFQ180SUFBUkFCRUFBQVlQLUNBQUVHYzNSeWFXNW5EQXdBQ25ObGMzTnBiMjVmYVdRR2MzUnlhVzVuREQ0QVBIUnZaMmRzTFdGd2FTMXpaWE56YVc5dUxUSXRaalU1WmpaalpEUTVOV1ZsTVRoaE1UaGhaalpqWkRkbU5XWTJNV0psWVRnd09EWmlPVEV3WkE9PXweAkG7kI6NBG-iqvhNn1MSDhkz2Pz_UYTzdBvZjCaA== -X DELETE https://api.track.toggl.com/api/v9/me/sessions