---
type: User Story
title: Authenticate with a Discord magic link
description: Discord users receive private single-use links that establish secure portal sessions.
tags: [player, discord, authentication, security]
timestamp: 2026-08-01T20:43:46Z
story_id: US-002
status: verified
---

# User Story

As a Discord community member, I want `/register` and `/account` to issue a private sign-in link, so that I can access the portal without creating another password.

# Acceptance Criteria

- [x] Given the configured guild, when a user runs `/register` or `/account`, then the bot responds ephemerally with a private link.
- [x] Given a generated link, then the raw login token is never stored in PostgreSQL.
- [x] Given a login token, then it expires after ten minutes and can be consumed only once.
- [x] Given repeated link requests, then requests are rate limited per Discord user and older active links are invalidated.
- [x] Given a valid link, when it is consumed, then the Discord user is created or refreshed and a secure seven-day session is established.
- [x] Given a magic-link result behind a reverse proxy, then the browser is redirected through the configured public application URL rather than an internal container address.
- [x] Given an invalid, expired, or consumed link, then the user sees a safe recovery page instructing them to request another link.

# Implementation

- [`apps/discord-bot/src/index.ts`](../apps/discord-bot/src/index.ts)
- [`packages/auth/src/index.ts`](../packages/auth/src/index.ts)
- [`packages/database/src/auth-repository.ts`](../packages/database/src/auth-repository.ts)
- [`apps/web/src/app/auth/discord/route.ts`](../apps/web/src/app/auth/discord/route.ts)
- [`apps/web/src/lib/application-url.ts`](../apps/web/src/lib/application-url.ts)

# Validation

- [`packages/auth/test/magic-link.test.ts`](../packages/auth/test/magic-link.test.ts)
- [`apps/web/src/lib/application-url.test.ts`](../apps/web/src/lib/application-url.test.ts)
- Discord command and authentication workspaces pass TypeScript validation.

# Related Stories

- [Enter through Discord](us-001-discord-entry.md)
- [Preserve an audit trail](us-010-audit-events.md)