API Reference

Complete reference for all UniAuth REST API endpoints. All endpoints are prefixed with /api unless noted otherwise. Authentication is via HTTP-only cookies (for first-party requests) or Bearer tokens (for OAuth-protected endpoints).

Legend

GET ReadPOST Create / ActionPUT UpdateDELETE Delete

Authentication login: 10 req/15min · register: 5 req/15min · forgot-password: 5 req/15min

Method	Path	Description	Auth
POST	/api/auth/register	Create a new user account. Accepts email, password, firstName, lastName. Validates password strength (zxcvbn), checks HIBP breach database, hashes with Argon2id.	No
POST	/api/auth/login	Authenticate with email and password. Returns user data or 2FA challenge. Sets auth_token cookie on success. Rate limited: 10 requests per 15 minutes.	No
POST	/api/auth/logout	End the current session. Clears auth_token cookie and deactivates the session in the database.	Yes
POST	/api/auth/forgot-password	Send a password reset email. Accepts email address. Token is SHA-256 hashed before storage. Rate limited: 5 per 15 minutes.	No
POST	/api/auth/reset-password	Reset password using a valid token. Validates new password strength, hashes with Argon2id.	No
POST	/api/auth/validate-reset-token	Check if a password reset token is still valid (not expired, not used).	No
POST	/api/auth/verify-email	Verify email address using a token from the verification email.	No
POST	/api/auth/resend-verification	Resend the email verification link.	Yes
GET	/api/auth/me	Get the currently authenticated user's basic info (id, email, name, avatar, role).	Yes

Social Login (OAuth)

Method	Path	Description	Auth
POST	/api/auth/oauth/initiate	Initiate social login. Accepts provider ("google" or "github"). Generates CSRF state + PKCE, returns authorization URL.	No
GET	/api/auth/oauth/callback	OAuth callback handler. Verifies state, exchanges code for tokens, creates or links user account.	No

WebAuthn / Passkeys

Method	Path	Description	Auth
POST	/api/auth/passkey/register-options	Get WebAuthn registration options. Generates a challenge stored in user metadata.	Yes
POST	/api/auth/passkey/register-verify	Verify and save a new passkey registration.	Yes
POST	/api/auth/passkey/authenticate-options	Get WebAuthn authentication options (for login). Supports Conditional UI.	No
POST	/api/auth/passkey/authenticate-verify	Verify passkey assertion and create a session.	No

Two-Factor Authentication 10 req/15min

Method	Path	Description	Auth
POST	/api/auth/2fa/setup	Initialize 2FA setup. Accepts method ("totp", "email", "sms"). For TOTP, returns QR code URI and encrypted secret.	Yes
POST	/api/auth/2fa/verify	Verify a 2FA code. Used both during setup confirmation and login verification. Accepts userId, code, and method.	Partial
POST	/api/auth/2fa/disable	Disable a specific 2FA method. Requires current password for verification.	Yes
POST	/api/auth/2fa/send-code	Send an OTP code via email or SMS. Used during login when the user's default 2FA method is email or SMS. Rate limited: 10 per 15 minutes.	Partial
POST	/api/auth/2fa/set-default	Set the default 2FA method when multiple are enabled.	Yes

User 100 req/15min

