Skip to content

PATTERN Cited by 1 source

OAuth-granted access to user wallet

Intent

Use standard OAuth 2.0 (not a wallet-specific consent surface) for the initial handshake in which a consumer grants an AI agent the right to request scoped spends from the consumer's wallet. Reusing OAuth avoids re-inventing the consent flow and lets wallet providers lean on mature IETF / OAuth standards for token issuance, scope, revocation, and refresh.

Context

When a consumer connects an AI agent to a wallet (e.g. Link's wallet for agents), the first question is "how does the consumer grant the agent access?" There are several viable answers:

  • Bespoke wallet consent UI — custom UX, custom token shape, custom revocation surface.
  • OAuth 2.0 — standard authorization-code flow, standard JWT / bearer tokens, standard scopes, standard revocation endpoint.
  • Magic-link / one-time-password — lightweight but harder to rotate, revoke, or scope.
  • Device-binding / WebAuthn — strong per-device but awkward for headless agent contexts.

OAuth 2.0 is the default because every consumer-facing identity system (Google, Apple, Microsoft, Stripe-account- OAuth, Link-account-OAuth) already speaks it; agent SDKs already implement it; scope / revocation / refresh are out-of-the-box.

The 2026-04-29 Link canonical framing:

"First, the consumer grants your agent access to their Link wallet via a standard OAuth flow."

Solution

The wallet plays the OAuth authorization server role. The agent (or the developer's application using the agent) plays the OAuth client role. The consumer is the resource owner. The wallet's spend-request API is the resource server.

agent (OAuth client)
    │
    │  1. kick off OAuth code flow
    ▼
consumer's browser  ─ redirected ─▶  wallet's
                                     authorization server
                                             │
                                             │  2. consumer
                                             │     signs in +
                                             │     reviews scopes
                                             ▼
                                     wallet issues
                                     authorization code
    ◀─── 3. redirect with code ───
agent
    │
    │  4. exchange code for access token
    ▼
wallet's token endpoint  ──▶  access token (+ refresh)
    │
    │  5. agent holds access token
    ▼
agent calls wallet's spend-request API
  with Bearer <access-token>
    │
    │  6. wallet validates token + scope,
    │     surfaces spend-request to consumer
    │     for per-transaction approval
    ▼
  … see
  [patterns/spend-request-approval-before-credential-issuance](<./spend-request-approval-before-credential-issuance.md>)

Load-bearing substrate primitives

  • Authorization-code flow with PKCE — standard OAuth 2.0 + best-practice PKCE for public clients.
  • Scopes — wallet-specific (e.g. "spend-request:create", "wallet:read") but using OAuth's scope parameter.
  • Access tokens — short-lived; typically JWT or opaque bearer. See concepts/oauth-jwt-short-lived-credential for the JWT sub-case.
  • Refresh tokens — longer-lived; rotate access without re-consent.
  • Revocation endpoint — RFC 7009 token revocation. The consumer can revoke an agent's entire grant via the wallet UI, which calls the revocation endpoint.
  1. Client ecosystem reuse. Every major agent SDK / platform already speaks OAuth 2.0; onboarding a new wallet = registering an OAuth client, not learning a new SDK.
  2. Token schema reuse. OAuth access tokens compose with every HTTP library's Bearer-auth support; no new header shape.
  3. Scope vocabulary reuse. Developers already understand OAuth scopes; wallets add their scope names but not new syntactic structure.
  4. Revocation primitive out-of-box. RFC 7009 revocation works; consumer UIs map 1:1 to revoke calls.
  5. Refresh flow standardised. Agents running for weeks don't need re-consent round-trips.
  6. Audit-log convention. OAuth token issuance events are already captured by most identity platforms.

When it fits

  • Consumer-to-agent wallet access — the consumer is a human who can complete an OAuth browser flow at setup time; the agent later acts on a standing grant.
  • Developer-built agents integrating with a third-party wallet. The developer registers as an OAuth client, the consumer authorizes the developer's agent, the agent SDK handles the token exchange.
  • Multi-agent consumer consent. Each agent can hold its own OAuth grant; revoking one doesn't revoke others.

When it doesn't

  • Server-to-server machine wallet access without a human in the loop. OAuth's client-credentials flow works but the consumer-authorization model is unnecessary.
  • Physical-presence-bound wallets (e.g. hardware security keys) where the wallet requires device-binding at each access. WebAuthn / FIDO is the fit.

Failure modes

  • OAuth phishing. An agent-install-time phishing site can impersonate the wallet's authorization server. Mitigation: official app-store listings, verified domains, wallet-issued developer application verification.
  • Over-broad scopes. If the wallet's scope vocabulary is coarse (e.g. a single "use wallet" scope), the consumer cannot grant a least-privilege agent access. Mitigation: fine-grained scopes per action type.
  • Long refresh-token lifetimes. A compromised refresh token may outlive the consumer's attention. Mitigation: anomaly detection + forced re-consent on new device.
  • Client impersonation. A compromised OAuth client secret lets an attacker mint tokens as that client. Mitigation: PKCE for public clients, client-credential rotation for confidential clients.
  • Consent-screen dark patterns. A wallet may default-opt-in to over-broad scopes. Mitigation: explicit per-scope toggles in the consent UI.

Composes with

Canonical instance

Link's wallet for agents (2026-04-29) — "a standard OAuth flow" grants an agent access to a consumer's Link wallet, after which the agent can create spend requests until the consumer revokes.

Prior art + lineage

  • OAuth 2.0 for payments broadly — Open Banking APIs (PSD2) use OAuth to grant third-party payment initiation access to bank accounts. Wallet-for-agents is the consumer-AI-agent specialisation of the same shape.
  • Stripe-account OAuth for Connect platforms — Stripe has a long-running OAuth integration pattern for platforms acting on connected accounts' behalf. Link's wallet for agents adapts the same OAuth-for-delegated- action shape to the agent-on-consumer-behalf case.

What's not disclosed

  • Scope vocabulary — the specific scope strings Link advertises. The launch post says "standard OAuth flow" without naming scopes.
  • Token TTL policy — access-token and refresh-token lifetimes.
  • Device-binding opt-ins — whether the wallet allows consumers to tie an OAuth grant to specific agent devices.
  • Multi-consumer / shared-account OAuth semantics — how joint-wallet grants are shared across principals.

Seen in

Last updated · 446 distilled / 1,275 read