Documentation Index
Fetch the complete documentation index at: https://mintlify.com/ricardomb-tech/auth-service/llms.txt
Use this file to discover all available pages before exploring further.
Auth Service is a stateless Spring Boot 3 microservice that centralises authentication and authorisation for your platform. It handles account registration with email verification, credential-based login, JWT + refresh-token issuance with rotation and reuse detection, logout, password reset, and federated login via Google and GitHub (OAuth2). Every error response follows Problem Details (RFC 9457) so all error shapes are uniform regardless of where in the request lifecycle they originate.
Base URL
| Environment | URL |
|---|
| Development | http://localhost:8080 |
| Configurable | Set APP_BASE_URL environment variable |
Authentication
All /auth/** endpoints are public — no token is required. Protected endpoints (e.g. GET /api/v1/users/me) require a valid JWT access token in the Authorization header:
Authorization: Bearer <accessToken>
SecurityConfig.
Content Type
| Direction | Header |
|---|
| Request body | Content-Type: application/json |
| Successful response | Content-Type: application/json |
| Error response | Content-Type: application/problem+json |
GlobalExceptionHandler — are returned as Problem Details (RFC 9457) with Content-Type: application/problem+json.
{
"type": "about:blank",
"title": "Unauthorized",
"status": 401,
"detail": "Full authentication is required to access this resource.",
"instance": "/api/v1/users/me"
}
detail field contains a human-readable explanation. The status field mirrors the HTTP status code. The instance field reflects the request path.
Endpoint Summary
| Method | Path | Auth Required | Description |
|---|
POST | /auth/register | No | Register a new account; sends a verification email. Anti-enumeration: always returns 202. |
POST | /auth/resend-verification | No | Re-send the verification email if the account is still pending. Anti-enumeration: always returns 202. |
POST | /auth/verify | No | Activate an account using the token from the verification email. |
POST | /auth/login | No | Validate credentials and issue a JWT access token + opaque refresh token. |
POST | /auth/refresh | No | Exchange a valid refresh token for a new access + refresh token pair. Detects and blocks token reuse. |
POST | /auth/logout | No | Revoke a refresh token. Idempotent — always returns 204. |
POST | /auth/forgot-password | No | Request a password-reset email. Anti-enumeration: always returns 202. |
POST | /auth/reset-password | No | Set a new password using a valid single-use reset token. |
GET | /oauth2/authorization/google | No | Initiate the Google OAuth2 login flow (redirects to Google). |
GET | /oauth2/authorization/github | No | Initiate the GitHub OAuth2 login flow (redirects to GitHub). |
POST | /auth/oauth2/exchange | No | Exchange the one-time code issued after a successful federated login for an access + refresh token pair. |
GET | /api/v1/users/me | Yes | Return the authenticated account’s profile. |
Swagger UI
Interactive API documentation is available at:
http://localhost:8080/swagger-ui.html
/v3/api-docs.