Log in with an external provider (OAuth2 / OIDC)

member.dev can act as an OAuth2/OIDC relying party, letting your hub members authenticate using an identity they already have — Google, Facebook, or any OIDC/OAuth2-compatible company SSO. This is the inverse of the Login with Hub guide (where member.dev is the Identity Provider). After authentication succeeds, the member receives a standard contact JWT — the same token used for every other member API call.

Provider support matrix

Provider	Sign-up	Login	How
Google	Yes (JIT)	Yes	OIDC — `id_token` signed by Google’s hardcoded JWKS
Facebook	No	Yes (after connect)	OAuth2 — server-side Graph API call
Generic OIDC (company SSO / Okta / Auth0 / etc.)	No — or Yes with Verified-Domain SSO	Yes (after connect; or JIT if domain verified)	OIDC — admin-supplied discovery + JWKS
Generic OAuth2	No	Yes (after connect)	OAuth2 — admin-supplied userinfo endpoint
Instagram	Not supported v1	Not supported v1	—

Google is the only provider that can create a new member account without domain verification. For generic OIDC, hub admins can unlock auto-creation by verifying ownership of the member’s email domain — see Verified-Domain SSO below. All other providers require the member to already have an account and to have explicitly connected the provider (see Connect flow).

How it works

Member                                  mio-backend                    External Provider
  |                                          |                                |
  |--GET /api/v1/external-login/{id}/start-->|                                |
  |                                          | gen PKCE + state + nonce       |
  |                                          | set CSRF cookie                |
  |<--------302 to provider authorize URL----|                                |
  |                                          |                                |
  |------ authenticates at provider -------->|                                |
  |                                          |                                |
  |<--------302 /api/v1/external-login/callback?code=&state=--------------<--|
  |                                          |                                |
  |                                          | verify CSRF cookie             |
  |                                          | exchange code (server-to-server pinned HTTPS)
  |                                          | verify id_token / fetch userinfo
  |                                          | resolve or create contact      |
  |                                          | mint bootstrap code (60s)      |
  |<--------302 return_to#code=<code>--------|                                |
  |                                          |                                |
  |--POST /api/v1/external-login/session {code}-->                           |
  |<--------{access_token, token_type, expires_in} + Set-Cookie: mio_contact_refresh

The one-time code in the fragment is exchanged server-side for the real token pair. The bearer token never appears in a URL, history, or referrer header.

Prerequisites

The hub admin has registered an external-login provider config (see Admin: configure a provider).
For Google: any member can log in (first-time creates an account using the verified email).
For Facebook / Generic: the member has already connected their external account while logged in (see Connect flow).

Step 1 — Redirect the member to the provider

GET /api/v1/external-login/{provider_config_id}/start?return_to=https://app.example.com/after-login

Parameter	Required	Notes
`provider_config_id`	Yes (path)	The `id` of the provider config from the admin API
`return_to`	No	Where to redirect after success. Must be in the hub’s allowed redirect origins. Defaults to the hub’s configured post-login URL.

The backend validates return_to, generates PKCE + state + nonce, stores a server-side flow binding (10-minute TTL), sets an HttpOnly CSRF cookie, and redirects the browser (302) to the external provider’s authorization URL. This is a browser redirect, not a fetch. Trigger it by setting window.location.href or using an <a> element.

Step 2 — Provider authenticates the member

The provider redirects back to:

GET /api/v1/external-login/callback?code=CODE&state=STATE

The backend handles this entirely server-side:

Validates the CSRF cookie against the stored binding
Exchanges the code for an access token / id_token via a pinned, SSRF-guarded server-to-server call
Verifies the id_token signature (OIDC) or fetches userinfo (OAuth2)
Resolves or creates the member’s contact (see Account linking)
Stores a single-use bootstrap code (60-second TTL) bound to the member’s contact

On success, the member’s browser is redirected to:

{return_to}#code=<bootstrap_code>

On any error, the backend returns a generic 400 JSON response. No internal details are exposed.

Step 3 — Exchange the bootstrap code for a token pair

Your frontend extracts code from window.location.hash and POSTs it:

curl -X POST "https://api.member.dev/api/v1/external-login/session" \
  -H "Content-Type: application/json" \
  -d '{"code": "BOOTSTRAP_CODE_FROM_FRAGMENT"}'

Response (200):

