Signup & Login¶

BlockAuth provides three authentication methods: email/password, passwordless OTP, and Web3 wallet. All are controlled by feature flags.

The signup flow uses a two-step OTP verification:

User submits email and password
BlockAuth sends an OTP via the configured notification class
User confirms with the OTP

Step 1: Register¶

POST /auth/signup/

{
  "email": "user@example.com",
  "password": "SecurePass123!"
}

The password is validated against Django's password validators. BlockAuth includes BlockAuthPasswordValidator for additional strength checks.

Step 2: Confirm OTP¶

POST /auth/signup/confirm/

{
  "email": "user@example.com",
  "otp": "123456"
}

Returns JWT tokens on success:

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

Resend OTP¶

If the OTP expires (default: 1 minute), request a new one:

POST /auth/signup/otp/resend/

{
  "email": "user@example.com"
}

Note

OTP resend is rate-limited. See Settings for REQUEST_LIMIT configuration.

Email and password authentication:

POST /auth/login/basic/

{
  "email": "user@example.com",
  "password": "SecurePass123!"
}

Returns:

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

OTP-based login without a password. Requires the PASSWORDLESS_LOGIN feature flag.

Step 1: Request OTP¶

POST /auth/login/passwordless/

{
  "email": "user@example.com"
}

Step 2: Confirm¶

POST /auth/login/passwordless/confirm/

{
  "email": "user@example.com",
  "otp": "123456"
}

Password Management¶

Reset Password¶

For users who forgot their password:

# Step 1: Request reset OTP
POST /auth/password/reset/

{
  "email": "user@example.com"
}

# Step 2: Set new password
POST /auth/password/reset/confirm/

{
  "email": "user@example.com",
  "otp": "123456",
  "new_password": "NewSecurePass456!"
}

Change Password¶

For authenticated users:

POST /auth/password/change/
Authorization: Bearer <access_token>

{
  "old_password": "SecurePass123!",
  "new_password": "NewSecurePass456!"
}

Email Change¶

Two-step OTP verification for email changes:

# Step 1: Request change
POST /auth/email/change/
Authorization: Bearer <access_token>

{
  "new_email": "newemail@example.com"
}

# Step 2: Confirm
POST /auth/email/change/confirm/

{
  "email": "newemail@example.com",
  "otp": "123456"
}

Token Refresh¶

Exchange a refresh token for new access and refresh tokens:

POST /auth/token/refresh/

{
  "refresh": "eyJ..."
}

When ROTATE_REFRESH_TOKENS is enabled (default), the old refresh token is blacklisted and a new pair is issued.

See JWT Tokens for token structure and custom claims.