Identity and credentials - Polygon Developer Docs

Your backend proves its identity to OMS with an OIDC ID token that you issue yourself. The SDK exchanges that token for a wallet credential and renews it automatically.

The identity triple

Three values identify your application to OMS:

Value	Meaning
`issuer`	The `iss` claim of your ID tokens, and the OIDC issuer URL you register with your OMS project
`audience`	The `aud` claim, registered alongside the issuer
`subject`	The `sub` claim, an immutable application identifier that you choose

One subject maps to one EVM wallet. Changing the subject addresses a different wallet, so treat it as permanent once you have funded the wallet it maps to.

Register the issuer

Your issuer must be reachable over public HTTPS and serve OIDC discovery and JWKS documents. Register its URL and audience with your OMS project before the SDK can authenticate. Keep the issuer signing key stable across restarts and deployments. A new key invalidates tokens that OMS has already cached against your published JWKS.

Supply ID tokens

tokenProvider issues a fresh ES256 ID token on demand:

const wallet = new ServerWallet({
  subject,
  issuer,
  audience,
  tokenProvider: async () => {
    const token = await signIdToken({ iss: issuer, aud: audience, sub: subject })
    return { token, expiresAt: Math.floor(Date.now() / 1000) + 300 }
  },
  transport,
  store,
  executor,
})

expiresAt is Unix time in seconds, not milliseconds. A millisecond value puts the expiry far in the future and stops the SDK from refreshing the token when it should. The SDK generates its own P-256 credential, commits the token’s hash, completes authentication, and binds the wallet for your identity. Your ID token never becomes the wallet credential.

Credential lifetime and renewal

Credentials last six hours by default. Set sessionLifetimeSeconds to change that. The SDK renews a credential once it comes within sixty seconds of expiring, so ordinary operation needs no renewal code. It also recovers on its own from a verified response reporting an unknown, expired, or revoked credential, by reauthenticating once and retrying. Persistent authorization failures propagate to your caller instead of retrying in a loop. Treat a repeated authorization failure as a configuration problem, not a transient one.

Inspect the current state

const snapshot = await wallet.inspect()

inspect reads persisted state without authenticating and without returning private material:

Field	Meaning
`wallet`	The bound wallet, absent until one exists
`disabled`	Whether the wallet is currently disabled
`expiresAt`	Credential expiry
`credentialId`	The SHA-256 credential identifier
`creationUncertain`	Whether a wallet creation returned no discoverable result

Rotate a credential

await wallet.rotate()

rotate self-revokes the current credential and then authenticates a fresh one. Use it on a schedule, or when you suspect a credential is exposed.

Disable and re-enable

await wallet.setDisabled(true)

Disabling blocks authentication until you explicitly re-enable the wallet. Automatic renewal does not bypass it. A disabled wallet cannot reauthenticate even to poll an operation status, and transfers you already submitted may still complete upstream. Disabling is not a way to cancel work in flight.

Identity errors

Code	Cause
`IDENTITY_MISMATCH`	`tokenProvider` returned a token whose subject or issuer differs from the configured identity
`WALLET_MISMATCH`	The identity resolved to a different wallet than the one in persisted state
`CREATION_UNCERTAIN`	A wallet creation returned no discoverable result

Do not clear persisted state to make a mismatch go away. A mismatch means the identity and the stored wallet disagree, and erasing the record loses the mapping rather than repairing it. CREATION_UNCERTAIN exists for the same reason: it blocks creating a replacement wallet until the original result is reconciled with OMS. Continue with storage and concurrency for the persistence this page assumes.

​The identity triple

​Register the issuer

​Supply ID tokens

​Credential lifetime and renewal

​Inspect the current state

​Rotate a credential

​Disable and re-enable

​Identity errors