Core Concepts

← Developer Docs · Introduction · Agent skill: phuze-skill.md

Client

Your app registration. You register once and receive a publishable_key (safe for frontend use) and a secret_key (backend only). All sessions, users, and quotas are scoped to your client.

User

A person who has authenticated through Phuze on your site. Identified by a stable uid. A user's email is verified at first login — they proved they control that inbox by clicking the magic link. Users are global to Phuze, but their sessions are scoped to your client.

Session

Created when a user successfully clicks a magic link. Contains a token (an opaque string stored in the user's browser), a uid, and an expiry. Sessions last 30 days. Your backend verifies sessions by calling /sessions/verify with the token.

Magic Link

A one-time sign-in link emailed to the user. It expires after 15 minutes and can only be used once. No passwords are involved.

Quotas, plans & overage

A "login" is one accepted magic-link send, counted against your plan's daily quota. Current quotas, prices, and the overage rate live at phuze.edato.me/pricing — that page renders straight from the plan config and is always authoritative; this page deliberately doesn't duplicate the numbers.

Paid plans keep working past their quota — extra logins are accepted and billed as overage at the published per-1,000 rate (invoiced by email during alpha) — with a hard cap above the quota where sends stop (429 quota_exceeded). The Free plan stops at its quota. MAU is not a plan limit: registered and returning users are never billed; a high flat guardrail exists purely as abuse protection.

GET /clients/me/quota reports your client's live effective values — limits.logins_per_day (quota), limits.logins_hard_cap_per_day, limits.mau (the guardrail), and current_period.overage_count (this month's accepted-over-quota logins) — the machine-readable authority for what actually applies to you right now.

Sender name (Builder and above)

Set the display name your users see on sign-in emails — "Your brand" <noreply@phuze.edato.me> — via PATCH /clients/me with { "from_name": "Your brand" } (1–40 characters, Unicode welcome; control characters and <>"@ are stripped; null clears it) or from the dashboard. The field is settable on any plan and activates on upgrade.

Feedback & feature requests

POST /api/v1/feedback (CLI or Secret key): { "topic": "custom_domains" | "other", "message": "..." }. Use custom_domains to register interest in sending magic links from your own domain — real interest is what schedules that feature. General feedback goes through other (message required, ≤2000 chars). Also available as a card in the dashboard. Returns 201.

Test Account

A declared address of your own that gets relaxed send limits (10/min · 60/hr vs the default 1/min · 5/hr) for 14 days — built for iterating against production during development. Managed via POST/DELETE /clients/me/test-accounts (CLI token) or the dashboard.

Phuze · phuze.edato.me · Developer Docs · Introduction