> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polygon.technology/llms.txt
> Use this file to discover all available pages before exploring further.

# Identity and credentials

> Register an OIDC issuer, supply ID tokens to the Server Wallet SDK, and manage credential renewal, rotation, and disablement.

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:

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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](/wallets/sdk/server/storage-and-concurrency) for the persistence this page assumes.