gigstack API
  1. Users
gigstack API
  • Welcome to gigstack API
  • gigstack Connect API Guide
  • Migrar de API v1 a v2 de gigstack
  • Clients
    • Clients API Guide
    • List clients
      GET
    • Get client
      GET
    • Update client
      PUT
    • Create client
      POST
    • Validate client fiscal information
      POST
    • Get client customer portal access token
      POST
    • Stamp pending receipts
      POST
    • Delete client
      DELETE
    • Search clients
      GET
    • Upload CSF PDF to create or update client
      POST
    • Upload support document
      POST
    • List support documents
      GET
  • Services
    • Services API Guide
    • List services
      GET
    • Get service
      GET
    • Update service
      PUT
    • Create service
      POST
    • Delete service
      DELETE
  • Invoices
    • Invoices API Guide
    • Income
      • List income invoices
      • Create income invoice
      • Get income invoice
    • Egress
      • List egress invoices
      • Create egress invoice
      • Get egress invoice
    • Drafts
      • Create draft invoice (pre-factura)
      • Stamp draft invoice (finalize)
      • Generate draft preview PDF (pre-factura)
      • Delete draft invoice
      • Update draft invoice
      • Get draft invoice
      • List draft invoices
    • List CFDI errors
    • List payment complement invoices
    • Get payment complement invoice
    • Get invoice files
    • Upload support document
    • List support documents
    • Cancel invoice
    • Search invoices
  • Payments
    • Payments API Guide
    • List payments
    • Get payment
    • Request payment
    • Register payment
    • Mark payment as paid
    • Refund payment
    • Cancel payment
    • Search payments
    • Upload support document
    • List support documents
  • Receipts
    • Receipts API Guide
    • List receipts
    • Get receipt
    • Create receipt
    • Stamp receipt
    • Cancel receipt
    • Search receipts
  • Teams
    • Teams API Guide
    • List teams
    • Get team
    • Get team integrations
    • Get team series
    • Get team onboarding URL
    • Update team
    • Update team series
    • Update team settings
    • Create team
    • Add team member
    • Remove team member
    • Create team series
    • Upload SAT CSD certificates
    • Sign manifest document
  • Users
    • Users API Guide
    • List users
      GET
    • Get user
      GET
    • Update user
      PUT
    • Create user
      POST
    • Reset user password
      POST
    • Generate login link
      POST
  • Catalogs
    • Tax Regimes Catalog (Régimen Fiscal)
    • Payment Forms | Formas de pago
    • CFDI Usage Catalog (Uso CFDI)
    • Payment Methods Catalog (Método de Pago)
    • Months and Bimesters Catalog (Meses y Bimestres)
    • Invoice Relationships Catalog (Relación entre Facturas)
  • Webhooks
    • Webhooks
    • List webhooks
    • Create webhook
    • Get webhook
    • Update webhook
    • Delete webhook
  • Retentions
    • Retentions
    • List retentions
    • Create retention
    • Get retention
    • Cancel retention
    • Get retention files
  • Schemas
    • Schemas
      • ApiResponse
      • Category
      • Pet
      • Tag
      • Order
      • StandardizedSuccessResponse
      • StandardizedErrorResponse
      • ApiErrorCode
    • RequestBodies
      • UserArray
    • OrderDirection
    • ApiPublicClient
    • Client
    • DateRangeFilter
    • Service
    • ListQueryParams
    • ClientInput
    • ApiPublicService
    • ServiceInput
    • PaginationMeta
    • Invoice
    • InvoiceIncomeInput
    • Payment
    • PaymentInput
    • PaymentItem
    • InvoiceInput
    • InvoiceEgressInput
    • Team
    • PaymentAllowedMethod
    • TeamInput
    • TeamSettingsInput
    • CfdiError
    • ApiPublicPaymentProcessorDetails
    • User
    • DraftInvoiceInput
    • ApiPublicPayment
    • UserInput
    • ClientAddress
    • DraftInvoiceUpdateInput
    • DraftInvoiceOutput
    • TaxSchema
    • RequestPaymentInput
    • StandardSuccessResponse
    • RegisterPaymentInput
    • ListResponse
    • ErrorResponse
    • ApiPublicIncomeInvoice
    • ValidationErrorResponse
    • RefundPaymentInput
    • ApiPublicTeam
    • MarkPaymentAsPaidInput
    • UnauthorizedError
    • ApiPublicUser
    • ApiPublicSearch
    • NotFoundError
    • ApiPublicThirdParty
    • InternalServerError
    • ApiPublicInvoiceConfig
    • ApiPublicRefund
    • ApiPublicAutomations
    • TeamSettings
    • TaxElement
    • SeriesInput
    • Series
    • ApiPublicWebhook
    • WebhookInput
    • ReceiptInput
    • WebhookUpdateInput
    • PaymentMethodEnum
    • PaymentFormEnum
    • AutomationTypeEnum
    • ItemSchema
    • SATDocument
    • UploadSupportDocumentInput
  1. Users

