AuthKit API reference

Browser API testing

Start AuthKit-Lite with the default configuration and open http://localhost:8080/api-test. The project-hosted console covers the available request flows and shows responses without requiring Postman or a separate frontend.

Use registration or the seeded demo accounts for authentication.
The console retains runtime tokens only in memory.
Protected endpoints keep the same Bearer-token, role, session, and CSRF rules documented below.
Enable passkeys through .env before testing successful WebAuthn ceremonies.

Authentication

Authentication endpoints
Method	Path	Access	Purpose
POST	/api/auth/register	Public	Create a user; passwords require at least 12 characters
POST	/api/auth/login	Public	Return JWT access and opaque refresh tokens
POST	/api/auth/refresh	Public	Rotate a valid refresh token and return a new token pair
POST	/api/auth/logout	Bearer JWT	Invalidate the supplied refresh-token session

POST/api/auth/registerPublic

Create an AuthKit-Lite user. The released validation boundary requires a password of at least 12 characters.

Headers

Content-Type: application/json

Relevant errors

Validation failure for an invalid request.
Conflict when the requested identity already exists.

cURL

curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  --data @registration.json

POST/api/auth/loginPublic

Verify username and password credentials and return a short-lived JWT access token with an opaque refresh token.

Headers

Content-Type: application/json

Request

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

Successful response

200 response

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

Relevant errors

Unauthorized when credentials are invalid or the user is disabled.

cURL

curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  --data '{"username":"developer","password":"<password>"}'

POST/api/auth/refreshPublic

Rotate a valid refresh token under the database lock and return a new token pair. Reuse of the previous token is rejected.

Headers

Content-Type: application/json

Relevant errors

Unauthorized when the token is invalid, expired, revoked, or already rotated.

cURL

curl -X POST http://localhost:8080/api/auth/refresh \
  -H "Content-Type: application/json" \
  --data @refresh.json

POST/api/auth/logoutBearer JWT

Invalidate the supplied refresh-token session. The current access token remains valid until its expiry.

Headers

Authorization: Bearer <access-token>
Content-Type: application/json

Relevant errors

Unauthorized when the Bearer token is missing or invalid.

cURL

curl -X POST http://localhost:8080/api/auth/logout \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  --data @logout.json

Users and admin

User endpoints
Method	Path	Access	Purpose
GET	/api/users/me	Bearer JWT	Return the current user profile
GET	/api/users	ROLE_ADMIN	Return a pageable user list
GET	/api/users/me/passkeys	Bearer JWT	List the current user's passkey metadata

GET/api/users/meBearer JWT

Return the profile represented by the validated access token.

Headers

Authorization: Bearer <access-token>

Relevant errors

Unauthorized for a missing, expired, or invalid token.

cURL

curl http://localhost:8080/api/users/me \
  -H "Authorization: Bearer <access-token>"

GET/api/usersROLE_ADMIN

Return the pageable administrative user listing.

Headers

Authorization: Bearer <admin-access-token>

Parameters

Pageable query parameters are accepted by the Spring Data boundary.

Relevant errors

Forbidden when the authenticated user does not have ROLE_ADMIN.

cURL

curl http://localhost:8080/api/users \
  -H "Authorization: Bearer <admin-access-token>"

GET/api/users/me/passkeysBearer JWT

List passkey metadata owned by the current user. Authenticator secrets are not returned.

Headers

Authorization: Bearer <access-token>

cURL

curl http://localhost:8080/api/users/me/passkeys \
  -H "Authorization: Bearer <access-token>"

Passkeys

WebAuthn endpoints
Method	Path	Access	Purpose
GET	/webauthn/csrf	Public	Create/read the ceremony CSRF token
POST	/webauthn/register/options	Bearer JWT + CSRF	Create registration options
POST	/webauthn/register	Bearer JWT + CSRF	Complete registration with browser attestation
DELETE	/webauthn/register/{credentialId}	Owner + CSRF	Delete an owned credential
POST	/webauthn/authenticate/options	Public + CSRF	Create authentication options
POST	/login/webauthn	Public + CSRF	Complete authentication and return AuthKit tokens

Passkey implementation guide

Operations and testing

Operational endpoints
Method	Path	Access	Purpose
GET	/actuator	Public	Actuator discovery links
GET	/actuator/health	Public	Health information
GET	/actuator/info	Public	Application information
GET	/api-test	Public	Redirect to the browser API console