Method	Path	Description	Auth
GET	/api/user/profile	Get the full user profile including OIDC claims (username, display_name, bio, date_of_birth, gender, company, job_title, website, location, address, locale, social_links, timezone).	Yes
PUT	/api/user/profile	Update user profile fields. Validates username format, date of birth, website URL, etc.	Yes
GET	/api/user/security	Get security overview: 2FA status, enabled methods, passkey count, email verification status.	Yes
POST	/api/user/password	Change password. Requires current password. Validates new password strength. Invalidates all other sessions.	Yes
GET	/api/user/sessions	List all active sessions for the current user (IP, user agent, device type, last activity, current session indicator).	Yes
POST	/api/user/sessions/revoke-all	Revoke all sessions except the current one.	Yes
GET	/api/user/passkeys	List registered passkeys (credential ID, device name, created date, last used).	Yes
DELETE	/api/user/passkeys	Delete a passkey by credential ID.	Yes
GET	/api/user/activity	Get the user's activity log (login, logout, password changes, 2FA events, etc.).	Yes
GET	/api/user/connected-services	List connected OAuth providers (Google, GitHub) with connection status.	Yes
GET	/api/user/authorized-apps	List OAuth applications the user has authorized (granted consent to).	Yes
POST	/api/user/email/request-change	Request an email address change. Sends verification to the new email.	Yes
POST	/api/user/email/verify-change	Confirm the email change using the verification token.	Yes
GET	/api/user/preferences	Get user preferences (language, timezone, date format, notification settings).	Yes
PUT	/api/user/preferences	Update user preferences.	Yes
POST	/api/user/avatar	Upload a user avatar image.	Yes
GET	/api/user/export	Export all user data (GDPR data portability).	Yes
DELETE	/api/user/delete	Permanently delete the user account and all associated data. Requires password confirmation.	Yes

Developer Console (OAuth Clients)

Method	Path	Description	Auth
GET	/api/user/oauth-clients	List OAuth clients created by the current user (max 10).	Yes
POST	/api/user/oauth-clients	Register a new OAuth client. Returns client_id and client_secret (shown once).	Yes
PUT	/api/user/oauth-clients/[id]	Update an OAuth client owned by the current user.	Yes
DELETE	/api/user/oauth-clients/[id]	Delete an OAuth client owned by the current user.	Yes

OAuth2 / OIDC authorize: 100 req/15min · token: 100 req/15min

Method	Path	Description	Auth
GET	/api/oauth/authorize	Authorization endpoint. Redirects to login (if needed) then consent screen. Requires response_type=code, client_id, redirect_uri, code_challenge, code_challenge_method=S256.	Session
POST	/api/oauth/authorize/consent	Handle user consent decision (approve or deny). Stores consent record and redirects with authorization code.	Session
POST	/api/oauth/token	Token endpoint. Supports grant types: authorization_code, refresh_token, client_credentials, device_code. Returns access_token, id_token, refresh_token.	Client
GET	/api/oauth/userinfo	Returns OIDC claims for the authenticated user based on granted scopes. Requires Bearer token.	Bearer
POST	/api/oauth/introspect	Token introspection (RFC 7662). Returns active status and token metadata. Requires client authentication.	Client
POST	/api/oauth/revoke	Token revocation (RFC 7009). Revoke access or refresh tokens. Always returns 200.	Client
GET	/api/oauth/end-session	RP-Initiated Logout. Clears session, triggers back-channel logout, redirects to post_logout_redirect_uri.	No
POST	/api/oauth/device	Device authorization (RFC 8628). Returns device_code, user_code, and verification URI.	No
POST	/api/oauth/device/verify	Verify a device user code (user-facing endpoint for approving device login).	Session
POST	/api/oauth/register	Dynamic client registration (RFC 7591). Register a new OAuth client programmatically.	No
GET	/api/oauth/client-info	Get client information for the consent page (includes current user for personalized scope previews).	Session

SCIM 2.0 Provisioning 100 req/15min

SCIM (System for Cross-domain Identity Management) endpoints for automated user provisioning. Authenticated via Bearer token (SCIM token configured per OAuth client).

Method	Path	Description	Auth
GET	/api/scim/v2/Users	List users with optional filtering, pagination (startIndex, count).	Bearer
POST	/api/scim/v2/Users	Create a new user via SCIM. Accepts SCIM User schema (userName, name, emails, etc.).	Bearer
GET	/api/scim/v2/Users/[id]	Get a specific user by ID in SCIM format.	Bearer
PUT	/api/scim/v2/Users/[id]	Replace a user (full update via SCIM).	Bearer
DELETE	/api/scim/v2/Users/[id]	Delete a user via SCIM.	Bearer
GET	/api/scim/v2/ServiceProviderConfig	SCIM service provider configuration (supported features, auth schemes).	No
GET	/api/scim/v2/Schemas	List supported SCIM schemas.	No
GET	/api/scim/v2/ResourceTypes	List supported SCIM resource types.	No

Administration 100 req/15min

