User & Authentication API

Catalog: /apis/user-api

Manages buyer and seller registration, login sessions, address books, profile details, and JWT validation. Buyers log in using passive OTP SMS codes, while sellers register with validated email addresses. The gateway handles token checking for protected resources.

Endpoints Reference

Complete list of GraphQL mutations, queries, gRPC procedures, and HTTP routes for this module.

GraphQL Mutation

buyerSendOTP(phone: String!)

Triggers a 6-digit verification code to the buyer's phone number. Bypassed in local development using master code 123456.

🔓 Public Access

Request Syntax / Parameters

mutation { buyerSendOTP(phone: "+263773333333") { message requestId } }

Expected JSON Response

{ "data": { "buyerSendOTP": { "message": "OTP sent successfully", "requestId": "mock-request-id-123456" } } }

GraphQL Mutation

buyerVerifyOTP(phone: String!, otp: String!)

Submits OTP code to authenticate. Performs an upsert: creates the user profile automatically if it does not exist, and returns JWT access/refresh tokens.

🔓 Public Access

Request Syntax / Parameters

mutation { buyerVerifyOTP(phone: "+263773333333", otp: "123456") { accessToken refreshToken user { id fullName role } } }

Expected JSON Response

{
  "data": {
    "buyerVerifyOTP": {
      "accessToken": "eyJhbGciOiJIUzI1NiIsInR5c...",
      "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5...",
      "user": {
        "id": "0099d266-98c4-4281-92c2-ec2895b1fd4c",
        "fullName": "Tendai Moyo",
        "role": "BUYER"
      }
    }
  }
}

GraphQL Mutation

sellerRegister(email: String!, password: String!, fullName: String!)

Registers a new seller profile with email verification workflow.

🔓 Public Access

Request Syntax / Parameters

mutation { sellerRegister(email: "seller@example.com", password: "Password123!", fullName: "Tatenda Store") { accessToken user { id role } } }

Expected JSON Response

{ "data": { "sellerRegister": { "accessToken": "eyJhbG...", "user": { "id": "b50d0370-4809-41a1-a48c-ea3db4805a0c", "role": "SELLER" } } } }

GraphQL Query

me

Retrieves the active user session metadata based on the Authorization Bearer token.

🔒 JWT Auth BUYER SELLER ADMIN

Request Syntax / Parameters

query { me { id email phone fullName role isVerified } }

Expected JSON Response

{ "data": { "me": { "id": "0099d266-98c4-4281-92c2", "fullName": "Tendai Moyo", "role": "BUYER", "isVerified": true } } }

gRPC

UserService.ValidateToken(ValidateTokenRequest)

Internal RPC called by API Gateway to check JWT signatures, verify expiration, and resolve role authorization lists.

🔓 Public Access

Request Syntax / Parameters

message ValidateTokenRequest { string token = 1; }

Expected JSON Response

message ValidateTokenResponse { string user_id = 1; UserRole role = 2; bool valid = 3; }

Database Tables & Data Models

Relational database schemas and custom payload models governing this service domain.

📂 users (PostgreSQL)

Holds profiles for buyers, sellers, and system administrators.

Field Name	Data Type	Description / Constraint
id	UUID (Primary Key)	Unique system user identifier.
email	VARCHAR(255)	Unique user email address (nullable for buyers).
phone	VARCHAR(50)	Unique mobile phone number (nullable for email-registered sellers).
password_hash	VARCHAR(255)	Bcrypt hash of user password (empty for phone-only logins).
role	VARCHAR(20)	User system capability: 'buyer' \| 'seller' \| 'admin'.
is_verified	BOOLEAN	Indicates whether OTP verification or email confirmation is completed.

📂 addresses (PostgreSQL)

User delivery and billing address book entries.

Field Name	Data Type	Description / Constraint
id	UUID (Primary Key)	Unique address identifier.
user_id	UUID	Foreign key reference to users table.
full_name	VARCHAR(255)	Recipient name for shipping label.
address_line1	TEXT	Street name and number details.
city	VARCHAR(100)	Shipping city.
country	VARCHAR(5)	2-letter ISO country code (e.g. 'ZW').
is_default	BOOLEAN	Marks standard address used for checkout defaults.