User API

The User API manages admin and staff accounts with role-based access control. Admin users are distinct from Customers -- they have access to the dashboard and management APIs.

User Structure

{
  "id": "usr_abc123",
  "email": "[email protected]",
  "firstName": "Alex",
  "lastName": "Chen",
  "role": "admin",
  "permissions": [
    "products:read",
    "products:write",
    "orders:read",
    "orders:write",
    "settings:read",
    "settings:write"
  ],
  "avatar": "https://cdn.hanzo.ai/avatars/usr_abc123.jpg",
  "status": "active",
  "lastLoginAt": "2024-06-15T10:00:00Z",
  "createdAt": "2024-01-10T08:00:00Z",
  "updatedAt": "2024-06-15T10:00:00Z"
}

Roles

Role	Description
`owner`	Full access, can manage billing and delete store
`admin`	Full access to all resources except billing
`manager`	Manage products, orders, and customers
`editor`	Create and edit products and collections
`viewer`	Read-only access to all resources
`custom`	Custom permission set

Permissions

Permission	Description
`products:read`	View products, variants, collections
`products:write`	Create, update, delete products
`orders:read`	View orders and payments
`orders:write`	Update orders, process refunds, fulfill
`customers:read`	View customer accounts
`customers:write`	Create, update, delete customers
`analytics:read`	View reports and analytics
`settings:read`	View store settings
`settings:write`	Modify store settings
`users:read`	View admin users
`users:write`	Create, update, delete admin users

Endpoints

List Users

GET /admin/user

Query Parameters:

Parameter	Type	Description
`page`	number	Page number (default: 1)
`display`	number	Items per page (default: 20, max: 100)
`sort`	string	Sort field (e.g. `createdAt:desc`)
`role`	string	Filter by role
`status`	string	`active`, `inactive`, `invited`
`q`	string	Search by name or email

curl "https://api.hanzo.ai/admin/user?role=admin&status=active" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "count": 5,
  "models": [
    {
      "id": "usr_abc123",
      "email": "[email protected]",
      "firstName": "Alex",
      "lastName": "Chen",
      "role": "admin",
      "status": "active",
      "lastLoginAt": "2024-06-15T10:00:00Z"
    }
  ]
}

Get User

GET /admin/user/:id

curl https://api.hanzo.ai/admin/user/usr_abc123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Create User

POST /admin/user

Create a new admin user. An invitation email is sent automatically.

curl -X POST https://api.hanzo.ai/admin/user \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "Sam",
    "lastName": "Rivera",
    "role": "manager"
  }'

Response: 201 Created

{
  "id": "usr_new456",
  "email": "[email protected]",
  "firstName": "Sam",
  "lastName": "Rivera",
  "role": "manager",
  "status": "invited",
  "createdAt": "2024-06-15T10:00:00Z"
}

New users receive an invitation email with a link to set their password. The invitation expires after 72 hours.

Update User

PUT /admin/user/:id

curl -X PUT https://api.hanzo.ai/admin/user/usr_abc123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin",
    "permissions": [
      "products:read",
      "products:write",
      "orders:read",
      "orders:write"
    ]
  }'

Delete User

DELETE /admin/user/:id

curl -X DELETE https://api.hanzo.ai/admin/user/usr_abc123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response: 204 No Content

You cannot delete your own account or the store owner. Deactivate users instead by setting status: "inactive".

Custom Roles

For fine-grained access control, create users with role: "custom" and specify explicit permissions:

curl -X POST https://api.hanzo.ai/admin/user \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "Pat",
    "lastName": "Morgan",
    "role": "custom",
    "permissions": [
      "orders:read",
      "orders:write",
      "customers:read"
    ]
  }'

Resend Invitation

POST /admin/user/:id/invite

Resend the invitation email to a user with invited status.

curl -X POST https://api.hanzo.ai/admin/user/usr_new456/invite \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Activity Log

GET /admin/user/:id/activity

Retrieve the audit log of actions performed by a user.

curl "https://api.hanzo.ai/admin/user/usr_abc123/activity?display=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "count": 156,
  "models": [
    {
      "id": "act_001",
      "action": "order.fulfill",
      "resourceType": "order",
      "resourceId": "order_abc123",
      "timestamp": "2024-06-15T10:05:00Z",
      "details": {
        "trackingNumber": "1Z999AA10123456784"
      }
    }
  ]
}

SDK Examples

JavaScript

import { Commerce } from '@hanzo/commerce'

const commerce = new Commerce({ apiKey: 'your_key' })

// List admin users
const users = await commerce.users.list({
  role: 'admin',
  status: 'active'
})

// Create user with custom role
const user = await commerce.users.create({
  email: '[email protected]',
  firstName: 'Pat',
  lastName: 'Morgan',
  role: 'custom',
  permissions: ['orders:read', 'orders:write']
})

// Update role
await commerce.users.update(user.id, {
  role: 'manager'
})

// Get activity log
const activity = await commerce.users.activity(user.id, {
  display: 20
})

// Delete user
await commerce.users.delete('usr_abc123')

Go

users, err := client.Users.List(ctx, &sdk.UserListParams{
    Role:   "admin",
    Status: "active",
})

user, err := client.Users.Create(ctx, &sdk.UserInput{
    Email:       "[email protected]",
    FirstName:   "Pat",
    LastName:    "Morgan",
    Role:        "custom",
    Permissions: []string{"orders:read", "orders:write"},
})

err = client.Users.Update(ctx, user.ID, &sdk.UserInput{
    Role: "manager",
})

activity, err := client.Users.Activity(ctx, user.ID, &sdk.ActivityParams{
    Display: 20,
})

On this page