Salesforce client credentials flow changes callback governance

At a glance

What this is: This is a technical guide to configuring Salesforce OAuth client credentials flow for OneSpan Sign callback notifications, with a focus on removing user-delegated refresh-token handling.

Why it matters: It matters because IAM teams need to govern server-to-server callback identities as non-human identities, not as simplified app integrations, or they will miss scope, ownership, and permission errors.

👉 Read OneSpan's guide to Salesforce OAuth 2.0 client credentials callbacks

Context

Salesforce callback integrations only stay safe when the non-human identity behind them is explicitly scoped, assigned, and monitored. In this pattern, the access token is not tied to a person but to an integration context, which means the usual assumptions behind delegated user auth no longer apply.

The practical IAM question is whether the integration has a stable operating identity, the right scopes, and a controlled run-as user. OneSpan's guide shows that client credentials flow can reduce token handling overhead, but it also makes the permission model and callback governance more explicit, not less.

Key questions

Q: How should teams govern Salesforce client credentials flows for server-to-server callbacks?

A: Treat the callback as a non-human identity with an assigned owner, a scoped app, and a defined run-as user. The key controls are matching OAuth scope to the grant type, limiting the permissions behind the run-as user, and storing the encoded credential bundle as a managed secret rather than a loose integration artifact.

Q: Why do Salesforce callbacks fail when the run-as user is not set correctly?

A: The client credentials flow needs a user context to determine what the issued token can do. If the run-as user is missing, inactive, or under-privileged, Salesforce returns invalid_grant or the callback cannot complete, because the application has no effective permission boundary to operate within.

Q: What do security teams get wrong about client credentials flow scopes?

A: They often keep refresh_token or offline_access in the app configuration out of habit from delegated flows. In client credentials flow, those scopes do not apply and can break authentication. The correct model is a narrow server-to-server scope set, usually api, aligned to the integration's actual callback work.

Q: How do teams know if a Salesforce callback integration is configured safely?

A: They should verify three things: the app is explicitly enabled for client credentials flow, the callback endpoint resolves in the target org, and the encoded key contains the correct host and secret values. If any of those drift, the integration may still exist technically but will not be trustworthy operationally.

Technical breakdown

Client credentials flow versus refresh token flow

Client credentials flow is designed for server-to-server authentication where no end user is present. Instead of obtaining a refresh token through interactive authorization, the calling service uses a client ID and client secret to obtain access on behalf of a configured application context. That changes the identity model from user-delegated access to application-delegated access. In Salesforce, the flow only works when the connected app or external client app permits it and the requested scopes match the grant type. Using refresh-token scopes in this flow causes authentication failure because the grant type does not support user-delegated consent.

Practical implication: Practitioners should treat this as an NHI pattern and validate that app scopes match the grant type before deployment.

Why the run-as user controls the effective privilege boundary

In Salesforce client credentials flow, the app itself does not act in a vacuum. The configured run-as user supplies the effective permission context for the issued token, which means object, field, and API permissions are inherited from that identity. This is why the guide requires an active integration or admin user with API Enabled permission and the required access rights. If the run-as user is missing or mis-scoped, Salesforce returns invalid_grant or the callback fails at runtime. From an identity governance perspective, the run-as user is the real control boundary, not the client secret alone.

Practical implication: Security teams should inventory run-as users as privileged non-human identities and review them with the same discipline as service accounts.

Callback registration and base64 key construction

The callback service registration uses a Base64-encoded JSON key containing the Salesforce host, client ID, and client secret. That key is not a generic secret blob. It is a compact credential package that binds the external callback service to a specific org domain and application identity. The guide also shows that line wrapping during Base64 encoding can break the key, which is an example of how secret handling errors often look like protocol failures. The callback endpoint itself is an Apex REST resource, so the receiving side must exist and be addressable before the event listener can work.

Practical implication: Teams should protect the callback key as a secret, validate the target domain, and confirm the receiving endpoint is deployed before registration.

NHI Mgmt Group analysis

Client credentials callback identity is a non-human identity governance problem, not a token-format choice: The article is really about which identity boundary governs a server-to-server callback, and that is an NHI boundary. The access decision shifts from user consent to application and run-as-user control, which means identity, scope, and callback trust have to be managed together. Practitioners should treat the integration as a governed machine identity rather than a convenience shortcut.

