Users

Manage users within an organization. Users are assigned roles that determine their permissions. See Authorization for role details.

List Users

GET /v1/organizations/{org_id}/users

Lists all users in the organization. Requires Owner or Admin role.

Request:

curl https://api.hatidata.com/v1/organizations/org_a1b2c3d4/users \
  -H "Authorization: Bearer <jwt>"

Response 200 OK:

{
  "data": [
    {
      "user_id": "usr_x1y2z3",
      "email": "alice@acme.com",
      "name": "Alice Chen",
      "role": "owner",
      "status": "active",
      "mfa_enabled": true,
      "last_login": "2026-02-16T09:30:00Z",
      "created_at": "2026-01-15T10:00:00Z"
    },
    {
      "user_id": "usr_a4b5c6",
      "email": "bob@acme.com",
      "name": "Bob Smith",
      "role": "developer",
      "status": "active",
      "mfa_enabled": false,
      "last_login": "2026-02-15T14:20:00Z",
      "created_at": "2026-01-20T11:00:00Z"
    },
    {
      "user_id": "usr_d7e8f9",
      "email": "carol@acme.com",
      "name": "Carol Davis",
      "role": "analyst",
      "status": "invited",
      "mfa_enabled": false,
      "last_login": null,
      "created_at": "2026-02-14T16:00:00Z"
    }
  ],
  "pagination": {
    "cursor": null,
    "has_more": false,
    "total": 3
  }
}

Query Parameters

Parameter	Type	Default	Description
role	string	--	Filter by role
status	string	--	Filter by status (active, invited, suspended)
limit	integer	50	Results per page (max 200)
cursor	string	--	Pagination cursor

Invite User

POST /v1/organizations/{org_id}/users

Invites a user to the organization. An invitation email is sent to the specified address. Requires Owner or Admin role.

Request:

curl -X POST https://api.hatidata.com/v1/organizations/org_a1b2c3d4/users \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dave@acme.com",
    "name": "Dave Wilson",
    "role": "analyst"
  }'

Response 201 Created:

{
  "user_id": "usr_g0h1i2",
  "email": "dave@acme.com",
  "name": "Dave Wilson",
  "role": "analyst",
  "status": "invited",
  "mfa_enabled": false,
  "invitation_expires_at": "2026-02-23T10:00:00Z",
  "created_at": "2026-02-16T10:00:00Z"
}

Field	Type	Required	Description
email	string	Yes	Email address (must be unique within org)
name	string	No	Display name
role	string	Yes	One of: admin, analyst, auditor, developer, service_account

Role Restrictions

• Only Owners can invite users with the admin role
• The owner role cannot be assigned via invitation -- ownership is transferred explicitly
• The service_account role creates a headless account with API key access only

Update User Role

PUT /v1/organizations/{org_id}/users/{user_id}/role

Changes a user's role. Requires Owner or Admin role. Role changes are recorded in the IAM audit trail.

Request:

curl -X PUT https://api.hatidata.com/v1/organizations/org_a1b2c3d4/users/usr_a4b5c6/role \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin"
  }'

Response 200 OK:

{
  "user_id": "usr_a4b5c6",
  "email": "bob@acme.com",
  "name": "Bob Smith",
  "role": "admin",
  "previous_role": "developer",
  "updated_at": "2026-02-16T11:00:00Z",
  "updated_by": "usr_x1y2z3"
}

Field	Type	Required	Description
role	string	Yes	New role: admin, analyst, auditor, developer, service_account

Elevation Restrictions

• Only Owners can promote users to admin
• Admins cannot elevate themselves to owner
• Demoting yourself requires at least one other admin remaining

Remove User

DELETE /v1/organizations/{org_id}/users/{user_id}

Removes a user from the organization. Their API keys are revoked and active sessions are terminated. Requires Owner or Admin role.

Request:

curl -X DELETE https://api.hatidata.com/v1/organizations/org_a1b2c3d4/users/usr_a4b5c6 \
  -H "Authorization: Bearer <jwt>"

Response 200 OK:

{
  "user_id": "usr_a4b5c6",
  "email": "bob@acme.com",
  "removed_at": "2026-02-16T11:30:00Z",
  "removed_by": "usr_x1y2z3",
  "api_keys_revoked": 2,
  "sessions_terminated": 1
}

Owner Removal

The organization Owner cannot be removed. Ownership must be transferred to another user first.

User Status Values

Status	Description
active	User has accepted the invitation and can log in
invited	Invitation sent but not yet accepted
suspended	Access temporarily revoked by an admin

Error Responses

Status	Code	Description
400	VALIDATION_ERROR	Invalid role or missing required fields
401	UNAUTHORIZED	Missing or invalid authentication
403	FORBIDDEN	Insufficient role for the requested operation
404	NOT_FOUND	User or organization not found
409	CONFLICT	Email already registered in this organization