Session URL Reference

This page documents the URL format and callback metadata for the browser-based session flow.

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}

Or, when using a preset:

https://x.cartridge.gg/session?public_key={public_key}&preset={preset}&rpc_url={rpc_url}&redirect_uri={redirect_uri}

Parameter	Required	Description
`public_key`	Yes	The public key generated by the native application
`policies`	Yes (unless `preset` is provided)	JSON-encoded session policies object
`preset`	Yes (unless `policies` is provided)	Preset name to resolve policies from `@cartridge/presets`
`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

Additional Fields for Already-Registered Sessions

When a session is already registered and authorized, the callback payload includes additional session identifiers:

Field	Type	Description
`allowedPoliciesRoot`	string	Root hash of the allowed policies for this session
`metadataHash`	string	Hash of the session metadata
`sessionKeyGuid`	string	Unique identifier for the session key
`guardianKeyGuid`	string	Unique identifier for the guardian key
`alreadyRegistered`	boolean	Flag indicating this is an existing session

These fields are only included when returning an existing authorized session (when alreadyRegistered is true). For new session registrations, only the basic metadata fields are returned.

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.