OAuth 2.0 for Encompass Developer Connect: Setup Without the Surprises
The SDK never made you think about authentication. Your plugin ran inside a logged-in session; your batch job stored an Encompass username and password and logged in like a person. Developer Connect replaces all of that with OAuth 2.0 — and in ICE’s own migration sequence, standing up OAuth is the step between “we’ve mapped our components” and “we’ve made our first API call.”
It’s not hard. But every team ports a few SDK habits that turn into production incidents later. Here’s the setup, and the habits to leave behind.
The moving parts
Developer Connect authentication comes down to four things:
- API credentials — a client ID and client secret issued for your Encompass instance through ICE’s developer portal, per environment. These identify your application, not a person.
- A grant flow — how you exchange credentials for a token. Server-to-server automations (the typical SDK-batch-job replacement) authenticate as an application, optionally tied to a dedicated service account; user-facing tools can authenticate on behalf of a specific Encompass user so actions attribute correctly.
- A bearer token — short-lived proof you present on every API request.
- Token lifecycle handling — the code that gets a fresh token before the old one expires, without requesting a new one per call.
The setup checklist
- Separate credentials per environment. Sandbox/test credentials and production credentials are different secrets against different instances. Nothing that touched production secrets should be reachable from a developer laptop.
- Create a dedicated service account for server-side automation, with a persona scoped to what the integration actually does. The SDK era’s habit — automation running under a shared admin login — is exactly the thing OAuth exists to end. When the auto-disclosure job misbehaves, you want its actions attributable to
svc-disclosures, not to whichever admin’s password got embedded in 2019. - Store secrets in a secrets manager (Azure Key Vault, AWS Secrets Manager, or equivalent) — not in
app.config, not in source control. If your SDK apps had credentials in config files, migration is the moment that debt gets paid. - Cache tokens; refresh proactively. Tokens are short-lived by design. The two classic failures: requesting a new token for every API call (you’ll hit auth rate limits and add latency to everything), and never refreshing (your long-running batch dies mid-pipeline when the token expires). Get a token, reuse it, refresh a comfortable margin before expiry.
- Plan for 401s anyway. Even with proactive refresh, treat an auth failure as a retry-with-fresh-token event, not a crash.
Where teams get bitten
The mid-batch expiry. An SDK job that ran for two hours on one login now outlives its token. Any loop long enough to span an expiry needs refresh logic inside the loop, not just at startup.
The everything-account. One service account, admin persona, shared by five integrations — the blast radius of one leaked secret becomes your whole instance, and the audit trail becomes a shrug. One integration, one account, least privilege.
The forgotten rotation. Client secrets should be rotatable without a deploy. If rotating a secret means editing a config file on a server by hand, you’ll postpone it until it’s an emergency.
Sandbox drift. Testing against a sandbox instance whose personas and settings don’t match production means your first production token “works” and your first production API call doesn’t. Sync the persona configuration, not just the credentials.
Why this step is worth doing properly
OAuth is the foundation everything after it stands on: the webhook consumers that replace your polling loops, the services that replace your plugins, the v3 loan API calls that replace your SDK reads and writes. A clean credential model set up in week one is invisible for the rest of the migration. A sloppy one generates mystery failures for years.
We set this up as part of every SDK-to-API migration — credentials, service accounts, token handling, and the first passing API call, documented so your team owns it.