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 expiry
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":       "2013-01-22T00:11:12Z"
}

List Tokens

GET /api/v2/oauth/tokens.json

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

For security reasons, tokens returned are truncated.

Status: 200 OK

{
  "tokens": [
    {
      "id": 223443,
      "token": "af3345kdja3...",
      ...
    },
    {
      "id": 8678530,
      "token": "34hjgkjasv4...",
      ...
    }
  ]
}

Show Token

GET /api/v2/oauth/tokens/{id}.json GET /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 \
  -v -u {email_address}:{password}
Example Response

For security reasons, tokens returned are truncated.

Status: 200 OK

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

Create Token

POST /api/v2/oauth/tokens.json

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

This will return the new oauth_token with un-truncated token value in "full_token".

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 the client this token belongs to
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