EndUser Management

Overview

The EndUser Management API provides endpoints for managing end user accounts within a tenant. In addition to creating, updating, and deleting users, operations such as suspend, lock, and anonymize are available.

Endpoint List

Method	Endpoint	Description
GET	`/api/admin/users`	List users
GET	`/api/admin/users/:id`	Get user details
POST	`/api/admin/users`	Create user
PUT	`/api/admin/users/:id`	Update user
DELETE	`/api/admin/users/:id`	Delete user
POST	`/api/admin/users/:id/suspend`	Suspend user
POST	`/api/admin/users/:id/unsuspend`	Unsuspend user
POST	`/api/admin/users/:id/lock`	Lock user
POST	`/api/admin/users/:id/unlock`	Unlock user
POST	`/api/admin/users/:id/anonymize`	Anonymize user
POST	`/api/admin/users/:id/retry-pii`	Retry PII sync
DELETE	`/api/admin/users/:id/pii`	Delete PII

List Users

Retrieve a list of users within the tenant.

Endpoint

GET /api/admin/users

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	-	Number of items (default: 20, max: 100)
`cursor`	string	-	Pagination cursor
`search`	string	-	Search query (email, name)
`status`	string	-	Status filter (`active`, `suspended`, `locked`)
`role`	string	-	Role filter
`created_after`	integer	-	After creation date (Unix timestamp)
`created_before`	integer	-	Before creation date (Unix timestamp)

Request Example

curl -X GET "https://{tenant-domain}/api/admin/users?limit=20&status=active" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "items": [
    {
      "id": "usr_abc123",
      "email": "[email protected]",
      "name": "John Doe",
      "status": "active",
      "email_verified": true,
      "created_at": 1705881600,
      "updated_at": 1705968000,
      "last_login_at": 1706054400
    }
  ],
  "total": 150,
  "cursor": "eyJpZCI6InVzcl9hYmMxMjMifQ=="
}

Get User Details

Retrieve detailed information for a specified user.

Endpoint

GET /api/admin/users/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string	✓	User ID

Request Example

curl -X GET "https://{tenant-domain}/api/admin/users/usr_abc123" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "usr_abc123",
  "email": "[email protected]",
  "name": "John Doe",
  "status": "active",
  "email_verified": true,
  "phone": "+1-555-123-4567",
  "phone_verified": true,
  "profile": {
    "picture": "https://example.com/avatar.jpg",
    "locale": "en",
    "timezone": "America/New_York"
  },
  "metadata": {
    "department": "Engineering"
  },
  "created_at": 1705881600,
  "updated_at": 1705968000,
  "last_login_at": 1706054400,
  "login_count": 42,
  "failed_login_attempts": 0
}

Error Responses

HTTP Status	Error Code	Description
404	`user_not_found`	User not found

Create User

Create a new user.

Endpoint

POST /api/admin/users

Request Body

Field	Type	Required	Description
`email`	string	✓	Email address
`name`	string	-	Display name
`password`	string	-	Password (invitation email sent if not specified)
`phone`	string	-	Phone number
`email_verified`	boolean	-	Mark as email verified
`phone_verified`	boolean	-	Mark as phone verified
`profile`	object	-	Profile information
`metadata`	object	-	Custom metadata
`send_welcome_email`	boolean	-	Send welcome email (default: true)

Request Example

curl -X POST "https://{tenant-domain}/api/admin/users" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "New User",
    "password": "SecurePassword123!",
    "email_verified": true,
    "profile": {
      "locale": "en",
      "timezone": "America/New_York"
    },
    "metadata": {
      "department": "Sales"
    }
  }'

Response Example

{
  "id": "usr_xyz789",
  "email": "[email protected]",
  "name": "New User",
  "status": "active",
  "email_verified": true,
  "created_at": 1706140800,
  "updated_at": 1706140800
}

Error Responses

HTTP Status	Error Code	Description
409	`email_already_exists`	Email address is already in use
422	`validation_error`	Invalid input data

Update User

Update existing user information.

Endpoint

PUT /api/admin/users/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string	✓	User ID

Request Body

Field	Type	Required	Description
`email`	string	-	Email address
`name`	string	-	Display name
`phone`	string	-	Phone number
`email_verified`	boolean	-	Email verification status
`phone_verified`	boolean	-	Phone verification status
`profile`	object	-	Profile information
`metadata`	object	-	Custom metadata

Request Example

curl -X PUT "https://{tenant-domain}/api/admin/users/usr_abc123" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe (Updated)",
    "metadata": {
      "department": "Marketing"
    }
  }'

Response Example

{
  "id": "usr_abc123",
  "email": "[email protected]",
  "name": "John Doe (Updated)",
  "status": "active",
  "updated_at": 1706227200
}

Delete User

Delete a user.

Endpoint

DELETE /api/admin/users/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string	✓	User ID

Request Example

curl -X DELETE "https://{tenant-domain}/api/admin/users/usr_abc123" \
  -H "Authorization: Bearer {token}"

Response

Status code 204 No Content (no body)

Suspend User

Temporarily suspend a user. Suspended users cannot log in.

Endpoint

POST /api/admin/users/:id/suspend

Path Parameters

Parameter	Type	Required	Description
`id`	string	✓	User ID

Request Body

Field	Type	Required	Description
`reason`	string	-	Suspension reason

Request Example

curl -X POST "https://{tenant-domain}/api/admin/users/usr_abc123/suspend" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Terms of service violation"
  }'

Response Example

{
  "id": "usr_abc123",
  "status": "suspended",
  "suspended_at": 1706313600,
  "suspended_reason": "Terms of service violation"
}

Unsuspend User

Reactivate a suspended user.

Endpoint

POST /api/admin/users/:id/unsuspend

Request Example

curl -X POST "https://{tenant-domain}/api/admin/users/usr_abc123/unsuspend" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "usr_abc123",
  "status": "active",
  "unsuspended_at": 1706400000
}

Lock User

Lock a user. Typically used when suspicious access is detected.

Endpoint

POST /api/admin/users/:id/lock

Request Example

curl -X POST "https://{tenant-domain}/api/admin/users/usr_abc123/lock" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Suspicious login attempts detected"
  }'

Unlock User

Unlock a locked user.

Endpoint

POST /api/admin/users/:id/unlock

Request Example

curl -X POST "https://{tenant-domain}/api/admin/users/usr_abc123/unlock" \
  -H "Authorization: Bearer {token}"

Anonymize User

Anonymize user personal information for compliance with privacy regulations such as GDPR.

Endpoint

POST /api/admin/users/:id/anonymize

Request Example

curl -X POST "https://{tenant-domain}/api/admin/users/usr_abc123/anonymize" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "usr_abc123",
  "status": "anonymized",
  "anonymized_at": 1706486400
}

Retry PII Sync

Retry synchronization for users where PII database sync failed.

Endpoint

POST /api/admin/users/:id/retry-pii

Request Example

curl -X POST "https://{tenant-domain}/api/admin/users/usr_abc123/retry-pii" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "usr_abc123",
  "pii_sync_status": "synced",
  "pii_synced_at": 1706572800
}

Delete PII

Delete only the user’s PII (Personally Identifiable Information). Core data is retained.

Endpoint

DELETE /api/admin/users/:id/pii

Request Example

curl -X DELETE "https://{tenant-domain}/api/admin/users/usr_abc123/pii" \
  -H "Authorization: Bearer {token}"

Response

Status code 204 No Content (no body)