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 create OAuth clients
• A Configly account — sign up at go.configly.app

Step 1: Create an OAuth Client in Zendesk

1. In Zendesk, go to Admin Centre → Apps and integrations → APIs → Zendesk API

2. Select the OAuth Clients tab

3. Click "Add OAuth Client"

4. Fill in the details:

   Field	Value
   Client Name	Configly (or any name you prefer)
   Description	Configuration management by Configly
   Company	Your company name
   Redirect URL	https://go.configly.app/api/auth/zendesk/callback

5. Click Save

6. Copy the Client ID — shown on the client page after saving

7. Copy the Secret — shown once immediately after saving

Step 2: 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. Paste the Client ID and Secret from Step 1
5. Click "Connect" — this opens the Zendesk OAuth authorization 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 read and write access to your Zendesk configuration. Read access is used to sync your configuration. Write access is used when you choose to apply changes from What-If Mode to your live instance.

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" — Configly uses your Client ID and Secret to start an OAuth flow
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. 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

"I didn't copy the secret"

You'll need to generate a new secret. In Zendesk, go to Admin Centre → Apps and integrations → APIs → Zendesk API → OAuth Clients, select your Configly client, and generate a new secret. Then update the secret in Configly.

"The redirect URL doesn't match"

Make sure the redirect URL in your Zendesk OAuth client is exactly:

https://go.configly.app/api/auth/zendesk/callback

No trailing slash. No http://. It must match exactly.

"I get a 403 error"

Your Zendesk account needs admin access to create OAuth clients. Check with your Zendesk administrator that your role has the necessary permissions.

"Subdomain not found"

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

"Authorization 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 →