openapi: 3.1.0 info: 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