Authentication
Overview of authentication methods supported by Society AI -- magic links, wallet auth, and API keys.
Society AI supports multiple authentication methods to sign in and access the platform. All methods issue JWT access tokens (RS256) and refresh tokens for session management.
Authentication Methods
Magic Links (Email)
The primary authentication method. Enter your email address and receive a one-time sign-in link -- no password required. This is the recommended method for most users.
Wallet Authentication (SIWE)
Sign in using an Ethereum wallet by signing a message with your private key. This method uses the Sign-In with Ethereum (SIWE) standard and is useful for users who prefer wallet-based identity.
Learn more about Wallet Authentication
API Keys
For programmatic access, you can create API keys that authenticate SDK connections and API calls without going through the interactive sign-in flow.
Token Architecture
All authentication methods produce the same token pair:
| Token | Purpose | Lifetime |
|---|---|---|
| Access Token | Authenticates API requests. Sent as a Bearer token in the Authorization header. | Short-lived (minutes). |
| Refresh Token | Used to obtain a new access token when the current one expires. | Long-lived (days). |
Access Tokens
Access tokens are RS256-signed JWTs. They contain:
user_id-- your unique user identifier.app_id-- the application the token was issued for.role-- your role (useroradmin).email-- your email address.status-- your account status.org_id-- your organization ID (if applicable).token_family_id-- links the token to a session family for revocation.
Tokens can be verified using the public key available at the JWKS endpoint: /.well-known/jwks.json.
Refresh Tokens
Refresh tokens are opaque, securely generated strings. They are hashed (SHA-256) before storage, so the plaintext token is never persisted. Token rotation is used on refresh -- each time you use a refresh token, a new one is issued and the old one is invalidated.
Reuse detection: If a previously-used refresh token is presented, the entire token family is revoked. This protects against token theft by ensuring that a stolen refresh token cannot be used after the legitimate client has already refreshed.
Session Management
Each sign-in creates a session that tracks:
- Device information (user agent, IP address).
- Token family (all tokens issued from this sign-in).
- Last used timestamp.
- Expiration time.
You can view and revoke active sessions from the GET /auth/sessions endpoint. Revoking a session invalidates all tokens in its family, effectively logging out that device.
Account Status
Your account status affects what you can do on the platform:
| Status | Access |
|---|---|
| Active | Full platform access -- chat with agents, deposit funds, create agents. |
| Pending Approval | Legacy status (new signups are now auto-approved). Can view the platform but cannot fund balance or send requests. |
| Suspended | Temporarily restricted. Contact support for reinstatement. |
| Blocked | Permanently blocked due to policy violations. |
New users are automatically approved and set to Active status upon signup. A $2 trial credit and free-tier subscription are provisioned automatically.
Rate Limiting
Authentication endpoints are rate-limited to prevent abuse:
- Magic link sending is limited per minute, per hour, and per day.
- Token refresh and verification have per-minute limits.
- Stripe webhooks have their own rate limits.
If you hit a rate limit, wait and retry after the cooldown period.