Documentation API Reference

OAuth Tokens

JSON format

OAuth Tokens are represented as JSON objects with the following properties:

Name Type Read-only Mandatory Description
client_id integer true false The id of the client this token belongs to
created_at string true false The time the token was created
expires_at string true false The time the token will expire
id integer true false Automatically assigned upon creation
refresh_token string true false The refresh token, if generated
scopes array true false An array of the valid scopes for this token. SeeScopesbelow
token string true false The access token
url string true false The API url of this record
used_at string true false The latest time this token was used for authentication
user_id integer true false The id of the user this token authenticates as

Example

             

              
{"client_id":41,"created_at":"2009-05-13T00:07:08Z","expires_at":"2011-07-22T00:11:12Z","id":1,"refresh_token":"af3t24tfj34h43s...","scopes":["read"],"token":"af3t24tfj34h43s...","url":"https://example.zendesk.com/api/v2/tokens/1.json","used_at":"2010-01-22T00:11:12Z","user_id":29}

List Tokens

  • GET /api/v2/oauth/tokens

Returns the properties of the tokens. For security reasons, only the first 10 characters of each access token are included.

Pagination

  • Cursor pagination (recommended)
  • Offset pagination

SeePagination.

Returns a maximum of 100 records per page.

Allowed For

  • Admins

Parameters

Name Type In Required Description
client_id integer 查询 false The id of the OAuth client

代码示例

