Users API Guide

Manage user accounts, profiles, and access control. The Users API handles user creation, updates, password management, and team associations.

📋 Overview

Users represent individual accounts that can access teams and resources. Each user has a profile, role assignments, and can belong to multiple teams with different permission levels.

🔑 Key Features

User Management - Create and update user accounts

Profile Information - Manage user details and contact info

Password Reset - Secure password management

Role Assignment - Control access levels per team

Multi-team Support - Users can belong to multiple teams

Address Management - Store user location information

📚 Endpoints

List Users

Retrieve a paginated list of users.

Query Parameters:

limit (integer, 1-100) - Number of results per page (default: 10)

next (string) - Pagination cursor for next page

team (string) - gigstack Connect: Target team ID

Example Request:

Example Response:

{
    "message": "Users retrieved successfully",
    "data": [
        {
            "id": "user_1234567890",
            "email": "john.doe@example.com",
            "name": "John Doe",
            "role": "admin",
            "created_at": 1677651234
        },
        {
            "id": "user_9876543210",
            "email": "jane.smith@example.com",
            "name": "Jane Smith",
            "role": "member",
            "created_at": 1677651234
        }
    ],
    "has_more": false,
    "total_results": 2
}

Create User

Create a new user account.

Request Body:

{
    "email": "new.user@example.com",
    "firstName": "New",
    "lastName": "User",
    "phone": "+52 55 1234 5678",
    "company_role": "Developer",
    "address": {
        "country": "Mexico",
        "street": "Av. Reforma",
        "zip": "06500",
        "city": "Ciudad de México",
        "state": "CDMX",
        "exterior": "456",
        "municipality": "Cuauhtémoc",
        "neighborhood": "Juárez"
    }
}

Example Request:

Example Response:

{
    "message": "User created successfully",
    "data": {
        "id": "user_new123456",
        "email": "developer@company.com",
        "name": "Carlos Rodriguez",
        "role": "member",
        "created_at": 1677651234,
        "invitation_sent": true
    }
}

Get User

Retrieve a specific user by ID.

Example Request:

Example Response:

{
    "message": "User retrieved successfully",
    "data": {
        "id": "user_1234567890",
        "email": "john.doe@example.com",
        "name": "John Doe",
        "firstName": "John",
        "lastName": "Doe",
        "phone": "+52 55 1234 5678",
        "company_role": "Manager",
        "role": "admin",
        "address": {
            "country": "Mexico",
            "street": "Av. Insurgentes Sur",
            "zip": "03100",
            "city": "Ciudad de México",
            "state": "CDMX",
            "exterior": "123",
            "municipality": "Benito Juárez",
            "neighborhood": "Del Valle"
        },
        "created_at": 1677651234,
        "last_login": 1677737634,
        "teams": [
            {
                "team_id": "team_1234567890",
                "team_name": "Main Company",
                "role": "admin"
            },
            {
                "team_id": "team_0987654321",
                "team_name": "Subsidiary",
                "role": "viewer"
            }
        ]
    }
}

Update User

Update an existing user's information.

Request Body:

{
    "firstName": "Jonathan",
    "lastName": "Doe",
    "phone": "+52 55 5555 5555",
    "company_role": "Senior Manager",
    "address": {
        "zip": "03200",
        "neighborhood": "Del Valle Sur"
    }
}

Example Request:

Reset Password

Reset a user's password.

Request Body:

{
    "email": "user@example.com"
}

Example Request:

Example Response:

{
    "message": "Password reset email sent",
    "data": {
        "email": "john.doe@example.com",
        "reset_link_sent": true,
        "expires_at": 1677655834
    }
}

🏗️ User Structure

User Fields

Field	Type	Description
`id`	string	Unique user identifier
`email`	string	User's email address (unique)
`firstName`	string	User's first name
`lastName`	string	User's last name
`name`	string	Full name (computed)
`phone`	string	Contact phone number
`company_role`	string	Position in company
`role`	string	System role (admin/member/viewer)
`address`	object	User's address information
`created_at`	number	Unix timestamp of creation

