Routes Reference
Core Kernia routes and how plugin routes are mounted.
All routes are mounted under KerniaOptions.base_path. This page shows routes with the common /api/auth mount. If your backend mounts at a different path, replace /api/auth with your configured path.
Route conventions
- Request and response bodies are JSON unless a provider callback requires query parameters.
- Mutating routes use
POST,PATCH, orDELETE. - Cookies are set by the server and must be sent by the browser with
credentials: "include". - Plugin routes use the same mount, error envelope, hooks, cookies, and rate limiter as core routes.
Health
/api/auth/okHealth check for the mounted auth router.
Email and password
/api/auth/sign-up/emailCreate an email/password user when email/password auth is enabled.
/api/auth/sign-in/emailSign in with email and password and set the session cookie.
/api/auth/change-passwordChange the active user's password.
/api/auth/forget-passwordSend a password reset email when the email client is configured.
/api/auth/reset-passwordConsume a password reset token and set a new password.
Sessions
/api/auth/get-sessionReturn the current session and user, or null when no valid session cookie exists.
/api/auth/sign-outRevoke the active session and clear auth cookies.
/api/auth/list-sessionsList sessions for the active user.
/api/auth/revoke-sessionRevoke one session by id.
/api/auth/revoke-sessionsRevoke all sessions for the active user.
/api/auth/revoke-other-sessionsRevoke every other session and keep the current one.
User and account
/api/auth/update-userUpdate user profile fields exposed by the configured schema.
/api/auth/change-emailStart or complete an email change flow, depending on verification configuration.
/api/auth/delete-userDelete or schedule deletion for the active user.
/api/auth/list-accountsList linked accounts for the active user.
/api/auth/unlink-accountUnlink a social or OAuth account when policy allows it.
OAuth
/api/auth/sign-in/socialStart a social OAuth flow. The body includes provider and an optional callback_url.
/api/auth/callback/:providerHandle provider callbacks, exchange the code, link or create the user, set cookies, and redirect.
Plugin route families
| Plugin | Route family |
|---|---|
| API key | /api/auth/api-key/* |
| Organization | /api/auth/organization/* |
| Passkey | /api/auth/passkey/* |
| SSO | /api/auth/sso/* |
| SCIM | /api/auth/scim/* |
| Stripe | /api/auth/stripe/*, /api/auth/billing/* |
| Admin config | /api/auth/admin/config/* |
Error envelope
{
"code": "UNAUTHORIZED",
"message": "Authentication required",
"status": 401
}Clients should branch on code, not localized message text.