{
  "access_token": "eyJ...",
  "token_type": "bearer",
  "expires_in": 3600
}

The mio_contact_refresh HttpOnly cookie is also set automatically. Use access_token as the Authorization: Bearer token for all subsequent member API calls. Errors (400):

{
  "error": "invalid_grant",
  "error_description": "Code not found or expired."
}

The bootstrap code is single-use and expires in 60 seconds. Do not replay it.

Connect flow

Facebook and generic providers (OIDC / OAuth2) do not auto-create accounts. A member must explicitly connect the provider to their existing contact while they are logged in.

Initiate a connect

curl -X POST "https://api.member.dev/api/v1/external-login/{provider_config_id}/connect?return_to=https%3A%2F%2Fapp.example.com%2Fsettings%2Faccounts" \
  -H "Authorization: Bearer MEMBER_ACCESS_TOKEN"

return_to is a query parameter (not a JSON body). The endpoint accepts no request body. Response (200):

{
  "authorize_url": "https://www.facebook.com/v19.0/dialog/oauth?..."
}

Redirect the member’s browser to authorize_url. The backend sets the CSRF cookie as part of this response. After the member authenticates at the provider, the callback runs the same verification path as the login flow. On success, the provider identity is linked to the member’s contact and the browser is redirected to return_to (no new token is issued — the member is already logged in). After a successful connect, the member can use the normal login flow (Step 1–3 above) for all future sessions with that provider.

Account linking

The backend follows a strict account-linking decision table. The outcome is determined entirely by verified, server-side assertions — the browser never supplies identity.

#	Situation	Result
0	Connect mode (logged-in member attaches provider)	Link identity to current contact. If the identity is already linked to a different contact: rejected.
1	Login — identity `(namespace, sub)` link already exists	Use the linked contact. `ContactAuthenticated` event emitted.
2	Login — Google, verified email, email matches an existing contact	Link identity to existing contact. Mark email verified if not already.
3	Login — Google, verified email, no matching contact	Create a new contact (race-safe). `ContactRegistered` + `ContactAuthenticated` events emitted.
4	Login — Facebook / generic (untrusted provider), no existing link	Rejected. Member must connect the provider first (row 0). Exception for `generic_oidc` with a verified domain (v2): if the member’s email belongs to a domain the hub has verified, a new account is created automatically (same as row 3). If an account with that email already exists, still rejected — the member must connect the provider while signed in. See Verified-Domain SSO. `generic_oauth2` does not qualify even with a verified domain (no signed `id_token` → no domain trust).
5	Login — Google, but no email claim	Rejected. Email is required for account creation/linking.

Why Google only for rows 2/3: Google’s token endpoint and JWKS are hardcoded constants in the backend — they cannot be overridden by admin configuration. This makes Google’s email_verified claim trustworthy. All other providers are “untrusted” because their identity endpoints are admin-supplied, and a malicious hub owner could otherwise forge email claims to take over arbitrary member accounts.

Security notes

CSRF: every flow is CSRF-protected by a persistent HttpOnly CSRF cookie (__Host-extlogin_csrf in production). The binding stores a hash of the cookie; the callback re-hashes and compares in constant time. Concurrent flows from the same browser share the cookie — starting provider A then B does not cancel A’s flow.
PKCE S256 is always used. The code_verifier lives only on the server in the flow binding.
No bearer token in URLs. The bootstrap code is a short-lived, single-use opaque value. Redeeming it requires an Origin header match against the code’s bound return-origin.
Token scope: the issued contact token covers only the hub that initiated the login. A hostile hub cannot trigger a login that produces a token covering the member’s other hubs.
Enumeration: all callback failures return one generic error response. The specific failure reason is written to the audit log only.
Rate limits: /start, /callback, /connect, and /session are rate-limited by IP.

1. Hub admin registers a Google provider config:
   POST /api/v1/teams/TEAM_ID/external-login-providers
   → {provider_kind: "google", client_id: "...", client_secret: "..."}
   → Receives provider config with id: "cfg_abc123"
   → callback_url (read from response) is registered in Google Console

2. Hub adds "Log in with Google" button:
   href="/api/v1/external-login/cfg_abc123/start?return_to=https://app.myhub.com/dashboard"

3. Alice (new member) clicks the button.
   → Browser redirects to Google OAuth consent screen.
   → Alice approves. Google redirects to /api/v1/external-login/callback?code=...&state=...

