GET /v1/auth/oauth/:provider/start

Start an OAuth authorization-code flow with a third-party provider. Issues a single-use state token, persists it server-side, and 307-redirects the browser to the provider's authorization URL.

::: tip Auth Required: none. :::

Request

GET /v1/auth/oauth/:provider/start?redirect_to=/dashboard

Path param	Notes
provider	One of google, github. Unknown providers return 404.

Query param	Required	Notes
redirect_to	no	Host-relative path to land on after a successful round-trip. Default /. Must begin with / and must not begin with // (open-redirect guard).

Response

307 Temporary Redirect

Location header points to the provider's authorization endpoint with all required query parameters set (client_id, redirect_uri, state, scope, response_type).

Error responses

Status	Code	When
400	invalid_input	redirect_to is empty, absolute, or protocol-relative.
404	not_found	Provider isn't google or github, OR the deployment has no client ID configured for the requested provider.
500	internal_error	URL build or cache write failure.

Example: browser

<a href="https://auth.example.com/v1/auth/oauth/google/start?redirect_to=/dashboard">
  Sign in with Google
</a>

Notes

• State tokens are 32-byte URL-safe base64 strings, stored in session_cache under IdentSphere:oauth:state:{token} with a 10-minute TTL.
• The redirect_to path is preserved in the state record; the callback uses it to land the user on the right page.
• The redirect URI registered with the provider must be {public_base_url}/v1/auth/oauth/{provider}/callback. Mismatches will fail at the provider, not at IdentSphere.