Authentication API Reference
Account creation, OTP email validation, credentials login, token rotation, and profile query.
POST /api/v1/auth/register
Registers a new user account with email and password, issuing an email OTP code.
Initiates account registration. Triggers automated verification OTP email.
Headers
| Parameter | Type | Requirement | Description |
|---|---|---|---|
| Content-Type | string | Required | application/json |
Body Parameters
| Parameter | Type | Requirement | Description |
|---|---|---|---|
| string | Required | Valid email address (max 254 characters). | |
| password | string | Required | Password between 8 and 128 characters. |
Response Example (200 OK)
{"user_id": "c62b0834-6330-4e38-89c0-eb28741369cf"}
POST /api/v1/auth/verify-otp
Validates the 6-digit OTP code sent to the user's email during registration, returning active auth tokens.
Confirms user registration and returns access and refresh tokens.
Headers
| Parameter | Type | Requirement | Description |
|---|---|---|---|
| Content-Type | string | Required | application/json |
Body Parameters
| Parameter | Type | Requirement | Description |
|---|---|---|---|
| string | Required | Registered email address. | |
| otp | string | Required | 6-digit verification code. |
Response Example (200 OK)
{"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","refresh_token": "a8fbc923-...","token_type": "Bearer"}
POST /api/v1/auth/login
Authenticates existing account credentials, returning fresh access and refresh tokens.
Locks for 15 minutes after 5 consecutive failed login attempts.
Headers
| Parameter | Type | Requirement | Description |
|---|---|---|---|
| Content-Type | string | Required | application/json |
Body Parameters
| Parameter | Type | Requirement | Description |
|---|---|---|---|
| string | Required | Registered user email. | |
| password | string | Required | User password. |
Response Example (200 OK)
{"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","refresh_token": "a8fbc923-...","token_type": "Bearer"}
POST /api/v1/auth/refresh
Rotates refresh token and issues a new access token. Discards the old refresh token automatically.
Implements single-use token rotation. Reusing an old token revokes all active sessions.
Headers
| Parameter | Type | Requirement | Description |
|---|---|---|---|
| Content-Type | string | Required | application/json |
Body Parameters
| Parameter | Type | Requirement | Description |
|---|---|---|---|
| refresh_token | string | Required | Active refresh token string. |
Response Example (200 OK)
{"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","refresh_token": "b9fbc741-...","token_type": "Bearer"}
POST /api/v1/auth/logout
Revokes the active refresh token session on the server.
Invalidates the provided refresh token session.
Headers
| Parameter | Type | Requirement | Description |
|---|---|---|---|
| Content-Type | string | Required | application/json |
Body Parameters
| Parameter | Type | Requirement | Description |
|---|---|---|---|
| refresh_token | string | Required | Refresh token to invalidate. |
Response Example (200 OK)
{"message": "logged out successfully"}
GET /api/v1/auth/me
Returns the profile details, role, and current credit balance of the authenticated user.
Requires JWT session authentication. Inaccessible via API keys.
Headers
| Parameter | Type | Requirement | Description |
|---|---|---|---|
| Authorization | string | Required | Bearer <access_token> |
Response Example (200 OK)
{"id": "c62b0834-6330-4e38-89c0-eb28741369cf","email": "[email protected]","credit_balance": 25,"role": "user"}