{ "consumes": [ "application/json" ], "produces": [ "application/json" ], "swagger": "2.0", "info": { "description": "Authentication and service management API for CheChe platform", "title": "CheChe Auth API", "termsOfService": "http://swagger.io/terms/", "contact": { "name": "CheChe Tech", "url": "https://cheche.et", "email": "support@cheche.et" }, "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" }, "version": "1.0.0" }, "host": "localhost:5003", "basePath": "/v1", "paths": { "/auth/auto-login": { "post": { "description": "Automatic login for existing users without credentials", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Common / OTP / Tokens" ], "summary": "Auto-login", "parameters": [ { "type": "string", "format": "uuid", "description": "Optional service ID to register user for", "name": "service_id", "in": "query" }, { "description": "Auto-login request with mobile and firstname", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UserAutoLoginInput" } } ], "responses": { "200": { "description": "Auto-login successful with access_token and refresh_token", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid input or validation error", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "User not found", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/auth/logout": { "post": { "description": "Revoke the presented access token immediately, and optionally revoke a refresh token too.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Common / Tokens" ], "summary": "Logout", "parameters": [ { "description": "Optional refresh token to revoke", "name": "request", "in": "body", "schema": { "$ref": "#/definitions/dto.UserLogoutInput" } } ], "responses": { "200": { "description": "Logout successful", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid input", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Invalid refresh token", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "Invalid token type", "schema": { "type": "object", "additionalProperties": true } } } } }, "/auth/otp-login": { "post": { "description": "Verify OTP and return access and refresh tokens for authentication", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Common / OTP / Tokens" ], "summary": "OTP login", "parameters": [ { "description": "OTP login request with mobile and OTP code", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UserVerifyOTPInput" } } ], "responses": { "200": { "description": "OTP login successful with access_token and refresh_token", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid input or invalid/expired OTP", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "User not found", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/auth/password/update/{id}": { "put": { "security": [ { "BearerAuth": [] } ], "description": "Update user password with old password verification (owner protected)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Password Authentication" ], "summary": "Update user password", "parameters": [ { "type": "string", "format": "uuid", "description": "User ID", "name": "id", "in": "path", "required": true }, { "description": "Update password request with old and new password", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UserUpdatePasswordInput" } } ], "responses": { "200": { "description": "Password updated successfully", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid input or new password same as old", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Old password is incorrect or unauthorized", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "User not found", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/auth/refresh": { "post": { "description": "Get new access and refresh tokens using a valid refresh token", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Common / OTP / Tokens" ], "summary": "Refresh access token", "parameters": [ { "description": "Refresh token request", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UserRefreshTokenInput" } } ], "responses": { "200": { "description": "Tokens refreshed successfully with new access_token and refresh_token", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid input", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Invalid or expired refresh token", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "Invalid token type", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/auth/sessions": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns active sessions for the authenticated user", "produces": [ "application/json" ], "tags": [ "Device Sessions" ], "summary": "List active device sessions", "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": true } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Revoke sessions for the authenticated user. Query scope=others (default) or scope=all.", "produces": [ "application/json" ], "tags": [ "Device Sessions" ], "summary": "Revoke device sessions in bulk", "parameters": [ { "type": "string", "description": "others (default) or all", "name": "scope", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": true } } } } }, "/auth/sessions/{id}": { "delete": { "security": [ { "BearerAuth": [] } ], "description": "Revokes a single session owned by the authenticated user", "produces": [ "application/json" ], "tags": [ "Device Sessions" ], "summary": "Revoke one device session", "parameters": [ { "type": "string", "format": "uuid", "description": "Session ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": true } } } } }, "/users": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get paginated list of users (JWT protected)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "User Management" ], "summary": "List users", "parameters": [ { "type": "string", "format": "uuid", "description": "Filter users by service ID", "name": "service_id", "in": "query" }, { "type": "integer", "description": "Page number (default: 1)", "name": "page", "in": "query" }, { "type": "integer", "description": "Items per page (default: 10, max: 100)", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "Users retrieved successfully with users array and count", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid input", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/users/check-status": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Check if a mobile number belongs to an existing user or is new (API Key protected).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "User Management" ], "summary": "Check user existence status", "parameters": [ { "type": "string", "description": "API Key", "name": "X-API-Key", "in": "header", "required": true }, { "type": "string", "description": "Mobile number", "name": "mobile", "in": "query", "required": true } ], "responses": { "200": { "description": "Status returned", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid input", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/users/create-verified": { "post": { "description": "Create a user with verified status (admin function, no OTP required)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "User Management" ], "summary": "Create verified user", "parameters": [ { "type": "string", "format": "uuid", "description": "Optional service ID to associate with user", "name": "service_id", "in": "query" }, { "description": "Create verified user request", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.CreateVerifiedUserInput" } } ], "responses": { "201": { "description": "Verified user created successfully", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid input or validation error", "schema": { "type": "object", "additionalProperties": true } }, "409": { "description": "User already exists", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/users/get-user-by-mobile": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retrieve user details by mobile number (JWT required). Optionally check service registration.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "User Management" ], "summary": "Get user by mobile", "parameters": [ { "type": "string", "description": "Mobile number in E.164 format (+251XXXXXXXXX)", "name": "mobile", "in": "query", "required": true }, { "type": "string", "format": "uuid", "description": "Optional service ID to check registration", "name": "service_id", "in": "query" } ], "responses": { "200": { "description": "User retrieved successfully", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid input or mobile format", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "User not found", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/users/get-user-by-mobile-api-key": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieve user details by mobile number using API Key authentication. Optionally check service registration.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "User Management" ], "summary": "Get user by mobile (API Key)", "parameters": [ { "type": "string", "description": "API Key", "name": "X-API-Key", "in": "header", "required": true }, { "type": "string", "description": "Mobile number in E.164 format (+251XXXXXXXXX)", "name": "mobile", "in": "query", "required": true }, { "type": "string", "format": "uuid", "description": "Optional service ID to check registration", "name": "service_id", "in": "query" } ], "responses": { "200": { "description": "User retrieved successfully", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid input or mobile format", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "User not found", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/users/list-specific-users-api-key": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieve a list of user details by user IDs using API Key authentication. Same request/response as list specific users.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "User Management" ], "summary": "Get specific users by IDs (API Key)", "parameters": [ { "type": "string", "description": "API Key", "name": "X-API-Key", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Filter users by service ID", "name": "service_id", "in": "query" }, { "type": "integer", "description": "Page number (default: 1)", "name": "page", "in": "query" }, { "type": "integer", "description": "Items per page (default: 10, max: 100)", "name": "page_size", "in": "query" }, { "description": "List of user IDs to fetch", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UserSpecificUsersInput" } } ], "responses": { "200": { "description": "Users retrieved successfully", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid input or user ID format", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/users/reset-password": { "post": { "description": "Reset user password using OTP verification. OTP must be sent first via /users/send-otp endpoint.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Password Authentication" ], "summary": "Reset password with OTP", "parameters": [ { "description": "Reset password request with mobile, OTP, and new password", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UserResetPasswordInput" } } ], "responses": { "200": { "description": "Password reset successfully", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid input or invalid/expired OTP", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "User not found", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/users/reset-pin": { "post": { "description": "Reset user PIN using OTP verification. OTP must be sent first via /users/send-otp endpoint.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "PIN Authentication" ], "summary": "Reset PIN with OTP", "parameters": [ { "description": "Reset PIN request with mobile, OTP, and new PIN", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UserResetPinInput" } } ], "responses": { "200": { "description": "Password reset successfully", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid input or invalid/expired OTP", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "User not found", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/users/search": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Search users by first name, last name, or phone number (JWT protected)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "User Management" ], "summary": "Search users", "parameters": [ { "type": "string", "description": "Search query (matches first name, last name, or phone)", "name": "q", "in": "query", "required": true }, { "type": "string", "format": "uuid", "description": "Filter users by service ID", "name": "service_id", "in": "query" }, { "type": "integer", "description": "Page number (default: 1)", "name": "page", "in": "query" }, { "type": "integer", "description": "Items per page (default: 10, max: 100)", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "Users retrieved successfully with users array and pagination info", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid input", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/users/send-otp": { "post": { "description": "Send OTP to mobile number for verification. User must exist in the system.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Common / OTP / Tokens" ], "summary": "Send OTP", "parameters": [ { "description": "Send OTP request with mobile number", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UserSendOTPInput" } } ], "responses": { "200": { "description": "OTP sent successfully", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid input or mobile format", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "User not found", "schema": { "type": "object", "additionalProperties": true } }, "429": { "description": "Too many requests", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Failed to send OTP", "schema": { "type": "object", "additionalProperties": true } } } } }, "/users/signin": { "post": { "description": "Authenticate user with PIN and get access tokens. If account is unverified, OTP will be resent.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "PIN Authentication" ], "summary": "User sign in with PIN", "parameters": [ { "type": "string", "description": "Optional service ID to verify user registration", "name": "service_id", "in": "query" }, { "type": "boolean", "description": "Include service IDs in token (default: false)", "name": "include_services", "in": "query" }, { "description": "Signin request with mobile and PIN", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UserSigninPinInput" } } ], "responses": { "200": { "description": "Signin successful with access_token and refresh_token", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid input", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Invalid credentials", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "User not verified or not registered for service", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "User not found", "schema": { "type": "object", "additionalProperties": true } }, "429": { "description": "Account locked due to too many failed attempts", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/users/signin/email": { "post": { "description": "Authenticate user with email and password and get access tokens.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Password Authentication" ], "summary": "User sign in with email", "parameters": [ { "type": "string", "description": "Optional service ID to verify user registration", "name": "service_id", "in": "query" }, { "type": "boolean", "description": "Include service IDs in token (default: false)", "name": "include_services", "in": "query" }, { "description": "Signin request with email and password", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UserSigninEmailInput" } } ], "responses": { "200": { "description": "Signin successful with access_token and refresh_token", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid input", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Invalid credentials", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "User not verified or not registered for service", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "User not found", "schema": { "type": "object", "additionalProperties": true } }, "429": { "description": "Account locked due to too many failed attempts", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/users/signin/password": { "post": { "description": "Authenticate user with password and get access tokens. If account is unverified, OTP will be resent.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Password Authentication" ], "summary": "User sign in with password", "parameters": [ { "type": "string", "description": "Optional service ID to verify user registration", "name": "service_id", "in": "query" }, { "type": "boolean", "description": "Include service IDs in token (default: false)", "name": "include_services", "in": "query" }, { "description": "Signin request with mobile and password", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UserSigninPasswordInput" } } ], "responses": { "200": { "description": "Signin successful with access_token and refresh_token", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid input", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Invalid credentials", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "User not verified or not registered for service", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "User not found", "schema": { "type": "object", "additionalProperties": true } }, "429": { "description": "Account locked due to too many failed attempts", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/users/signin/pin-password": { "post": { "description": "Authenticate user with PIN or password (either one is sufficient). Returns access and refresh tokens plus the user's service IDs (also embedded in the JWT).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "PIN Authentication" ], "summary": "User sign in with PIN and/or password", "parameters": [ { "type": "string", "description": "Optional service ID to verify user registration", "name": "service_id", "in": "query" }, { "description": "Signin request with mobile and at least one of pin or password", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UserSigninPinPasswordInput" } } ], "responses": { "200": { "description": "Signin successful with access_token, refresh_token, and service_ids", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid input", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Invalid credentials", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "User not verified or not registered for service", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "User not found", "schema": { "type": "object", "additionalProperties": true } }, "429": { "description": "Account locked due to too many failed attempts", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/users/signup": { "post": { "description": "Register a new user account with PIN authentication. Account will be UNVERIFIED and OTP will be sent to mobile.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "PIN Authentication" ], "summary": "User registration with PIN", "parameters": [ { "type": "string", "format": "uuid", "description": "Optional service ID to associate with user", "name": "service_id", "in": "query" }, { "description": "Signup request with firstname, middlename, lastname, mobile, and PIN", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UserSignupPinInput" } } ], "responses": { "201": { "description": "User registered successfully", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid input or validation error", "schema": { "type": "object", "additionalProperties": true } }, "409": { "description": "User already exists", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/users/signup/password": { "post": { "description": "Register a new user account with password authentication. Account will be UNVERIFIED and OTP will be sent to mobile.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Password Authentication" ], "summary": "User registration with password", "parameters": [ { "type": "string", "format": "uuid", "description": "Optional service ID to associate with user", "name": "service_id", "in": "query" }, { "description": "Signup request with firstname, middlename, lastname, mobile, and password", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UserSignupPasswordInput" } } ], "responses": { "201": { "description": "User registered successfully", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid input or validation error", "schema": { "type": "object", "additionalProperties": true } }, "409": { "description": "User already exists", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/users/specific_users": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Get specific users by their IDs (bulk fetch, JWT protected)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "User Management" ], "summary": "Get specific users", "parameters": [ { "type": "string", "format": "uuid", "description": "Filter users by service ID", "name": "service_id", "in": "query" }, { "type": "integer", "description": "Page number (default: 1)", "name": "page", "in": "query" }, { "type": "integer", "description": "Items per page (default: 10, max: 100)", "name": "page_size", "in": "query" }, { "description": "List of user IDs to fetch", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UserSpecificUsersInput" } } ], "responses": { "200": { "description": "Users retrieved successfully", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid input or user ID format", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/users/update-api-key": { "put": { "security": [ { "ApiKeyAuth": [] } ], "description": "Update user profile fields and optional PIN using wallet API key authentication with user_id in query or body.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "User Management" ], "summary": "Update user by API key (wallet only, POST)", "parameters": [ { "type": "string", "description": "API Key", "name": "X-API-Key", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "User ID", "name": "user_id", "in": "query" }, { "description": "Wallet user update request", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.WalletUserUpdatePostInput" } } ], "responses": { "200": { "description": "User updated successfully", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid input", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "User not found", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": true } } } }, "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Update user profile fields and optional PIN using wallet API key authentication with user_id in query or body.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "User Management" ], "summary": "Update user by API key (wallet only, POST)", "parameters": [ { "type": "string", "description": "API Key", "name": "X-API-Key", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "User ID", "name": "user_id", "in": "query" }, { "description": "Wallet user update request", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.WalletUserUpdatePostInput" } } ], "responses": { "200": { "description": "User updated successfully", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid input", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "User not found", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/users/verify-otp": { "post": { "description": "Verify OTP code and activate user account. Changes status from UNVERIFIED to VERIFIED.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Common / OTP / Tokens" ], "summary": "Verify OTP", "parameters": [ { "description": "OTP verification request with mobile and OTP code", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UserVerifyOTPInput" } } ], "responses": { "200": { "description": "Account verified successfully", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid input or invalid/expired OTP", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "User not found", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/users/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retrieve user details by ID (owner verification required)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "User Management" ], "summary": "Get user by ID", "parameters": [ { "type": "string", "format": "uuid", "description": "User ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "User retrieved successfully", "schema": { "$ref": "#/definitions/models.User" } }, "400": { "description": "Invalid user ID format", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "Forbidden - not owner", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "User not found", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": true } } } }, "put": { "security": [ { "BearerAuth": [] } ], "description": "Update user information and optionally set up first-time credentials (JWT protected)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "User Management" ], "summary": "Update user", "parameters": [ { "type": "string", "format": "uuid", "description": "User ID", "name": "id", "in": "path", "required": true }, { "type": "boolean", "description": "Return new tokens after update (default: false)", "name": "requireToken", "in": "query" }, { "description": "User update request with profile fields and optional credentials", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UserUpdateInput" } } ], "responses": { "200": { "description": "User updated successfully", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid input", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": true } }, "409": { "description": "PIN or password already set", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/users/{id}/avatar": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Upload avatar image for a user (owner protected)", "consumes": [ "multipart/form-data" ], "produces": [ "application/json" ], "tags": [ "User Management" ], "summary": "Upload user avatar", "parameters": [ { "type": "string", "format": "uuid", "description": "User ID", "name": "id", "in": "path", "required": true }, { "type": "file", "description": "Avatar image file", "name": "avatar", "in": "formData", "required": true } ], "responses": { "200": { "description": "Avatar uploaded successfully with avatar_url", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid user ID or missing file", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/users/{id}/pin": { "put": { "security": [ { "BearerAuth": [] } ], "description": "Update user PIN with old PIN verification (JWT protected)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "PIN Authentication" ], "summary": "Update user PIN", "parameters": [ { "type": "string", "format": "uuid", "description": "User ID", "name": "id", "in": "path", "required": true }, { "description": "Update PIN request with old and new PIN", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.UserUpdatePinInput" } } ], "responses": { "200": { "description": "User password updated successfully", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid input or new PIN same as old", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Old PIN is incorrect or unauthorized", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/users/{id}/update-api-key": { "put": { "security": [ { "ApiKeyAuth": [] } ], "description": "Update user profile fields and optional PIN using wallet API key authentication.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "User Management" ], "summary": "Update user by API key (wallet only)", "parameters": [ { "type": "string", "description": "API Key", "name": "X-API-Key", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "User ID", "name": "id", "in": "path", "required": true }, { "description": "Wallet user update request", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.WalletUserUpdateInput" } } ], "responses": { "200": { "description": "User updated successfully", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid input", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "User not found", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/v1/stats/dashboard": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get comprehensive dashboard statistics including user counts, service counts, etc.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Statistics" ], "summary": "Get dashboard statistics", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/dto.DashboardStatsResponse" } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/v1/stats/logs": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Fetch recent JSON log entries from the server logs directory. Admin only.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Statistics" ], "summary": "Get recent logs (admin only)", "parameters": [ { "type": "integer", "default": 200, "description": "Number of log lines to return (max 1000)", "name": "lines", "in": "query" }, { "type": "integer", "default": 2, "description": "How many days back to scan (default 2)", "name": "days", "in": "query" }, { "type": "string", "description": "Filter by level: debug|info|warn|error", "name": "level", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/dto.AdminLogsResponse" } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": true } } } } } }, "definitions": { "dto.AdminLogEntryResponse": { "type": "object", "properties": { "level": { "type": "string" }, "message": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} }, "raw": { "description": "Only set when a line couldn't be parsed as JSON.", "type": "string" }, "requestId": { "type": "string" }, "timestamp": { "type": "string" } } }, "dto.AdminLogsResponse": { "type": "object", "properties": { "days": { "type": "integer" }, "entries": { "type": "array", "items": { "$ref": "#/definitions/dto.AdminLogEntryResponse" } }, "level": { "type": "string" }, "lines": { "type": "integer" } } }, "dto.CreateVerifiedUserInput": { "type": "object", "required": [ "mobile" ], "properties": { "email": { "type": "string" }, "firstname": { "$ref": "#/definitions/models.LocalizedString" }, "lastname": { "$ref": "#/definitions/models.LocalizedString" }, "middlename": { "$ref": "#/definitions/models.LocalizedString" }, "mobile": { "type": "string" }, "password": { "type": "string" }, "pin": { "type": "string" } } }, "dto.DailyActivity": { "type": "object", "properties": { "day": { "description": "e.g. \"Mon\", \"Tue\"", "type": "string" }, "logins": { "type": "integer" }, "registrations": { "type": "integer" }, "services": { "type": "integer" } } }, "dto.DashboardStatsResponse": { "type": "object", "properties": { "activeServices": { "description": "Added to match handler", "type": "integer" }, "activeUsers": { "type": "integer" }, "dailyActivity": { "type": "array", "items": { "$ref": "#/definitions/dto.DailyActivity" } }, "failedLogins": { "description": "Added to match previous handler logic", "type": "integer" }, "lockedAccounts": { "description": "Added to match previous handler logic", "type": "integer" }, "recentSignups": { "type": "integer" }, "serviceCategories": { "type": "array", "items": { "$ref": "#/definitions/dto.ServiceCategory" } }, "serviceUsage": { "type": "array", "items": { "$ref": "#/definitions/dto.ServiceUsage" } }, "statusDistribution": { "type": "array", "items": { "$ref": "#/definitions/dto.StatusDistribution" } }, "totalCategories": { "description": "Added to match previous handler logic", "type": "integer" }, "totalServices": { "type": "integer" }, "totalUsers": { "type": "integer" }, "userGrowth": { "type": "array", "items": { "$ref": "#/definitions/dto.UserGrowth" } } } }, "dto.ServiceCategory": { "type": "object", "properties": { "category": { "type": "string" }, "color": { "description": "Optional, can let frontend handle", "type": "string" }, "count": { "type": "integer" } } }, "dto.ServiceUsage": { "type": "object", "properties": { "name": { "type": "string" }, "percentage": { "type": "number" }, "users": { "type": "integer" } } }, "dto.StatusDistribution": { "type": "object", "properties": { "name": { "description": "\"active\", \"inactive\"", "type": "string" }, "value": { "type": "integer" } } }, "dto.UserAutoLoginInput": { "type": "object", "required": [ "mobile" ], "properties": { "device_id": { "type": "string" }, "device_name": { "type": "string" }, "firstname": { "$ref": "#/definitions/models.LocalizedString" }, "mobile": { "type": "string" }, "platform": { "type": "string" } } }, "dto.UserGrowth": { "type": "object", "properties": { "active": { "description": "Active users in this month", "type": "integer" }, "month": { "description": "e.g. \"Jan\", \"Feb\"", "type": "string" }, "newUsers": { "description": "New users in this month", "type": "integer" }, "users": { "description": "Total cumulative users", "type": "integer" } } }, "dto.UserLogoutInput": { "type": "object", "properties": { "refresh_token": { "type": "string" } } }, "dto.UserRefreshTokenInput": { "type": "object", "required": [ "refresh_token" ], "properties": { "device_id": { "type": "string" }, "device_name": { "type": "string" }, "platform": { "type": "string" }, "refresh_token": { "type": "string" } } }, "dto.UserResetPasswordInput": { "type": "object", "required": [ "mobile", "new_password", "otp" ], "properties": { "mobile": { "type": "string" }, "new_password": { "type": "string" }, "otp": { "type": "string" } } }, "dto.UserResetPinInput": { "type": "object", "required": [ "mobile", "new_pin", "otp" ], "properties": { "mobile": { "type": "string" }, "new_pin": { "type": "string" }, "otp": { "type": "string" } } }, "dto.UserSendOTPInput": { "type": "object", "required": [ "mobile" ], "properties": { "mobile": { "type": "string" } } }, "dto.UserSigninEmailInput": { "type": "object", "required": [ "email", "password" ], "properties": { "device_id": { "type": "string" }, "device_name": { "type": "string" }, "email": { "type": "string" }, "password": { "type": "string" }, "platform": { "type": "string" } } }, "dto.UserSigninPasswordInput": { "type": "object", "required": [ "mobile", "password" ], "properties": { "device_id": { "type": "string" }, "device_name": { "type": "string" }, "mobile": { "type": "string" }, "password": { "type": "string" }, "platform": { "type": "string" } } }, "dto.UserSigninPinInput": { "type": "object", "required": [ "mobile", "pin" ], "properties": { "device_id": { "type": "string" }, "device_name": { "type": "string" }, "mobile": { "type": "string" }, "pin": { "type": "string" }, "platform": { "type": "string" } } }, "dto.UserSigninPinPasswordInput": { "type": "object", "required": [ "mobile" ], "properties": { "device_id": { "type": "string" }, "device_name": { "type": "string" }, "mobile": { "type": "string" }, "password": { "type": "string" }, "pin": { "type": "string" }, "platform": { "type": "string" } } }, "dto.UserSignupPasswordInput": { "type": "object", "required": [ "mobile", "password" ], "properties": { "firstname": { "$ref": "#/definitions/models.LocalizedString" }, "lastname": { "$ref": "#/definitions/models.LocalizedString" }, "middlename": { "$ref": "#/definitions/models.LocalizedString" }, "mobile": { "type": "string" }, "password": { "type": "string" } } }, "dto.UserSignupPinInput": { "type": "object", "required": [ "mobile", "pin" ], "properties": { "firstname": { "$ref": "#/definitions/models.LocalizedString" }, "lastname": { "$ref": "#/definitions/models.LocalizedString" }, "middlename": { "$ref": "#/definitions/models.LocalizedString" }, "mobile": { "type": "string" }, "pin": { "type": "string" } } }, "dto.UserSpecificUsersInput": { "type": "object", "required": [ "user_ids" ], "properties": { "user_ids": { "type": "array", "items": { "type": "string" } } } }, "dto.UserUpdateInput": { "type": "object", "properties": { "address": { "type": "string" }, "date_of_birth": { "type": "string" }, "email": { "type": "string" }, "firstname": { "description": "Profile fields (all optional for partial updates)", "allOf": [ { "$ref": "#/definitions/models.LocalizedString" } ] }, "lastname": { "$ref": "#/definitions/models.LocalizedString" }, "middlename": { "$ref": "#/definitions/models.LocalizedString" }, "mobile": { "type": "string" }, "mother_name": { "$ref": "#/definitions/models.LocalizedString" }, "password": { "type": "string" }, "pin": { "description": "First-time credential setup (optional)\nThese will be rejected if credentials already exist", "type": "string" }, "referral_phone": { "type": "string" }, "sex": { "type": "string" }, "status": { "description": "ACTIVE, DISABLED, UNVERIFIED", "type": "string" } } }, "dto.UserUpdatePasswordInput": { "type": "object", "required": [ "new_password", "old_password" ], "properties": { "new_password": { "type": "string" }, "old_password": { "type": "string" } } }, "dto.UserUpdatePinInput": { "type": "object", "required": [ "old_pin", "pin" ], "properties": { "old_pin": { "type": "string" }, "pin": { "type": "string" } } }, "dto.UserVerifyOTPInput": { "type": "object", "required": [ "mobile", "otp" ], "properties": { "device_id": { "type": "string" }, "device_name": { "type": "string" }, "mobile": { "type": "string" }, "otp": { "type": "string" }, "platform": { "type": "string" } } }, "dto.WalletUserUpdateInput": { "type": "object", "properties": { "address": { "type": "string" }, "date_of_birth": { "type": "string" }, "email": { "type": "string" }, "firstname": { "$ref": "#/definitions/models.LocalizedString" }, "lastname": { "$ref": "#/definitions/models.LocalizedString" }, "middlename": { "$ref": "#/definitions/models.LocalizedString" }, "mobile": { "type": "string" }, "mother_name": { "$ref": "#/definitions/models.LocalizedString" }, "pin": { "type": "string" }, "referral_phone": { "type": "string" }, "sex": { "type": "string" }, "status": { "description": "ACTIVE, DISABLED, UNVERIFIED", "type": "string" } } }, "dto.WalletUserUpdatePostInput": { "type": "object", "properties": { "address": { "type": "string" }, "date_of_birth": { "type": "string" }, "email": { "type": "string" }, "firstname": { "$ref": "#/definitions/models.LocalizedString" }, "lastname": { "$ref": "#/definitions/models.LocalizedString" }, "middlename": { "$ref": "#/definitions/models.LocalizedString" }, "mobile": { "type": "string" }, "mother_name": { "$ref": "#/definitions/models.LocalizedString" }, "pin": { "type": "string" }, "referral_phone": { "type": "string" }, "sex": { "type": "string" }, "status": { "description": "ACTIVE, DISABLED, UNVERIFIED", "type": "string" }, "user_id": { "type": "string" } } }, "models.LocalizedString": { "description": "Locale map (en/am) or a plain string. Example: {\"en\":\"Abebe\",\"am\":\"አበበ\"}", "type": "object", "additionalProperties": { "type": "string" } }, "models.User": { "type": "object", "properties": { "address": { "type": "string" }, "avatar_url": { "type": "string" }, "created_at": { "type": "string" }, "date_of_birth": { "type": "string" }, "email": { "type": "string" }, "failed_login_attempts": { "type": "integer" }, "firstname": { "type": "string", "example": "Abebe" }, "id": { "type": "string" }, "last_failed_attempt": { "type": "string" }, "lastname": { "type": "string", "example": "Kebede" }, "locked_out_until": { "type": "string" }, "middlename": { "type": "string" }, "mobile": { "type": "string" }, "mother_name": { "type": "string" }, "password": { "type": "string" }, "pin": { "type": "string" }, "referral_phone": { "type": "string" }, "role_id": { "description": "nil = app user; set = admin (e.g. super_admin)", "type": "string" }, "role_name": { "description": "populated when loading user with role (e.g. for JWT)", "type": "string" }, "sex": { "type": "string" }, "status": { "type": "string" }, "updated_at": { "type": "string" } } } }, "securityDefinitions": { "BearerAuth": { "description": "Type \"Bearer\" followed by a space and JWT token.", "type": "apiKey", "name": "Authorization", "in": "header" } } }