API Documentation

Backend implementation overview for frontend integration. Base URL for all requests: <API_BASE_URL(https://gritagencies.top/bodybyarwa)>/auth. For frontend migration, see Updated Endpoints.

Authentication

Auth API

All auth endpoints are under the /auth prefix. Use JSON request bodies and Content-Type: application/json. Protected routes require the header Authorization: Bearer <access_token>.

Endpoints

POST /auth/register

Customer registration only. Body: email, password, first_name, last_name. Returns access_token, refresh_token. Rate limit: 10/min.

POST /auth/login

Login with email or phone (customers only for phone, and only if phone_verified) plus password. Returns access_token, refresh_token. Rate limit: 5/min.

POST /auth/refresh

Send Authorization: Bearer <refresh_token>. Returns new access_token and refresh_token. Refresh token rotation: previous refresh token is invalidated.

POST /auth/logout

Requires access token. Revokes the current access token.

POST /auth/verify-email

Body: token (from verification email link). Marks user as email-verified. Rate limit: 10/min.

POST /auth/send-verification-email

Requires access token. Creates and sends verification email. Returns 204. Rate limit: 3/min.

POST /auth/send-phone-code

Requires access token. Body: optional phone. Sends OTP via SMS. Returns 204. Rate limit: 3/min.

POST /auth/verify-phone

Requires access token. Body: code (OTP). Marks user as phone-verified. Rate limit: 10/min.

POST /auth/forgot-password

Body: email or phone. Sends password reset email if account exists. Always returns same message (no user enumeration). Rate limit: 3/min.

POST /auth/reset-password

Body: token (from reset email), new_password. Invalidates token and all existing sessions for the user. Rate limit: 5/min.

Token usage

Access token is a JWT. Include in header: Authorization: Bearer <access_token>. Token payload includes sub (user UUID), role, token_version. User and profile IDs are UUIDs (hard to guess). Do not store tokens in localStorage if XSS is a concern; consider httpOnly cookies or secure storage.

For viewing and updating the current user profile, see Profile API. For listing and viewing users (customers, staff, admins) and search, see Users API. For dashboard counts, see Metrics API.

RBAC (roles and permissions)

Some routes require a specific role (e.g. admin, staff) or permission. If the user is authenticated but lacks the required role or permission, the API returns 403 Forbidden with a body such as {"error": "Insufficient role", "required_roles": ["admin"]} or {"error": "Insufficient permission", "required_permissions": ["manage_users"]}. Frontend should treat 403 as “not allowed” and hide or disable the corresponding UI.

Other APIs

Users API (/users): list customers, staff, admins; view a specific user by ID. Search (/search): GET /search/customers?q=... for customer search (admin or staff with view_customers).

Metrics API (/metrics): dashboard counts — GET /metrics/admin-dashboard (user totals, product/inventory counts, inventory revenue), GET /metrics/staff-dashboard (customer totals), GET /metrics/inventory (product inventory metrics, manage_inventory).

RBAC API (/rbac): manage roles and permissions (admin only). List, create, edit roles and permissions; assign roles to users (e.g. staff), permissions to roles.

Departments API (/departments): manage departments (admin only). List, create, update, disable, delete. Staff are linked to departments via department_id.

Products API (/products): categories, brands, products, images, inventory, pricing. Public: list products, product detail, categories, brands, stock status, pricing. manage_products for create/update/delete. manage_inventory for create inventory, restock, logs. SKU and slugs auto-generated when not provided.

Inventory API (/inventory): low-stock, out-of-stock, needs-reorder reports. Requires manage_inventory. Product-scoped inventory (create, status, restock, logs) are in Products API.

Currencies API (/currencies): manage currencies and exchange rates. List, default, and convert are public. admin for create, update, set default.

Taxes API (/taxes): manage tax rates (VAT, sales tax). admin for create and set default. view_products for list, get default, get by country.

Payment Methods API (/admin/payment-methods): manage M-Pesa, Pesapal, Cash on Delivery. admin only. Configure environment (sandbox/production), enable/disable, update settings.

Billing & Payments API (/admin/invoices, /admin/transactions, /payments/*, /callbacks/*): invoice management, COD verification/collection, customer checkout payment flows, gateway status checks, webhook handling, and development test routes.

Data

Models (summary)

Single users table; RBAC via roles and permissions; profile tables extend identity (one-to-one with user).

User

id (UUID, not guessable), email (unique), password_hash, first_name, last_name, phone (unique), is_active, is_verified (email), phone_verified, token_version, created_at, updated_at. Roles: many-to-many with roles.

Profiles

CustomerProfile: user_id, recipient_name, recipient_phone, address fields, country. Customers can complete these after registration.

StaffProfile: id (UUID), user_id (UUID), employee_id (auto-generated, format BBA+YY+DD+seq), department_id (FK to Department), job_title, hired_at. CustomerProfile and AdminProfile: id (UUID), user_id (UUID). Department: id, name, description, is_active, created_at.

AdminProfile: user_id, created_at.

Roles

At least customer (used for registration). staff and admin for internal users. Permissions are many-to-many with roles.

Integration

Suggested frontend flows

Register: POST /auth/register with email, password, first_name, last_name → store access_token and refresh_token; optionally redirect to verify-email (link from email).
Login: POST /auth/login with email (or phone for customers with phone_verified) + password → store tokens; use access_token for API calls.
Refresh: When access token expires (401), POST /auth/refresh with refresh_token in Authorization header → replace stored tokens with new pair.
Verify email: User opens link from email (e.g. APP_BASE_URL/verify-email?token=…). Frontend reads token from query and POSTs to /auth/verify-email with body { "token": "…" }.
Reset password: User requests reset → backend sends email. User opens link (e.g. APP_BASE_URL/reset-password?token=…). Frontend shows form, reads token from query, POSTs /auth/reset-password with token and new_password.