Zendesk Configuration#

Configure a Zendesk Support subdomain and an OAuth access token authorized to read staff and legacy API-token metadata.

Authentication#

Use a dedicated account with the permissions below and obtain an OAuth access token using Zendesk’s OAuth setup guide. Supply the token through an environment variable; Cartography authenticates with Authorization: Bearer. The module does not create, revoke, or automatically refresh credentials. Supply a valid token again after expiry or revocation. The OAuth credential authenticates Cartography; the inventory contains legacy API tokens, not OAuth access tokens.

Required Permissions#

For ListApiTokens, Zendesk’s official OpenAPI specification allows administrators or agents with the Manage APIs permission. Full administrator access is therefore not required. On Enterprise plans, use a custom agent role with Manage APIs and permission to view team members for the staff inventory. Manage APIs includes credential-management capabilities on the account; it is not a read-only role permission.

Restrict the collector’s OAuth token to the read scope. The module only issues GET requests to the Users and API Tokens endpoints. Zendesk does not document a dedicated legacy-token inventory OAuth scope in its scope reference. A users:read token alone does not document access to the token inventory.

Configure Cartography#

Option	Value
`--zendesk-subdomain`	Subdomain only, e.g. `acme` for `https://acme.zendesk.com`. URLs and custom hostnames are not accepted.
`--zendesk-oauth-token-env-var`	Name of the environment variable holding the OAuth access token, e.g. `ZENDESK_OAUTH_TOKEN`.
`--selected-modules`	Include `zendesk`.

If either the subdomain or token is missing, the module logs that it is unconfigured and skips ingestion.

Run Cartography#

export ZENDESK_OAUTH_TOKEN='your-oauth-access-token'
cartography \
  --neo4j-uri bolt://localhost:7687 \
  --selected-modules zendesk \
  --zendesk-subdomain acme \
  --zendesk-oauth-token-env-var ZENDESK_OAUTH_TOKEN

Troubleshooting#

401: Check that the OAuth access token is valid and belongs to the configured Zendesk account.
403: Check the token’s read scope and the authenticating user’s administrator role or Manage APIs permission. For the API Tokens endpoint, the module warns and skips token load and cleanup, preserving the previous inventory.
404 from the API Tokens endpoint: Zendesk documents this when API token access is disabled. The module treats this as an empty token inventory and cleans up previously ingested tokens for that account, allowing the run to continue. The endpoint is also scheduled for removal on April 30, 2027.
429: Zendesk rate-limited the request. Rerun after the response’s Retry-After interval; failed collections retain their previously ingested graph data.