auth

Begin an OAuth2 transaction (login, link, establish or claim).

Changed on

Creates a single-use server-side transaction (PKCE S256 always) and returns the IdP authorization URL. login is anonymous and bound by a __Host- browser-binding cookie set on this response (A2/A16); link and establish require an authenticated session and are session-bound; claim binds a credential authority. link verifies the account-security proof up front (A6). OAuth2 cannot perform disclosure reauthentication; reauth returns a local-authenticator or passkey remedy (409). A login records its intent (absent = sign-in) and, for a sign-up, the addressed scope (signup_org, absent = instance); the start reads no registration policy (#604 d5).

post/api/v1/auth/oauth2/{provider}/start

Request

  • Base URL: / (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /api/v1/auth/oauth2/{provider}/start
  • Auth: HTTP bearer

Request body

purposestring required

Reauth is always refused with 409 and a local-factor remedy.

intent'sign-in' | 'sign-up'

Valid only with purpose login (#604); absent = sign-in. It decides only what happens to an unknown identity at the callback: sign-in refuses it uniformly, sign-up enters the registration policy of the addressed scope. A known identity signs in under either. Supplied on any other purpose, the start refuses uniformly.

signup_orgstring

The org whose registration policy a sign-up addresses; absent = the instance scope. Valid only with intent sign-up. The start reads no policy: an unknown org refuses at the callback as a closed door.

environment_idstring

Never accepted. Any supplied value is refused with 400; OAuth2 cannot perform disclosure reauthentication.

proofstring

Required for link (the pre-existing password) and for claim (the credential-establishment authority being spent, #610).

browserboolean

Redirect the callback to the SPA done page instead of returning JSON.

Response

The IdP authorization URL.

authorization_urlstring required

The IdP authorization URL to redirect the browser to.

Changes