Password Authentication

Overview

Password authentication is the standard email + password flow. Users submit credentials on the auth service’s login page, and on success receive an authorization code.

Endpoints

Form Submission (Browser)

POST https://auth.beshoy.ai/auth/login-form
Content-Type: application/x-www-form-urlencoded

Used by the server-rendered login page. Redirects on success/failure.

JSON API

POST https://auth.beshoy.ai/auth/login
Content-Type: application/json

Used for programmatic authentication (e.g., testing, CLI tools).

Request Fields

Field	Type	Required	Description
email	string	Yes	User’s email address
password	string	Yes	User’s password
project_id	string	Yes	Target project
redirect_uri	string	Yes	Where to redirect after auth
code_challenge	string	Yes	PKCE S256 challenge
state	string	Yes	Opaque state to return

Flow

1. User submits email + password
2. Auth service looks up user by email
3. Verifies password via Argon2id
4. Checks user exists in the target project (project_users)
5. Checks user status is not “blocked”
6. Generates authorization code, stores PKCE data in KV
7. Redirects to redirect_uri with code and state

Rate Limiting

• 5 attempts per 15 minutes per IP per project
• Applies to both successful and failed attempts
• Fails closed (KV unavailable → request denied)

Note

Rate limiting is per IP per project. A user being rate-limited on proj_gym can still authenticate on proj_bot.

Password Requirements

For signup (not enforced on existing passwords):

• Minimum 8 characters
• At least one lowercase letter
• At least one uppercase letter
• At least one digit

Password Hashing

• Algorithm: Argon2id
• Memory: 19,456 KiB (19 MiB)
• Iterations: 2
• Parallelism: 1
• Library: hash-wasm (WebAssembly, runs on Workers)

Error Responses

Error	Cause
Invalid credentials	Email not found or password mismatch
Account blocked	User status is “blocked” in this project
Not a member	User exists but isn’t in this project
Rate limited	Too many attempts from this IP