Address Structure

{
    "country": "Mexico",
    "street": "Street name",
    "exterior": "123",
    "interior": "4B",
    "neighborhood": "Neighborhood",
    "municipality": "Municipality",
    "city": "City",
    "state": "State",
    "zip": "12345"
}

👥 User Roles & Permissions

System Roles

Role	Permissions	Description
admin	Full access	Can manage team and billing
member	Read/Write	Can create and edit resources
viewer	Read only	Can only view resources

Role Hierarchy

Permission Matrix

Action	Admin	Member	Viewer
View resources	✅	✅	✅
Create invoices	✅	✅	❌
Edit clients	✅	✅	❌
Manage users	✅	❌	❌
Change settings	✅	❌	❌
Delete team	✅	❌	❌
Manage billing	✅	❌	❌

🎯 Common Scenarios

1. Onboard New Employee

2. Update User Profile

3. Bulk User Creation

4. Password Reset Flow

🔄 User Lifecycle

User Creation Flow

User Deactivation Flow

💡 Best Practices

Use strong passwords - Enforce password complexity requirements

Regular access reviews - Audit user permissions periodically

Minimize admin users - Only essential personnel should have admin access

Complete profiles - Ensure all user information is up-to-date

Use appropriate roles - Follow principle of least privilege

Monitor user activity - Track login and action patterns

Clean up inactive users - Remove or disable unused accounts

🔒 Security Considerations

Password Requirements

Minimum 8 characters

Must contain uppercase and lowercase

Must contain numbers

Must contain special characters

Cannot reuse last 5 passwords

Session Management

Sessions expire after 24 hours of inactivity

Refresh tokens valid for 30 days

Multi-device support with individual sessions

Teams API - Manage team membership

gigstack Connect - Multi-team user access

Clients API - Users create and manage clients

Invoices API - User permissions affect invoice access

🚨 Error Handling

User Already Exists

{
    "message": "User creation failed",
    "error": "Email address already registered"
}

Invalid Email Format

{
    "message": "Invalid request",
    "error": "Email format is invalid"
}

User Not Found

{
    "message": "User not found",
    "error": "The specified user does not exist"
}

Insufficient Permissions

{
    "message": "Access denied",
    "error": "Admin role required to manage users"
}

Password Reset Failed

{
    "message": "Password reset failed",
    "error": "No user found with that email address"
}

Need help with user management? Check our support documentation or contact support@gigstack.io

📋 Overview#

🔑 Key Features#

📚 Endpoints#

List Users#

Create User#

Get User#

Update User#

Reset Password#

🏗️ User Structure#

User Fields#

Address Structure#

👥 User Roles & Permissions#

System Roles#

Role Hierarchy#

Permission Matrix#

🎯 Common Scenarios#

1. Onboard New Employee#

2. Update User Profile#

3. Bulk User Creation#

4. Password Reset Flow#

🔄 User Lifecycle#

User Creation Flow#

User Deactivation Flow#

💡 Best Practices#

🔒 Security Considerations#

Password Requirements#

Session Management#

🔗 Related Resources#

🚨 Error Handling#

User Already Exists#

Invalid Email Format#

User Not Found#

Insufficient Permissions#

Password Reset Failed#

📋 Overview

🔑 Key Features

📚 Endpoints

List Users

Create User

Get User

Update User

Reset Password

🏗️ User Structure

User Fields

Address Structure

👥 User Roles & Permissions

System Roles

Role Hierarchy

Permission Matrix

🎯 Common Scenarios

1. Onboard New Employee

2. Update User Profile

3. Bulk User Creation

4. Password Reset Flow

🔄 User Lifecycle

User Creation Flow

User Deactivation Flow

💡 Best Practices

🔒 Security Considerations

Password Requirements

Session Management

🔗 Related Resources

🚨 Error Handling

User Already Exists

Invalid Email Format

User Not Found

Insufficient Permissions

Password Reset Failed