Authentication Endpoints

Health Check

get

Check the health status of the authentication service. This endpoint is used by load balancers, monitoring systems, and orchestration tools to determine if the service is healthy and ready to handle requests.

Response Status:

• 200 OK: Service is healthy and all components are operational

• 503 Service Unavailable: Service is unhealthy (database connection failed)

Use Cases:

• Load balancer health checks

• Kubernetes liveness/readiness probes

• Monitoring system status checks

• CI/CD pipeline health verification

Responses

200Success

application/json

get

/v1/auth/health/

HTTPcURLJavaScriptPython

GET /v1/auth/health/ HTTP/1.1
Host: localhost:8000
Accept: */*

200Success

{
  "status": "text",
  "timestamp": "text",
  "service": "text",
  "environment": "text",
  "app_version": "text",
  "components": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Basic Authentication Login

post

Authenticate user with email/phone and password to obtain access tokens

Authentication Flow:

1. User provides identifier (email/phone) and password

2. System validates credentials

3. Returns JWT access and refresh tokens

4. User can use access token for authenticated requests

Security Features:

• Password hashing and validation

• Account lockout after failed attempts

• JWT token expiration

• Refresh token for token renewal

Token Usage:

• Access Token: Include in Authorization header for API calls

• Refresh Token: Use to get new access token when expired

Prerequisites:

• User account must be verified

• Valid email/phone and password combination

Use Cases:

• Web application user login

• Mobile app authentication

• API access for authenticated users

• E-commerce platform customer login

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

identifierstring · min: 1 · max: 100Required

Email or Phone number

passwordstring · min: 1Write-onlyRequired

Your password can’t be too similar to your other personal information.

Your password must contain at least 8 characters.

Your password can’t be a commonly used password.

Your password can’t be entirely numeric.

Responses

200

Login successful

application/json

400

Invalid credentials

application/json

401

Authentication failed

application/json

429

Too many login attempts

application/json

500

Internal server error

application/json

post

/v1/auth/login/basic/

HTTPcURLJavaScriptPython

POST /v1/auth/login/basic/ HTTP/1.1
Host: localhost:8000
Content-Type: application/json
Accept: */*
Content-Length: 66

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

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

Email LoginPhone Login

{
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 123,
    "email": "[email protected]",
    "is_verified": true
  }
}

Passwordless Login

post

Initiate passwordless login by sending OTP or verification link

Process:

1. User provides email/phone number

2. System sends OTP or verification link

3. User enters OTP or clicks link

4. System authenticates user and returns tokens

Benefits:

• No password required

• Enhanced security through time-based codes

• Reduced password management overhead

Security:

• Rate limiting prevents abuse

• OTP expiration for security

• One-time use codes

Use Cases:

• Password-free authentication for mobile apps

• Quick login for returning users

• Enhanced security for sensitive applications

• Corporate SSO integration

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

methodall ofOptional

Method to send message

• email - email
• sms - sms

Default: email

string · enumOptional

• email - email
• sms - sms

Possible values:

verification_typeall ofOptional

OTP or Link

• otp - otp
• link - link

Default: otp

string · enumOptional

• otp - otp
• link - link

Possible values:

identifierstring · min: 1 · max: 100Required

Email or Phone number

Responses

200

Login OTP/link sent successfully

application/json

400

Invalid identifier or user not found

application/json

429

Rate limit exceeded

application/json

500

Internal server error

application/json

post

/v1/auth/login/passwordless/

HTTPcURLJavaScriptPython

POST /v1/auth/login/passwordless/ HTTP/1.1
Host: localhost:8000
Content-Type: application/json
Accept: */*
Content-Length: 76

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

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

Email OTP LoginPhone SMS Login

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

Confirm Passwordless Login

post

Complete passwordless login by verifying OTP or link

Process:

1. User provides identifier and verification code

2. System validates OTP/link

3. Authenticates user and returns JWT tokens

4. User can now access protected resources

Security:

• OTP validation with expiration check

• One-time use verification codes

• Rate limiting on verification attempts

Use Cases:

• Completing passwordless login flow

• Two-factor authentication verification

• Temporary access code validation

• Guest user authentication

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

identifierstring · min: 1 · max: 100Required

Email or Phone number

codestring · min: 1Required

Verification code received

Responses

200

Login successful

application/json

400

Invalid verification code

application/json

500

Internal server error

application/json

post

/v1/auth/login/passwordless/confirm/

HTTPcURLJavaScriptPython

POST /v1/auth/login/passwordless/confirm/ HTTP/1.1
Host: localhost:8000
Content-Type: application/json
Accept: */*
Content-Length: 49

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

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

Email OTP ConfirmationPhone OTP Confirmation

