Authentication
End-to-end authentication lifecycle — registration, email verification, login, OAuth providers, password reset, session management, and rate limiting.
Overview#
NaaP provides a complete authentication system with email/password registration, OAuth provider sign-in (Google, GitHub), email verification, password reset, and JWT-based session management. All auth endpoints include rate limiting to prevent brute-force attacks.
This page covers the platform-level auth lifecycle. For plugin-level auth (SDK hooks like useAuth, useShell), see SDK Hooks and Shell Context.
Registration#
Email/Password Registration#
POST /api/v1/auth/registerRegister a new account with email and password. Rate limited per IP.
Request Body:
| 1 | { |
| 2 | "email": "user@example.com", |
| 3 | "password": "securePassword123", |
| 4 | "displayName": "Jane Doe" |
| 5 | } |
On success, a verification email is sent via Resend. The response intentionally does not reveal whether the email is already registered (to prevent enumeration).
Email Verification#
POST /api/v1/auth/verify-emailVerify the user's email address using the token from the verification email.
POST /api/v1/auth/resend-verificationResend the verification email if the original expired or was not received.
Login#
Email/Password Login#
POST /api/v1/auth/loginAuthenticate with email and password. Returns a JWT session token.
Request Body:
| 1 | { |
| 2 | "email": "user@example.com", |
| 3 | "password": "securePassword123" |
| 4 | } |
Response:
| 1 | { |
| 2 | "success": true, |
| 3 | "data": { |
| 4 | "token": "eyJhbGciOiJIUzI1NiIs...", |
| 5 | "user": { |
| 6 | "id": "...", |
| 7 | "email": "user@example.com", |
| 8 | "displayName": "Jane Doe", |
| 9 | "roles": ["user"] |
| 10 | } |
| 11 | } |
| 12 | } |
OAuth Provider Login#
NaaP supports signing in with external OAuth providers.
List available providers:
GET /api/v1/auth/providersStart OAuth flow:
GET /api/v1/auth/providers/{slug}/startRedirects the user to the provider's consent page.
Handle callback:
GET /api/v1/auth/providers/{slug}/callbackProcesses the OAuth callback and creates or links the account.
Supported providers:
- Google (
google) - GitHub (
github)
Password Reset#
Request Reset#
POST /api/v1/auth/forgot-passwordSend a password reset email. Rate limited to prevent abuse. Uses Resend for email delivery.
Request Body:
{
"email": "user@example.com"
}Complete Reset#
POST /api/v1/auth/reset-passwordReset the password using the token from the reset email.
Request Body:
| 1 | { |
| 2 | "token": "reset-token-from-email", |
| 3 | "password": "newSecurePassword456" |
| 4 | } |
Session Management#
Get Current Session#
GET /api/v1/auth/meReturns the current user's profile and session details from the JWT.
Refresh Token#
POST /api/v1/auth/refreshExchange an expiring JWT for a fresh one.
Logout#
POST /api/v1/auth/logoutInvalidate the current session.
Profile#
GET /api/v1/auth/profile
PUT /api/v1/auth/profileRetrieve or update the current user's profile (display name, avatar URL, etc.).
CSRF Protection#
GET /api/v1/auth/csrfReturns a CSRF token. Mutating API calls validate this token via the x-csrf-token header.
Security Features#
Rate Limiting#
All auth endpoints are rate limited per IP address:
| Endpoint | Limit | Window |
|---|---|---|
POST /api/v1/auth/register | Throttled | Per-IP |
POST /api/v1/auth/login | Throttled | Per-IP |
POST /api/v1/auth/forgot-password | Throttled | Per-IP |
Rate-limited requests receive a 429 Too Many Requests response.
JWT Structure#
Sessions are JWT-based with the following flow:
- User authenticates (login or OAuth callback)
- Server issues a signed JWT containing user ID and roles
- Client sends
Authorization: Bearer <token>on subsequent requests - Server validates the token via
validateSession()on each API call
RBAC (Role-Based Access Control)#
Users are assigned roles via the UserRole → Role relationship:
| Role | Description |
|---|---|
user | Default role for all users |
system:admin | Platform administrator — access to admin APIs |
Plugins can check roles via sessionUser.roles.includes('system:admin').
Auth Headers for Plugins#
When the shell proxies requests to plugin backends, it forwards these auth headers:
| Header | Description |
|---|---|
x-user-id | Current user's ID |
x-user-email | Current user's email |
x-team-id | Current team's ID (if applicable) |
x-request-id | Unique request identifier |
authorization | Bearer token |
Related Resources#
- SDK Hooks —
useAuthand other plugin-level auth hooks - Shell Context —
authservice in the shell context - Admin Operations — Admin user management