Skip to Content
C-Ushuru v1.0 is now available
API ReferenceUsers API

Users API

Manage users and access control for your client account. Users are the individuals who can access and operate within your C-Ushuru account.

Overview

The Users API allows you to:

  • List users with filtering by branch, role, or status
  • Create new users with role-based permissions
  • Update user information and branch access
  • Change user passwords
  • Deactivate or delete users

User Structure

Key Fields

FieldDescription
nameUser’s full name
emailUnique email address for login
phoneContact phone number
rolePermission level (owner, admin, accountant, cashier)
branchesArray of branch IDs the user can access
all_branchesIf true, user has access to all branches
is_activeWhether the user account is active

User Roles

RoleDescriptionPermissions
ownerAccount ownerFull access to all features and settings
adminAdministratorManage users, branches, devices, and all transactions
accountantAccountantCreate and manage transactions, view reports
cashierCashierCreate sales and view own transactions only

List Users

Get all users for your account.

GET/api/v1/users

List Users

Retrieve all users for your client account with their roles and branch assignments.

Authentication
Parameters
branch_id
string · query

Filter users by branch ID

role
string · query

Filter users by role (owner, admin, accountant, cashier)

status
string · query

Filter by status (active, inactive)

Response

Status: 200 OK

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "+254712345678",
      "role": "owner",
      "branches": ["00", "01", "02"],
      "all_branches": true,
      "is_active": true,
      "last_login_at": "2025-01-15T10:00:00Z",
      "created_at": "2025-01-01T10:00:00Z"
    },
    {
      "id": 2,
      "name": "Jane Smith",
      "email": "jane@example.com",
      "phone": "+254722345678",
      "role": "admin",
      "branches": ["00", "01"],
      "all_branches": false,
      "is_active": true,
      "last_login_at": "2025-01-14T08:30:00Z",
      "created_at": "2025-01-05T10:00:00Z"
    }
  ],
  "meta": {
    "total": 2,
    "timestamp": "2025-01-15T14:30:00Z"
  }
}

Create User

Create a new user for your account.

POST/api/v1/users

Create User

Create a new user with specified role and branch access.

Authentication
Request BodyJSON

Field Descriptions

FieldTypeRequiredDescription
namestringYesUser’s full name (max 255 chars)
emailstringYesUnique email address for login
phonestringNoContact phone number (max 50 chars)
passwordstringYesPassword (min 8 chars, must include uppercase, lowercase, number)
rolestringYesUser role: owner, admin, accountant, cashier
branchesarrayNoArray of branch IDs the user can access
all_branchesbooleanNoIf true, user has access to all branches (default: false)

Response

Status: 201 Created

{
  "status": "success",
  "message": "User created successfully",
  "data": {
    "id": 3,
    "name": "Alice Johnson",
    "email": "alice@example.com",
    "phone": "+254733345678",
    "role": "accountant",
    "branches": ["00", "01"],
    "all_branches": false,
    "is_active": true,
    "created_at": "2025-01-17T10:00:00Z"
  },
  "meta": {
    "timestamp": "2025-01-17T10:00:00Z",
    "request_id": "req_abc123"
  }
}

Get User Details

Retrieve details of a specific user.

GET/api/v1/users/{userId}

Get User Details

Retrieve detailed information about a specific user including their activity.

Authentication
Parameters
userId*
integer · path

User ID

Response

Status: 200 OK

{
  "status": "success",
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+254712345678",
    "role": "owner",
    "branches": ["00", "01", "02"],
    "all_branches": true,
    "is_active": true,
    "email_verified_at": "2025-01-01T12:00:00Z",
    "last_login_at": "2025-01-15T10:00:00Z",
    "last_login_ip": "192.168.1.1",
    "activity_summary": {
      "total_transactions": 450,
      "this_month_transactions": 85,
      "last_activity_at": "2025-01-15T14:00:00Z"
    },
    "created_at": "2025-01-01T10:00:00Z",
    "updated_at": "2025-01-15T10:00:00Z"
  }
}

Status: 404 Not Found

{
  "status": "error",
  "message": "User not found"
}

Update User

Update an existing user’s information.

PUT/api/v1/users/{userId}

Update User

Update user information. All fields are optional - only provided fields will be updated.