{
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 123,
    "email": "[email protected]",
    "is_verified": true
  }
}

Ethereum Wallet Authentication

post

Authenticate user using Ethereum wallet signature verification

Process:

1. User provides wallet address, message, and signature

2. System verifies signature using Ethereum cryptography

3. Creates or retrieves user account

4. Returns JWT access and refresh tokens

Security Features:

• Cryptographic signature verification

• Nonce-based replay protection

• Wallet address validation

• Automatic user creation for new wallets

Message Format: The message to sign follows this format: Welcome to BlockAuth!

Please sign this message to authenticate with your wallet.

Wallet Address: {wallet_address} Nonce: {nonce} Timestamp: {timestamp}

This signature will be used to authenticate your account.

Prerequisites:

• Valid Ethereum wallet address

• Properly signed message with correct format

• Valid signature that matches the wallet address

Use Cases:

• DeFi application user authentication

• NFT marketplace user access

• Web3 gaming platform login

• Decentralized application (dApp) login

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

wallet_addressstring · min: 1 · max: 42Required

Ethereum wallet address (0x...)

messagestring · min: 1Required

Message that was signed by the wallet user.

signaturestring · min: 1 · max: 132Required

Ethereum signature (0x-prefixed, 130 hex chars, e.g. 0x1234...)

Responses

200

Wallet authentication successful

application/json

400

Invalid wallet data or signature

application/json

401

Authentication failed

application/json

500

Internal server error

application/json

post

/v1/auth/login/wallet/

HTTPcURLJavaScriptPython

POST /v1/auth/login/wallet/ HTTP/1.1
Host: localhost:8000
Content-Type: application/json
Accept: */*
Content-Length: 471

{
  "wallet_address": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  "message": "Welcome to BlockAuth!\n\nPlease sign this message to authenticate with your wallet.\n\nWallet Address: 0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6\nNonce: 1234567890\nTimestamp: 1640995200\n\nThis signature will be used to authenticate your account.",
  "signature": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b"
}

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

New Wallet UserExisting Wallet User

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

Get Current User Profile

get

Retrieve the complete profile information for the currently authenticated user. This endpoint requires a valid JWT access token in the Authorization header.

Authentication: Required (Bearer token)

Profile Information:

• Basic user details (ID, email, name)

• Account status (verification, online status)

• Profile data (birth date, bio)

• Authentication methods used

• Account creation and last login timestamps

Use Cases:

• Display user profile in frontend applications

• Verify user authentication status

• Retrieve user preferences and settings

• Check account verification status

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200Success

application/json

get

/v1/auth/me/

HTTPcURLJavaScriptPython

GET /v1/auth/me/ HTTP/1.1
Host: localhost:8000
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200Success

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "email": "[email protected]",
  "first_name": "text",
  "last_name": "text",
  "date_joined": "2026-02-05T11:39:48.673Z",
  "is_online": true,
  "date_of_birth": "2026-02-05",
  "bio": "text",
  "authentication_type": "text",
  "is_verified": true,
  "wallet_address": "text"
}

Change Password

post

Change password for authenticated user.

Process:

1. User provides old password, new password, and confirmation

2. System validates old password and password confirmation

3. Updates to new password

4. Invalidates all existing sessions

Security:

• Requires old password verification

• Password strength validation

• Password confirmation matching

• Session invalidation for security

• Rate limiting on attempts

Authentication Required:

• Valid JWT access token in Authorization header

Use Cases:

• Proactive password security updates

• Regular password rotation compliance

• Account security enhancement

• Password policy enforcement

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

old_passwordstring · min: 1Write-onlyRequired

Your password can’t be too similar to your other personal information.

Your password must contain at least 8 characters.

Your password can’t be a commonly used password.

Your password can’t be entirely numeric.

new_passwordstring · min: 1Write-onlyRequired

Your password can’t be too similar to your other personal information.

Your password must contain at least 8 characters.

Your password can’t be a commonly used password.

Your password can’t be entirely numeric.

confirm_passwordstring · min: 1Write-onlyRequired

Your password can’t be too similar to your other personal information.

Your password must contain at least 8 characters.

Your password can’t be a commonly used password.

Your password can’t be entirely numeric.

Responses

200

Password changed successfully

application/json

400

Invalid current password or weak new password

application/json

401

Authentication required

application/json

429

Rate limit exceeded

application/json

500

Internal server error

application/json

post

/v1/auth/password/change/

HTTPcURLJavaScriptPython

POST /v1/auth/password/change/ HTTP/1.1
Host: localhost:8000
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 113

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

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

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

Request Password Reset

post

Initiate password reset process by sending OTP or reset link

Process:

1. User provides email/phone number

2. System validates user exists

3. Sends OTP or reset link

4. User completes reset via separate endpoint

Security:

• Rate limiting prevents abuse

• No indication if user exists (security through obscurity)

• Time-limited reset tokens

Use Cases:

• User forgot password

• Account compromise recovery

• Password expiration notification

• Security policy enforcement

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

methodall ofOptional

Method to send message

• email - email
• sms - sms

Default: email

string · enumOptional

• email - email
• sms - sms

Possible values:

verification_typeall ofOptional

OTP or Link

• otp - otp
• link - link

Default: otp

string · enumOptional

• otp - otp
• link - link

Possible values:

identifierstring · min: 1 · max: 100Required

Email or Phone number

Responses

200

Password reset initiated successfully

application/json

400

Invalid identifier

application/json

429

Rate limit exceeded

application/json

500

Internal server error

application/json

post

/v1/auth/password/reset/

HTTPcURLJavaScriptPython

POST /v1/auth/password/reset/ HTTP/1.1
Host: localhost:8000
Content-Type: application/json
Accept: */*
Content-Length: 76

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

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