Run-as user is the effective privilege owner for the callback flow: Salesforce may issue the token to the application, but the permissions exercised by the callback are rooted in the configured user context. That makes this a lifecycle and privilege-governance issue, not just an OAuth setup task. The control lesson is that the run-as user should be reviewed, assigned, and offboarded like any other privileged NHI.

Static credential packaging is the real operational risk in this pattern: The base64 key combines host, client_id, and client_secret into one deployable object, which concentrates trust and failure into a small credential bundle. Credential packaging drift: this setup is designed for a fixed org host and a stable application secret, but it fails when the encoded key, host, or app context is reused outside that boundary. The implication is that practitioners must rethink how integration secrets are distributed and validated.

OAuth scope hygiene becomes a hard control, not a documentation detail: The guide explicitly warns against adding refresh_token and offline_access in client credentials flow. That is the right pattern for this kind of identity because the flow should not inherit user-delegated semantics. Teams should treat scope mismatch as a governance failure mode and prevent it through app review, not after authentication errors appear.

From our research:

• 64% of valid secrets leaked in 2022 are still valid and exploitable today, proving that detection alone is not enough without automated revocation, according to the State of Secrets Sprawl 2026.
• AI-related credential leaks surged 81.5% year-over-year in 2025, with the surrounding AI infrastructure leaking 5x faster than core LLM providers.
• For a deeper control lens, see Ultimate Guide to NHIs , Static vs Dynamic Secrets for how long-lived secrets and ephemeral credentials change governance.

What this signals

Client credentials flows will keep expanding because they simplify machine-to-machine integration, but the governance burden shifts to ownership, scope, and secret handling. In practice, that means integration identity reviews need to include the run-as user, the encoded credential bundle, and the callback endpoint together, not as separate checklists.

Credential bundle governance: the encoded key is not just transport data, it is the operational boundary of the integration. Teams that already rely on secrets managers, lifecycle reviews, and privileged access controls should extend those controls to callback identities before sprawl turns into invisible access debt.

For practitioners

• Map the callback to a governed NHI owner Assign ownership for the Salesforce callback integration to a named platform or identity team, and treat the client_id, client_secret, and run-as user as one managed identity set. Review that owner during lifecycle and access recertification, not only during implementation.
• Separate client credentials flows from delegated OAuth patterns Remove refresh_token and offline_access from any app used for server-to-server callbacks, and verify that only api scope is granted. This prevents user-delegated semantics from leaking into a non-human integration pattern.
• Validate the callback endpoint before registration Confirm the Apex REST resource exists, the namespace path is correct, and the callback URL matches the org host exactly before registering the listener. Keep sandbox and production host values separate so the key does not fail during authentication.
• Treat the encoded callback key as a secret bundle Store the Base64-encoded JSON key in a secret manager, restrict who can regenerate it, and rotate the underlying client_secret on a defined schedule. The encoded object should be handled like other operational secrets, not pasted into scripts or tickets.

Key takeaways

• Salesforce client credentials callbacks are governed as non-human identities, so the run-as user and app scopes define the real permission boundary.
• The strongest operational risk is not the OAuth label but the secret bundle, because host, client_id, and client_secret can drift outside the intended org boundary.
• Teams that manage callback integrations as lifecycle-governed NHIs will catch scope errors, permission mismatches, and secret sprawl earlier.

Key terms

• Client Credentials Flow: A machine-to-machine OAuth grant that lets an application obtain access without a human user signing in. In identity governance terms, the application becomes the controlled actor, so scope, secret handling, and ownership matter more than end-user consent mechanics.
• Run-as User: The Salesforce user context that supplies the effective permissions for a client credentials flow. It is the privilege anchor for the integration, which means its status, permissions, and lifecycle must be managed like a privileged non-human identity.
• Callback Endpoint: A receiving service that accepts event notifications from another system, often through a REST interface. For identity teams, the endpoint is part of the trust boundary because its authentication, reachability, and authorization determine whether the integration can be safely used.
• Encoded Secret Bundle: A packaged secret object that combines multiple credential values into one transferable string, often for configuration or registration. It is convenient operationally but increases governance risk because one leaked bundle can expose both identity material and environment context.

Deepen your knowledge

NHI governance, agentic AI identity, and machine identity security are core topics in our NHI Foundation Level course, the industry's only accredited NHI security programme. If you are responsible for identity security strategy or NHI governance in your organisation, it is worth exploring.

This post draws on content published by OneSpan: Salesforce OAuth 2.0 client credentials flow for OneSpan Sign developers. Read the original.