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>

bytes, err := json.Marshal('{"code":"string","enabled":"boolean","token":"string"}')
if err != nil {
    print(err)
}
req, err := http.NewRequest(http.MethodPost, 
  "https://api.track.toggl.com/api/v9/me/enable_oauth/{provider}", bytes.NewBuffer(bytes))
if err != nil {
    print(err)
}
req.Header.Set("Content-Type", "application/json; charset=utf-8")
req.SetBasicAuth("<email>", "<password>")

client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
    print(err)
}

defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
    print(err)
}

fmt.Print(string(body))

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://api.track.toggl.com/api/v9/me/enable_oauth/{provider}')
http = Net::HTTP.new(uri.host, uri.port)
req = Net::HTTP::Post.new(uri.path)
req['Content-Type'] = "application/json"
req.body = {"code":"string","enabled":"boolean","token":"string"}.to_json
request.basic_auth '<email>', '<password>'
res = http.request(req)
puts JSON.parse(res.body)

fetch("https://api.track.toggl.com/api/v9/me/enable_oauth/{provider}", {
  method: "POST",
  body: {"code":"string","enabled":"boolean","token":"string"},
  headers: {
    "Content-Type": "application/json",
"Authorization": `Basic ${base64.encode(<email>:<password>)}`
  },
})
.then((resp) => resp.json())
.then((json) => {
  console.log(json);
})
.catch(err => console.error(err));

import requests
from base64 import b64encode

data = requests.post('https://api.track.toggl.com/api/v9/me/enable_oauth/{provider}', json='{"code":"string","enabled":"boolean","token":"string"}', headers={'content-type': 'application/json', 'Authorization' : 'Basic %s' %  b64encode(b"<email>:<password>").decode("ascii")})
print(data.json())

extern crate tokio;
extern crate serde_json;
use reqwest::{Client};
use reqwest::header::{CONTENT_TYPE};

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
  let client = Client::new().basic_auth("<email>", "<password>");
  let json = client.request(Method::POST, "https://api.track.toggl.com/api/v9/me/enable_oauth/{provider}".to_string())
.json(&serde_json::json!({"code":"string","enabled":"boolean","token":"string"}))
  .header(CONTENT_TYPE, "application/json")
  .send()
  .await?
  .json()
  .await?;
  
  println!("{:#?}", json);

  Ok(())
}

Parameters

Query

name	type	required	description
error	string	false	Error

Body

name	type	description
code	string	OAuth code
enabled	boolean	Whether to enable or disable OAuth
token	string	OAuth 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>

req, err := http.NewRequest(http.MethodPost, 
  "https://api.track.toggl.com/api/v9/me/reset_token")
if err != nil {
    print(err)
}
req.Header.Set("Content-Type", "application/json; charset=utf-8")
req.SetBasicAuth("<email>", "<password>")

client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
    print(err)
}

defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
    print(err)
}

fmt.Print(string(body))

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://api.track.toggl.com/api/v9/me/reset_token')
http = Net::HTTP.new(uri.host, uri.port)
req = Net::HTTP::Post.new(uri.path)
req['Content-Type'] = "application/json"
request.basic_auth '<email>', '<password>'
res = http.request(req)
puts JSON.parse(res.body)

fetch("https://api.track.toggl.com/api/v9/me/reset_token", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
"Authorization": `Basic ${base64.encode(<email>:<password>)}`
  },
})
.then((resp) => resp.json())
.then((json) => {
  console.log(json);
})
.catch(err => console.error(err));

import requests
from base64 import b64encode

data = requests.post('https://api.track.toggl.com/api/v9/me/reset_token', headers={'content-type': 'application/json', 'Authorization' : 'Basic %s' %  b64encode(b"<email>:<password>").decode("ascii")})
print(data.json())

extern crate tokio;
extern crate serde_json;
use reqwest::{Client};
use reqwest::header::{CONTENT_TYPE};

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
  let client = Client::new().basic_auth("<email>", "<password>");
  let json = client.request(Method::POST, "https://api.track.toggl.com/api/v9/me/reset_token".to_string())
  .header(CONTENT_TYPE, "application/json")
  .send()
  .await?
  .json()
  .await?;
  
  println!("{:#?}", json);

  Ok(())
}

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"}'

bytes, err := json.Marshal('{"remember_me":"boolean"}')
if err != nil {
    print(err)
}
req, err := http.NewRequest(http.MethodPost, 
  "https://api.track.toggl.com/api/v9/me/sessions", bytes.NewBuffer(bytes))
if err != nil {
    print(err)
}
req.Header.Set("Content-Type", "application/json; charset=utf-8")

client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
    print(err)
}

defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
    print(err)
}

fmt.Print(string(body))

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://api.track.toggl.com/api/v9/me/sessions')
http = Net::HTTP.new(uri.host, uri.port)
req = Net::HTTP::Post.new(uri.path)
req['Content-Type'] = "application/json"
req.body = {"remember_me":"boolean"}.to_json
res = http.request(req)
puts JSON.parse(res.body)

fetch("https://api.track.toggl.com/api/v9/me/sessions", {
  method: "POST",
  body: {"remember_me":"boolean"},
  headers: {
    "Content-Type": "application/json"
  },
})
.then((resp) => resp.json())
.then((json) => {
  console.log(json);
})
.catch(err => console.error(err));

import requests
from base64 import b64encode

data = requests.post('https://api.track.toggl.com/api/v9/me/sessions', json='{"remember_me":"boolean"}', headers={'content-type': 'application/json'})
print(data.json())

extern crate tokio;
extern crate serde_json;
use reqwest::{Client};
use reqwest::header::{CONTENT_TYPE};

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
  let client = Client::new();
  let json = client.request(Method::POST, "https://api.track.toggl.com/api/v9/me/sessions".to_string())
