Auth & Profile API

Create a new customer account. Sends a verification email.

Request Body

{
  "name": "Jane Doe",        // string, required
  "email": "jane@email.com", // string, required, unique
  "password": "Secure@123",  // string, required, min 8 chars
  "phone": "0712345678"      // string, optional
}

Response

{
  "success": true,
  "data": {
    "user": { "id": "uuid", "name": "Jane Doe", "email": "jane@email.com", "phone": "0712345678", "email_verified": false },
    "access_token": "eyJ..."
  },
  "message": "Check your email to verify your account."
}

Possible Errors

Authenticate. Returns access token and sets HTTP-only refresh cookie. If OTP enabled, returns otp_token instead.

Request Body

{
  "email": "jane@email.com", // required
  "password": "Secure@123"   // required
}

Response

// Without OTP:
{ "success": true, "data": { "requires_otp": false, "access_token": "eyJ...", "user": { "id", "name", "email", "role": null } } }

// With OTP enabled:
{ "success": true, "data": { "requires_otp": true, "otp_token": "eyJ..." } }

Possible Errors

Exchange OTP token + 6-digit code for a full access token (2FA login step 2).

Request Body

{
  "otp_token": "eyJ...", // from login response when requires_otp: true
  "code": "123456"       // 6-digit TOTP code from authenticator app
}

Response

{ "success": true, "data": { "access_token": "eyJ...", "user": { ... } } }

Possible Errors

Clear the HTTP-only refresh token cookie.

Response

{ "success": true, "message": "Logged out successfully." }

Get a new access token using the refresh cookie.

Response

{ "success": true, "data": { "access_token": "eyJ..." } }

Possible Errors

Get the current authenticated user profile.

Response

{ "success": true, "data": { "id": "uuid", "name": "Jane", "email": "...", "phone": "...", "avatar_url": null, "email_verified": true, "otp_enabled": false, "role": null, "preferences": {} } }

Update name, phone, or avatar_url.

Request Body

{ "name": "Jane Smith", "phone": "0700000000", "avatar_url": "https://..." }

Response

{ "success": true, "data": { "id", "name", "email", "phone", "avatar_url" } }

Change password. Requires current password for verification.

Request Body

{ "current_password": "OldPass@1", "new_password": "NewPass@2" }

Response

{ "success": true, "message": "Password updated successfully." }

Possible Errors

Send a password reset link to the given email. Always returns success to prevent enumeration.

Request Body

{ "email": "jane@email.com" }

Response

{ "success": true, "message": "If that email exists, a password reset link has been sent." }

Reset password using the token from the email link.

Request Body

{ "token": "hex-token", "email": "jane@email.com", "new_password": "NewPass@2" }

Response

{ "success": true, "message": "Password reset successfully. Please log in." }

Possible Errors

Generate a TOTP secret and QR code URL. Save the secret in your authenticator app.

Response

{ "success": true, "data": { "secret": "BASE32SECRET", "qr_code_url": "otpauth://totp/ALOPAY:jane@email.com?secret=...&issuer=ALOPAY" } }

Confirm OTP setup by submitting the first 6-digit code. Enables 2FA on account.

Request Body

{ "code": "123456" }

Response

{ "success": true, "message": "Two-factor authentication is now enabled." }

Possible Errors

Disable 2FA. Requires password confirmation.

Request Body

{ "password": "Secure@123" }

Response

{ "success": true, "message": "Two-factor authentication disabled." }

Possible Errors

List all saved addresses for the current user.

Response

{ "success": true, "data": { "addresses": [ { "id", "label", "recipient_name", "phone", "street", "county", "town", "is_default" } ] } }

Add a new delivery address.

Request Body

{
  "label": "Home",                              // required
  "recipient_name": "Jane Doe",                 // required
  "phone": "0712345678",                        // required
  "street": "Kimathi Street",                   // required
  "county": "nairobi",                          // required — must be valid Kenya county
  "town": "Nairobi CBD",                        // optional
  "landmark": "Next to KFC",                    // optional
  "coordinates": { "lat": -1.286, "lng": 36.817 }, // optional
  "is_default": true                            // optional
}

Response

{ "success": true, "data": { "address": { "id", "label", ... } } }

Update a saved address. Same fields as POST.

Response

{ "success": true, "data": { "address": { ... } } }

Delete a saved address.

Response

{ "success": true, "data": null }

Set this address as the default. Clears default from all other addresses.

Response

{ "success": true, "data": { "address": { "id", "is_default": true } } }