Acumatica Secure API Key Rotation

API key rotation on Acumatica integrations sounds simple until you try to do it on a live instance with three external systems calling in around the clock, and discover the naive approach - revoke the old key, generate a new one, update every caller - guarantees a window where every integration is broken simultaneously. The fix is not a smarter revocation script; it's designing the credential so rotation is a non-event in the first place.

The single-key model is the actual problem

Most Acumatica REST integrations I inherit authenticate with one shared API user and one long-lived credential, referenced by every consuming system. Rotating that credential means a coordinated cutover across every integration at once, which in practice never happens cleanly - someone always forgets a scheduled job, a Zapier connection, or a partner's system that only your client's ops team knows about. The fix isn't a better rotation runbook for the single-key model; it's not having a single shared key at all.

Dual-key overlap: the pattern that actually works

Acumatica's OAuth 2.0 client credential flow supports multiple active client secrets per connected application simultaneously - use that instead of forcing a hard cutover. Generate the new secret alongside the old one, update consumers one at a time over a real overlap window, then retire the old secret only once nothing is using it anymore:

protected virtual void _(Events.RowInserted<AccessTokenLog> e)
{
    if (e.Row == null) return;
    // Tag every issued token with the client secret's key ID so you can
    // see, from actual traffic, when the old secret truly stops being used
    e.Row.UsrClientSecretKeyID = e.Row.ClientID?.Substring(0, 8);
}

On a payment-gateway integration I rotated last year, the overlap window ran two weeks - long enough to catch a scheduled nightly reconciliation job that only fired once every two weeks and would otherwise have silently started failing with 401s after the old key was pulled.

Don't retire the old key until traffic tells you to

The mistake I made once, early on: retiring the old credential on a calendar date rather than on evidence. Instrument token issuance (or, at minimum, check Acumatica's connected application usage logs) to confirm zero requests are still authenticating with the old secret before you revoke it. A calendar-based cutover assumes you have a complete inventory of every consumer, and on any instance with more than two integrations, that inventory is wrong more often than people admit.

Pick a cadence and automate the reminder, not the rotation itself

I don't recommend fully automated unattended rotation for Acumatica API keys - the overlap window needs a human confirming traffic has actually moved before the old key dies, because the blast radius of getting it wrong is every integration failing at once. What I do automate: a scheduled reminder (a Business Event, ironically, or just a calendar hook) at a fixed interval - quarterly is reasonable for most clients, monthly for anything handling payment or PII data - that kicks off the dual-key overlap process rather than letting rotation happen only reactively after an incident or an auditor's question.

Wrapping up

Rotation is painful exactly in proportion to how many things depend on one shared, long-lived key. Move to per-consumer OAuth client credentials where you can, always rotate through a real overlap window with both secrets valid simultaneously, and confirm the old key is unused from actual traffic before revoking it rather than trusting your own inventory of who's calling in.