Users API

Create, read, update, and delete users. Manage user profiles, authentication methods, and lifecycle states.

Endpoints

Method	Endpoint	Description
`GET`	`/users`	List users
`GET`	`/users/:id`	Get user by ID
`POST`	`/users`	Create user
`PATCH`	`/users/:id`	Update user
`DELETE`	`/users/:id`	Delete user

List Users

GET /v1/organizations/:org/usersbash

curl "https://api.accessiq.io/v1/organizations/acme-corp/users?limit=20&status=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "data": [
    {
      "id": "user_abc123",
      "email": "john.doe@acme.com",
      "firstName": "John",
      "lastName": "Doe",
      "displayName": "John Doe",
      "status": "active",
      "emailVerified": true,
      "mfaEnabled": true,
      "roles": [
        {
          "id": "role_admin",
          "name": "Admin"
        }
      ],
      "metadata": {
        "department": "Engineering",
        "employeeId": "E12345"
      },
      "lastLoginAt": "2024-01-15T10:30:00Z",
      "createdAt": "2023-06-01T09:00:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 523,
    "page": 1,
    "limit": 20,
    "hasMore": true
  }
}

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of users to return (1-100, default 20)
`after`	string	Cursor for pagination (user ID)
`status`	string	Filter by status: active, suspended, pending
`email`	string	Filter by email (exact match)
`search`	string	Search by name or email
`role`	string	Filter by role ID

Get User

GET /v1/organizations/:org/users/:idbash

curl https://api.accessiq.io/v1/organizations/acme-corp/users/user_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "data": {
    "id": "user_abc123",
    "email": "john.doe@acme.com",
    "firstName": "John",
    "lastName": "Doe",
    "displayName": "John Doe",
    "picture": "https://cdn.accessiq.io/avatars/user_abc123.jpg",
    "status": "active",
    "emailVerified": true,
    "phoneNumber": "+1234567890",
    "phoneVerified": true,
    "mfaEnabled": true,
    "mfaMethods": ["totp", "sms"],
    "roles": [
      {
        "id": "role_admin",
        "name": "Admin",
        "permissions": ["users:read", "users:write"]
      }
    ],
    "organizations": [
      {
        "id": "org_acme",
        "name": "Acme Corp",
        "role": "admin"
      }
    ],
    "metadata": {
      "department": "Engineering",
      "employeeId": "E12345",
      "manager": "user_xyz789"
    },
    "identityProviders": [
      {
        "provider": "azure-ad",
        "externalId": "abc123-def456"
      }
    ],
    "lastLoginAt": "2024-01-15T10:30:00Z",
    "createdAt": "2023-06-01T09:00:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

Create User

POST /v1/organizations/:org/usersbash

curl -X POST https://api.accessiq.io/v1/organizations/acme-corp/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.smith@acme.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "displayName": "Jane Smith",
    "phoneNumber": "+1234567890",
    "roles": ["role_user"],
    "metadata": {
      "department": "Marketing",
      "employeeId": "E12346"
    },
    "sendInvitation": true
  }'

# Response (201 Created)
{
  "data": {
    "id": "user_def456",
    "email": "jane.smith@acme.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "status": "pending",
    "emailVerified": false,
    "createdAt": "2024-01-15T11:00:00Z"
  }
}

Invitation Email

When sendInvitation is true, the user receives an email with a link to set their password and complete registration.

Update User

PATCH /v1/organizations/:org/users/:idbash

curl -X PATCH https://api.accessiq.io/v1/organizations/acme-corp/users/user_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jonathan",
    "metadata": {
      "department": "Product"
    }
  }'

# Response
{
  "data": {
    "id": "user_abc123",
    "email": "john.doe@acme.com",
    "firstName": "Jonathan",
    "lastName": "Doe",
    "metadata": {
      "department": "Product",
      "employeeId": "E12345"
    },
    "updatedAt": "2024-01-15T12:00:00Z"
  }
}

Delete User

DELETE /v1/organizations/:org/users/:idbash

curl -X DELETE https://api.accessiq.io/v1/organizations/acme-corp/users/user_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response: 204 No Content

Soft Delete

By default, users are soft-deleted and can be restored within 30 days. Use?permanent=true for immediate permanent deletion (GDPR).

Suspend User

POST /v1/organizations/:org/users/:id/suspendbash

curl -X POST https://api.accessiq.io/v1/organizations/acme-corp/users/user_abc123/suspend \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Security review pending",
    "revokeActiveSessions": true
  }'

# Response
{
  "data": {
    "id": "user_abc123",
    "status": "suspended",
    "suspendedAt": "2024-01-15T12:00:00Z",
    "suspendedReason": "Security review pending"
  }
}

User Roles

Manage User Rolesbash

# Add role to user
curl -X POST https://api.accessiq.io/v1/organizations/acme-corp/users/user_abc123/roles \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "roleId": "role_admin" }'

# Remove role from user
curl -X DELETE https://api.accessiq.io/v1/organizations/acme-corp/users/user_abc123/roles/role_admin \
  -H "Authorization: Bearer YOUR_API_KEY"

User Schema

User Objecttypescript

interface User {
  id: string;
  email: string;
  firstName?: string;
  lastName?: string;
  displayName?: string;
  picture?: string;
  status: 'active' | 'suspended' | 'pending' | 'deleted';
  emailVerified: boolean;
  phoneNumber?: string;
  phoneVerified: boolean;
  mfaEnabled: boolean;
  mfaMethods?: ('totp' | 'sms' | 'email' | 'passkey')[];
  roles: Role[];
  organizations: OrganizationMembership[];
  metadata?: Record<string, any>;
  identityProviders?: IdentityProviderLink[];
  lastLoginAt?: string;
  lastPasswordChangeAt?: string;
  createdAt: string;
  updatedAt: string;
}

Webhooks

Configure webhooks to receive real-time notifications when users are created, updated, or deleted.