Zendesk Grant Type Tokens API

openapi: 3.1.0
info:
  version: '1.0'
  title: Zendesk Account Account Settings Grant Type Tokens API
  description: Needs a description.
tags:
- name: Grant Type Tokens
paths:
  /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.\n\nUsing a Zendesk username and password to gain an OAuth access token (password grant type flow) has been deprecated and is highly discouraged.\n\nAn access token can be revoked. Use the [OAuth Tokens API](/api-reference/ticketing/oauth/oauth_tokens) to list, show, or revoke tokens.\n\n#### Request parameters\n\nThe POST request takes the following parameters, which must be formatted as JSON:\n\n| Name          | Description\n| ------------- | --------------------------------------------------\n| grant_type    | \"authorization_code\", \"refresh_token\", or \"client_credentials\"\n| 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\n| 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)\n| 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)\n| 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)\n| scope         | Valid scope for this token. A string of space-separated values. See [Scope](#scope) below\n| 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\n| 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)\n| refresh_token | The refresh token\n\n**Example Node.js authorization code grant flow**\n\n```javascript\nconst tokenResponse = await axios.post(\n  `https://${ZENDESK_SUBDOMAIN}.zendesk.com/oauth/tokens`,\n  {\n    grant_type: \"authorization_code\",\n    code: req.query.code,\n    client_id: ZENDESK_CLIENT_ID,\n    redirect_uri: REDIRECT_URI_PKCE,\n    scope: \"read write\",\n    code_verifier: CODE_VERIFIER,\n    expires_in: 86400,\n    refresh_token_expires_in: 604800,\n  },\n  { headers: { \"Content-Type\": \"application/json\" } }\n);\n```\n\n**Example Node.js refresh token grant flow**\n\n```javascript\nconst tokenResponse = await axios.post(\n  `https://${ZENDESK_SUBDOMAIN}.zendesk.com/oauth/tokens`,\n  {\n    grant_type: \"refresh_token\",\n    refresh_token: refresh_token,\n    client_id: ZENDESK_CLIENT_ID,\n    client_secret: ZENDESK_CLIENT_SECRET,\n    scopes: \"tickets:write\",\n    expires_in: 86400,\n    refresh_token_expires_in: 604800,\n  },\n  { headers: { \"Content-Type\": \"application/json\" } }\n);\n```\n\n#### Scope\n\nYou 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.\n\n**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).\n\nThe \"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/).\n\nFor example, the following parameter gives read access to all resources:\n\n`\"scope\": \"read\"`\n\nThe following parameter gives read and write access to all resources:\n\n`\"scope\": \"read write\"`\n\nYou can fine-tune the scope of the following resources:\n\n- [tickets](/api-reference/ticketing/tickets/tickets/)\n- [users](/api-reference/ticketing/users/users/)\n- [audit logs (read only)](/api-reference/ticketing/account-configuration/audit_logs/)\n- [organizations](/api-reference/ticketing/organizations/organizations/)\n- [help center resources](/api-reference/help_center/help-center-api/introduction/)\n- [apps](/api-reference/apps/introduction/)\n- [triggers](/api-reference/ticketing/business-rules/triggers/)\n- [automations](/api-reference/ticketing/business-rules/automations/)\n- [targets](/api-reference/ticketing/targets/targets/)\n- [webhooks](/api-reference/webhooks/introduction/)\n\nThe syntax is as follows:\n\n`\"scope\": \"resource:scope\"`\n\nFor example, the following parameter restricts the scope to only reading tickets:\n\n`\"scope\": \"tickets:read\"`\n\nTo give read and write access to a resource, specify both scopes:\n\n`\"scope\": \"users:read users:write\"`\n\nTo give write access only to one resource, such as organizations, and read access to everything else:\n\n`\"scope\": \"organizations:write read\"`\n\n**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.\n\n#### Tokens for Implicit Grant Type\n\nThe implicit grant flow has been deprecated. It's considered insecure and its use is highly discouraged.\n"
      responses:
        '201':
          description: Created response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthTokenForGrantTypesObject'
              examples:
                default:
                  $ref: '#/components/examples/OAuthTokenForGrantTypesResponseExample'