Authio docs

Part of Authio Lobby

Lobby's job is to prove who signed in, not to run a full CRM signup form. That keeps conversion high and matches how most teams integrate Authio (and how WorkOS AuthKit is typically used).

What Authio stores by default

Field	When it is set
`email`	Always — anchor for passkey, magic link, OAuth, and SSO.
`email_verified`	After verify flow, SSO, or admin confirmation.
`name`	When OAuth returns a display name (Google/Microsoft), SSO attribute maps resolve one, or your app calls `PATCH /v1/me`.
`avatar_url`	OAuth picture URL or your app via `PATCH /v1/me`.
`phone_e164`	Only after the user completes phone verify (optional MFA / phone-primary).
`metadata`	SSO JIT mappings (job title, department, custom keys), imports, or your backend via Management API.

Authio does not split first_name / last_name on the core user row today. SSO maps those into name or metadata.first_name / metadata.last_name. Dashboard surfaces (Locate log, audit) resolve a display label from all of the above.

What WorkOS does (for comparison)

WorkOS User Management exposes first_name, last_name, profile_picture_url, metadata, and external_id on the user object. AuthKit sign-in still only proves identity — profile CRUD is a separate API pass. Authio follows the same split: Lobby sign-in is minimal; enrichment is deliberate.

Pattern 1 — Post-sign-in onboarding in your app (recommended)

After the Lobby callback sets session cookies, send new users to a one-screen “Complete your profile” step. Persist with:

PATCH /v1/me
Authorization: Bearer <session access token>
X-Authio-Project: proj_…
Content-Type: application/json

{ "name": "Tony Castiglione" }

From a Next.js BFF, proxy through your existing authioFetch helper (same as GET /v1/me). Read the result on the next GET /v1/me — name is what Locate logs and your nav bar should show.

Pattern 2 — OAuth fills name automatically

Google / Microsoft sign-in already pass a display name on first login. Email-only passkey or magic-link users will have an empty name until Pattern 1 or SSO runs.

Pattern 3 — Enterprise SSO / SCIM

Map IdP attributes in the dashboard under your SSO connection (attribute mapping). Example:

{
  "user.email": "$assertion.email",
  "user.first_name": "$assertion.Attribute[givenName]",
  "user.last_name": "$assertion.Attribute[sn]",
  "user.name": "$assertion.Attribute[displayName]"
}

Extended fields land in users.metadata (job title, department, etc.). SCIM provisioning keeps rows in sync for large directories.

Pattern 4 — Webhooks (mirror to your CRM)

Subscribe to user.created and user.updated (event catalog). Your backend can upsert into Salesforce, HubSpot, or your own users table keyed by Authio user_id.

What Lobby itself does not do (by design)

No mandatory name/phone fields on the hosted sign-in card — add them in your app after auth succeeds.
No callback URL that returns PII beyond the session JWT — use GET /v1/me server-side instead of trusting query params.

Next steps

Lobby quickstart — wire callback + GET /v1/me
SAML attribute mapping
Webhook events

User profiles