Admin endpoints require the user to have the admin or moderator role. Role-based permissions are enforced via the verifyAdmin() helper.

Method	Path	Description	Role
GET	/api/admin/users	List all users with search, pagination, and filtering by role/status.	Admin
GET	/api/admin/users/[id]	Get detailed information about a specific user.	Admin
PUT	/api/admin/users/[id]	Update a user (change role, lock/unlock account, modify profile).	Admin
DELETE	/api/admin/users/[id]	Delete a user account and all associated data.	Admin
GET	/api/admin/sessions	List all active sessions across all users.	Admin
GET	/api/admin/activity	System-wide activity log with search and filtering.	Admin
GET	/api/admin/roles	List all roles with their permissions.	Admin
POST	/api/admin/roles	Create a new role with custom permissions.	Admin
GET	/api/admin/settings	Get system settings (email, security, etc.).	Admin
PUT	/api/admin/settings	Update system settings.	Admin
GET	/api/admin/stats	Dashboard statistics (total users, active sessions, registrations, etc.).	Admin
GET	/api/admin/analytics	Detailed analytics data (user growth, login trends, 2FA adoption, etc.).	Admin
GET	/api/admin/oauth-clients	List all OAuth clients (across all users).	Admin
POST	/api/admin/oauth-clients	Create an OAuth client (admin can create first-party clients).	Admin
PUT	/api/admin/oauth-clients/[id]	Update any OAuth client (including first-party flag, active status).	Admin
DELETE	/api/admin/oauth-clients/[id]	Delete an OAuth client.	Admin
POST	/api/admin/oidc-keys	Rotate the OIDC RS256 keypair. Generates a new keypair and encrypts the private key.	Admin
POST	/api/admin/impersonate	Start impersonating a user. Sets a special impersonation cookie alongside the admin's session.	Admin
POST	/api/admin/impersonate/stop	Stop impersonating and return to admin view.	Admin

Webhooks

Method	Path	Description	Role
GET	/api/admin/webhooks	List all configured webhooks.	Admin
POST	/api/admin/webhooks	Create a webhook. Specify URL, secret, and subscribed events (user.created, user.updated, user.deleted, login.success, login.failed, etc.).	Admin
GET	/api/admin/webhooks/[id]	Get webhook details including recent delivery history.	Admin
PUT	/api/admin/webhooks/[id]	Update a webhook (URL, events, active status).	Admin
DELETE	/api/admin/webhooks/[id]	Delete a webhook and all delivery records.	Admin
POST	/api/admin/webhooks/[id]/test	Send a test event to the webhook URL to verify connectivity.	Admin

Well-Known Endpoints

Method	Path	Description	Auth
GET	/.well-known/openid-configuration	OpenID Connect Discovery document. Returns issuer, endpoints, supported scopes, response types, grant types, and signing algorithms.	No
GET	/.well-known/jwks.json	JSON Web Key Set. Returns the RS256 public key used for ID token signature verification.	No

Other Endpoints

Method	Path	Description	Auth
GET	/api/avatar/[id]	Get a user's avatar image by user ID. Returns the image directly or a generated fallback.	No

Rate Limiting

All API endpoints are rate-limited. The limits are applied per IP address with a 15-minute sliding window:

Endpoint Pattern	Limit	Window
`/api/auth/login`	10 requests	15 minutes
`/api/auth/register`	5 requests	15 minutes
`/api/auth/forgot-password`	5 requests	15 minutes
`/api/auth/2fa/*`	10 requests	15 minutes
All other `/api/*`	100 requests	15 minutes

When rate limited, the API returns HTTP 429 with a Retry-After header indicating when the client can retry.

Error Responses

All API errors follow a consistent JSON format:

// Standard error response
{
  "success": false,
  "error": "Human-readable error message"
}

// Common HTTP status codes:
// 400 — Bad request (validation error, missing fields)
// 401 — Unauthorized (not authenticated)
// 403 — Forbidden (insufficient permissions)
// 404 — Not found
// 409 — Conflict (duplicate resource)
// 423 — Locked (account lockout)
// 429 — Too many requests (rate limited)
// 500 — Internal server error