curl 
              

               
curlhttps://{subdomain}.zendesk.com/api/v2/oauth/tokens.json\-v -u{email_address}:{password}
Go 
              

               
import("fmt""io""net/http")funcmain(){url:="https://support.zendesk.com/api/v2/oauth/tokens?client_id=223443"method:="GET"req,err:=http.NewRequest(method,url,nil)iferr!=nil{fmt.Println(err)return}req.Header.Add("Content-Type","application/json")req.Header.Add("Authorization","Basic ")// Base64 encoded "username:password"client:=&http.Client{}res,err:=client.Do(req)iferr!=nil{fmt.Println(err)return}deferres.Body.Close()body,err:=io.ReadAll(res.Body)iferr!=nil{fmt.Println(err)return}fmt.Println(string(body))}
Java 
              

               
importcom.squareup.okhttp.*;OkHttpClientclient=newOkHttpClient();HttpUrl.BuilderurlBuilder=HttpUrl.parse("https://support.zendesk.com/api/v2/oauth/tokens").newBuilder().addQueryParameter("client_id","223443");Requestrequest=newRequest.Builder().url(urlBuilder.build()).method("GET",null).addHeader("Content-Type","application/json").addHeader("Authorization",Credentials.basic("your-email","your-password")).build();Responseresponse=client.newCall(request).execute();
Nodejs 
              

               
varaxios=require('axios');varconfig={method:'GET',url:'https://support.zendesk.com/api/v2/oauth/tokens',headers:{'Content-Type':'application/json','Authorization':'Basic ',// Base64 encoded "username:password"},params:{'client_id':'223443',},};axios(config).then(function(response){console.log(JSON.stringify(response.data));}).catch(function(error){console.log(error);});
Python 
              

               
importrequestsurl="https://support.zendesk.com/api/v2/oauth/tokens?client_id=223443"headers={"Content-Type":"application/json",}response=requests.request("GET",url,auth=('',''),headers=headers)print(response.text)
Ruby 
              

               
require"net/http"uri=URI("https://support.zendesk.com/api/v2/oauth/tokens")uri.query=URI.encode_www_form("client_id":"223443")request=Net::HTTP::Get.new(uri,"Content-Type":"application/json")request.basic_auth"username","password"response=Net::HTTP.start uri.hostname,uri.port,use_ssl:truedo|http|http.request(request)end

Example response(s)

200 OK 
              

               
// Status 200 OK{"tokens":[{"client_id":41,"created_at":"2009-05-13T00:07:08Z","expires_at":"2011-07-22T00:11:12Z","id":223443,"refresh_token":"af3t24tfj34h43s...","scopes":["read"],"token":"af3345kdj3","url":"https://example.zendesk.com/api/v2/tokens/223443.json","used_at":"2010-01-22T00:11:12Z","user_id":29},{"client_id":41,"created_at":"2009-05-13T00:07:08Z","expires_at":"2011-07-22T00:11:12Z","id":8678530,"refresh_token":"af3t24tfj34h43s...","scopes":["read"],"token":"34hjgkjas4","url":"https://example.zendesk.com/api/v2/tokens/8678530.json","used_at":"2010-01-22T00:11:12Z","user_id":29}]}

Show Token

  • GET /api/v2/oauth/tokens/{oauth_token_id}
  • GET /api/v2/oauth/tokens/current.json

Returns the properties of the specified token. For security reasons, only the first 10 characters of the access token are included.

In the first endpoint,idis a token id, not the full token.

In the second endpoint, include anAuthorization: Bearerheader with the full token to get its associated properties. Example:

             

              
curl https://{subdomain}.zendesk.com/api/v2/oauth/tokens/current.json \-H 'Authorization: Bearer ${authToken}' \-v -u {email_address}:{password}

Allowed for

  • Admins, Agents, End Users

Parameters

Name Type In Required Description
oauth_token_id integer Path true The ID of the OAuth token

代码示例

curl 
              

               
curlhttps://{subdomain}.zendesk.com/api/v2/oauth/tokens/{oauth_token_id}.json\-v -u{email_address}:{password}
Go 
              

               
import("fmt""io""net/http")funcmain(){url:="https://support.zendesk.com/api/v2/oauth/tokens/223443"method:="GET"req,err:=http.NewRequest(method,url,nil)iferr!=nil{fmt.Println(err)return}req.Header.Add("Content-Type","application/json")req.Header.Add("Authorization","Basic ")// Base64 encoded "username:password"client:=&http.Client{}res,err:=client.Do(req)iferr!=nil{fmt.Println(err)return}deferres.Body.Close()body,err:=io.ReadAll(res.Body)iferr!=nil{fmt.Println(err)return}fmt.Println(string(body))}
Java 
              

               
importcom.squareup.okhttp.*;OkHttpClientclient=newOkHttpClient();HttpUrl.BuilderurlBuilder=HttpUrl.parse("https://support.zendesk.com/api/v2/oauth/tokens/223443").newBuilder();Requestrequest=newRequest.Builder().url(urlBuilder.build()).method("GET",null).addHeader("Content-Type","application/json").addHeader("Authorization",Credentials.basic("your-email","your-password")).build();Responseresponse=client.newCall(request).execute();
Nodejs 
              

               
varaxios=require('axios');varconfig={method:'GET',url:'https://support.zendesk.com/api/v2/oauth/tokens/223443',headers:{'Content-Type':'application/json','Authorization':'Basic ',// Base64 encoded "username:password"},};axios(config).then(function(response){console.log(JSON.stringify(response.data));}).catch(function(error){console.log(error);});
Python 
              

               
importrequestsurl="https://support.zendesk.com/api/v2/oauth/tokens/223443"headers={"Content-Type":"application/json",}response=requests.request("GET",url,auth=('',''),headers=headers)print(response.text)
Ruby 
              

               
require"net/http"uri=URI("https://support.zendesk.com/api/v2/oauth/tokens/223443")request=Net::HTTP::Get.new(uri,"Content-Type":"application/json")request.basic_auth"username","password"response=Net::HTTP.start uri.hostname,uri.port,use_ssl:truedo|http|http.request(request)end

Example response(s)

200 OK 
              

               
// Status 200 OK{"token":{"client_id":1234,"created_at":"2009-05-13T00:07:08Z","expires_at":"2011-07-22T00:11:12Z","id":223443,"refresh_token":"af3t24tfj34h43s...","scopes":["read","write"],"token":"af3345kdj3","url":"https://example.zendesk.com/api/v2/tokens/223443.json","used_at":"2010-01-22T00:11:12Z","user_id":29}}

Create Token

  • POST /api/v2/oauth/tokens

Returns an OAuth access token with a specifiedscope.

Refresh tokens aren't used. An access token doesn't expire but it can berevoked.

For a tutorial, seeCreating and using OAuth tokens with the API.

Note: For OAuth authorization code or password grant types, use theCreate Token for Grant Typeendpoint. The two APIs don't share the same path, JSON format, or request parameters. However, both APIs return access tokens that can be used toauthenticate API requests.

Allowed For

  • Admins

Request parameters

The POST request takes a "token" object that contains an OAuth client's resource id and scopes.

Name Type Description
client_id integer The resourceidof anOAuth client(not the client's unique identifier). For the ids, seeList Clients
scopes array Valid scopes for the token. SeeScopesbelow

Scopes

Thescopesparameter defines whether requests authenticated with the token can post, put, and delete data, or only get data.

Note: Don't confuse thescopesparameter (plural) with thescopeparameter (singular) forgrant-type tokens.

Thescopesparameter is an array of strings, each specifying a resource name and an access setting. Access is either "read" or "write". If you don't specify a resource, access to all resources is assumed. If you don't specify the access, read and write access are assumed.

The syntax is as follows:

"scopes": [resource:scope, ...]

whereresourceis optional.

Examples

"scopes": ["read"]

"scopes": ["tickets:read"]

To give read and write access to a resource, specify both scopes:

"scopes": ["users:read", "users:write"]

To give write access only to one resource and read access to everything else:

"scopes": ["organizations:write", "read"]

Note: The endpoint returns an access token even if you specify an invalid scope. Any request you make with the token will return a "Forbidden" error.

Available scopes

  • read- gives access to GET endpoints. Includes

permission to sideload related resources

  • write- gives access to POST, PUT, and DELETE endpoints
  • impersonate- allows Zendesk Support admins to make requests on behalf of

end users. SeeMaking API requests on behalf of end users

Resources that can be scoped

  • tickets
  • users
  • auditlogs (read only)
  • organizations
  • hc
  • apps
  • triggers
  • automations
  • targets
  • webhooks
  • macros
  • requests
  • satisfaction_ratings
  • dynamic_content
  • any_channel (write only)
  • web_widget (write only)

Parameters

Name Type In Required Description
client_id integer 查询 false The id of the OAuth client

代码示例

curl 
              

               
curlhttps://{subdomain}.zendesk.com/api/v2/oauth/tokens.json\-H"Content-Type: application/json"\-d'{"token": {"client_id": 1234, "scopes": ["read", "write"]}}'\-X POST -v -u{email_address}:{password}
Go 
              

               
import("fmt""io""net/http")funcmain(){url:="https://support.zendesk.com/api/v2/oauth/tokens?client_id=223443"method:="POST"req,err:=http.NewRequest(method,url,nil)iferr!=nil{fmt.Println(err)return}req.Header.Add("Content-Type","application/json")req.Header.Add("Authorization","Basic ")// Base64 encoded "username:password"client:=&http.Client{}res,err:=client.Do(req)iferr!=nil{fmt.Println(err)return}deferres.Body.Close()body,err:=io.ReadAll(res.Body)iferr!=nil{fmt.Println(err)return}fmt.Println(string(body))}
Java 
              

               
importcom.squareup.okhttp.*;OkHttpClientclient=newOkHttpClient();HttpUrl.BuilderurlBuilder=HttpUrl.parse("https://support.zendesk.com/api/v2/oauth/tokens").newBuilder().addQueryParameter("client_id","223443");RequestBodybody=RequestBody.create(MediaType.parse("application/json"),"""""");Requestrequest=newRequest.Builder().url(urlBuilder.build()).method("POST",body).addHeader("Content-Type","application/json").addHeader("Authorization",Credentials.basic("your-email","your-password")).build();Responseresponse=client.newCall(request).execute();
Nodejs 
              

               
varaxios=require('axios');varconfig={method:'POST',url:'https://support.zendesk.com/api/v2/oauth/tokens',headers:{'Content-Type':'application/json','Authorization':'Basic ',// Base64 encoded "username:password"},params:{'client_id':'223443',},};axios(config).then(function(response){console.log(JSON.stringify(response.data));}).catch(function(error){console.log(error);});
Python 
              

               
importrequestsurl="https://support.zendesk.com/api/v2/oauth/tokens?client_id=223443"headers={"Content-Type":"application/json",}response=requests.request("POST",url,auth=('',''),headers=headers)print(response.text)
Ruby 
              

               
require"net/http"uri=URI("https://support.zendesk.com/api/v2/oauth/tokens")uri.query=URI.encode_www_form("client_id":"223443")request=Net::HTTP::Post.new(uri,"Content-Type":"application/json")request.basic_auth"username","password"response=Net::HTTP.start uri.hostname,uri.port,use_ssl:truedo|http|http.request(request)end

Example response(s)

201 Created 
              

               
// Status 201 Created{"token":{"client_id":1234,"created_at":"2009-05-13T00:07:08Z","expires_at":"2011-07-22T00:11:12Z","id":223443,"refresh_token":"af3t24tfj34h43s...","scopes":["read","write"],"token":"af3345kdj3","url":"https://example.zendesk.com/api/v2/tokens/223443.json","used_at":"2010-01-22T00:11:12Z","user_id":29}}

Revoke Token

  • DELETE /api/v2/oauth/tokens/{oauth_token_id}
  • 删除/ api / v2 / oauth /令牌/ current.json

Allowed for

  • Admins, Agents, End Users

Parameters

Name Type In Required Description
oauth_token_id integer Path true The ID of the OAuth token

代码示例

curl 
              

               
curlhttps://{subdomain}.zendesk.com/api/v2/oauth/tokens/{oauth_token_id}.json\-X DELETE -v -u{email_address}:{password}
Go 
              

               
import("fmt""io""net/http")funcmain(){url:="https://support.zendesk.com/api/v2/oauth/tokens/223443"method:="DELETE"req,err:=http.NewRequest(method,url,nil)iferr!=nil{fmt.Println(err)return}req.Header.Add("Content-Type","application/json")req.Header.Add("Authorization","Basic ")// Base64 encoded "username:password"client:=&http.Client{}res,err:=client.Do(req)iferr!=nil{fmt.Println(err)return}deferres.Body.Close()body,err:=io.ReadAll(res.Body)iferr!=nil{fmt.Println(err)return}fmt.Println(string(body))}
Java 
              

               
importcom.squareup.okhttp.*;OkHttpClientclient=newOkHttpClient();HttpUrl.BuilderurlBuilder=HttpUrl.parse("https://support.zendesk.com/api/v2/oauth/tokens/223443").newBuilder();Requestrequest=newRequest.Builder().url(urlBuilder.build()).method("DELETE",null).addHeader("Content-Type","application/json").addHeader("Authorization",Credentials.basic("your-email","your-password")).build();Responseresponse=client.newCall(request).execute();
Nodejs 
              

               
varaxios=require('axios');varconfig={method:'DELETE',url:'https://support.zendesk.com/api/v2/oauth/tokens/223443',headers:{'Content-Type':'application/json','Authorization':'Basic ',// Base64 encoded "username:password"},};axios(config).then(function(response){console.log(JSON.stringify(response.data));}).catch(function(error){console.log(error);});
Python 
              

               
importrequestsurl="https://support.zendesk.com/api/v2/oauth/tokens/223443"headers={"Content-Type":"application/json",}response=requests.request("DELETE",url,auth=('',''),headers=headers)print(response.text)
Ruby 
              

               
require"net/http"uri=URI("https://support.zendesk.com/api/v2/oauth/tokens/223443")request=Net::HTTP::删除.new(uri,"Content-Type":"application/json")request.basic_auth"username","password"response=Net::HTTP.start uri.hostname,uri.port,use_ssl:truedo|http|http.request(request)end

Example response(s)

204 No Content 
              

               
// Status 204 No Contentnull