{
  "message": "Password reset OTP sent via email."
}

Confirm Password Reset

post

Complete password reset by providing verification code, new password, and confirmation.

Process:

1. User provides identifier, verification code, new password, and confirmation

2. System validates code, password, and confirmation matching

3. Updates user password

4. Invalidates all existing sessions

Security:

• Password strength validation

• Password confirmation matching

• Code expiration check

• Session invalidation for security

Use Cases:

• Completing forgotten password recovery

• Account security restoration

• Compromised account recovery

• Password policy compliance

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

identifierstring · min: 1 · max: 100Required

Email or Phone number

codestring · min: 1Required

Verification code received

new_passwordstring · min: 1Write-onlyRequired

Your password can’t be too similar to your other personal information.

Your password must contain at least 8 characters.

Your password can’t be a commonly used password.

Your password can’t be entirely numeric.

confirm_passwordstring · min: 1Write-onlyRequired

Your password can’t be too similar to your other personal information.

Your password must contain at least 8 characters.

Your password can’t be a commonly used password.

Your password can’t be entirely numeric.

Responses

200

Password reset successful

application/json

400

Invalid code or weak password

application/json

500

Internal server error

application/json

post

/v1/auth/password/reset/confirm/

HTTPcURLJavaScriptPython

POST /v1/auth/password/reset/confirm/ HTTP/1.1
Host: localhost:8000
Content-Type: application/json
Accept: */*
Content-Length: 129

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

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

{
  "message": "Password reset successful."
}

User Registration

post

Create a new user account with email/phone verification (Basic Signup).

Process:

1. User provides email/phone and password

2. System validates input data

3. Creates user account (unverified)

4. Sends OTP or verification link

5. User completes verification via separate endpoint

Verification Methods:

• OTP: Time-based one-time password sent via email/SMS

• Link: Verification link sent via email

Security:

• Password is hashed using Django's secure hashing

• Rate limiting applied to prevent abuse

• Email/phone validation before account creation

Prerequisites:

• Valid email address or phone number

• Strong password (minimum 8 characters)

• Unique identifier (email/phone not already registered)

Use Cases:

• New user registration for web/mobile applications

• Account creation for e-commerce platforms

• User onboarding for SaaS applications

• Community platform member registration

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

methodall ofOptional

Method to send message

• email - email
• sms - sms

Default: email

string · enumOptional

• email - email
• sms - sms

Possible values:

verification_typeall ofOptional

OTP or Link

• otp - otp
• link - link

Default: otp

string · enumOptional

• otp - otp
• link - link

Possible values:

identifierstring · min: 1 · max: 100Required

Email or Phone number

passwordstring · min: 1Write-onlyRequired

Your password can’t be too similar to your other personal information.

Your password must contain at least 8 characters.

Your password can’t be a commonly used password.

Your password can’t be entirely numeric.

Responses

200

Registration initiated successfully

application/json

400

Validation error - Invalid input data

application/json

429

Rate limit exceeded

application/json

500

Internal server error

application/json

post

/v1/auth/signup/

HTTPcURLJavaScriptPython

POST /v1/auth/signup/ HTTP/1.1
Host: localhost:8000
Content-Type: application/json
Accept: */*
Content-Length: 109

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

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

Email Registration (OTP)Email Registration (Link)Phone Registration (SMS)

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

Confirm User Registration

post

Verify OTP or click verification link to complete user registration

Process:

1. User provides identifier and verification code

2. System validates OTP/link

3. Marks user as verified

4. User can now login to the system

Verification Types:

• OTP: Numeric code sent via email/SMS

