Authentication Endpoints

1. User Registration

Endpoint: POST /api/v1/auth/signup/ Purpose: Register a new user account with email verification. Authentication: Not required

Endpoint Details:

URL: http://auth.fabric.dev:8000/api/v1/auth/signup/
Method: POST
Content-Type: application/json

Request Format:

{
  "identifier": "[email protected]",
  "password": "MySecretPassword123",
  "method": "email",
  "verification_type": "otp"
}

Response:

{
  "message": "otp sent via email."
}

Parameters:

identifier (string, required): Email address or phone number
password (string, required): Strong password (minimum 8 characters)
method (string, required): "email" or "sms" (currently only email supported)
verification_type (string, required): "otp" or "link" (currently only OTP supported)

Error Scenarios:

400 Bad Request: Invalid email format, weak password, missing fields
409 Conflict: User already exists
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Email service unavailable

Endpoint: POST /api/v1/auth/signup/otp/resend/ Purpose: Resend OTP for signup verification Authentication: Not required

Endpoint Details:

URL: http://auth.fabric.dev:8000/api/v1/auth/signup/otp/resend/
Method: POST
Content-Type: application/json

Request Example:

{
  "identifier": "[email protected]",
  "method": "email",
  "verification_type": "otp"
}

Response Example:

{
  "message": "otp sent via email."
}

Parameters:

identifier (string, required): Email address or phone number
method (string, required): "email" or "sms"
verification_type (string, required): "otp" or "link"

Error Scenarios:

400 Bad Request: Invalid identifier format
404 Not Found: User not found
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Email service unavailable

Endpoint: POST /api/v1/auth/signup/confirm/ Purpose: Verify OTP and complete user registration Authentication: Not required

Endpoint Details:

URL: http://auth.fabric.dev:8000/api/v1/auth/signup/confirm/
Method: POST
Content-Type: application/json

Request Example:

{
  "identifier": "[email protected]",
  "code": "123456"
}

Response Example:

{
  "message": "Sign up success"
}

Parameters:

identifier (string, required): Email address or phone number
code (string, required): 6-digit OTP code

Error Scenarios:

400 Bad Request: Invalid OTP code, expired OTP
404 Not Found: User not found
429 Too Many Requests: Too many attempts
500 Internal Server Error: Database error

Endpoint: POST /api/v1/auth/login/basic/ Purpose: Authenticate user with email/phone and password Authentication: Not required

Endpoint Details:

URL: http://auth.fabric.dev:8000/api/v1/auth/login/basic/
Method: POST
Content-Type: application/json

Request Example:

{
  "identifier": "[email protected]",
  "password": "MySecretPassword123"
}

Response Example:

