Authentication

The Grails API uses Sign-In with Ethereum (SIWE) for authentication. This produces a JWT token used for all authenticated requests.

Authentication Flow

Request a nonce — GET /api/v1/auth/nonce?address=0x...
Construct SIWE message — Build a SIWE message client-side using the nonce
Sign with wallet — Sign the message with the user’s Ethereum wallet
Verify signature — POST /api/v1/auth/verify with the message and signature
Receive JWT — The API returns a JWT token and user object
Use token — Include the token in subsequent requests

Using the Token

Include the JWT in the Authorization header for all authenticated requests:


curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://api.grails.app/api/v1/auth/me

Token Payload

The JWT contains the following claims:

Claim	Type	Description
`sub`	string	User ID
`address`	string	Ethereum address (lowercase)
`iat`	number	Issued at (Unix timestamp)
`exp`	number	Expires at (Unix timestamp)

Auth Middleware

Endpoints use two types of auth middleware:

Required (requireAuth) — Request fails with 401 UNAUTHORIZED if no valid token is provided
Optional (optionalAuth) — Request succeeds without a token, but authenticated users receive enhanced responses (e.g., personalized data)

Smart Wallet Support

The verification endpoint supports both EOA signatures and smart wallet signatures (ERC-1271, ERC-6492). Smart wallet signatures are verified on-chain via viem.