• Link: URL-based verification (handled separately)

Security:

• OTP has expiration time

• One-time use only

• Rate limiting on attempts

• CSRF protection for link verification

Use Cases:

• Completing email verification after signup

• Phone number verification for SMS-based auth

• Account activation after registration

• Two-factor authentication setup

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

identifierstring · min: 1 · max: 100Required

Email or Phone number

codestring · min: 1Required

Verification code received

Responses

200

Registration confirmed successfully

application/json

400

Invalid verification code

application/json

500

Internal server error

application/json

post

/v1/auth/signup/confirm/

HTTPcURLJavaScriptPython

POST /v1/auth/signup/confirm/ HTTP/1.1
Host: localhost:8000
Content-Type: application/json
Accept: */*
Content-Length: 49

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

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

Email OTP ConfirmationPhone OTP Confirmation

{
  "message": "Email verified successfully."
}

Resend Verification OTP/Link

post

Resend OTP or verification link for signup confirmation or wallet email verification.

Use Cases:

• User didn't receive initial verification

• OTP expired and needs renewal

• Wallet user adding email verification

Rate Limiting:

• Prevents abuse and spam

• Configurable wait time between requests

• Different limits for signup vs wallet verification

Security:

• Rate limiting prevents brute force attacks

• Validates identifier format before sending

• Logs all attempts for monitoring

Use Cases:

• User didn't receive initial verification email/SMS

• OTP expired and needs renewal

• Wallet user adding email verification

• Account recovery for unverified users

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

methodall ofOptional

Method to send message

• email - email
• sms - sms

Default: email

string · enumOptional

• email - email
• sms - sms

Possible values:

verification_typeall ofOptional

OTP or Link

• otp - otp
• link - link

Default: otp

string · enumOptional

• otp - otp
• link - link

Possible values:

identifierstring · min: 1 · max: 100Required

Email or Phone number

Responses

200

Verification OTP/link sent successfully

application/json

400

Validation error

application/json

429

Rate limit exceeded

application/json

500

Internal server error

application/json

post

/v1/auth/signup/otp/resend/

HTTPcURLJavaScriptPython

POST /v1/auth/signup/otp/resend/ HTTP/1.1
Host: localhost:8000
Content-Type: application/json
Accept: */*
Content-Length: 76

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

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

Signup Verification (OTP)Wallet Email Verification

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

Refresh Access Token

post

Get a new access token using a valid refresh token

Process:

1. User provides valid refresh token

2. System validates refresh token

3. Returns new access and refresh tokens

4. Old refresh token becomes invalid

Security:

• Refresh tokens have longer expiration

• Token rotation for enhanced security

• Automatic invalidation of old tokens

Use Cases:

• Access token expired during active session

• Regular token rotation for security

• Session renewal for long-running applications

• Mobile app background token refresh

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

refreshstring · min: 1Required

Refresh token to get new access token

Responses

200

Token refreshed successfully

application/json

400

Invalid refresh token

application/json

401

Token expired or invalid

application/json

500

Internal server error

application/json

post

/v1/auth/token/refresh/

HTTPcURLJavaScriptPython

POST /v1/auth/token/refresh/ HTTP/1.1
Host: localhost:8000
Content-Type: application/json
Accept: */*
Content-Length: 53

{
  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

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

Add Email to Wallet Account

post

Add an email address to a wallet-based user account and send verification

Process:

1. User provides email address

2. System validates email format

3. Updates user account with email

4. Sends verification OTP/link to email

5. User completes verification via separate endpoint

Benefits:

• Enhanced account recovery options

• Email notifications and updates

• Additional verification layer

• Better user experience

Security:

• Email format validation

• Rate limiting on requests

• Verification required before email is active

• Authentication required

Authentication Required:

• Valid JWT access token in Authorization header

Use Cases:

• Wallet user account enhancement

• Account recovery setup for wallet users

• Email notification preferences

• Multi-factor authentication setup

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

emailstring · email · min: 1Required

Email address to add and verify

verification_typeall ofOptional

Type of verification to send (OTP or link)

• otp - otp
• link - link

Default: otp

string · enumOptional

• otp - otp
• link - link

Possible values:

Responses

200

Email added and verification sent successfully

application/json

400

Invalid email or validation error

application/json

401

Authentication required

application/json

429

Rate limit exceeded

application/json

500

Internal server error

application/json

post

/v1/auth/wallet/email/add/

HTTPcURLJavaScriptPython

POST /v1/auth/wallet/email/add/ HTTP/1.1
Host: localhost:8000
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 54

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

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

Add Email with OTPAdd Email with Link

{
  "message": "Email added successfully. otp sent via email."
}