API Endpoints Reference

OAuth / OIDC

GET /api/oauth/authorize

Starts the OAuth authorization-code flow.

GET /api/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/auth/callback
  &response_type=code
  &scope=openid%20profile%20email%20offline_access
  &state=RANDOM_STATE
  &nonce=RANDOM_NONCE
  &code_challenge=PKCE_CHALLENGE
  &code_challenge_method=S256

Optional parameters currently supported include prompt, provider, and login_hint.

POST /api/oauth/token

Exchanges an authorization code or refresh token for new tokens.

POST /api/oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "AUTHORIZATION_CODE",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "redirect_uri": "https://yourapp.com/auth/callback",
  "code_verifier": "PKCE_VERIFIER"
}

GET /api/oauth/userinfo

Returns OIDC claims for the current access token.

POST /api/oauth/revoke

Revokes a token owned by the requesting client.

GET /.well-known/openid-configuration

Returns discovery metadata for OIDC clients.

GET /.well-known/jwks.json

Returns the public signing keys used for JWT verification.

Public Authentication

POST /api/public/register

Creates a new public user, or adds a password to an existing social-only account with the same email.

POST /api/public/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "StrongPassword123",
  "name": "User Name"
}

POST /api/public/login

Authenticates a user with email and password, then sets the public-session cookie.

POST /api/public/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "StrongPassword123"
}

This endpoint is cookie-session based. It does not return OAuth tokens.

POST /api/public/request-magic-link

Requests a passwordless magic link for a verified public user account.

POST /api/public/request-magic-link
Content-Type: application/json

{
  "email": "user@example.com",
  "redirect_uri": "https://yourapp.com/after-login"
}

Response is intentionally generic even when the account does not exist.

POST /api/public/verify-pin

Completes a PIN-gated login flow.

GET /api/public/session

Validates the public-session cookie and returns sanitized user information.

GET /api/sso/validate

Compatibility endpoint for mixed admin/public shared-domain session validation.

Social Login

GET /api/auth/google/login

GET /api/auth/google/callback

GET /api/auth/facebook/login

GET /api/auth/facebook/callback

Social login uses the same hosted SSO flow, with canonical callback-state parsing, CSRF binding, and public-session creation. These callbacks can also resume an OAuth flow when the login originated inside /api/oauth/authorize.

Permission APIs

GET /api/users/[userId]/apps/[clientId]/permissions

Reads a permission record for a user/client pair.

Allowed via:

• matching user-bound access token for the same client
• matching client token with manage_permissions
• admin session

PUT /api/users/[userId]/apps/[clientId]/permissions

Client-managed permission upsert. Requires a bearer token for the same client with manage_permissions.

PUT /api/users/{userId}/apps/{clientId}/permissions
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "role": "user",
  "status": "approved"
}

DELETE /api/users/[userId]/apps/[clientId]/permissions

Client-managed revoke for the same client.

POST /api/users/[userId]/apps/[clientId]/request-access

Creates a pending access request for the same token subject and same token client.

POST /api/users/{userId}/apps/{clientId}/request-access
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "email": "user@example.com",
  "name": "User Name"
}

PUT /api/admin/users/[userId]/apps/[clientId]/permissions

Admin-managed permission update.

PUT /api/admin/users/{userId}/apps/{clientId}/permissions
Cookie: admin-session=... or public-session=...
Content-Type: application/json

{
  "role": "admin",
  "status": "approved"
}

DELETE /api/admin/users/[userId]/apps/[clientId]/permissions

Admin-managed revoke. Returns a canonical revoked/none permission shape.