The Zendesk OAuth API implements the OAuth 2.0 standard to let apps securely access Zendesk data on a users or accounts behalf without sharing passwords. Developers register an OAuth client in a Zendesk account, redirect users to Zendesk for signin and consent, and exchange the returned authorization code for access (and optionally refresh) tokens.
openapi: 3.1.0
info:
version: "1.0"
title: Zendesk Oauth
description: Needs a description.
paths:
/api/v2/oauth/clients:
get:
operationId: ListOAuthClients
tags:
- OAuth Clients
summary: Zendesk Get Api V2 Oauth Clients
description: |
#### Pagination
* Cursor pagination (recommended)
* Offset pagination
See [Pagination](/api-reference/introduction/pagination/).
Returns a maximum of 100 records per page.
#### Allowed For
* Admins
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthClientsResponse'
examples:
default:
$ref: '#/components/examples/OAuthClientsResponseExample'
post:
operationId: CreateOAuthClient
tags:
- OAuth Clients
summary: Zendesk Post Api V2 Oauth Clients
description: |
#### Allowed For
* Admins
responses:
'201':
description: Created response
content:
application/json:
schema:
$ref: '#/components/schemas/OauthClientResponse'
examples:
default:
$ref: '#/components/examples/OAuthClientResponseExample'
/api/v2/oauth/clients/{oauth_client_id}:
parameters:
- $ref: '#/components/parameters/OAuthClientId'
get:
operationId: ShowClient
tags:
- OAuth Clients
summary: Zendesk Get Api V2 Oauth Clients Oauth_client_id
description: |
#### Allowed for
* Admins
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/OauthClientResponse'
examples:
default:
$ref: '#/components/examples/OAuthClientResponseExample'
put:
operationId: UpdateClient
tags:
- OAuth Clients
summary: Zendesk Put Api V2 Oauth Clients Oauth_client_id
description: |
#### Allowed for
* Admins
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/OauthClientResponse'
examples:
default:
$ref: '#/components/examples/OAuthClientUpdateResponseExample'
delete:
operationId: DeleteClient
tags:
- OAuth Clients
summary: Zendesk Delete Api V2 Oauth Clients Oauth_client_id
description: |
#### Allowed for
* Admins
responses:
'204':
description: No content response
/api/v2/oauth/clients/{oauth_client_id}/generate_secret:
parameters:
- $ref: '#/components/parameters/OAuthClientId'
put:
operationId: ClientGenerateSecret
tags:
- OAuth Clients
summary: Zendesk Put Api V2 Oauth Clients Oauth_client_id Generate_secret
description: |
#### Allowed for
* Admins
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/OauthClientResponse'
examples:
default:
$ref: '#/components/examples/OAuthClientResponseExample'
/api/v2/oauth/global_clients:
get:
operationId: ListGlobalOAuthClients
tags:
- Global Clients
summary: Zendesk Get Api V2 Oauth Global_clients
description: >
Returns all the global OAuth clients that users on your account have
authorized.
#### Pagination
* Cursor pagination (recommended)
* Offset pagination
See [Pagination](/api-reference/introduction/pagination/).
Returns a maximum of 100 records per page.
#### Allowed For
* Admins
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/GlobalClientsResponse'
examples:
default:
$ref: '#/components/examples/GlobalClientsResponseExample'
/api/v2/oauth/global_clients/{global_client_id}:
parameters:
- $ref: '#/components/parameters/GlobalClientId'
get:
operationId: ShowGlobalClient
tags:
- Global Clients
summary: Zendesk Get Api V2 Oauth Global_clients Global_client_id
description: >
Returns the global OAuth client associated with the ID sent on the
request.
#### Allowed for
* Admins
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/GlobalClientResponse'
examples:
default:
$ref: '#/components/examples/GlobalClientResponseExample'
/api/v2/oauth/global_clients/token_summary:
parameters:
- $ref: '#/components/parameters/OAuthGlobalClientIdQuery'
- $ref: >-
#/components/parameters/GlobalClientTokenSummaryIncludeExpiredTokensQuery
get:
operationId: GlobalOAuthClientsTokenSummary
tags:
- Global Clients
summary: Zendesk Get Api V2 Oauth Global_clients Token_summary
description: >
Returns information about tokens for the global clients that your
account has authorized.
#### Pagination
* Cursor pagination (recommended)
* Offset pagination
See [Pagination](/api-reference/introduction/pagination/).
Returns a maximum of 100 records per page.
#### Allowed For
* Admins
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/GlobalClientsTokenSummaryResponse'
examples:
default:
$ref: >-
#/components/examples/GlobalClientsTokenSummaryResponseExample
/api/v2/oauth/tokens:
parameters:
- $ref: '#/components/parameters/OAuthClientIdQuery'
- $ref: '#/components/parameters/OAuthGlobalClientIdQuery'
- $ref: '#/components/parameters/OAuthAllTokensQuery'
get:
operationId: ListOAuthTokens
tags:
- OAuth Tokens
summary: Zendesk Get Api V2 Oauth Tokens
description: >
Returns the properties of the tokens for the current user. Admins can
view OAuth token properties for all users using the
[all](/api-reference/ticketing/oauth/oauth_tokens/#parameters)
parameter. The
[client_id](/api-reference/ticketing/oauth/oauth_tokens/#parameters)
parameter can be included to filter that list by a global or local OAuth
client ID. For security reasons, only the first 10 characters of each
access token are included.
#### Pagination
* Cursor pagination (recommended)
* Offset pagination
See [Pagination](/api-reference/introduction/pagination/).
Returns a maximum of 100 records per page.
#### Allowed For
* Admins
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthTokensResponse'
examples:
default:
$ref: '#/components/examples/OAuthTokensResponseExample'
post:
operationId: CreateOAuthToken
tags:
- OAuth Tokens
summary: Zendesk Post Api V2 Oauth Tokens
description: >
Returns an OAuth access token with a specified [scope](#scopes).
Refresh tokens aren't used. An access token doesn't expire but it can be
[revoked](#revoke-token).
For a tutorial, see [Creating and using OAuth tokens with the
API](/documentation/ticketing/working-with-oauth/creating-and-using-oauth-tokens-with-the-api/).
**Note**: For OAuth authorization code, use the [Create Token for Grant
Type](/api-reference/ticketing/oauth/grant_type_tokens/#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](/api-reference/ticketing/introduction/#oauth-access-token).
#### 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 resource `id` of an [OAuth
client](/api-reference/ticketing/oauth/oauth_clients/#json-format) (not
the client's unique identifier). For the ids, see [List
Clients](/api-reference/ticketing/oauth/oauth_clients/#list-clients)
| scopes | array | Valid scopes for the token. See
[Scopes](#scopes) below
#### 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](/api-reference/ticketing/oauth/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](/documentation/ticketing/using-the-zendesk-api/making-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)
responses:
'201':
description: Created response
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthTokenResponse'
examples:
default:
$ref: '#/components/examples/OAuthTokenResponseExample'
/api/v2/oauth/tokens/{oauth_token_id}:
parameters:
- $ref: '#/components/parameters/OAuthTokenId'
get:
operationId: ShowToken
tags:
- OAuth Tokens
summary: Zendesk Get Api V2 Oauth Tokens Oauth_token_id
description: >
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:
```sh
curl https://{subdomain}.zendesk.com/api/v2/oauth/tokens/current.json \
-H 'Authorization: Bearer ${authToken}' \
-v -u {email_address}/token:{api_token}
```
#### Allowed for
* Admins, Agents, End Users
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthTokenResponse'
examples:
default:
$ref: '#/components/examples/OAuthTokenResponseExample'
delete:
operationId: RevokeOAuthToken
tags:
- OAuth Tokens
summary: Zendesk Delete Api V2 Oauth Tokens Oauth_token_id
description: |
#### Allowed for
* Admins, Agents, End Users
responses:
'204':
description: No content response
/oauth/tokens:
post:
operationId: CreateTokenForGrantType
tags:
- Grant Type Tokens
summary: Zendesk Post Oauth Tokens
description: >
Returns an OAuth access token in exchange for an [authorization
code](https://support.zendesk.com/hc/en-us/articles/203663836#topic_pvr_ncl_1l)
valid for 120 seconds.
Using a Zendesk username and password to gain an OAuth access token
(password grant type flow) has been deprecated and is highly
discouraged.
An access token can be revoked. Use the [OAuth Tokens
API](/api-reference/ticketing/oauth/oauth_tokens) to list, show, or
revoke tokens.
#### Request parameters
The POST request takes the following parameters, which must be formatted
as JSON:
| Name | Description
| ------------- | --------------------------------------------------
| grant_type | "authorization_code", "refresh_token", or
"client_credentials"
| code | Authorization grant flow only. The authorization code
you received from Zendesk after the user granted access. See [Handle the
user's authorization
decision](https://support.zendesk.com/hc/en-us/articles/203663836#topic_tfc_cdl_1l)
in Help Center
| client_id | The **Unique Identifier** specified in an OAuth client
in the Support admin interface (**Apps and integrations** > **APIs** >
**OAuth clients**). See [Registering your application with
Zendesk](https://support.zendesk.com/hc/en-us/articles/203663836#topic_s21_lfs_qk)
| client_secret | The **Secret** specified in an OAuth client in the
Support admin interface (**Apps and integrations** > **APIs** > **OAuth
clients**). See [Registering your application with
Zendesk](https://support.zendesk.com/hc/en-us/articles/203663836#topic_s21_lfs_qk)
| redirect_uri | Authorization grant flow only. The redirect URL you
specified when you sent the user to the Zendesk authorization page. For
ID purposes only. See [Send the user to the Zendesk authorization
page](https://support.zendesk.com/hc/en-us/articles/203663836#topic_qk3_d3s_qk)
| scope | Valid scope for this token. A string of
space-separated values. See [Scope](#scope) below
| expires_in | Number of seconds the access token is valid. Must be
more than 300 seconds (5 minutes) and less than 172,800 seconds (2
days), or less than `refresh_token_expires_in`, whichever is the
smallest. Defaults to null
| refresh_token_expires_in | Number of seconds the refresh token is
valid. Must be more than 604,800 seconds (7 days) or `expires_in` (if
given), and less than 7,776,000 seconds (90 days). Defaults to 2,592,000
seconds (30 days)
| refresh_token | The refresh token
**Example Node.js authorization code grant flow**
```javascript
const tokenResponse = await axios.post(
`https://${ZENDESK_SUBDOMAIN}.zendesk.com/oauth/tokens`,
{
grant_type: "authorization_code",
code: req.query.code,
client_id: ZENDESK_CLIENT_ID,
redirect_uri: REDIRECT_URI_PKCE,
scope: "read write",
code_verifier: CODE_VERIFIER,
expires_in: 86400,
refresh_token_expires_in: 604800,
},
{ headers: { "Content-Type": "application/json" } }
);
```
**Example Node.js refresh token grant flow**
```javascript
const tokenResponse = await axios.post(
`https://${ZENDESK_SUBDOMAIN}.zendesk.com/oauth/tokens`,
{
grant_type: "refresh_token",
refresh_token: refresh_token,
client_id: ZENDESK_CLIENT_ID,
client_secret: ZENDESK_CLIENT_SECRET,
scopes: "tickets:write",
expires_in: 86400,
refresh_token_expires_in: 604800,
},
{ headers: { "Content-Type": "application/json" } }
);
```
#### Scope
You must specify a scope to control the app's access to Zendesk
resources. The "read" scope gives access to GET endpoints. It includes
permission to sideload related resources. The "write" scope gives access
to POST, PUT, and DELETE endpoints for creating, updating, and deleting
resources.
**Note**: Don't confuse the **scope** parameter (singular) with the
**scopes** parameter (plural) for non-grant-type tokens described in
[OAuth Tokens](/api-reference/ticketing/oauth/oauth_tokens).
The "impersonate" scope allows a Zendesk admin to make requests on
behalf of end users. See [Making API requests on behalf of end
users](/documentation/ticketing/using-the-zendesk-api/making-api-requests-on-behalf-of-end-users/).
For example, the following parameter gives read access to all resources:
`"scope": "read"`
The following parameter gives read and write access to all resources:
`"scope": "read write"`
You can fine-tune the scope of the following resources:
- [tickets](/api-reference/ticketing/tickets/tickets/)
- [users](/api-reference/ticketing/users/users/)
- [audit logs (read
only)](/api-reference/ticketing/account-configuration/audit_logs/)
- [organizations](/api-reference/ticketing/organizations/organizations/)
- [help center
resources](/api-reference/help_center/help-center-api/introduction/)
- [apps](/api-reference/apps/introduction/)
- [triggers](/api-reference/ticketing/business-rules/triggers/)
- [automations](/api-reference/ticketing/business-rules/automations/)
- [targets](/api-reference/ticketing/targets/targets/)
- [webhooks](/api-reference/webhooks/introduction/)
The syntax is as follows:
`"scope": "resource:scope"`
For example, the following parameter restricts the scope to only reading
tickets:
`"scope": "tickets:read"`
To give read and write access to a resource, specify both scopes:
`"scope": "users:read users:write"`
To give write access only to one resource, such as organizations, and
read access to everything else:
`"scope": "organizations:write read"`
**Note**: The endpoint returns an access token even if you specify an
invalid scope such as `"scope": ["read", "write"]` (no parentheses). Any
request you make with the token will return a "Forbidden" error.
#### Tokens for Implicit Grant Type
The implicit grant flow has been deprecated. It's considered insecure
and its use is highly discouraged.
responses:
'201':
description: Created response
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthTokenForGrantTypesObject'
examples:
default:
$ref: '#/components/examples/OAuthTokenForGrantTypesResponseExample'
components:
schemas:
OAuthClientsResponse:
type: object
properties:
clients:
type: array
items:
$ref: '#/components/schemas/OAuthClientObject'
OauthClientResponse:
type: object
properties:
client:
$ref: '#/components/schemas/OAuthClientObject'
GlobalClientsResponse:
type: object
properties:
global_clients:
type: array
items:
$ref: '#/components/schemas/GlobalClientObject'
GlobalClientResponse:
type: object
properties:
global_client:
$ref: '#/components/schemas/GlobalClientObject'
GlobalClientsTokenSummaryResponse:
type: object
properties:
global_clients:
type: array
items:
$ref: '#/components/schemas/GlobalClientTokenSummaryObject'
OAuthTokensResponse:
type: object
properties:
tokens:
type: array
items:
$ref: '#/components/schemas/OauthTokenObject'
OAuthTokenResponse:
type: object
properties:
token:
$ref: '#/components/schemas/OauthTokenObject'
tags:
- name: Global Clients
- name: Grant Type Tokens
- name: OAuth Clients
- name: OAuth Tokens