Skip to main content

Managing Session Keys

This guide covers the operational details of creating, listing, and revoking session keys via the Clearnode API.

Prerequisites

Before diving into session key management, make sure you understand the core concepts: what session keys are, how applications and allowances work, and the expiration rules. See Session Keys for the conceptual foundation.

How to Manage Session Keys​

Clearnode​

Create and Configure​

To create a session key, use the auth_request method during authentication. This registers the session key with its configuration:

Request:

{
  "req": [
    1,
    "auth_request",
    {
      "address": "0x1234567890abcdef...",
      "session_key": "0x9876543210fedcba...",
      "application": "Chess Game",
      "allowances": [
        {
          "asset": "usdc",
          "amount": "100.0"
        },
        {
          "asset": "eth",
          "amount": "0.5"
        }
      ],
      "scope": "app.create",
      "expires_at": 1762417328
    },
    1619123456789
  ],
  "sig": ["0x5432abcdef..."]
}

Parameters:

  • address (required): The wallet address that owns this session key
  • session_key (required): The address of the session key to register
  • application (optional): Name of the application using this session key (defaults to "clearnode" if not provided)
  • allowances (optional): Array of asset allowances specifying spending limits
  • scope (optional): Permission scope (e.g., "app.create", "ledger.readonly"). Note: This feature is not yet implemented
  • expires_at (required): Unix timestamp (in seconds) when this session key expires
note

When authenticating with an already registered session key, you must still fill in all fields in the request, at least with arbitrary values. This is required by the request itself, however, the values will be ignored as the system uses the session key configuration stored during initial registration. This behavior will be improved in future versions.

List Active Session Keys​

Use the get_session_keys method to retrieve all active (non-expired) session keys for the authenticated user:

Request:

{
  "req": [1, "get_session_keys", {}, 1619123456789],
  "sig": ["0x9876fedcba..."]
}

Response:

{
  "res": [
    1,
    "get_session_keys",
    {
      "session_keys": [
        {
          "id": 1,
          "session_key": "0xabcdef1234567890...",
          "application": "Chess Game",
          "allowances": [
            {
              "asset": "usdc",
              "allowance": "100.0",
              "used": "45.0"
            },
            {
              "asset": "eth",
              "allowance": "0.5",
              "used": "0.0"
            }
          ],
          "scope": "app.create",
          "expires_at": "2024-12-31T23:59:59Z",
          "created_at": "2024-01-01T00:00:00Z"
        }
      ]
    },
    1619123456789
  ],
  "sig": ["0xabcd1234..."]
}

Response Fields:

  • id: Unique identifier for the session key record
  • session_key: The address of the session key
  • application: Application name this session key is authorized for
  • allowances: Array of allowances with usage tracking:
    • asset: Symbol of the asset (e.g., "usdc", "eth")
    • allowance: Maximum amount the session key can spend
    • used: Amount already spent by this session key
  • scope: Permission scope (omitted if empty)
  • expires_at: When this session key expires (ISO 8601 format)
  • created_at: When the session key was created (ISO 8601 format)

Revoke a Session Key​

To immediately invalidate a session key, use the revoke_session_key method:

Request:

{
  "req": [
    1,
    "revoke_session_key",
    {
      "session_key": "0xabcdef1234567890..."
    },
    1619123456789
  ],
  "sig": ["0x9876fedcba..."]
}

Response:

{
  "res": [
    1,
    "revoke_session_key",
    {
      "session_key": "0xabcdef1234567890..."
    },
    1619123456789
  ],
  "sig": ["0xabcd1234..."]
}

Permission Rules:

  • A wallet can revoke any of its session keys
  • A session key can revoke itself
  • A session key with application: "clearnode" can revoke other session keys belonging to the same wallet
  • A non-"clearnode" session key cannot revoke other session keys (only itself)

Important Notes:

  • Revocation is immediate and cannot be undone
  • After revocation, any operations attempted with the revoked session key will fail with a validation error
  • The revoked session key will no longer appear in the get_session_keys response
  • Revocation is useful for security purposes when a session key may have been compromised

Error Cases:

  • Session key does not exist, belongs to another wallet, or is expired: "operation denied: provided address is not an active session key of this user"
  • Non-"clearnode" session key attempting to revoke another session key: "operation denied: insufficient permissions for the active session key"

Nitrolite SDK​

The Nitrolite SDK provides a higher-level abstraction for managing session keys. For detailed information on using session keys with the Nitrolite SDK, please refer to the SDK documentation.