AuthKit-Pro API reference

Conventions

AuthKit-owned API bodies are JSON. Spring browser authentication endpoints use forms or native WebAuthn payloads. Bearer JWTs protect authenticated API routes; browser state-changing routes also require the CSRF cookie and X-XSRF-TOKEN header returned by /browser/csrf or /webauthn/csrf.

Passwords require at least 12 characters and must fit BCrypt's 72 UTF-8 byte limit.
Public registration, verification, and recovery responses are intentionally generic.
Wrong credentials return 401; ownership failures 403; invalid lifecycle credentials 400; authenticated email or identity uniqueness conflicts 409.

Core authentication

Core authentication endpoints
Method	Path	Access	Purpose
POST	/api/auth/register	Public	Create a local account and request verification
POST	/api/auth/login	Public	Create an independent session and return access/refresh credentials
POST	/api/auth/refresh	Public	Rotate a refresh credential and return a new pair
POST	/api/auth/logout	Bearer JWT	Revoke the owned refresh family

POST/api/auth/registerPublic

Request

json

{
  "username": "developer",
  "email": "developer@example.com",
  "password": "choose-at-least-12-characters"
}

Successful response

json

{
  "message": "If registration is available, the account was created and verification requested"
}

Relevant errors

400 for invalid input.

POST/api/auth/loginPublic

Authenticate a local username and password and create an independent refresh session.

Request

json

{
  "username": "developer",
  "password": "<your-password>"
}

Successful response

json

{
  "accessToken": "<jwt>",
  "refreshToken": "<opaque-credential>",
  "tokenType": "Bearer",
  "expiresInSeconds": 900,
  "refreshTokenExpiresInSeconds": 1209600
}

Relevant errors

401 for invalid credentials or account state.

POST/api/auth/refreshPublic

Consume and rotate one active refresh credential. Reuse of a consumed credential compromises and revokes that session family.

Request

json

{
  "refreshToken": "<opaque-refresh-credential>"
}

Successful response

json

{
  "accessToken": "<jwt>",
  "refreshToken": "<rotated-opaque-credential>",
  "tokenType": "Bearer",
  "expiresInSeconds": 900,
  "refreshTokenExpiresInSeconds": 1209600
}

Relevant errors

401 for an invalid, expired, revoked, or replayed credential.

POST/api/auth/logoutBearer JWT

Revoke the session family that owns the supplied refresh credential.

Headers

Authorization: Bearer <access-token>

Request

json

{
  "refreshToken": "<opaque-refresh-credential>"
}

Successful response

json

{
  "message": "Logged out successfully"
}

Relevant errors

401 for a missing or invalid JWT.
403 when the refresh credential is not owned by the authenticated account.

Users

User endpoints
Method	Path	Access	Purpose
GET	/api/users/me	Bearer JWT	Return the current profile, roles, enabled state, and email verification state
GET	/api/users	ROLE_ADMIN	Return pageable user summaries

Sessions

Session endpoints
Method	Path	Access	Purpose
GET	/api/account/sessions	Bearer JWT	List own sessions and identify the current session
DELETE	/api/account/sessions/{id}	Bearer JWT	Revoke one owned session
DELETE	/api/account/sessions/others	Bearer JWT	Revoke every session except the current sid
DELETE	/api/account/sessions	Bearer JWT	Revoke all sessions, including current

Email verification

Email verification endpoints
Method	Path	Access	Purpose
POST	/api/auth/verification/request	Public	Request a verification message for an email address
POST	/api/auth/verification/confirm	Public	Consume a verification token

POST/api/auth/verification/requestPublic

Request verification without revealing whether the account exists.

Request

json

{
  "email": "developer@example.com"
}

Successful response

json

{
  "message": "If the account is eligible, an email will be sent"
}

POST/api/auth/verification/confirmPublic

Consume a single-use verification credential.

Request

json

{
  "token": "<verification-token>"
}

Successful response

json

{
  "message": "Email verified"
}

Relevant errors

400 for an invalid, expired, consumed, or wrong-purpose token.

Password lifecycle

Password lifecycle endpoints
Method	Path	Access	Purpose
POST	/api/auth/password/forgot	Public	Request a password-reset message
POST	/api/auth/password/reset	Public	Consume a reset token and set a new password
POST	/api/account/password	Bearer JWT	Verify the current password and set a new password

Email change

Email-change endpoints
Method	Path	Access	Purpose
POST	/api/account/email	Bearer JWT	Prove the current password and request verification at a new address
POST	/api/auth/email/confirm	Public	Verify and commit the replacement email

Administration

Administration endpoints
Method	Path	Access	Purpose
POST	/api/admin/users/{id}/state	ROLE_ADMIN	Enable or disable an account from { "enabled": true\|false }

Security activity

Security activity endpoint
Method	Path	Access	Purpose
GET	/api/account/activity	Bearer JWT	Return own pageable activity history; maximum page size 100

External identities

External identity endpoints
Method	Path	Access	Purpose
GET	/api/account/identities	Bearer JWT	List own provider metadata without provider tokens
DELETE	/api/account/identities/{id}	Bearer JWT	Prove the current password and unlink an owned identity

Browser OAuth and CSRF

Browser OAuth endpoints
Method	Path	Access	Purpose
GET	/browser/csrf	Public	Create/read browser CSRF cookie and header token
POST	/oauth2/link/{registrationId}	Bearer JWT + CSRF	Prove the current password and begin explicit account linking
GET	/oauth2/authorization/{registrationId}	Spring OAuth entry	Begin authorization for a configured provider
GET	/login/oauth2/code/{registrationId}	Spring callback	Verify provider response and return AuthKit tokens as JSON

One-Time Token magic links

Magic-link endpoints
Method	Path	Access	Purpose
POST	/ott/generate	CSRF form; optional feature	Request a link for an enabled, verified local account
POST	/login/ott	CSRF form; optional feature	Consume the Spring One-Time Token and return AuthKit tokens

Passkeys and WebAuthn

WebAuthn endpoints
Method	Path	Access	Purpose
GET	/webauthn/csrf	Public	Create/read ceremony CSRF state
POST	/webauthn/register/options	Bearer JWT + CSRF	Create native registration options
POST	/webauthn/register	Bearer JWT + CSRF	Complete native credential registration
DELETE	/webauthn/register/{credentialId}	Credential owner + CSRF	Delete an owned credential
POST	/webauthn/authenticate/options	Public + CSRF	Create native assertion options
POST	/login/webauthn	Public + CSRF	Complete native authentication and return AuthKit tokens
GET	/api/users/me/passkeys	Bearer JWT	List own passkey metadata