{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

Parameters:

identifier (string, required): Email address or phone number
password (string, required): User password

Error Scenarios:

400 Bad Request: Invalid credentials, missing fields
401 Unauthorized: Incorrect password
404 Not Found: User not found
429 Too Many Requests: Rate limit exceeded

5. Refresh Token

Endpoint: POST /api/v1/auth/token/refresh/ Purpose: Obtain new access token using refresh token Authentication: Not required

Endpoint Details:

URL: http://auth.fabric.dev:8000/api/v1/auth/token/refresh/
Method: POST
Content-Type: application/json

Request Example:

{
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

Response Example:

{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

Parameters:

refresh (string, required): Valid refresh token

Error Scenarios:

400 Bad Request: Invalid refresh token
401 Unauthorized: Expired refresh token
500 Internal Server Error: Token processing error

6. Get Current User

Endpoint: GET /api/v1/me/ Purpose: Retrieve current authenticated user's profile Authentication: Required (Bearer token)

Endpoint Details:

URL: http://auth.fabric.dev:8000/api/v1/me
Method: GET
Headers: Authorization: Bearer <access_token>

Request Example: GET /api/v1/me Headers: Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

Response Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "date_joined": "2025-07-04T12:34:56.789Z",
  "is_online": true,
  "date_of_birth": "1990-01-01",
  "bio": "Hello, I'm John!"
}

Parameters: None (uses token for authentication)

Error Scenarios:

401 Unauthorized: Invalid or missing token
404 Not Found: User not found in database
500 Internal Server Error: Database error

Endpoint: POST /login/passwordless/ Purpose: Request OTP for passwordless login Authentication: Not required

Endpoint Details:

URL: http://auth.fabric.dev:8000/api/v1/auth/login/passwordless/
Method: POST
Content-Type: application/json

Request Example:

{
  "identifier": "[email protected]",
  "method": "email",
  "verification_type": "otp"
}

Response Example:

{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

Parameters:

identifier (string, required): Email address or phone number
code (string, required): 6-digit OTP code

Error Scenarios:

400 Bad Request: Invalid OTP code, expired OTP
404 Not Found: User not found
429 Too Many Requests: Too many attempts
500 Internal Server Error: Database error

Endpoint: POST /api/v1/auth/login/passwordless/confirm/ Purpose: Verify OTP and receive authentication tokens Authentication: Not required

Endpoint Details:

URL: http://auth.fabric.dev:8000/api/v1/auth/login/passwordless/confirm/
Method: POST
Content-Type: application/json

Request Example:

{
  "identifier": "[email protected]",
  "code": "123456"
}

Response Example:

{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

Parameters:

identifier (string, required): Email address or phone number
code (string, required): 6-digit OTP code

Error Scenarios:

400 Bad Request: Invalid OTP code, expired OTP
404 Not Found: User not found
429 Too Many Requests: Too many attempts
500 Internal Server Error: Database error

9. Password Reset Request

Endpoint: POST /api/v1/auth/password/reset/ Purpose: Request OTP for password reset Authentication: Not required

Endpoint Details:

URL: http://auth.fabric.dev:8000/api/v1/auth/password/reset/
Method: POST
Content-Type: application/json

Request Example:

{
  "identifier": "[email protected]",
  "method": "email",
  "verification_type": "otp"
}

Response Example:

{
  "message": "otp sent via email."
}

Parameters:

identifier (string, required): Email address or phone number
method (string, required): "email" or "sms"
verification_type (string, required): "otp" or "link"

Error Scenarios:

400 Bad Request: Invalid identifier format
404 Not Found: User not found
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Email service unavailable

9. Confirm Password Reset

Endpoint: POST /api/v1/auth/password/reset/confirm/ Purpose: Reset password using OTP verification Authentication: Not required

Endpoint Details:

URL: http://auth.fabric.dev:8000/api/v1/auth/password/reset/confirm/
Method: POST
Content-Type: application/json

Request Example:

{
  "identifier": "[email protected]",
  "code": "123456",
  "new_password": "NewSecretPassword123",
  "confirm_password": "NewSecretPassword123"
}

Response Example:

{
  "message": "Password has been reset successfully."
}

Parameters:

identifier (string, required): Email address or phone number
code (string, required): 6-digit OTP code
new_password (string, required): New password
confirm_password (string, required): Password confirmation

Error Scenarios:

400 Bad Request: Invalid OTP, password mismatch, weak password
404 Not Found: User not found
429 Too Many Requests: Too many attempts
500 Internal Server Error: Database error

10. Confirm Password Reset

Endpoint: POST /api/v1/auth/password/reset/confirm/ Purpose: Reset password using OTP verification Authentication: Not required

Endpoint Details:

URL: http://auth.fabric.dev:8000/api/v1/auth/password/reset/confirm/
Method: POST
Content-Type: application/json

Request Example:

{
  "identifier": "[email protected]",
  "code": "123456",
  "new_password": "NewSecretPassword123",
  "confirm_password": "NewSecretPassword123"
}

Response Example:

{
  "message": "Password has been reset successfully."
}

Parameters:

identifier (string, required): Email address or phone number
code (string, required): 6-digit OTP code
new_password (string, required): New password
confirm_password (string, required): Password confirmation

Error Scenarios:

400 Bad Request: Invalid OTP, password mismatch, weak password
404 Not Found: User not found
429 Too Many Requests: Too many attempts
500 Internal Server Error: Database error

11. Change Password

Endpoint: POST /api/v1/authpassword/change/ Purpose: Change password for authenticated user Authentication: Required (Bearer token)

Endpoint Details:

URL: http://auth.fabric.dev:8000/api/v1/auth/password/change/
Method: POST
Content-Type: application/json
Headers: Authorization: Bearer <access_token>

Request Example:

{
  "old_password": "OldPassword123",
  "new_password": "NewSecretPassword123",
  "confirm_password": "NewSecretPassword123"
}

Response Example:

{
  "message": "Password has been changed successfully."
}

Parameters:

old_password (string, required): Current password
new_password (string, required): New password
confirm_password (string, required): Password confirmation

Error Scenarios:

400 Bad Request: Incorrect old password, password mismatch, weak password
401 Unauthorized: Invalid or missing token
500 Internal Server Error: Database error

12. Email Change Request

Endpoint: POST /api/v1/auth/email/change/ Purpose: Request to change email address Authentication: Required (Bearer token)

Endpoint Details:

URL: http://auth.fabric.dev:8000/api/v1/auth/email/change/
Method: POST
Content-Type: application/json
Headers: Authorization: Bearer <access_token>

Request Example:

{
  "new_email": "[email protected]",
  "current_password": "MySecretPassword123",
  "verification_type": "otp"
}

Response Example:

{
  "message": "otp has been sent to the email."
}

Parameters:

new_email (string, required): New email address
current_password (string, required): Current password
verification_type (string, required): "otp" or "link"

Error Scenarios:

400 Bad Request: Invalid email format, incorrect password
401 Unauthorized: Invalid or missing token
409 Conflict: Email already exists
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Email service unavailable

13. Confirm Email Change

Endpoint: POST /api/v1/auth/email/change/confirm/ Purpose: Confirm email change with OTP verification Authentication: Not required

Endpoint Details:

URL: http://auth.fabric.dev:8000/api/v1/auth/email/change/confirm/
Method: POST
Content-Type: application/json

Request Example:

{
  "identifier": "[email protected]",
  "code": "123456"
}

Response Example:

{
  "message": "Email has been changed successfully."
}

Parameters:

identifier (string, required): New email address
code (string, required): 6-digit OTP code

Error Scenarios:

400 Bad Request: Invalid OTP code, expired OTP
404 Not Found: Email change request not found
429 Too Many Requests: Too many attempts
500 Internal Server Error: Database error

14. Health Check

Endpoint: GET /health/ Purpose: Check service health and status Authentication: Not required

Endpoint Details:

URL: http://auth.fabric.dev:8000/health/
Method: GET

Request Example: GET /health/

Response Example:

{
  "status": "ok",
  "timestamp": "2025-07-04T12:34:56.789Z",
  "service": "fabric-auth-service",
  "environment": "development",
  "app_version": "0.1.0",
  "components": {
    "database": "ok"
  }
}

Parameters: None

Error Scenarios:

503 Service Unavailable: Database connection failed

PreviousAuthentication API NextAuthentication Methods

Last updated 1 day ago

Was this helpful?

1. User Registration

2. Resend Signup OTP

3. Confirm Signup

4. Basic Login

5. Refresh Token

6. Get Current User

7. Passwordless Login Request

8. Confirm Passwordless Login

9. Password Reset Request

9. Confirm Password Reset

10. Confirm Password Reset

11. Change Password

12. Email Change Request

13. Confirm Email Change

14. Health Check