Zendesk Read-Only Mode

Zendesk Read-Only Mode is a connection setting that restricts Configly to read-only access to your Zendesk instance. Configly can still analyse your configuration, diff snapshots, map dependencies, run health checks, analyse with AI, and export to GitHub. It cannot modify anything in your Zendesk.

Who Read-Only Mode is for

Read-Only Mode is the recommended default for most customers. It is particularly useful if you:

Are evaluating Configly and want to understand what it does before granting write access
Use Configly primarily for visibility, auditing, or Git-based change tracking
Have a security policy that requires least-privilege access for third-party integrations
Want a strong guarantee that Configly cannot affect live configuration, even accidentally

Read-Only Mode is not for you if you need Configly to write changes back to your Zendesk instance. If you plan to use Apply Changes or push configuration back through GitHub Sync, choose Read/Write when you connect, or upgrade a Read-Only connection later.

What Read-Only Mode does

When you connect in Read-Only Mode, Configly requests only the Zendesk read OAuth scope. Zendesk's consent screen shows read-only access, and the token issued by Zendesk grants read-only access.

In Read-Only Mode, Configly can:

Sync your Zendesk configuration into Configly (triggers, automations, macros, views, fields, SLAs, and every other configuration object Configly supports)
Snapshot, diff, and visualise configuration changes over time
Map dependencies between configuration objects
Run health checks and surface broken references
Analyse impact with AI
Export configuration to GitHub as YAML (GitHub Sync push is one-way: Configly writes to GitHub, not to Zendesk)

What Read-Only Mode does not do

In Read-Only Mode, Configly cannot:

Apply Changes back to your Zendesk configuration
Push configuration changes from GitHub back to Zendesk
Modify, create, or delete any trigger, macro, view, field, or any other Zendesk configuration

Write restrictions are enforced at two layers:

At Zendesk -- the OAuth token granted to Configly has read-only scope. Any write API call made with that token is refused by Zendesk with a 403 Forbidden response. This enforcement happens on Zendesk's infrastructure, outside Configly's control.
In Configly -- the Configly application layer independently blocks write operations on Read-Only connections. Apply Changes and GitHub push-back actions are disabled in the UI with a clear prompt to upgrade the connection if you want to apply changes.

Either layer alone is sufficient to block writes. Both are in place for defence in depth.

Choose Read-Only Mode for a new connection

When you add a new Zendesk connection, the Connect Zendesk dialog shows a mode selector asking "How should Configly access this Zendesk instance?". Choose one of:

Read-Only (default, recommended) -- Configly can analyse your configuration but cannot make changes.
Read/Write -- Full access. Choose if you plan to apply changes or push from GitHub.

After choosing, click Connect and approve the OAuth consent screen that Zendesk shows. The scope listed on the consent screen will match your choice.

Upgrade a Read-Only connection to Read/Write

You can upgrade a Read-Only connection to Read/Write at any time. On the Connections page, find the connection you want to upgrade and click Upgrade to Read/Write. You are redirected to Zendesk's consent screen to approve the new scopes. When you approve, Configly stores the new token and the connection is immediately ready for Apply Changes.

Upgrades preserve your connection history. Existing snapshots, virtual changes, and sync state remain intact -- only the OAuth scope changes.

Downgrade a Read/Write connection to Read-Only

You can downgrade a Read/Write connection to Read-Only from the Connections page. Click Downgrade to Read-Only. A confirmation dialog explains that downgrading re-authorises the connection with read-only access, and that you will lose Apply Changes and GitHub push-back for this instance until you upgrade again.

Like upgrades, downgrades preserve your connection history and re-authorise at the new scope.

FAQ

Is Read-Only Mode available on existing connections?

Yes. Any existing OAuth-based Read/Write connection can be downgraded to Read-Only from the Connections page. Your connection history is preserved.

Does Read-Only Mode affect GitHub Sync?

No. GitHub Sync is one-way -- Configly exports your Zendesk configuration to GitHub as YAML. This is a write to GitHub, not a write to Zendesk, and works identically in Read-Only and Read/Write modes.

The only GitHub Sync feature that Read-Only Mode affects is push-back, which would write Git-committed changes back to Zendesk. Push-back is a write to Zendesk and therefore requires Read/Write scope.

Does downgrading lose any data?

No. Downgrading replaces the OAuth token but preserves the connection itself. Snapshots, diffs, dependency maps, and all other Configly data for that connection remain intact. You can upgrade back to Read/Write at any time without losing anything.

What happens to pending virtual changes if I downgrade?

Pending virtual changes are preserved. They remain visible in Configly and you can continue to review, edit, and discard them. However, you cannot apply them to Zendesk until you upgrade the connection back to Read/Write.

Is Read-Only Mode available on all plans?

Yes. Read-Only Mode is available on every Configly plan.

Does Read-Only Mode affect how I'm billed?

No. Read-Only Mode is a connection setting, not a plan or pricing change. You are billed the same regardless of which mode a connection is in.

Can I use Read-Only Mode with an API token instead of OAuth?

No. Read-Only Mode applies to OAuth-based connections only. Zendesk API tokens inherit the full permissions of the user who created the token, so Configly cannot restrict an API token's scope. If you need strict read-only access, use an OAuth connection in Read-Only Mode.

How do I verify a connection is actually Read-Only?

On the Connections page, Read-Only connections show a Read Only badge with a lock icon next to the connection name. You can also verify from Zendesk's side: in the Zendesk Admin Center under Apps and integrations → OAuth Clients → Authorizations, the Configly authorisation shows the granted scopes.

What does Configly traffic look like in my Zendesk audit log?

Every Configly API call to your Zendesk instance includes a User-Agent: Configly/<version> HTTP header and is authorised by the Configly OAuth client (zdg-configly-app). You can filter your Zendesk HTTP request logs by User-Agent to see all Configly traffic, or review authorised OAuth clients in the Zendesk Admin Center to see Configly's granted scopes.

What happens when I disconnect a Configly connection?

When you disconnect a Zendesk connection from Configly, the OAuth token is explicitly revoked at Zendesk as part of the disconnect. The token cannot be used after the disconnect completes, regardless of its remaining lifetime. This behaviour applies in both Read-Only and Read/Write modes.

You can additionally revoke Configly's authorisation from the Zendesk Admin Center at any time.