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

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

• 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.

• Admins

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

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
    }
  ]
}

• POST /api/v2/oauth/tokens

Returns an OAuth access token with a specified scope.

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

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

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

• Admins

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

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

Note: Don't confuse the scopes parameter (plural) with the scope parameter (singular) for grant-type tokens.

The scopes parameter 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, ...]

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"]

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. 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)

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}

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

• 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, 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}

• Admins, Agents, End Users

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

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

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

• Admins, Agents, End Users

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

Status 204 No Content