Connecting Your Zendesk Instance

Configly uses OAuth 2.0 to securely connect to your Zendesk instance. This page explains how to set it up.

What You'll Need

• Zendesk admin access -- you need permission to approve Zendesk's OAuth consent screen for your account
• A Configly account — sign up at go.configly.app

Step 1: Add the Connection in Configly

1. Go to go.configly.app and sign in
2. Click "Add Connection"
3. Enter your Zendesk subdomain (e.g., acme from acme.zendesk.com)
4. Choose how Configly should access this Zendesk instance. Read-Only (recommended) lets Configly analyse your configuration without being able to make changes. Read/Write grants full access, including Apply Changes and GitHub push-back. You can change this later from the Connections page. See Zendesk Read-Only Mode for detail.
5. Click "Connect with Zendesk" -- this opens the Zendesk OAuth authorisation flow
6. In the Zendesk popup, click "Allow" to authorize Configly
7. You'll be redirected back to Configly with your connection established

Now you can run your first sync →

What Permissions Does Configly Need?

Configly requests one of two OAuth scope sets depending on the access mode you choose when connecting:

• Read-Only -- Configly requests the Zendesk read OAuth scope only. This grants access to read configuration metadata (triggers, automations, macros, views, fields, SLAs, and related objects). Configly cannot modify, create, or delete anything in your Zendesk in this mode.
• Read/Write -- Configly requests the Zendesk read write OAuth scope. This grants the same read access plus the ability to update configuration objects. Required for Apply Changes and GitHub Sync push-back.

Read-Only is the recommended default for most customers and for security reviews. You can switch a connection between modes at any time from the Connections page -- see Zendesk Read-Only Mode.

Neither mode grants access to ticket content, user data, attachments, Help Centre content, or conversation data. Configly works with configuration metadata only.

API endpoints accessed:

Configly accesses 41 configuration types across 7 groups via the Zendesk REST API. All access is read-only unless you explicitly use Apply Changes (Multi-Instance and Agency plans).

Your connection dashboard shows a scope badge indicating whether your connection has read-only or read+write access. If you connected before Apply Changes was available, you can re-authorize to upgrade your permissions.

What Happens Behind the Scenes?

1. You click "Connect with Zendesk" -- Configly redirects your browser to Zendesk with the OAuth scopes for the mode you chose
2. Zendesk asks you to approve — you see exactly what permissions Configly needs
3. You approve — Zendesk sends Configly a secure access token
4. Configly stores the token — encrypted in our database, never exposed
5. Token automatically refreshes — before it expires, Configly gets a new one (no action needed)

Security & Privacy

• Controlled access — Configly only writes to Zendesk when you explicitly use Apply Changes, and only on connections you've granted Read/Write scope. Connections in Read-Only Mode cannot write to Zendesk under any circumstances. Every write requires a change reason, and all operations are logged with full audit trail and rollback support.
• Encrypted storage — all credentials are encrypted using AES-256-GCM
• Automatic token refresh — access tokens are refreshed automatically before expiry
• Revokable — you can disconnect at any time from Configly or Zendesk

Connection Status

Your connection status shows:

• Active — connected and working correctly
• Token Expired — automatic refresh in progress (usually resolves itself)
• Error — connection issue needs attention

If you see an error, click "Refresh Token" to manually refresh the OAuth token.

Managing Connections

Editing a Connection

You can rename your connection at any time:

1. Go to Connections
2. Click the three dots menu
3. Select "Edit"
4. Update the name

Deleting a Connection

Deleting a connection will:

• Remove all stored credentials
• Delete all configuration snapshots for that connection
• Cannot be undone

To delete:

1. Go to Connections
2. Click the three dots menu
3. Select "Delete"
4. Confirm deletion

Troubleshooting

"Subdomain not found"

Your Zendesk subdomain is incorrect. Check the URL you use to access Zendesk (e.g., yourcompany.zendesk.com → use yourcompany).

"Authorisation failed"

You cancelled the OAuth approval or there was an error. Try again, and make sure to click "Allow" when Zendesk asks for permission.

"Connection test failed"

Zendesk may be experiencing issues, or your account may lack the necessary permissions. Contact your Zendesk administrator.

See more troubleshooting →

Next Steps

Once connected, you're ready to run your first sync →