Authentication
Parameters
userId*
integer · path

User ID

Request BodyJSON

Response

Status: 200 OK

{
  "status": "success",
  "message": "User updated successfully",
  "data": {
    "id": 2,
    "name": "Jane Smith Updated",
    "email": "jane@example.com",
    "phone": "+254722999999",
    "role": "admin",
    "branches": ["00", "01", "02"],
    "all_branches": false,
    "is_active": true,
    "updated_at": "2025-01-17T15:00:00Z"
  }
}

Change User Password

Change a user’s password.

POST/api/v1/users/{userId}/change-password

Change Password

Change a user's password. Only the user themselves or an admin/owner can change passwords.

Authentication
Parameters
userId*
integer · path

User ID

Request BodyJSON

Response

Status: 200 OK

{
  "status": "success",
  "message": "Password changed successfully"
}

Delete User

Delete a user (soft delete).

DELETE/api/v1/users/{userId}

Delete User

Soft delete a user. The account owner cannot be deleted.

Authentication
Parameters
userId*
integer · path

User ID to delete

Response

Status: 200 OK

{
  "status": "success",
  "message": "User deleted successfully"
}

Note: The account owner cannot be deleted. Users with pending transactions may need those resolved before deletion.

Error Responses

400 Bad Request

{
  "status": "error",
  "message": "Validation failed",
  "errors": {
    "email": ["The email has already been taken."],
    "password": ["The password must be at least 8 characters."]
  }
}

403 Forbidden

{
  "status": "error",
  "message": "You do not have permission to perform this action"
}

404 Not Found

{
  "status": "error",
  "message": "User not found"
}

Code Examples

JavaScript

const axios = require('axios');
 
const apiKey = process.env.CTAX_API_KEY;
const baseURL = 'https://c-ushuru.com/api/v1';
 
// List all users
const users = await axios.get(`${baseURL}/users`, {
  headers: { Authorization: `Bearer ${apiKey}` }
});
 
// Create a new user
const newUser = await axios.post(`${baseURL}/users`, {
  name: 'Alice Johnson',
  email: 'alice@example.com',
  phone: '+254733345678',
  password: 'SecurePassword123!',
  role: 'accountant',
  branches: ['00', '01']
}, {
  headers: { Authorization: `Bearer ${apiKey}` }
});
 
// Update a user
const updated = await axios.put(`${baseURL}/users/3`, {
  role: 'admin',
  branches: ['00', '01', '02']
}, {
  headers: { Authorization: `Bearer ${apiKey}` }
});

PHP

use GuzzleHttp\Client;
 
$client = new Client([
    'base_uri' => 'https://c-ushuru.com/api/v1/',
    'headers' => [
        'Authorization' => 'Bearer ' . env('CTAX_API_KEY'),
        'Content-Type' => 'application/json',
    ],
]);
 
// List all users
$users = $client->get('users');
 
// Create a new user
$response = $client->post('users', [
    'json' => [
        'name' => 'Alice Johnson',
        'email' => 'alice@example.com',
        'password' => 'SecurePassword123!',
        'role' => 'accountant',
        'branches' => ['00', '01'],
    ],
]);

Python

import requests
import os
 
api_key = os.environ['CTAX_API_KEY']
base_url = 'https://c-ushuru.com/api/v1'
headers = {'Authorization': f'Bearer {api_key}'}
 
# List all users
response = requests.get(f'{base_url}/users', headers=headers)
users = response.json()['data']
 
# Create a new user
new_user = requests.post(
    f'{base_url}/users',
    json={
        'name': 'Alice Johnson',
        'email': 'alice@example.com',
        'password': 'SecurePassword123!',
        'role': 'accountant',
        'branches': ['00', '01'],
    },
    headers=headers
)

Best Practices

  1. Strong Passwords - Enforce strong passwords with uppercase, lowercase, numbers, and special characters
  2. Least Privilege - Assign the minimum role necessary for each user’s job function
  3. Branch Restrictions - Limit user access to only the branches they need
  4. Regular Reviews - Periodically review user access and deactivate unused accounts
  5. Audit Trails - Monitor user activity through transaction logs
  6. Secure Credentials - Never share login credentials between users
Last updated on
AuthenticationCustomers API