Authentication flows.

Tenant invitation acceptance

1. An owner or administrator creates an invitation using a unique idempotency key. ComplicatedAuth queues its email transactionally and returns only safe invitation metadata.
2. The invited person receives a fragment-based one-time link. Its proof is not exposed to the administrator, and the fragment is available to browser code without entering the HTTP request line.
3. The invited person establishes a display name and password. The browser submits the token in the JSON body to the invitation-specific acceptance operation.
4. The API locks the invitation, verifies its token and expiry, creates the Tenant Member, marks the email verified by possession, consumes the invitation, and creates a bootstrap session in one transaction.
5. The bootstrap session may discover itself, sign out, and enroll the member’s first management passkey or security key. It cannot access ordinary management resources.
6. Successful WebAuthn registration upgrades the session to strong. If the invitation response is lost, the member starts a new password-verified login and completes the required first enrollment; the invitation is not retried.

Tenant Member management login

1. Create POST /v1/console/login-attempts with the email. The response is deliberately non-enumerating and contains a five-minute attempt UUID plus a one-time client secret.
2. Keep the client secret only in function memory. Send it in X-ComplicatedAuth-Login-Secret to that attempt’s child operations; never put it in cookies, URLs, browser storage, traces, or logs.
3. Create a password-verification child resource. Success reports whether first credential setup is required but creates no session.
4. For an existing member credential, create and complete an authentication ceremony. For recovery or first use, create and complete the initial registration ceremony.
5. Only successful user-verified WebAuthn completion consumes the attempt and creates a strong HttpOnly management session.

Passkey and hybrid authentication select enrolled platform credentials. Security-key authentication selects a cross-platform credential whose enrollment supplied non-none attestation. Password verification remains mandatory for both modes.

Tenant Member credentials and sessions

The account page exposes at most ten safe credential metadata resources. Registration excludes every already-enrolled credential identifier so one authenticator cannot silently replace a discoverable credential that the server still trusts. Rename and removal require the latest strong ETag. The final credential cannot be removed; add a replacement first. Removing any other credential revokes every other management session and retains only the current strong session.

Session inventory never returns reusable cookie values. Deleting a session revokes it immediately; deleting the current session also clears the cookie. Disabling or removing a member invalidates all of their management sessions.

Project User authentication through a customer BFF

The following SDK flow applies to customer Project Users, not Tenant Members who administer ComplicatedAuth.

Password plus passkey

1. Call startLogin(email). The BFF stores the backend login reference and returns a random browser token.
2. Call startPasswordAuth(password). A successful response verifies a factor but does not issue a session.
3. Call startPasskeyAuth() or startHybridAuth(). The SDK obtains options, invokes WebAuthn, and verifies the credential.
4. The BFF replaces the backend session reference with a browser token. The client stores that token in session storage.

Security-key login

After startPasswordAuth(password), startSecurityKeyAuth() requires user verification and a credential that satisfied the server’s attestation policy when enrolled. It is a distinct second-factor category, not a passwordless exception.

Password plus face

Start the login and verify the password before calling startBiometricAuth(selfie). The API currently accepts the configured provider's match decision; the application must not describe this as spoof-resistant until a liveness signal is implemented.

Enrollment

A newly provisioned user verifies their password and calls startFirstPasskeyEnrollment() or startFirstSecurityKeyEnrollment(). The bootstrap route is accepted only while that user has no FIDO credential; successful registration completes login. Later enrollment requires an authenticated session through startPasskeyEnrollment(), startSecurityKeyEnrollment(), or startBiometricEnrollment(). Registration excludes existing credentials. A Project’s RP ID locks after its first FIDO credential is created.

Restore and logout

Call restoreSession() during application bootstrap. It introspects the server-side reference; an expired or revoked session clears local state and returns null. Call logout() for explicit sign-out. It attempts backend revocation and clears browser state even if the request fails.