Users API Guide

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
Login Link Generation - Create direct login links for API-created users
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",
    "first_name": "New",
    "last_name": "User",
    "phone": "+52 55 1234 5678",
    "company_role": "Developer",
    "address": {
        "country": "MEX",
        "street": "Av. Reforma",
        "zip": "06500",
        "city": "Ciudad de México",
        "state": "CDMX",
        "exterior": "456",
        "neighborhood": "Juárez"
    },
    "auto_join": true,
    "role": "editor"
}
Body Parameters:
email (string, optional) - User email address
first_name (string, optional) - User first name
last_name (string, optional) - User last name
phone (string, optional) - User phone number
company_role (string, optional) - User role in the company
address (object, optional) - User address information
country (string, optional) - Country name
street (string, optional) - Street address
zip (string, optional) - Postal code
city (string, optional) - City name
state (string, optional) - State/province
exterior (string, optional) - Exterior number
municipality (string, optional) - Municipality (stored but not returned in responses)
neighborhood (string, optional) - Neighborhood/colony
auto_join (boolean, optional) - If true, automatically adds the user to the team associated with the API key. Defaults to false. When true and role is specified, the user will be added to the team with that role.
role (string, optional) - Role to assign to the user when auto_join is true. Can be "editor", "admin", or "viewer". Defaults to "viewer" if not specified. This parameter only takes effect when auto_join is true - it determines the permissions the user will have within the team.
Notes:
The municipality field can be included in requests and will be stored, but is not returned in response objects.
When auto_join is true, the user will be automatically added to the team and billing account associated with your API key.
The role parameter works in conjunction with auto_join. When both are used, the user is added to the team with the specified role (editor, admin, or viewer). If role is not specified, the user defaults to "viewer" role.
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",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "+52 55 1234 5678",
        "company_role": "Manager",
        "role": "admin",
        "address": {
            "country": "MEX",
            "street": "Av. Insurgentes Sur",
            "zip": "03100",
            "city": "Ciudad de México",
            "state": "CDMX",
            "exterior": "123",
            "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:
All fields are optional. Only provide the fields you want to update.
{
    "first_name": "Jonathan",
    "last_name": "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
    }
}

Generate Login Link#

Generate a login link for a user. The link contains a custom Firebase token that allows the user to authenticate directly without a password.
Requirements:
User must have been created via API (from: 'api')
User must belong to the billing account making the request
If requirements are not met, returns a 404 error
gigstack Connect: Generate login links for other teams' users using the team query parameter.
Request Body:
{
    "user_id": "abc123xyz"
}
Parameters:
user_id (required, string) - The Firebase UID of the user
Example Request:
Example Response:
{
    "message": "Login link generated",
    "data": {
        "login_link": "https://app.gigstack.pro/auth/token-login?token=eyJhbGc...",
        "valid_until": 1732657200000,
        "method": "token"
    }
}
Response Fields:
login_link (string) - The login URL with embedded token
valid_until (number) - Unix timestamp in milliseconds when the token expires (1 hour from generation)
method (string) - The authentication method used (always 'token')
Error Responses:
404 - User Not Found or Not Accessible:
{
    "message": "User not found or not accessible via API",
    "error": "The user either does not exist or was not created via API"
}

User Structure#

User Fields#

FieldTypeDescription
idstringUnique user identifier
emailstringUser's email address (unique)
first_namestringUser's first name
last_namestringUser's last name
namestringFull name (computed)
phonestringContact phone number
company_rolestringPosition in company
rolestringSystem role (admin/member/viewer)
addressobjectUser's address information
created_atnumberUnix timestamp of creation

Address Structure#

The address object supports the following fields:
{
    "country": "MEX",
    "street": "Street name",
    "zip": "12345",
    "city": "City",
    "state": "State",
    "exterior": "123",
    "neighborhood": "Neighborhood"
}
Note:
The municipality field can be included in POST/PUT requests and will be stored in the database, but is not returned in GET responses.
All address fields are optional and nullable.
Address fields returned in responses: country, street, zip, city, state, exterior, neighborhood

User Roles and Permissions#

System Roles#

RolePermissionsDescription
adminFull accessCan manage team and billing
memberRead/WriteCan create and edit resources
viewerRead onlyCan only view resources

Role Hierarchy#

Permission Matrix#

ActionAdminMemberViewer
View resourcesYesYesYes
Create invoicesYesYesNo
Edit clientsYesYesNo
Manage usersYesNoNo
Change settingsYesNoNo
Delete teamYesNoNo
Manage billingYesNoNo

Common Scenarios#

1. Onboard New Employee#

Option A: Using auto_join with role (Recommended)
Option B: Manual team addition

2. Update User Profile#

3. Bulk User Creation with Different Roles#

4. Password Reset Flow#

5. Generate Login Link for API User#

Use Cases:
Onboard external users without requiring password setup
Provide temporary access to contractors or auditors
Enable single sign-on for integrated applications
Create magic links for embedded user experiences

User Lifecycle#

User Creation Flow#

User Deactivation Flow#

Best Practices#

1.
Use strong passwords - Enforce password complexity requirements
2.
Regular access reviews - Audit user permissions periodically
3.
Minimize admin users - Only essential personnel should have admin access
4.
Complete profiles - Ensure all user information is up-to-date
5.
Use appropriate roles - Follow principle of least privilege
6.
Monitor user activity - Track login and action patterns
7.
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

Related Resources#

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"
}

Login Link Generation Failed#

User Not Created via API:
{
    "message": "User not found or not accessible via API",
    "error": "This user was not created through the API or does not exist"
}
User Not in Billing Account:
{
    "message": "Access denied",
    "error": "User does not belong to your billing account"
}

For additional assistance, contact support@gigstack.io
Modified at 2026-03-11 10:58:02
Previous
Sign manifest document
Next
List users
Built with