OAuth Tokens

JSON Format

OAuth2 tokens are represented with the following read-only attributes:

Name Type Comment
id integer Automatically assigned upon creation
user_id integer The id of the user this token authenticates as
client_id integer The id of the client this token belongs to
token string The access token
refresh_token string The refresh token, if generated
scopes array An array of the valid scopes for this token. See Scopes below
url string The API url of this record
created_at date The time the token was created
expires_at date The time the token will expire
used_at date The latest time this token was used for authentication
Example
{
  "id":            1,
  "token":         "af3t24tfj34h43s...",
  "refresh_token": "af3t24tfj34h43s...",
  "scopes":        ["read"],
  "user_id":       29,
  "client_id":     41,
  "url":           "https://example.zendesk.com/api/v2/tokens/1.json",
  "created_at":    "2009-05-13T00:07:08Z",
  "expires_at":    "2011-07-22T00:11:12Z",
  "used_at":       "2010-01-22T00:11:12Z"
}

List Tokens

GET /api/v2/oauth/tokens.json

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

Allowed For
  • Admins, Agents, End Users
Using curl
curl https://{subdomain}.zendesk.com/api/v2/oauth/tokens.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "tokens": [
    {
      "id": 223443,
      "token": "af3345kdj3",
      ...
    },
    {
      "id": 8678530,
      "token": "34hjgkjas4",
      ...
    }
  ]
}

Show Token

GET /api/v2/oauth/tokens/{id}.json

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, id is a token id, not the full token.

In the second endpoint, include an Authorization: Bearer header with the full token to get its associated properties. Example:

curl https://{subdomain}.zendesk.com/api/v2/oauth/tokens/current.json \
  -H 'Authorization: Bearer 58787ff987e8031f6bc54a...' \
  -v -u {email_address}:{password}
Allowed For
  • Admins, Agents, End Users
Using curl
curl https://{subdomain}.zendesk.com/api/v2/oauth/tokens/{id}.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "token": {
    "id": 223443,
    "token": "af3245kdj3",
    ...
  }
}

Create Token

POST /api/v2/oauth/tokens.json

Creates an OAuth access token with a specified scope.

The endpoint takes the id of an OAuth client in your account. To create a client, see Registering your application with Zendesk in the Support Help Center. To get the id of the client, use the List Clients endpoint.

Note: The client id is not the same as the client's unique identifier.

Allowed For
  • Admins
Using curl
 curl https://{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}
Example Response
Status: 201 Created

{
  "token": {
    "id": 223443,
    "full_token": "af3245kdja3...",
    ...
  }
}
Request parameters

The POST request takes two parameter, a token object that contains a client id and scopes.

Name Description
client_id The numeric id of an OAuth client (not the client's identifier)
scopes An array of the valid scopes for this token. See Scopes below
Scopes

You can specify a scope to control access to resources. The syntax is as follows:

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

where resource is 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"]

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. See Making API requests on behalf of end users

Resources that can be scoped

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

Revoke Token

DELETE /api/v2/oauth/tokens/{id}.json DELETE /api/v2/oauth/tokens/current.json

Allowed For
  • Admins, Agents, End Users
Using curl
curl https://{subdomain}.zendesk.com/api/v2/oauth/tokens/{id}.json \
  -X DELETE -v -u {email_address}:{password}
Example Response
Status: 204 No Content