Authentication¶
10 endpoint(s).
| Endpoint | Method | Summary | Auth |
|---|---|---|---|
/api/v1/auth/change-password |
POST |
Change Password | 🔒 |
/api/v1/auth/forgot-password |
POST |
Forgot Password | |
/api/v1/auth/login |
POST |
Login | |
/api/v1/auth/logout |
POST |
Logout | 🔒 |
/api/v1/auth/me |
GET |
Get Current User Info | 🔒 |
/api/v1/auth/refresh |
POST |
Refresh Token | |
/api/v1/auth/register |
POST |
Register | |
/api/v1/auth/reset-password |
POST |
Reset Password | |
/api/v1/auth/verify |
POST |
Verify Email | |
/api/v1/auth/verify |
GET |
Verify Email Get |
POST /api/v1/auth/change-password¶
Change Password
Change the authenticated user's password.
🔒 Authentication required — send
Authorization: Bearer <API_KEY>
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
current_password |
string |
yes | |
new_password |
string |
yes |
Response 200 — AuthResponse
Example
curl -X POST 'https://api.example.com/api/v1/auth/change-password' \
-H 'Authorization: Bearer <API_KEY>'
POST /api/v1/auth/forgot-password¶
Forgot Password
Issue a password-reset token + email. Always returns generic success to prevent account enumeration.
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
email |
email |
yes |
Response 200 — AuthResponse
Example
curl -X POST 'https://api.example.com/api/v1/auth/forgot-password' \
-H 'Authorization: Bearer <API_KEY>'
POST /api/v1/auth/login¶
Login
Login with email + password. Returns access + refresh JWTs.
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
email |
email |
yes | |
password |
string |
yes |
Response 200 — Token
Example
curl -X POST 'https://api.example.com/api/v1/auth/login' \
-H 'Authorization: Bearer <API_KEY>'
POST /api/v1/auth/logout¶
Logout
Stateless logout — client should discard its tokens.
🔒 Authentication required — send
Authorization: Bearer <API_KEY>
Response 200 — AuthResponse
Example
curl -X POST 'https://api.example.com/api/v1/auth/logout' \
-H 'Authorization: Bearer <API_KEY>'
GET /api/v1/auth/me¶
Get Current User Info
Return the authenticated user's profile.
🔒 Authentication required — send
Authorization: Bearer <API_KEY>
Response 200 — UserResponse
Example
curl -X GET 'https://api.example.com/api/v1/auth/me' \
-H 'Authorization: Bearer <API_KEY>'
POST /api/v1/auth/refresh¶
Refresh Token
Issue a new access token from a valid refresh token.
Re-fetches the user row instead of trusting only the refresh token's
sub/user_id: the refresh token deliberately carries no authz claims, so
the old code minted the new access token with role/tier/etc. entirely
absent. Every role check downstream (e.g. Lal Kitab's admin bypass)
reads payload.get("role", "user"), so a missing claim silently demoted
every user to "user" on refresh. Re-querying also means a role change
made after login takes effect on the next refresh, matching login's
query shape exactly so the two code paths can't drift.
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
refresh_token |
string |
yes |
Response 200 — Token
Example
curl -X POST 'https://api.example.com/api/v1/auth/refresh' \
-H 'Authorization: Bearer <API_KEY>'
POST /api/v1/auth/register¶
Register
Register a new user account.
Creates an unverified user, sends a verification email, and returns the new user. If SMTP is not configured the user is still created — verification can be re-triggered later by an admin / re-send endpoint.
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
email |
email |
yes | |
username |
string |
yes | |
password |
string |
yes | |
full_name |
any |
no | |
phone |
any |
no |
Response 201 — AuthResponse
Example
curl -X POST 'https://api.example.com/api/v1/auth/register' \
-H 'Authorization: Bearer <API_KEY>'
POST /api/v1/auth/reset-password¶
Reset Password
Set a new password given a valid reset token.
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
token |
string |
yes | |
new_password |
string |
yes |
Response 200 — AuthResponse
Example
curl -X POST 'https://api.example.com/api/v1/auth/reset-password' \
-H 'Authorization: Bearer <API_KEY>'
POST /api/v1/auth/verify¶
Verify Email
Mark a user verified given a still-valid verification token.
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
token |
string |
yes |
Response 200 — AuthResponse
Example
curl -X POST 'https://api.example.com/api/v1/auth/verify' \
-H 'Authorization: Bearer <API_KEY>'
GET /api/v1/auth/verify¶
Verify Email Get
Convenience GET so users can click the email link directly.
| Param | In | Type | Required | Description |
|---|---|---|---|---|
token |
query | string | yes |
Response 200 — AuthResponse
Example
curl -X GET 'https://api.example.com/api/v1/auth/verify' \
-H 'Authorization: Bearer <API_KEY>'