comfyauthEXPLAINED
API docs ↗Workspace ↗
THE VISUAL GUIDE · PAGE 2 OF 3

From “hello”
to signed in.

Four everyday situations: creating an account, logging in, staying logged in, and ending access.

A

Sign up: “Is this really your email?”

Create the account, then prove you own the inbox.
  1. 1 · Fill in the form

    Email + a provisional password. A display name is optional.

  2. 2 · Save safely

    Save the user and a provisional password hash. Queue an encrypted verification email. Login is still blocked.

  3. 3 · Open your email

    Follow the link to the verification page. The link lasts 1 hour.

  4. 4 · Choose your final password

    The email owner submits the link token and a chosen password. ComfyAuth replaces the signup password, verifies the email, and cancels existing sessions and action links together.

An unverified account cannot log in. Signup gives the same general response for an existing email, so it does not directly announce who already has an account. Choosing the final password after opening the email means someone who signed up using your address cannot keep a password they chose for you.

How does the email actually get sent?
The outbox is a waiting tray for encrypted messages.
  1. Database outbox

    Save the encrypted email with the signup.

  2. Email worker

    Read a ready message, decrypt it, and try SMTP delivery.

  3. Provider accepts it?

    Yes: remove the queued message. No: schedule a retry.

On Vercel, an accepted email request attempts up to two messages for that project before replying. Failed attempts back off, up to ten attempts. A message can occasionally be sent twice; its link is still single-use.

Hobby limitation: Vercel runs daily cleanup, not a once-a-minute mail worker. Reliable retries when there is no traffic need an external scheduler. That scheduler is not configured yet.

B

Log in: “Can I have a temporary pass?”

A password check creates a revocable session.
  1. Email + password

    Your app sends the submitted credentials to the login API.

  2. Check the account

    Does the password match? Is the email verified? Is the account enabled?

  3. Create a login pass

    If all checks pass, create a random session token. With renewable login, also give the app a private renewal token.

If any check fails, return a general login error. Password and account checks are repeated under a database lock where needed, so a concurrent reset cannot leave a valid login with the old password.

CUSTOMER APPLICATION

Token → your backend

For browser apps, keep the ComfyAuth token on your server. Your own page uses your app’s secure cookie. Native apps use secure OS storage.

COMFYAUTH DEVELOPER PORTAL

Token → protected cookie

The portal keeps access and renewal tokens in Secure, HttpOnly cookies. Its JavaScript cannot read them. No token is placed in local storage.

C

Stay signed in: “Is this pass still valid?”

Each identity check asks ComfyAuth again.
  1. Send the pass

    Your backend calls GET /v1/me with the project ID and session token.

  2. Check the saved record

    Correct project? Not expired? Not revoked? User still active?

  3. Allow or reject

    Valid: return the user’s ID and profile. Invalid: reject the request.

Your application then checks its own permissions. Ordinary login keeps the original 24-hour pass. Add renewable: true at login to let your app replace short-lived passes automatically.

Renewal: replace the pass without typing the password again.
  1. The short pass expires

    Usually after 15 minutes. Your app sends its current private renewal token to POST /v1/auth/refresh.

  2. Check and replace

    Check the account, time limits and whether this renewal token was already used. Replace both tokens together.

  3. Continue using the app

    Your app saves the new pair and retries the rejected identity check once. The session ID stays the same.

The old pair stops working. Only one renewal can run at a time. Reusing a spent renewal token cancels that device’s session, so a lost response means signing in again.

SIMPLE DEFAULTS

15 minutes · 7 days · 30 days

A short pass lasts 15 minutes. Seven days without renewal means sign in again. Thirty days from the original login is the maximum, even if the app is used every day.

YOUR PROJECT SETTINGS

Choose the time limits

Access: 5–60 minutes. Inactivity: 1–90 days. Total lifetime: 1–365 days. Inactivity cannot exceed total lifetime. Shorter settings affect later renewals; longer settings never extend an existing login’s original maximum.

The developer portal handles renewal through protected cookies and coordinates browser tabs. Browsers without Web Locks or working browser storage require login again after access expires. Only a nonsecret pending marker uses browser storage; credentials stay in protected cookies. Native apps and customer backends use the same JSON endpoint and secure token storage. Logout and password recovery still cancel the session and its renewal tokens.

D

Forgotten password? Lost device? Change the pass.

Forgot password

  1. Request a reset email.
  2. Open the link within 20 minutes.
  3. Submit the token + a new password.
  4. Replace the password hash and cancel all sessions.

Change password

  1. Be signed in.
  2. Confirm your current password.
  3. Submit a new password.
  4. Cancel all sessions; sign in again.

Log out / revoke

  1. Choose one session or all sessions.
  2. Mark the selected passes as revoked.
  3. The next identity check fails.
  4. Already-authorised requests cannot be recalled.
What “protected” means — and what it does not mean.

Hashing = a one-way fingerprint

Passwords use salted Argon2id hashes. Session, API, and email-action tokens are saved as hashes, not reusable raw secrets.

Encryption = a locked envelope

The email queue uses AES-256-GCM because the worker must read the message to send it. Production web and database traffic use encrypted connections.

Email addresses and usernames remain readable to the application and database administrators. This is not end-to-end encryption. Storage encryption and backups also need infrastructure controls. The service has not had an independent security audit.