Security

A session removes the per-transaction wallet prompt, so its safety depends on both key custody and the onchain scope the user approved. Rhinestone coordinates the grant and intent flow; it does not hold the session private key or decide whether an out-of-scope call is valid.

Responsibility boundaries

Layer	Stores or controls	Does not control
Your application	The session signer, the returned session handle, and when to request signatures.	It cannot make the onchain validator accept authority the owner did not grant.
Rhinestone	Public grant metadata: account and session-key addresses, origin, permissions, per-chain IDs and statuses, transaction hashes, expiry, and the recoverable handle.	It does not receive the session private key. Its registry is not the execution authority.
Smart account and session-key validator	Installed permission configuration, chain-specific authority, policy state, and revocation.	It does not verify app-supplied labels or protect an in-scope key from misuse.
Orchestrator and settlement contracts	The prepared intent, signatures, routing, and settlement execution.	They do not broaden the session configuration installed on the account.

The onchain validator checks the contract, selector, calldata rules, native value limit, time window, usage limit, and any crosschain claim permit encoded in the approved session. A request outside those rules fails even if Rhinestone prepared or forwarded it. Names and ABI metadata shown during review improve readability only. Only Rhinestone’s maintained clear-signing registry can supply verified display metadata; app-supplied metadata is not an authorization boundary.

Protect the signer

Treat a session key as a bearer credential for everything inside its scope.

The buildSmartSessionHeadlessSignatures() helper requires an extractable Hex private key. Keep that key in protected local or backend secret storage appropriate to the grant’s value.
A non-exportable KMS or HSM key needs a custom signer and session-key signature implementation. Do not pass a key reference to the helper; that integration is outside this guide.
If a browser must sign, keep the scope short-lived and low-value. Any script that can read the key can use it.
Separate keys by user, account, environment, and purpose. Do not reuse one signer across unrelated grants.
Persist the grant ID, account, signer address, private key, and handle together. Refuse to sign unless the stored account and signer match the handle.
Bind your own backend requests to the authenticated application user and expected smart account before allowing a signing job.
Stop scheduling a function on a chain as soon as its counter is exhausted. Other function or chain counters can remain active. Stop all work on expiry or suspected compromise. Onchain rejection is the final backstop, not normal control flow.

See Session limits for the least-authority controls.

Recover grant metadata

Your application can recover public grant records after local handle loss. The user must have an active embedded-wallet session in the account namespace that created the grant. oneAuth is the @rhinestone/1auth client from Accounts.

const result = await oneAuth.listSessionGrants({
  accountAddress,
});

if (!result.success || !result.grants) {
  throw new Error(result.error?.message ?? "Could not load session grants");
}

const activeGrant = result.grants.find(
  (grant) => !grant.revokedAt && grant.sessionKeyHandle,
);

if (!activeGrant?.sessionKeyHandle) {
  throw new Error("No recoverable active grant");
}

The default app-origin account namespace is the exact browser host. A registered app can explicitly configure a shared rpId; its server-authorized sibling origins then use that shared RP and account namespace. A matching clientId alone does not share the account namespace. Reuse the same clientId, rpId, and authenticated account configuration when recovering a shared-RP grant. The recovered handle contains no private signing capability. Pair it only with a signer whose public address matches sessionKeyHandle.sessionKeyAddress and whose stored account matches sessionKeyHandle.accountAddress. If the private key was lost, create a new signer and grant rather than pretending the old session is recoverable.

Revoke authority

The public @rhinestone/1auth 0.10.1 SDK has no app-origin revoke method or app-origin account-management entry point. openAccountDialog() is available only to integrations already using experimental cross-origin mode. Do not switch WebAuthn modes to reach it—the modes select different credentials and accounts—and do not call the provider’s internal revoke routes.

Deleting a key or handle from application storage does not revoke the onchain session. It stops that copy of the app from using the grant, but a leaked key can still use any unexpired function and chain counter.

For app-origin integrations, stop automation immediately and contact Rhinestone through your existing support channel with the account address, grant ID, session-key address, and affected chains. Ask for the currently supported response options; support contact is not itself onchain revocation. Until a public owner-authorized path exists, use short expiry windows, low per-call caps, and low per-function use counts. Fail closed when grant state or signer consistency cannot be confirmed. For an experimental cross-origin integration, the user can inspect and revoke grants in its account dialog. For a multi-chain grant, confirm the result on every chain. One chain can remain active after another has been removed.

Incident response

If a signer may be compromised:

Stop every worker and browser task that can use it, and reject new signing requests.
Preserve the account address, grant ID, signer address, handle, and affected chain IDs for response.
If the existing integration uses experimental cross-origin mode, direct the user to its account dialog. If it uses app-origin mode, escalate through your Rhinestone support channel.
Treat every unexpired function and chain counter as usable until its onchain configuration is confirmed removed or its limits expire.
Remove the signer from application storage, then create a narrower replacement only after identifying the exposure.

Never rotate only the stored handle. Permission IDs and handles describe authority; they are not replacement credentials.

Embedded wallet

Custom setup

Responsibility boundaries

Protect the signer

Recover grant metadata

Revoke authority

Incident response

​Responsibility boundaries

​Protect the signer

​Recover grant metadata

​Revoke authority

​Incident response

Responsibility boundaries

Protect the signer

Recover grant metadata

Revoke authority

Incident response