4. Backend verifies the id_token (hardcoded Google JWKS, RS256, nonce, aud, iss).
   → email_verified: true + no existing contact → creates Alice's contact (row 3).
   → Issues contact token pair → stores bootstrap code → 302 to:
     https://app.myhub.com/dashboard#code=BOOTSTRAP

5. Frontend extracts BOOTSTRAP from location.hash, POSTs to /session.
   → Receives {access_token: "eyJ..."} + mio_contact_refresh cookie.
   → Alice is logged in. Member API calls use the access_token.

6. Next time Alice logs in via Google → row 1 (existing link), no account creation.

1. Hub admin registers a Facebook provider config (display_name: "Facebook").

2. Bob (existing member, logged in) goes to Account Settings.
   Frontend: POST /api/v1/external-login/{cfg_id}/connect (Bearer token)
   → Receives {authorize_url: "https://www.facebook.com/v19.0/dialog/oauth?..."}

3. Frontend redirects Bob to authorize_url.
   → Bob approves Facebook login. Callback runs.
   → Backend fetches identity from Graph API (appsecret_proof).
   → Links (provider_config_id, facebook_sub) → Bob's contact (row 0).
   → 302 to return_to (no new token — Bob is already logged in).

4. Next time Bob visits the hub:
   GET /api/v1/external-login/{cfg_id}/start
   → Callback resolves via row 1 (existing link) → issues token pair.

Verified-Domain SSO (v2)

By default, a generic_oidc provider can only log in members who have already connected it (row 0 → row 1 in the account-linking table). With Verified-Domain SSO, a hub admin can unlock automatic account creation for members whose email belongs to a company domain the hub has proven it controls.

How it extends v1

	Google (v1)	Generic OIDC — no domain	Generic OIDC — domain verified (v2)
Auto-create new account	Yes	No	Yes
Login after connect	—	Yes	Yes
Merges into existing account	Yes	No	No (connect-first rule)

The connect-first rule is permanent: if a member already has a member.dev account with alice@acme.com, logging in through the OIDC provider will not silently adopt that account. Alice must sign in with her existing method and connect the provider while logged in.

Set up in three steps

Register a domain — POST /api/v1/teams/{team_id}/verified-domains {hub_id, domain}. Returns the DNS TXT record to publish.
Publish the TXT record — add _member-dev-challenge.<domain> = member-dev-verify=<token> to your DNS provider.
Trigger verification — POST /api/v1/teams/{team_id}/verified-domains/{id}/verify. The backend resolves the TXT; on success the domain moves to verified.

From that point on, any new @<domain> member who authenticates through a generic_oidc provider on this hub gets an account created automatically (subject to the hub’s registration_enabled setting). See the Verified-Domain SSO guide for the full walkthrough, DNS record format, lifecycle management, and security notes.

Admin: configure a provider

See the External Login Provider configuration guide for the full admin API reference, per-provider required fields, and where to obtain the callback_url to register in the provider console.

Start here

Core concepts

Guides

API reference

Log in with an external provider (OAuth2 / OIDC)

Provider support matrix

How it works

Prerequisites

Step 1 — Redirect the member to the provider

Step 2 — Provider authenticates the member

Step 3 — Exchange the bootstrap code for a token pair

Connect flow

Initiate a connect

Account linking

Security notes

Verified-Domain SSO (v2)

How it extends v1

Set up in three steps

Admin: configure a provider

​Provider support matrix

​How it works

​Prerequisites

​Login flow (frontend implementation)

​Step 1 — Redirect the member to the provider

​Step 2 — Provider authenticates the member

​Step 3 — Exchange the bootstrap code for a token pair

​Connect flow

​Initiate a connect

​Account linking

​Security notes

​Worked example: Google login

​Worked example: Facebook connect then login

​Verified-Domain SSO (v2)

​How it extends v1

​Set up in three steps

​Admin: configure a provider

Provider support matrix

How it works

Prerequisites

Login flow (frontend implementation)

Step 1 — Redirect the member to the provider

Step 2 — Provider authenticates the member

Step 3 — Exchange the bootstrap code for a token pair

Connect flow

Initiate a connect

Account linking

Security notes

Worked example: Google login

Worked example: Facebook connect then login

Verified-Domain SSO (v2)

How it extends v1

Set up in three steps

Admin: configure a provider