Skip to main content
The Hansel Bot API supports two authentication methods depending on whether you’re a user or a bot. Users authenticate via a Discord-based login code flow. Once verified, a session cookie (hsession) is set and used for subsequent requests.

​
Flow

1

Request a login code

Call POST /v1/authentication/request with your Discord ID or username. The bot will DM you a code.
2

Verify the code

Call POST /v1/authentication/verify with the 8-character code and your Discord ID.
3

Use the session

The response sets an hsession cookie. Include this cookie in all subsequent requests.

​
Example

# Step 1: Request a login code
curl -X POST https://hapi.7331.org/v1/authentication/request \
  -H "Content-Type: application/json" \
  -d '{"discord_id": 123456789012345678}'

# Step 2: Verify the code (the bot DMs you)
curl -X POST https://hapi.7331.org/v1/authentication/verify \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"code": "ABCD1234", "discord_id": 123456789012345678}'

# Step 3: Use authenticated endpoints
curl https://hapi.7331.org/v1/users/me \
  -b cookies.txt

​
Bot Authentication (API Key)

Bots authenticate using an API key passed in the X-API-Key header. API keys are generated when a bot is registered via the admin panel.

​
Usage

curl https://hapi.7331.org/v1/bot/me \
  -H "X-API-Key: your-bot-api-key"
API keys are only shown once when a bot is registered. Store them securely.

​
Admin Authentication

Admin users authenticate through the same login flow as regular users. There are no separate admin auth endpoints — permission checks happen per-request via session cookies. When an admin or owner logs in, the session cookie is automatically configured with a shorter TTL:
  • Cookie TTL: 1 day (vs 30 days for regular users)
All session cookies use SameSite=none, Secure=true, and domain .7331.org to work across subdomains (hapi, hws, portal, hansel). Admin endpoints verify the caller’s permission level on every request. There is no separate “admin session” — the same hsession cookie is used for all authenticated requests.