Zendesk OAuth Tokens API

openapi: 3.2.0
info:
  version: '1.0'
  title: Zendesk Oauth OAuth Tokens API
  description: Needs a description.
tags:
- name: OAuth Tokens
paths:
  /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 parameter. The client_id 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.


        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.


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


        #### 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 (not the client''s unique identifier). For the ids, see List Clients

        | scopes | array | Valid scopes for the token. See 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.


        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

        * 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
components:
  schemas:
    OAuthTokensResponse:
      type: object
      properties:
        tokens:
          type: array
          items:
            $ref: '#/components/schemas/OauthTokenObject'
    OAuthTokenResponse:
      type: object
      properties:
        token:
          $ref: '#/components/schemas/OauthTokenObject'