Sessions
When an administrator, agent, or end user signs in to a Zendesk Support instance, a session is created. The Sessions API lets you view who is currently signed in. It also lets you terminate one or more sessions. Terminating a session signs out the user.
JSON format
Sessions are represented as JSON objects with the following properties:
| Name | Type | Read-only | Mandatory | Description |
|---|---|---|---|---|
| authenticated_at | string | false | false | When the session was created |
| id | integer | false | true | Automatically assigned when the session is created |
| last_seen_at | string | false | false | The last approximate time this session was seen. This does not update on every request. |
| url | string | false | false | The API URL of this session |
| user_id | integer | false | false | The id of the user |
Example
{"authenticated_at": "2014-11-18T17:24:29Z","id": 3432,"last_seen_at": "2014-11-18T17:30:52Z","url": "https://company.zendesk.com/api/v2/users/12345/sessions/3432.json","user_id": 12345}
List Sessions
GET /api/v2/sessionsGET /api/v2/users/{user_id}/sessions.json
If authenticated as an admin, returns all the account's sessions. If authenticated as an agent or end user, returns only the sessions of the user making the request.
Pagination
- Cursor pagination (recommended)
- Offset pagination
See Pagination.
Allowed For
- Admins, Agents, End users
Parameters
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| user_id | integer | Path | true | The id of the user |
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/sessions.json \-v -u {email_address}/token:{api_token}
Go
import ("fmt""io""net/http")func main() {url := "https://example.zendesk.com/api/v2/sessions"method := "GET"req, err := http.NewRequest(method, url, nil)if err != nil {fmt.Println(err)return}req.Header.Add("Content-Type", "application/json")req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"client := &http.Client {}res, err := client.Do(req)if err != nil {fmt.Println(err)return}defer res.Body.Close()body, err := io.ReadAll(res.Body)if err != nil {fmt.Println(err)return}fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/sessions").newBuilder();String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());Request request = new Request.Builder().url(urlBuilder.build()).method("GET", null).addHeader("Content-Type", "application/json").addHeader("Authorization", basicAuth).build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');var config = {method: 'GET',url: 'https://example.zendesk.com/api/v2/sessions',headers: {'Content-Type': 'application/json','Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"},};axios(config).then(function (response) {console.log(JSON.stringify(response.data));}).catch(function (error) {console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuthurl = "https://example.zendesk.com/api/v2/sessions"headers = {"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)response = requests.request("GET",url,auth=auth,headers=headers)print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://example.zendesk.com/api/v2/sessions")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|http.request(request)end
Example response(s)
200 OK
// Status 200 OK{"sessions": [{"authenticated_at": "2014-11-18T17:24:29Z","id": 3432,"last_seen_at": "2014-11-18T17:30:52Z","url": "https://company.zendesk.com/api/v2/users/12345/sessions/3432.json","user_id": 12345}]}
Show Session
GET /api/v2/users/{user_id}/sessions/{session_id}
Allowed For
- Admins, Agents, End users
Parameters
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| session_id | integer | Path | true | The ID of the session |
| user_id | integer | Path | true | The id of the user |
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}/sessions/{session_id}.json \-v -u {email_address}/token:{api_token}
Go
import ("fmt""io""net/http")func main() {url := "https://example.zendesk.com/api/v2/users/35436/sessions/14"method := "GET"req, err := http.NewRequest(method, url, nil)if err != nil {fmt.Println(err)return}req.Header.Add("Content-Type", "application/json")req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"client := &http.Client {}res, err := client.Do(req)if err != nil {fmt.Println(err)return}defer res.Body.Close()body, err := io.ReadAll(res.Body)if err != nil {fmt.Println(err)return}fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/users/35436/sessions/14").newBuilder();String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());Request request = new Request.Builder().url(urlBuilder.build()).method("GET", null).addHeader("Content-Type", "application/json").addHeader("Authorization", basicAuth).build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');var config = {method: 'GET',url: 'https://example.zendesk.com/api/v2/users/35436/sessions/14',headers: {'Content-Type': 'application/json','Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"},};axios(config).then(function (response) {console.log(JSON.stringify(response.data));}).catch(function (error) {console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuthurl = "https://example.zendesk.com/api/v2/users/35436/sessions/14"headers = {"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)response = requests.request("GET",url,auth=auth,headers=headers)print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://example.zendesk.com/api/v2/users/35436/sessions/14")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|http.request(request)end
Example response(s)
200 OK
// Status 200 OK{"session": [{"authenticated_at": "2014-11-18T17:24:29Z","id": 3432,"last_seen_at": "2014-11-18T17:30:52Z","url": "https://company.zendesk.com/api/v2/users/12345/sessions/3432.json","user_id": 12345}]}
Show the Currently Authenticated Session
GET /api/v2/users/me/session
Allowed For
- Admins, Agents, End users
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/users/me/session.json \-v -u {email_address}/token:{api_token}
Go
import ("fmt""io""net/http")func main() {url := "https://example.zendesk.com/api/v2/users/me/session"method := "GET"req, err := http.NewRequest(method, url, nil)if err != nil {fmt.Println(err)return}req.Header.Add("Content-Type", "application/json")req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"client := &http.Client {}res, err := client.Do(req)if err != nil {fmt.Println(err)return}defer res.Body.Close()body, err := io.ReadAll(res.Body)if err != nil {fmt.Println(err)return}fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/users/me/session").newBuilder();String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());Request request = new Request.Builder().url(urlBuilder.build()).method("GET", null).addHeader("Content-Type", "application/json").addHeader("Authorization", basicAuth).build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');var config = {method: 'GET',url: 'https://example.zendesk.com/api/v2/users/me/session',headers: {'Content-Type': 'application/json','Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"},};axios(config).then(function (response) {console.log(JSON.stringify(response.data));}).catch(function (error) {console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuthurl = "https://example.zendesk.com/api/v2/users/me/session"headers = {"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)response = requests.request("GET",url,auth=auth,headers=headers)print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://example.zendesk.com/api/v2/users/me/session")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|http.request(request)end
Example response(s)
200 OK
// Status 200 OK{"session": [{"authenticated_at": "2014-11-18T17:24:29Z","id": 3432,"last_seen_at": "2014-11-18T17:30:52Z","url": "https://company.zendesk.com/api/v2/users/12345/sessions/3432.json","user_id": 12345}]}
Renew the current session
GET /api/v2/users/me/session/renew
Allowed For
- Admins, Agents, End users
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/users/me/session/renew.json \-v -u {email_address}/token:{api_token}
Go
import ("fmt""io""net/http")func main() {url := "https://example.zendesk.com/api/v2/users/me/session/renew"method := "GET"req, err := http.NewRequest(method, url, nil)if err != nil {fmt.Println(err)return}req.Header.Add("Content-Type", "application/json")req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"client := &http.Client {}res, err := client.Do(req)if err != nil {fmt.Println(err)return}defer res.Body.Close()body, err := io.ReadAll(res.Body)if err != nil {fmt.Println(err)return}fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/users/me/session/renew").newBuilder();String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());Request request = new Request.Builder().url(urlBuilder.build()).method("GET", null).addHeader("Content-Type", "application/json").addHeader("Authorization", basicAuth).build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');var config = {method: 'GET',url: 'https://example.zendesk.com/api/v2/users/me/session/renew',headers: {'Content-Type': 'application/json','Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"},};axios(config).then(function (response) {console.log(JSON.stringify(response.data));}).catch(function (error) {console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuthurl = "https://example.zendesk.com/api/v2/users/me/session/renew"headers = {"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)response = requests.request("GET",url,auth=auth,headers=headers)print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://example.zendesk.com/api/v2/users/me/session/renew")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|http.request(request)end
Example response(s)
200 OK
// Status 200 OK{"authenticity_token": "huU19Z76zNC9Yvt+i9p7MviIOlOIg/JWqEdf6nGmnu9JInV04fksCIdtNDvoYAoV"}
Delete Session
DELETE /api/v2/users/{user_id}/sessions/{session_id}
Allowed For
- Admins, Agents, End users
Parameters
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| session_id | integer | Path | true | The ID of the session |
| user_id | integer | Path | true | The id of the user |
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}/sessions/{session_id}.json \-v -u {email_address}/token:{api_token} -X DELETE
Go
import ("fmt""io""net/http")func main() {url := "https://example.zendesk.com/api/v2/users/35436/sessions/14"method := "DELETE"req, err := http.NewRequest(method, url, nil)if err != nil {fmt.Println(err)return}req.Header.Add("Content-Type", "application/json")req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"client := &http.Client {}res, err := client.Do(req)if err != nil {fmt.Println(err)return}defer res.Body.Close()body, err := io.ReadAll(res.Body)if err != nil {fmt.Println(err)return}fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/users/35436/sessions/14").newBuilder();String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());Request request = new Request.Builder().url(urlBuilder.build()).method("DELETE", null).addHeader("Content-Type", "application/json").addHeader("Authorization", basicAuth).build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');var config = {method: 'DELETE',url: 'https://example.zendesk.com/api/v2/users/35436/sessions/14',headers: {'Content-Type': 'application/json','Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"},};axios(config).then(function (response) {console.log(JSON.stringify(response.data));}).catch(function (error) {console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuthurl = "https://example.zendesk.com/api/v2/users/35436/sessions/14"headers = {"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)response = requests.request("DELETE",url,auth=auth,headers=headers)print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://example.zendesk.com/api/v2/users/35436/sessions/14")request = Net::HTTP::Delete.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|http.request(request)end
Example response(s)
204 No Content
// Status 204 No Contentnull
Delete the Authenticated Session
DELETE /api/v2/users/me/logout
Deletes the current session. In practice, this only works when using session auth for requests, such as client-side requests made from a Zendesk app. When using OAuth or basic authentication, you don't have a current session so this endpoint has no effect.
Allowed For
- Admins, Agents, End users
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/users/me/logout.json \-v -u {email_address}/token:{api_token} -X DELETE
Go
import ("fmt""io""net/http")func main() {url := "https://example.zendesk.com/api/v2/users/me/logout"method := "DELETE"req, err := http.NewRequest(method, url, nil)if err != nil {fmt.Println(err)return}req.Header.Add("Content-Type", "application/json")req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"client := &http.Client {}res, err := client.Do(req)if err != nil {fmt.Println(err)return}defer res.Body.Close()body, err := io.ReadAll(res.Body)if err != nil {fmt.Println(err)return}fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/users/me/logout").newBuilder();String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());Request request = new Request.Builder().url(urlBuilder.build()).method("DELETE", null).addHeader("Content-Type", "application/json").addHeader("Authorization", basicAuth).build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');var config = {method: 'DELETE',url: 'https://example.zendesk.com/api/v2/users/me/logout',headers: {'Content-Type': 'application/json','Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"},};axios(config).then(function (response) {console.log(JSON.stringify(response.data));}).catch(function (error) {console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuthurl = "https://example.zendesk.com/api/v2/users/me/logout"headers = {"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)response = requests.request("DELETE",url,auth=auth,headers=headers)print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://example.zendesk.com/api/v2/users/me/logout")request = Net::HTTP::Delete.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|http.request(request)end
Example response(s)
204 No Content
// Status 204 No Contentnull
Bulk Delete Sessions
DELETE /api/v2/users/{user_id}/sessions
Deletes all the sessions for a user.
Allowed For
- Admins, Agents, End users
Parameters
| Name | Type | In | Required | Description |
|---|---|---|---|---|
| user_id | integer | Path | true | The id of the user |
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}/sessions.json \-v -u {email_address}/token:{api_token} -X DELETE
Go
import ("fmt""io""net/http")func main() {url := "https://example.zendesk.com/api/v2/users/35436/sessions"method := "DELETE"req, err := http.NewRequest(method, url, nil)if err != nil {fmt.Println(err)return}req.Header.Add("Content-Type", "application/json")req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"client := &http.Client {}res, err := client.Do(req)if err != nil {fmt.Println(err)return}defer res.Body.Close()body, err := io.ReadAll(res.Body)if err != nil {fmt.Println(err)return}fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/users/35436/sessions").newBuilder();String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());Request request = new Request.Builder().url(urlBuilder.build()).method("DELETE", null).addHeader("Content-Type", "application/json").addHeader("Authorization", basicAuth).build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');var config = {method: 'DELETE',url: 'https://example.zendesk.com/api/v2/users/35436/sessions',headers: {'Content-Type': 'application/json','Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"},};axios(config).then(function (response) {console.log(JSON.stringify(response.data));}).catch(function (error) {console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuthurl = "https://example.zendesk.com/api/v2/users/35436/sessions"headers = {"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)response = requests.request("DELETE",url,auth=auth,headers=headers)print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://example.zendesk.com/api/v2/users/35436/sessions")request = Net::HTTP::Delete.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|http.request(request)end
Example response(s)
204 No Content
// Status 204 No Contentnull