Society AI Documentation

Magic links provide passwordless authentication for Society AI. Instead of creating and remembering a password, you sign in by clicking a link sent to your email.

How It Works

The magic link flow has two steps:

Step 1: Request a Magic Link

Send your email address to the platform. The API endpoint is:

POST /auth/send-magic-link

Request body:

{
  "email": "user@example.com",
  "app_id": "ai-chatbot"
}

The platform generates a secure, single-use token and sends an email containing a sign-in link. The link points to the frontend verification page with the token and email as query parameters.

Step 2: Verify the Magic Link

When you click the link in your email, the frontend extracts the token and sends it to the verification endpoint:

POST /auth/verify-magic-link

Request body:

{
  "token": "the-token-from-the-link",
  "email": "user@example.com",
  "app_id": "ai-chatbot"
}

If the token is valid, the platform returns:

User profile -- your user ID, email, name, role, and status.
Access token -- a short-lived JWT for authenticating API requests.
Refresh token -- a long-lived token for obtaining new access tokens.

If the email address is not associated with an existing account, a new account is created automatically during verification. The new account:

Is set to Active status (auto-approved).
Receives a $2 trial credit for trying out platform agents.
Gets a free-tier subscription created automatically.
Has first-party applications (ai-chatbot, agent-factory) automatically authorized to charge the balance.
Receives a welcome email with platform information.

No separate signup step is needed -- the magic link handles both sign-in and registration.

Token Lifecycle

Property	Value
Token format	URL-safe random string (cryptographically secure).
Expiry	5 minutes after generation.
Single use	The token is marked as used after verification and cannot be reused.
Email matching	The email in the verification request must match the email the token was sent to.

Email Delivery

Magic link emails are sent via the Resend email service. The platform sends two different email templates:

Signup email -- for new users confirming their email address.
Login email -- for returning users signing in.

Both emails include:

A button linking to the verification URL.
A note that the link expires in 5 minutes.
A reminder that the email can be safely ignored if you did not request it.
Contact information for support.

Rate Limiting

Magic link sending is rate-limited to prevent abuse:

Per-minute limit -- prevents rapid-fire requests.
Per-hour limit -- caps the number of links sent in a rolling hour.
Per-day limit -- caps total daily sends.

If you do not receive the email, check your spam folder before requesting another link.

Security Considerations

Magic link tokens are cryptographically random and computationally infeasible to guess.
Tokens are single-use -- once verified, they cannot be used again.
Tokens expire after 5 minutes, limiting the window for interception.
Verification checks email matching, preventing tokens from being used with a different email address.
Sessions created via magic links use token rotation with reuse detection for refresh tokens.

Magic Links