Authentication

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.

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 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 is optional OIDC account login. It is not required for these wallet flows and does not replace shipping verification.

Getting started

Build a flow

Reference

Partner integrations

Credentials by operation

Keep the builder key on your backend

Verify a wallet for shipping

Frontend origin and API issuer

Session timing

Identity providers

​Credentials by operation

​Keep the builder key on your backend

​Verify a wallet for shipping

​Frontend origin and API issuer

​Session timing

​Identity providers

Credentials by operation

Keep the builder key on your backend

Verify a wallet for shipping

Frontend origin and API issuer

Session timing

Identity providers