Skip to main content

Authentication

POST Enable/Disable OAuth​

https://api.track.toggl.com/api/v9/me/enable_oauth/{provider}

Enable/Disable login using user's provider account to existing Toggl account.

curl -X POST https://api.track.toggl.com/api/v9/me/enable_oauth/{provider} \
-H "Content-Type: application/json" \
-d '{"code":"string","enabled":"boolean","token":"string"}' \
-u <email>:<password>

Parameters​

Query​

nametyperequireddescription
errorstringfalseError

Body​

nametypedescription
codestringOAuth code
enabledbooleanWhether to enable or disable OAuth
tokenstringOAuth token

Response​

200​

Successful operation.

400​

Possible error messages:

* unknown provider
* Missing 'enabled' field
* Missing 'code' or 'token' field

* user already has an associated oauth account from this provider

* this oauth account is already associated with a toggl account

POST ResetToken​

https://api.track.toggl.com/api/v9/me/reset_token

Resets API token for the current user.

curl -X POST https://api.track.toggl.com/api/v9/me/reset_token \
-H "Content-Type: application/json" \
-u <email>:<password>

Response​

200​

Successful operation.

403​

User does not have access to this resource.

500​

Internal Server Error

POST Create session​

https://api.track.toggl.com/api/v9/me/sessions

Creates a session and sets a cookie in the response header which can be used for authentication in API requests

curl -X POST https://api.track.toggl.com/api/v9/me/sessions \
-H "Content-Type: application/json" \
-d '{"remember_me":"boolean"}'

Parameters​

Body​

nametypedescription
remember_mebooleanIf true, the session cookie will be valid for 24 hours, otherwise until the browser is closed

Response​

200​

nametypedescription
api_tokenstringwill be omitted if empty
emailstring-
fullnamestring-
idinteger-
timezonestring-

400​

Invalid JSON input

DELETE Delete session​

https://api.track.toggl.com/api/v9/me/sessions

Deletes a session used for authenticating the current request

curl -X DELETE https://api.track.toggl.com/api/v9/me/sessions \
-H "Content-Type: application/json"

Response​

200​

OK

500​

Internal Server Error

POST Signup​

https://api.track.toggl.com/api/v9/signup

Sign up as a new user.

curl -X POST https://api.track.toggl.com/api/v9/signup \
-H "Content-Type: application/json" \
-d '{"code":"string","country_id":"integer","created_with":"string","email":"string","experiment":"string","full_name":"string","google_access_token":"string","invitation_code":"string","password":"string","provider":"string","timezone":"string","token":"string","tos_accepted":"boolean","workspace":{"initial_pricing_plan":"integer","initial_trial":"boolean","name":"string"}}'

Parameters​

Body​

nametypedescription
codestringRequired if signing up via OAuth
country_idintegerUser's country ID, if not provided will be United States
created_withstringShould describe the application/service that is using the API
emailstringEmail for new user account
experimentstringExperiment holds A/B testing group name TODO: Remove after A/B testing is over: https://github.com/toggl/backend-amber-alpaca/issues/866
full_namestringUser's full name, if not provided will be derived from the email address
google_access_tokenstringLegacy field
invitation_codestringOptional, used when creating account through an invitation
passwordstringPassword for new user account
providerstringRequired if signing up via OAuth
timezonestringUser's timezone, if not provided will be UTC
tokenstringRequired if signing up via OAuth
tos_acceptedbooleanWhether the Terms of Service have been accepted
workspace
nametypedescription
initial_pricing_planintegerPlan ID for the new workspace
initial_trialbooleanNew workspace should be created with a trial subscription? (only for stage)
namestringWorkspace name, if not provided it will be based on the user's full name
Optional workspace settings, used when creating account not through an invitation

Response​

200​

nametypedescription
api_tokenstringwill be omitted if empty
atstring-
beginning_of_weekinteger-
country_idinteger-
created_atstring-
default_workspace_idinteger-
emailstring-
fullnamestring-
has_passwordboolean-
idinteger-
image_urlstring-
intercom_hashstringwill be omitted if empty
openid_emailstring-
openid_enabledboolean-
options
nametypedescription
additionalPropertiesobject-
will be omitted if empty
timezonestring-
updated_atstring-

400​

Possible error messages:

* Account has pending invite
* email is required
* initial workspace pricing plan must be specified
* Invalid country ID
* Invalid e-mail
* invalid e-mail: domain not permitted
* Invalid invitation code
* Invalid pricing plan specified
* invalid timezone value
* Must accept terms of service
* password is missing
* password should be at least 6 characters
* provider is missing
* Sorry, but this invitation seems either accepted or canceled
* user with this email already exists
* workspace name must contain non-space characters

403​

Possible error messages:

* Expected OAuth 2 access token
* Invalid Credentials
* invalid_grant
* token expired and refresh token is not set
* unauthorized_client

408​

connection reset by peer

500​

Internal Server Error

503​

Any unexpected OAuth error message.
© 2023 Toggl. All rights reserved.