Social login

Google and GitHub, with your own OAuth app.

That last part is the design, not a limitation. The consent screen names the application asking for access, so if we ran one app for the whole platform your users would be told that xplatform wanted their email — from a company they have never heard of, at the exact moment people abandon a sign-up. Your app, your name on the screen.

1. Register this redirect URL with the provider

$BASE/v1/auth/callback/google

It points at us, because the token exchange happens here. Getting this wrong is the most common way an OAuth setup fails, and it fails on the provider's site where we cannot tell you anything useful — so the studio shows the exact string to paste.

Match it character for character: no trailing slash, and the host has to be the one your app is actually served from.

Give us the credentials. Secret key, from your server.

1curl -X PUT "$BASE/v1/auth/providers/google" \2  -H "authorization: Bearer $SK" \3  -H "content-type: application/json" \4  -d '{"clientId":"…","clientSecret":"…"}'

PUT replaces the pair whole; there is no partial update, because a rotated secret and a swapped app look identical from our side and a half-update would let you believe you had changed something you had not.

1curl "$BASE/v1/auth/providers" -H "authorization: Bearer $SK"

1[2  {3    "provider": "google",4    "clientId": "123.apps.googleusercontent.com",5    "callbackUrl": "https://<your-deployment>/v1/auth/callback/google"6  }7]

Client secrets are never returned. They are encrypted at rest and there is no endpoint that reads one back — you can replace a secret, not retrieve it.

callbackUrl is returned because it is the value people get wrong, and reading it from the API beats copying it out of a doc.

1curl -X DELETE "$BASE/v1/auth/providers/google" -H "authorization: Bearer $SK"

Accounts already linked through it are left alone. Someone who signed up with Google keeps their user record and everything attached to it. Disconnecting stops new sign-ins; it does not delete people.

Send people to the provider. Publishable key.

1curl -X POST "$BASE/v1/auth/sign-in/social" \2  -H "authorization: Bearer $PK" \3  -H "content-type: application/json" \4  -d '{"provider":"google","callbackURL":"https://yourapp.com/welcome"}'

1{ "url": "https://accounts.google.com/o/oauth2/v2/auth?…", "redirect": true }

Redirect the browser there. They come back signed in, with the same session cookie a password sign-in produces.

When the address already has an account

If the same address already signed up with a password, the provider is linked to that existing account rather than creating a second one — but only once your record of the address is verified. Until then the callback fails with account_not_linked.

Verify email explains why, and what to offer someone who hits it.

Errors

A provider you have not configured answers 404 rather than showing your users a button that fails after they have left your site.