***

title: Wallet Auth
subtitle: Normalize Gwop auth into app-owned primitives
slug: integration-patterns/wallet-auth
--------------------------------------

Keep the Gwop auth lifecycle in a thin adapter instead of calling the SDK directly from routes. That keeps your API surface app-shaped while still making the upstream flow obvious.

## The lifecycle

1. Create the auth intent.
2. Hand the returned payment URLs to the agent.
3. Exchange the settled intent for a bearer token.
4. Use `sid` for live session lookup or revocation.

## Create an auth challenge

```typescript
import { randomUUID } from "node:crypto";

const { result: intent } = await gwop.authIntents.create(
  {
    idempotencyKey: randomUUID(),
    body: {
      metadata: {
        source: "docs-example",
      },
    },
  },
  identityRequestOptions,
);

console.log(intent.authIntentId);
console.log(intent.challenge.paymentMethods);
```

Each returned `paymentUrl` is a payable x402 challenge. The wallet proves control by settling that dust invoice.

## Exchange for a bearer token

```typescript
const { result: token } = await gwop.authIntents.exchange(
  {
    authIntentId: intent.authIntentId,
    idempotencyKey: randomUUID(),
  },
  identityRequestOptions,
);

console.log(token.accessToken);
console.log(token.principal.sub);
console.log(token.session.sid);
console.log(token.account.isNewAccount);
```

Carry four things forward from the exchange response:

* `accessToken` for authenticated requests
* `principal.sub` as the durable wallet identity
* `session.sid` as the revocable session handle
* `account.isNewAccount` to shape signup versus repeat-login UX

## Why the adapter matters

The adapter converts Gwop responses into app primitives and keeps upstream details like chain normalization, session status mapping, and logging out of route handlers.

## Related pages

<CardGroup cols={2}>
  <Card title="Auth Overview" icon="duotone shield-halved" href="/auth/overview">
    See the full wallet-auth lifecycle and what auth unlocks in your backend
  </Card>

  <Card title="Wallet Identity" icon="duotone fingerprint" href="/concepts/wallet-identity">
    Learn why `{chain}:{address}` is the durable identity you carry forward
  </Card>

  <Card title="Create Auth Intent" icon="duotone key" href="/auth/create-intent">
    See the raw create call and response fields in the operational docs
  </Card>

  <Card title="Sessions" icon="duotone id-card" href="/auth/sessions">
    Check the live session state and revoke sessions when logout matters
  </Card>
</CardGroup>