Skip to content

The return from Google or GitHub → open a session

GET
/v1/auth/oauth/{provider}/callback
curl --request GET \
--url https://beta-api.plune.ai/v1/auth/oauth/google/callback

The provider sends the browser here with code and state (#2534); the redirect URI to register with the provider is <PUBLIC_BASE_URL>/v1/auth/oauth/<provider>/callback. The state must be the one in this browser’s cookie (the cookie is spent by the return whatever it comes to); the code is exchanged with the PKCE verifier. The address is the one the provider vouches for: Google’s email only when email_verified is true, GitHub’s primary address only when it is verified. It is matched to the account that address already has (a person who signed in by link lands in the same account), or makes one — through the same door, SSO rule and Bin as the magic link. Always a 302 to the web app: on success to /auth/callback#provider=<provider> with the plune_session cookie set; on a refusal to the page the start came from (default /login) with the reason in the URL FRAGMENT, never the query, so the address reaches no server log: #provider=<p>&refused=failed (cancelled or refused on the provider’s page, a state that does not match, a failed exchange, company SSO required, an account in the Bin), #provider=<p>&refused=no_email (no verified address), #provider=<p>&refused=not_invited&email=<address> (the door is invite-only and the address is not invited; no account is made). 404 for an unknown or unconfigured provider. 20 returns in 15 minutes from one client address. Sent with Cache-Control: no-store and Referrer-Policy: no-referrer.

provider
required
string
Allowed values: google github
code
string
state
string
error
string

Set by the provider when the person cancelled or the provider refused.

To the web app: /auth/callback with the session cookie set, or the sign-in page with the refusal in the fragment

Location
string

Unknown provider, or its OAuth app is not configured

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}

Rate-limited by the client IP (20 in 15 minutes). error names the limit and the wait.

Retry-After
integer

Seconds until the window rolls over