API Reference

API Endpoints Reference

Canonical endpoint map for OAuth, public auth, social login, and permission-management APIs.

API Version

5.44.0

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.

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.

GET /api/apps/[clientId]/users

Lists every SSO account related to the client — a live consent or a permission record — joined with the account. This is how an application's own rights management sees a user before that user's first sign-in to it. Requires a client_credentials bearer token for the same client with manage_permissions: 401 without a valid token, 403 without the scope or for another client's id.

GET /api/apps/{clientId}/users?search=&page=1&limit=50
Authorization: Bearer MACHINE_ACCESS_TOKEN

search matches email or name as a literal, case-insensitive substring; limit is at most 200. The response is { clientId, users, total, page, pages, limit }; each user carries id, email, name, status, emailVerified, picture, createdAt, lastLoginAt, consent ({ scope, grantedAt } or null) and permission (the canonical permission DTO fields or null). No password hash or provider payload is ever included.

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.

Response formats