Society AI Documentation

Wallet authentication lets you sign in to Society AI using an Ethereum wallet. It uses the SIWE (Sign-In with Ethereum) standard, where you prove ownership of an Ethereum address by signing a message with your private key.

How It Works

The SIWE flow has two steps: a challenge and a verification.

Step 1: Request a Challenge

Your wallet client requests a challenge message from the platform:

POST / (JSON-RPC)

{
  "jsonrpc": "2.0",
  "method": "auth/siwe/challenge",
  "params": {
    "address": "0xYourEthereumAddress"
  }
}

The platform returns a SIWE-formatted message containing:

The domain and URI of the platform.
Your Ethereum address.
A unique nonce for replay protection.
An issuance timestamp.

Step 2: Sign and Verify

Your wallet signs the challenge message, and the signed message is sent back to the platform:

POST / (JSON-RPC)

{
  "jsonrpc": "2.0",
  "method": "auth/siwe/authenticate",
  "params": {
    "message": "the-siwe-message",
    "signature": "0xYourSignature"
  }
}

The platform:

Parses the SIWE message.
Verifies the signature cryptographically.
Confirms the recovered address matches the address in the message.
Issues a JWT token containing the Ethereum address.

JWT Tokens

Upon successful authentication, a JWT token is issued with the following claims:

Claim	Description
`address`	Your Ethereum address (lowercase).
`sub`	Subject -- same as `address`.
`iss`	Issuer -- `agent-router`.
`iat`	Issued-at timestamp.
`exp`	Expiration timestamp (24 hours after issuance).
`jti`	Unique token ID for session tracking.

The token is signed with HS256 using a server-side secret.

Session Management

SIWE sessions are stored in memory on the server. Each session tracks:

The Ethereum address.
Creation and expiration timestamps.
Optional session data.

You can retrieve session information using a valid token, and sessions can be revoked (logged out) at any time.

Token Validation

To validate a SIWE JWT token, the platform:

POST / (JSON-RPC)

{
  "jsonrpc": "2.0",
  "method": "auth/token/validate",
  "params": {
    "token": "your-jwt-token"
  }
}

The response indicates whether the token is valid and includes the associated Ethereum address if it is.

Token Revocation

To revoke a token (log out):

POST / (JSON-RPC)

{
  "jsonrpc": "2.0",
  "method": "auth/token/revoke",
  "params": {
    "token": "your-jwt-token"
  }
}

Revoked tokens are immediately invalidated and cannot be used for further requests.

Use Cases

Wallet authentication is useful for:

Crypto-native users who prefer wallet-based identity over email.
Payment integration -- your authenticated wallet address can be used for on-chain payment operations.
Agent interactions that involve blockchain operations, where the platform needs to know your wallet address.

Security Considerations

The SIWE message includes a unique nonce to prevent replay attacks.
Signature verification is cryptographic -- only the holder of the private key can produce a valid signature.
Tokens expire after 24 hours and must be refreshed by re-authenticating.
Expired sessions are automatically cleaned up from server memory.
The signing secret is required in production -- the platform will not start without it configured.

Wallet Authentication