Auth API

Endpoints for OIDC authentication and session management. These endpoints are only available after setup is complete (instance state is ready). Calling them before setup returns 409 Conflict with code setup_incomplete.

OIDC Start

Initiate an OIDC authorization code flow. Returns an authorization URL to redirect the user to.

GET /v1/auth/oidc/start

Authentication: None (public)

Query parameters

Parameter	Required	Description
redirect_uri	No	Custom redirect URI (defaults to standard callback)

Response 200 OK

{
  "authorization_url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...&state=...&nonce=...",
  "state": "abc123-csrf-state-token"
}

Field	Type	Description
authorization_url	string	Full authorization URL to redirect the user to
state	string	CSRF state token for validating the callback

The daemon generates a PKCE challenge (S256), CSRF state token, and nonce internally. Pending auth entries expire after 10 minutes.

Error responses

Status	Code	Description
409	setup_incomplete	Setup is not yet complete
429	too_many_pending	Too many pending auth requests (limit: 1000)
500	oidc_not_configured	OIDC configuration is missing
502	oidc_discovery_error	Failed to perform OIDC discovery

---

OIDC Callback

Complete the OIDC authorization code flow. Exchanges the authorization code for tokens, verifies the ID token, and creates a user session.

POST /v1/auth/oidc/callback

Authentication: None (public)

Request body

{
  "code": "4/0AX4XfWh...",
  "state": "abc123-csrf-state-token"
}

Field	Type	Required	Description
code	string	Yes	Authorization code from the IdP callback
state	string	Yes	CSRF state token (must match the value from oidc/start)

Response 200 OK

{
  "session_token": "user_session_abc123...",
  "expires_at": 1738886400,
  "user": {
    "email": "[email protected]",
    "oidc_subject": "110123456789012345678",
    "user_id": "user_def456",
    "role": "developer",
    "avatar_url": "https://lh3.googleusercontent.com/..."
  }
}

Field	Type	Description
session_token	string	User session token (24-hour TTL)
expires_at	integer	Session expiry as Unix epoch (seconds)
user	object	Authenticated user details

Error responses

Status	Code	Description
400	invalid_state	Unknown or expired OIDC state parameter
400	auth_expired	OIDC authorization request expired (10-minute TTL)
403	user_not_found	No user account for this email/identity
409	setup_incomplete	Setup is not yet complete
500	decryption_error	Failed to decrypt stored OIDC client secret
500	session_error	Failed to create session
500	store_error	Database operation failed
502	oidc_discovery_error	Failed to perform OIDC discovery
502	token_exchange_error	Failed to exchange authorization code
502	missing_id_token	IdP did not return an ID token
502	id_token_verification_error	ID token verification failed
502	missing_email	ID token missing email claim

INFO

Users must be invited before they can sign in. If a user authenticates successfully with the OIDC provider but has no account in Oore CI, the callback returns 403 with code user_not_found.

---

Local Login

Create a loopback-only local session without OIDC.

POST /v1/auth/local/login

Authentication: None (public)

Request body

{
  "email": "[email protected]"
}

email is optional when exactly one active user exists.

Response 200 OK

Returns LocalLoginResponse.

Error responses

Status	Code	Description
400	email_required	Multiple active users exist and email was omitted
403	mode_restricted	Setup is incomplete while runtime mode is remote
403	local_login_loopback_required	Local login attempted from non-loopback source
403	user_not_found	No active user matched the provided email

WARNING

Local login is always loopback-only. Any non-loopback access path must use External Access (runtime_mode=remote) and OIDC.

---

Logout

Invalidate the current user session.

POST /v1/auth/logout

Authentication: User session (Bearer)

Response 200 OK

{
  "ok": true
}

Error responses

Status	Code	Description
401	missing_auth	Authorization header not provided
401	invalid_session	Session token is invalid or already expired