PIN Authentication

Overview

PIN authentication provides anonymous, shared-device access. Instead of identifying a specific user, PINs grant access with a specific set of privileges. Ideal for:

• TV/kiosk displays
• Shared household devices
• Guest access with limited permissions

How It Works

1. Admin creates a PIN for a project (via admin API or authdash)
2. User enters the PIN on the auth login page
3. Auth service verifies against all active PINs for that project
4. On match: issues a PIN token (sub: "anon", no user identity)

Token Differences

PIN tokens differ from user tokens:

Claim	User Token	PIN Token
sub	usr_xxx	"anon"
role	"admin" / "member"	"pin_member"
pin_id	—	pin_xxx
privileges	—	["view", "edit"]
email	User’s email	—
Refresh lifetime	7 days	30 days

Endpoints

Form Submission

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

JSON API

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

Request Fields

Field	Type	Required	Description
pin	string	Yes	Numeric PIN (5+ digits)
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

Verification Process

The auth service:

1. Retrieves all active PINs for the project
2. Compares the submitted PIN against each hash (Argon2id)
3. First match wins — no indication of which PIN matched in the response

Caution

PIN verification checks all active PINs sequentially. With 10 PINs and Argon2’s intentional slowness, this can take 1-2 seconds. Keep the number of active PINs reasonable.

PIN Revocation

When a PIN is revoked:

• New authentications with that PIN are rejected immediately
• Existing sessions (refresh tokens) are rejected on next refresh attempt
• Current access tokens remain valid until their 5-minute expiry

Rate Limiting

• 5 attempts per 15 minutes per IP per project
• Same rate limit pool as password authentication

Privileges

PINs carry a privileges array — arbitrary strings that your app interprets:

{
  "pin_id": "pin_abc123",
  "privileges": ["view", "edit", "date-spots"]
}

The auth service doesn’t enforce these — it just embeds them in the token. Your app decides what each privilege means.

Creating PINs

See Admin PINs API for creating and managing PINs.