.json(&serde_json::json!({"remember_me":"boolean"}))
  .header(CONTENT_TYPE, "application/json")
  .send()
  .await?
  .json()
  .await?;
  
  println!("{:#?}", json);

  Ok(())
}

Parameters

Body

name	type	description
remember_me	boolean	If true, the session cookie will be valid for 24 hours, otherwise until the browser is closed

Response

200

name	type	description
api_token	string	will be omitted if empty
email	string	-
fullname	string	-
id	integer	-
timezone	string	-

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"

req, err := http.NewRequest(http.MethodPut, 
  "https://api.track.toggl.com/api/v9/me/sessions")
if err != nil {
    print(err)
}
req.Header.Set("Content-Type", "application/json; charset=utf-8")

client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
    print(err)
}

defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
    print(err)
}

fmt.Print(string(body))

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://api.track.toggl.com/api/v9/me/sessions')
http = Net::HTTP.new(uri.host, uri.port)
req = Net::HTTP::Delete.new(uri.path)
req['Content-Type'] = "application/json"
res = http.request(req)
puts JSON.parse(res.body)

fetch("https://api.track.toggl.com/api/v9/me/sessions", {
  method: "DELETE",
  headers: {
    "Content-Type": "application/json"
  },
})
.then((resp) => resp.json())
.then((json) => {
  console.log(json);
})
.catch(err => console.error(err));

import requests
from base64 import b64encode

data = requests.delete('https://api.track.toggl.com/api/v9/me/sessions', headers={'content-type': 'application/json'})
print(data.json())

extern crate tokio;
extern crate serde_json;
use reqwest::{Client};
use reqwest::header::{CONTENT_TYPE};

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
  let client = Client::new();
  let json = client.request(Method::DELETE, "https://api.track.toggl.com/api/v9/me/sessions".to_string())
  .header(CONTENT_TYPE, "application/json")
  .send()
  .await?
  .json()
  .await?;
  
  println!("{:#?}", json);

  Ok(())
}

Response

200

OK

500

Internal Server Error

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

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"}}'

bytes, err := json.Marshal('{"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"}}')
if err != nil {
    print(err)
}
req, err := http.NewRequest(http.MethodPost, 
  "https://api.track.toggl.com/api/v9/signup", bytes.NewBuffer(bytes))
if err != nil {
    print(err)
}
req.Header.Set("Content-Type", "application/json; charset=utf-8")

client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
    print(err)
}

defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
    print(err)
}

fmt.Print(string(body))

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://api.track.toggl.com/api/v9/signup')
http = Net::HTTP.new(uri.host, uri.port)
req = Net::HTTP::Post.new(uri.path)
req['Content-Type'] = "application/json"
req.body = {"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"}}.to_json
res = http.request(req)
puts JSON.parse(res.body)

fetch("https://api.track.toggl.com/api/v9/signup", {
  method: "POST",
  body: {"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"}},
  headers: {
    "Content-Type": "application/json"
  },
})
.then((resp) => resp.json())
.then((json) => {
  console.log(json);
})
.catch(err => console.error(err));

import requests
from base64 import b64encode

data = requests.post('https://api.track.toggl.com/api/v9/signup', json='{"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"}}', headers={'content-type': 'application/json'})
print(data.json())

extern crate tokio;
extern crate serde_json;
use reqwest::{Client};
use reqwest::header::{CONTENT_TYPE};

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
  let client = Client::new();
  let json = client.request(Method::POST, "https://api.track.toggl.com/api/v9/signup".to_string())
.json(&serde_json::json!({"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"}}))
  .header(CONTENT_TYPE, "application/json")
  .send()
  .await?
  .json()
  .await?;
  
  println!("{:#?}", json);

  Ok(())
}

Parameters

Body

name

type

description

code

string

Required if signing up via OAuth

country_id

integer

User's country ID, if not provided will be United States

created_with

string

Should describe the application/service that is using the API

string

Email for new user account

experiment

string

Experiment holds A/B testing group name TODO: Remove after A/B testing is over: https://github.com/toggl/backend-amber-alpaca/issues/866

full_name

string

User's full name, if not provided will be derived from the email address

google_access_token

string

Legacy field

invitation_code

string

Optional, used when creating account through an invitation

password

string

Password for new user account

provider

string

Required if signing up via OAuth

timezone

string

User's timezone, if not provided will be UTC

token

string

Required if signing up via OAuth

tos_accepted

boolean

Whether the Terms of Service have been accepted

workspace

name	type	description
initial_pricing_plan	integer	Plan ID for the new workspace
initial_trial	boolean	New workspace should be created with a trial subscription? (only for stage)
name	string	Workspace 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

name

type

description

api_token

string

will be omitted if empty

string

beginning_of_week

integer

country_id

integer

created_at

string

default_workspace_id

integer

string

fullname

string

has_password

boolean

integer

image_url

string

intercom_hash

string

will be omitted if empty

openid_email

string

openid_enabled

boolean

options

name	type	description
additionalProperties	object	-

will be omitted if empty

timezone

string

updated_at

string

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.

POST Enable/Disable OAuth​

Parameters​

Query​

Body​

Response​

200​

400​

POST ResetToken​

Response​

200​

403​

500​

POST Create session​

Parameters​

Body​

Response​

200​

400​

DELETE Delete session​

Response​

200​

500​

POST Signup​

Parameters​

Body​

Response​

200​

400​

403​

408​

500​

503​

POST Enable/Disable OAuth

Parameters

Query

Body

Response

200

400

POST ResetToken

Response

200

403

500

POST Create session

Parameters

Body

Response

200

400

DELETE Delete session

Response

200

500

POST Signup

Parameters

Body

Response

200

400

403

408

500

503