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

# Authentication

> Keep your own login, authorize requests with a builder key and verify wallets for shipping.

Your app owns account login and wallet connection. Gacha, Marketplace and Redeem support a user's EOA without a Renaiss account or Safe. Renaiss checks the builder's permission and the wallet's authority for each action.

## Credentials by operation

| Operation | Builder key | Wallet access token | Wallet signature |
| - | - | - | - |
| Public pack and marketplace catalogs | No | No | No |
| Wallet pull history, draw status and buyback offers | Yes | No | No |
| Gacha pull or buyback | Yes | No | Action signature |
| Marketplace prepare | Yes | No | No |
| Marketplace order, trade or cancellation | Yes | No | Action signature |
| Shipping challenge, verification, refresh or revoke | Yes | No | Message signature at verification |
| Redeem cards, quotes, orders and tracking | Yes | Yes | No |
| Redeem checkout submission | Yes | Yes | Action signature |

The builder key uses `x-builder-api-key`. A wallet access token uses `Authorization: Bearer <accessToken>`. When both are required, send both headers; they serve different purposes.

Wallet access tokens are issued after wallet verification. Their scopes determine which operations they authorize. The currently supported scopes are `redeem:read` and `redeem:write`, used for private Redeem operations.

## Keep the builder key on your backend

For browser integrations, send SDK requests through a backend route such as `/api/renaiss`. The backend forwards to your assigned API and supplies its builder key.

Authenticate requests with your own user session, authorize the requested operation and apply rate limits. Allow only the required upstream routes and methods. Set the upstream key yourself rather than forwarding a client-supplied key. Forward the wallet access token when required and preserve streaming responses for gacha pulls.

Do not put builder keys in `NEXT_PUBLIC_*` variables or return them to the browser. Exclude bearer tokens, refresh tokens, signatures and shipping details from routine application logs.

## Verify a wallet for shipping

Request verification when the user opens private shipping data or starts Redeem. Wallet connection alone does not create this session. The user signs a message allowing shipping access; checkout later requires a separate action signature.

```ts theme={null}
import {
  BNB_TESTNET,
  createRedemptionClient,
  getError,
  isFailed,
  type RenaissSigner,
} from '@renaiss-protocol/client';

export async function verifyForShipping(signer: RenaissSigner) {
  const shipping = createRedemptionClient({
    baseUrl: '/api/renaiss',
    network: BNB_TESTNET,
    signer,
    walletSessionIssuer:
      'https://dev-api.renaiss.xyz/v2/auth/wallet',
  });

  const result = await shipping.connectRedemptionWallet({
    origin: window.location.origin,
  });
  if (isFailed(result)) throw new Error(getError(result).detail);
  return shipping;
}
```

Reuse that client for private requests. It holds the scoped credentials in memory and refreshes them within the session lifetime. On your app's logout, wallet change or chain change, call `disconnectRedemptionWallet()` and clear private UI state.

### Frontend origin and API issuer

| Setting | Example | Identifies |
| - | - | - |
| Registered frontend origin | `https://cards.example.com` | The page requesting the signature |
| `walletSessionIssuer` | `https://dev-api.renaiss.xyz/v2/auth/wallet` | The API issuing and verifying the session |
| SDK `baseUrl` | `/api/renaiss` | Where the browser sends requests |

Register the exact frontend scheme, host and port for your builder. An origin has no path or trailing slash. Local HTTP loopback origins must be registered explicitly; `http://localhost:3311` and `http://127.0.0.1:3311` are separate origins.

Configure the issuer from your deployment details. With a relative proxy it is required; with an absolute API URL the SDK defaults to that origin plus `/v2/auth/wallet`. An alias may still have a different canonical issuer. Never take the expected issuer from an unvalidated signing challenge.

### Session timing

| Timer | Default | When it expires |
| - | - | - |
| Signing challenge | 5 minutes | Request a fresh challenge and signature |
| Wallet access token | 15 minutes | SDK refreshes it within the renewable session |
| Renewable session | 7 days | Verify the wallet again |

An expired or cancelled signature prompt leaves the wallet unverified. Retry after the user's next verification action. The signed message explains the permission and session duration; it does not authorize a transaction.

For raw HTTP integration, use `/v2/auth/wallet/nonce`, `/verify`, `/refresh` and `/revoke`. Sign the returned message byte for byte. The SDK validates the wallet, chain, origin, issuer, audience, scopes and expiry before prompting. The [API reference](/api-reference) defines the request bodies and challenge context.

## Identity providers

You can supply an EOA signer from your own Privy or other embedded-wallet integration. Its login token is not a Renaiss wallet access token. Partner identity-token/JWKS authentication is not supported by this API; obtain a wallet access token through wallet verification.

[Sign in with Renaiss](/sso-integration) is optional OIDC account login. It is not required for these wallet flows and does not replace shipping verification.