Session Flow
Native applications use a browser-based authentication flow to link locally-generated session keys to a user's Controller account. This allows the native app to sign transactions on behalf of the user without requiring the user to authenticate for each transaction.
Flow Overview
Generate a new keypair locally
The native application generates a new keypair using a local cryptographic utility. The private key should be stored securely and used to sign transactions. The public key will be sent to the Controller keychain for registration.
Initiate the Controller login flow via browser
The application opens a browser window to the Controller session URL, passing the public key and session policies as URL parameters. The user is prompted to log in with their Controller account.
User authenticates and session is registered
The user completes the Controller WebAuthn login flow in the browser. The keychain signs the public key and policy root using the user's credentials. The session registration is submitted through the Cartridge API, which records the session authorization onchain at the Controller contract.
Application receives callback with Controller address
After successful authentication, the application receives the user's Controller address via callback. This address should be used when preparing transactions.
Application signs transactions with the session signer
The native application can now sign transactions using the locally-stored private key. These transactions are validated against the recorded session and executed.
Session URL Format
The session URL follows this structure:
https://x.cartridge.gg/session?public_key={public_key}&policies={policies}&rpc_url={rpc_url}&redirect_uri={redirect_uri}| Parameter | Required | Description |
|---|---|---|
public_key | Yes | The public key generated by the native application |
policies | Yes | JSON-encoded array of policy objects |
rpc_url | Yes | The RPC URL for the target chain |
redirect_uri | No | URL to redirect after session creation |
redirect_query_name | No | Query parameter name for the redirect |
callback_uri | No | URL to POST session data after creation |
Policy Structure
Each policy object defines which contract methods the session key is authorized to call:
{
"target": "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7",
"method": "transfer"
}The policies parameter should be a JSON array of these objects.
Session Metadata
After successful session creation, the following metadata is available:
| Field | Type | Description |
|---|---|---|
address | string | The user's Controller contract address |
ownerGuid | string | Unique identifier for the account owner |
expiresAt | number | Session expiration timestamp (Unix seconds) |
username | string? | The user's Cartridge username |
sessionId | string? | Unique identifier for this session |
appId | string? | The application identifier |
isRevoked | boolean | Whether the session has been revoked |
Fields marked with ? are only populated when creating sessions via the subscription API flow (createFromSubscribe).
When creating sessions directly with the constructor, these fields will be null.