# Users

## User Model

### Fields

- **`object`** `"user"`

- **`name`** `string`

- **`email`** `string`

- **`id`** `string`

- **`default_team_id`** `string | null`

   The team the user lands in at sign-in; null falls back to the first team they belong to.

- **`created_at`** [`ISODateString`](/api/users#iso-date-string)

- **`updated_at`** [`ISODateString`](/api/users#iso-date-string)

- **`last_active_at`** [`ISODateString | null`](/api/users#iso-date-string)

   When the user last made an authenticated request. Updated at most once every few minutes.

- **`profile_url`** `string | null`

   URL of the user's avatar image; null when none is set.

- **`role`** [`Role | null`](/api/roles#model)

   The user's role on the team the request is scoped to; null when they have none.

- **`status`** [`UserStatus`](/api/users#user-status)

   `blocked` and `locked` accounts cannot act; `waitlisted` accounts signed up but have not been
   granted access yet.

- **`default_auth_method`** [`AuthMethod`](/api/users#auth-method)

   The sign-in method preselected for the user.

- **`available_auth_methods`** [`AuthMethod[]`](/api/users#auth-method)

   The sign-in methods enabled on the account.

- **`is_totp_enabled`** `boolean`

   Whether an authenticator app is set up for two-factor sign-in.

- **`totp_backup_codes_count`** `number`

   How many unused two-factor backup codes remain.

- **`totp_default_count`** `number`

   How many backup codes a full set contains, for showing "N of M remaining".

- **`password_updated_at`** [`ISODateString | null`](/api/users#iso-date-string)

   When the password was last changed; null when password sign-in is not enabled.

- **`monitor_auto_subscribe`** `boolean`

   Whether the user is automatically subscribed to alert emails for monitors newly created in
   their team.

- **`monitor_cooloff_minutes`** `number`

   Minimum minutes between alert emails about the same monitor.

- **`product_update_notifications`** `boolean`

   Whether the user receives product update emails.

- **`appearance_palette`** `string`

   Color palette the dashboard renders in for this user.

- **`appearance_type_set`** `string`

   Font pairing the dashboard uses.

- **`appearance_accent`** `string`

   Accent color the dashboard uses.

- **`appearance_scale`** `string`

   Interface density preference. Applied to dashboard content at tablet and desktop widths; phones
   always render at full size.

- **`default_ai_model`** [`AiChatSelection | null`](/api/users#ai-chat-selection)

   Selection a new chat opens on. Null when no preference is set. An unavailable saved selection
   requires an explicit replacement; it never silently changes the payer.

- **`default_ai_effort`** [`AiEffortLevel`](/api/users#ai-effort-level)

   How hard the assistant is asked to work on each turn by default.

### Referenced Types

#### ISODateString

`ISODateString`

An ISO 8601 date-time string returned at the JSON API boundary.

#### Scope

`"users" | "roles" | "keys" | "records" | "projects" | "metrics" | "views" | "billing" | "pages" | "monitors" | "alerts" | "chats" | "secrets" | "servers" | "ingest_keys" | "sources" | "domains" | "facets" | "drains" | "pulls" | "checks" | "logs"`

#### ScopeValue

`"read" | "write" | "delete"`

#### UserStatus

`"active" | "blocked" | "waitlisted" | "locked"`

#### AuthMethod

`"magic_link" | "password"`

#### AiChatSelection

`"claude-opus-5-5" | "claude-sonnet-5" | "gpt-6-sol" | "gpt-5.6-terra" | "gpt-6-luna" | "claude-opus-5" | "gpt-5.6-sol" | "gpt-5.6-luna" | "claude-opus-4-6" | "tailglow"`

An explicit choice of Tailglow-managed access or a model using the member's own key.

#### AiEffortLevel

`"low" | "medium" | "high" | "xhigh" | "max"`

How hard a model works on a turn. A model that accepts a narrower range declares it in
`AI_MODEL_CONFIGS[model].efforts`.

## List Users

### Endpoint

Retrieve a list of users in the current team.

```http
GET /v1/users
```

**Scope:** `users:read`

### Query Parameters

- **`order_by`** `string`
  Field used to order the users. Optional. Defaults to `"name"`. Allowed values: `"created_at"`, `"name"`.

- **`name`** [`TextFilter`](/api/users#text-filter)
  Filter by display name. Accepts a filter operator, for example `contains:ada` or `starts_with:ada`. Optional.

- **`status`** [`UserStatus`](/api/users#user-status)
  Filter by status. Accepts a filter operator, for example `in:active,blocked`. Optional.

- **`limit`** `number`
  Maximum number of items to return. Optional. Defaults to `25`. Minimum: `1`. Maximum: `200`.

- **`after`** `string`
  Cursor from `pagination.next_cursor` of a previous response. Returns the resources after that page. Optional.

- **`before`** `string`
  Cursor from `pagination.prev_cursor` of a previous response. Returns the resources before that page. Optional.

- **`sort`** `string`
  Sort direction for the result set. Optional. Defaults to `"desc"`. Allowed values: `"asc"`, `"desc"`.

### Response

```ts
{
  message: string;
  data: User[];
  status: 200;
  error: null;
  pagination: Pagination;
  endpoint: string;
}
```

### Comments

- `after` and `before` are mutually exclusive.

## Retrieve User

### Endpoint

Retrieve a single user.

```http
GET /v1/users/:user_id
```

### Path Parameters

- **`user_id`** `string` -- **Required**
  Unique identifier of the user.

### Response

User retrieved

```ts
{
  message: string;
  data: User;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}
```

### Comments

- You can retrieve your own user, or a user who is a member of your team.

## Update User

### Endpoint

Update a user's profile and preferences.

```http
POST /v1/users/:user_id
```

### Path Parameters

- **`user_id`** `string` -- **Required**
  Unique identifier of the user.

### Request Body

- **`name`** `string`
  Display name for the user. Optional. Minimum length: `2`. Maximum length: `60`.

- **`default_team_id`** `string`
  ID of the team the user lands in after signing in. Optional.

- **`profile_url`** `string`
  Profile image as a JPEG or PNG base64 data URI. Optional.

- **`email`** `string (email)`
  Email address of the user. Optional.

- **`monitor_auto_subscribe`** `boolean`
  Whether the user is subscribed to new monitors automatically. Optional.

- **`monitor_cooloff_minutes`** `integer`
  Minutes to wait before sending another notification for the same monitor. Between 30 and 1440. Optional. Minimum: `30`. Maximum: `1440`.

- **`product_update_notifications`** `boolean`
  Whether the user receives product update emails. Optional.

- **`appearance_palette`** `string`
  Color palette used by the dashboard. Optional. Allowed values: `"light"`, `"dark"`, `"dim"`, `"midnight"`, `"paper"`.

- **`appearance_type_set`** `string`
  Font pairing used by the dashboard. Optional. Allowed values: `"system"`, `"grotesk"`, `"editorial"`, `"geometric"`.

- **`appearance_accent`** `string`
  Accent color used by the dashboard. Optional. Allowed values: `"orange"`, `"azure"`, `"burgundy"`, `"ink"`, `"emerald"`, `"violet"`.

- **`appearance_scale`** `string`
  Interface density used by the dashboard. Optional. Allowed values: `"comfortable"`, `"cozy"`, `"compact"`.

- **`default_ai_model`** [`AiChatSelection`](/api/users#ai-chat-selection)
  Model a new chat opens on. Null clears the preference. An unavailable selection asks the member to choose again; it never changes who pays automatically. Optional.

- **`default_ai_effort`** [`AiEffortLevel`](/api/users#ai-effort-level)
  How hard the assistant is asked to work on each turn by default. Optional.

- **`role_id`** `string`
  ID of the role that grants the user their permissions. Optional.

- **`default_auth_method`** [`AuthMethod`](/api/users#auth-method)
  Method the user signs in with by default. Optional.

- **`status`** [`UserStatus`](/api/users#user-status)
  Status of the user. Optional.

### Response

User updated

```ts
{
  message: string;
  data: User;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}
```

### Comments

- You can only update your own profile.
- `email` cannot be changed here. Sending a different address returns an error.
- `role_id` and `status` are ignored here. Manage a user's role through the team endpoints.
- `default_team_id` must be a team the user is already a member of.
- Setting `default_auth_method` to `password` requires password authentication and MFA to be enabled first.
- `profile_url` images must be at least 256x256 pixels. They are resized and stored as PNG, and the response returns the hosted image URL.
- `profile_url` images must not exceed 5 MB.

## Enable Password Authentication

### Endpoint

Enable password authentication for a user.

```http
POST /v1/users/:user_id/enable_password
```

### Path Parameters

- **`user_id`** `string` -- **Required**
  Unique identifier of the user.

### Response

Password auth has been enabled

```ts
{
  message: string;
  data: null;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}
```

### Comments

- You can only enable password authentication for your own user.
- MFA must be enabled before password authentication can be turned on.

## List User Teams

### Endpoint

Retrieve a list of teams a user belongs to.

```http
GET /v1/users/:user_id/teams
```

### Path Parameters

- **`user_id`** `string` -- **Required**
  Unique identifier of the user.

### Query Parameters

- **`order_by`** `string`
  Field used to order the teams. Optional. Defaults to `"name"`. Allowed values: `"created_at"`, `"name"`.

- **`name`** [`TextFilter`](/api/users#text-filter)
  Filter by team name, written as `operator:value`. For example `contains:acme` or `equals:Acme Inc`. Optional.

- **`status`** [`TeamStatus`](/api/teams#team-status)
  Filter by team status, written as `operator:value`. For example `equals:active` or `in:active,delinquent`. Optional.

- **`billing_plan`** [`BillingPlan`](/api/teams#billing-plan)
  Filter by billing plan, written as `operator:value`. For example `in:pro_v1,enterprise_v1`. Optional.

- **`created_at`** [`DateFilter`](/api/users#date-filter)
  Filter by creation date, written as `operator:value`. For example `gt:2026-01-01` or `between:2026-01-01,2026-02-01`. Optional.

- **`deleted_at`** [`NullableDateFilter`](/api/users#nullable-date-filter)
  Filter by scheduled deletion date. Use `null` for teams that are not scheduled for deletion, `not:null` for teams that are. Optional.

- **`limit`** `number`
  Maximum number of items to return. Optional. Defaults to `25`. Minimum: `1`. Maximum: `200`.

- **`after`** `string`
  Cursor from `pagination.next_cursor` of a previous response. Returns the resources after that page. Optional.

- **`before`** `string`
  Cursor from `pagination.prev_cursor` of a previous response. Returns the resources before that page. Optional.

- **`sort`** `string`
  Sort direction for the result set. Optional. Defaults to `"desc"`. Allowed values: `"asc"`, `"desc"`.

### Response

```ts
{
  message: string;
  data: Team[];
  status: 200;
  error: null;
  pagination: Pagination;
  endpoint: string;
}
```

### Comments

- You can only list your own teams.
- `after` and `before` are mutually exclusive.