User (authenticated via Clerk)
  → Settings → API Tokens → "Create Token"
  → issue_token_for_user(user_id, name, expires_in_days)
  → Generates: {prefix}{short_token}_{long_token}
     ├── short_token: stored plaintext, indexed for O(1) lookup
     └── long_token: only SHA-256 hash stored (split-token pattern)
  → Returns full token string ONCE (never retrievable again)

External App
  → Authorization: Bearer sj_abc123_xyzLongSecret...
  → verify_token(token_string) → TokenVerification { user_id, token_id, name }

sj_<short_token>_<long_token>
│   │              │
│   │              └── long_token (base64url, 32 bytes entropy)
│   └── short_token (hex, 6 bytes = 12 chars, indexed for lookup)
└── prefix (configurable, default "sj_")

# Create token (requires existing valid token — bootstrap with make admin-token)
POST /api/ext/tokens
Authorization: Bearer sj_...
Body: { "name": "My Token", "expires_in_days": 30 }

# List tokens (masked, no secrets)
GET /api/ext/tokens
Authorization: Bearer sj_...

# Revoke token
DELETE /api/ext/tokens/{token_id}
Authorization: Bearer sj_...

# Issue a token for the demo user (no running server needed)
make admin-token

# Custom options
make admin-token-custom ARGS="--name 'QA Token' --expires 7 --user-id user_demo_2abc3def"

from reflex_clerk_api import validate_api_token, TokenVerification
from fastapi import Depends

@router.get("/protected")
def my_endpoint(auth: TokenVerification = Depends(validate_api_token)):
    # auth.user_id, auth.token_id, auth.name
    return {"user": auth.user_id}

Syntropy Journals (authenticated session)
  → User clicks "Pair Device"
  → issue_passcode(self, "user@email.com", channel="openclaw")
  → Generates 6 random digits (cryptographic: secrets.randbelow)
  → SHA-256 hash stored in clerk_passcodes table
  → Plaintext code shown to user (or sent via email/SMS)
  → Existing unused passcodes for same user+channel invalidated

External App (OpenClaw, mobile)
  → User enters 6-digit code
  → POST /auth/passcodes/verify
    Body: { "code": "847291", "user_identifier": "user@email.com", "channel": "openclaw" }
  → verify_passcode() → constant-time hash comparison
  → Returns: { user_id, passcode_id, user_identifier, channel }
  → Passcode marked as used (single-use)

POST /auth/passcodes/verify
Content-Type: application/json

{
  "code": "847291",
  "user_identifier": "user@email.com",
  "channel": "openclaw"
}

# Response (200):
{
  "user_id": "user_2abc3def",
  "passcode_id": "uuid-...",
  "user_identifier": "user@email.com",
  "channel": "openclaw"
}

# Response (401): Invalid, expired, or already used

# Inside a Reflex event handler (requires authenticated session)
result = await clerk.issue_passcode(
    self,
    user_identifier="user@email.com",
    channel="openclaw",
)
# result.code = "847291" — send to user via email/SMS/display on screen
# result.expires_at = datetime (10 min from now)

OpenClaw → Authorization: Bearer sj_abc123_...
        → GET /api/ext/health-profile
        → GET /api/ext/diet-score

Step 1: User clicks "Pair with OpenClaw" in Syntropy
        → issue_passcode(self, email, "openclaw")
        → Shows 6-digit code on screen

Step 2: User enters code in OpenClaw
        → POST /auth/passcodes/verify { code, email, "openclaw" }
        → Gets back user_id

Step 3: OpenClaw requests a persistent API token
        → POST /api/ext/tokens (with temporary session from Step 2)
        → Gets back sj_... token for ongoing use

Step 4: OpenClaw stores the API token locally
        → All subsequent calls use the API token

Step 1: User requests passcode in Syntropy
Step 2: User enters code in external app
Step 3: External app verifies → gets user_id
Step 4: External app uses user_id for the session (no stored token)
Step 5: Session expires, user re-pairs next time

clerk.ClerkState.set_token_config(
    prefix="sj_",                # Token prefix
    token_code_length=32,        # 256 bits of entropy
    short_token_length=6,        # 12 hex chars for DB lookup
    passcode_length=6,           # 6-digit OTP
    passcode_ttl_seconds=600,    # 10 minutes
)