> ## Documentation Index
> Fetch the complete documentation index at: https://www.1password.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# List users

Retrieve a list of users in a 1Password account. Use query parameters to filter by users state (active or suspended).

<table>
  <thead>
    <tr>
      <th>Method</th>
      <th>Endpoint URL</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>GET</code></td>
      <td><code>\<base\_url>/v1beta1/accounts/\<account\_id>/users</code></td>
    </tr>
  </tbody>
</table>

## Make a request

### Request headers

Include the following headers:

* `Authorization: Bearer <YOUR_ACCESS_TOKEN>`
* `User-Agent: <CompanyOrProductName>/<version>`

### Path parameters

<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Type</th>
      <th>Required</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>account\_id</code></td>
      <td>string</td>
      <td><span class="badge badge--primary">Yes</span></td>
      <td>The unique identifier of the 1Password account.</td>
    </tr>
  </tbody>
</table>

### Query parameters

<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Type</th>
      <th>Required</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>filter</code></td>
      <td>string</td>
      <td><span class="badge badge--secondary">No</span></td>

      <td>
        Filter users by state.
        Supported values:

        <ul>
          <li><code>user.isActive()</code></li>
          <li><code>user.isSuspended()</code></li>
        </ul>

        Omit or leave empty to return both.
        Invalid values result in an <code>InvalidArgument</code> error.
      </td>
    </tr>

    <tr>
      <td><code>max\_page\_size</code></td>
      <td>integer</td>
      <td><span class="badge badge--secondary">No</span></td>
      <td>The maximum number of user records to return per page, up to 1000. The default setting is 25 if no maximum page size is specified.</td>
    </tr>
  </tbody>
</table>

### Example requests

Retrieve a list of all users in a 1Password account, with a query parameter to specify a maximum of 100 records per page:

```shell theme={null}
curl --request GET \
  --url "https://api.1password.com/v1beta1/accounts/<account_id>/users?max_page_size=100"  \
	--header "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
	--header "User-Agent: <CompanyOrProductName>/<version>"
```

Retrieve a list of all suspended users in a 1Password account, with a maximum of 100 user records returned per page:

```shell theme={null}
curl --request GET \
  --url "https://api.1password.com/v1beta1/accounts/<account_id>/users?filter=user.isSuspended()&max_page_size=100" \
	--header "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
	--header "User-Agent: <CompanyOrProductName>/<version>"
```

Fetch the next page of user records in the list using the `next_page_token` returned from a previous request. Include the token in the `page_token` query parameter:

```shell theme={null}
curl --request GET \
  --url "https://api.1password.com/v1beta1/accounts/<account_id>/users?page_token=CAIQAg" \
	--header "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
	--header "User-Agent: <CompanyOrProductName>/<version>"
```

## Receive a response

A successful response returns `200 OK` with a list of users ([`ListUsersResponse` object](#listusersresponse-object)) in the specified 1Password account matching your query parameters (if any exist), along with a `next_page_token` if there are more pages of results to fetch.

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "IR7VJHJ36JHINBFAD7V2T5MP3E",
      "email": "wendy_appleseed@agilebits.com",
      "display_name": "Wendy Appleseed",
      "state": "ACTIVE",
      "create_time": "2024-01-15T10:30:00Z",
      "path": "accounts/ACCOUNT123/users/IR7VJHJ36JHINBFAD7V2T5MP3E"
    },
    {
      "id": "56YE2TYN2VFYRLNSHKPW5NVT5E",
      "email": "riley_smith@example.com",
      "display_name": "Riley Smith",
      "state": "SUSPENDED",
      "create_time": "2024-03-20T09:15:00Z",
      "path": "accounts/ACCOUNT123/users/56YE2TYN2VFYRLNSHKPW5NVT5E"
    }
  ],
  "next_page_token": "CAIQAg"
}
```

### Response schemas

#### ListUsersResponse object

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>results</code></td>
      <td>Array of [<code>User</code> objects](#user-object)</td>
      <td>List of users returned for this page.</td>
    </tr>

    <tr>
      <td><code>next\_page\_token</code></td>
      <td>string</td>
      <td>Base64-encoded opaque token for fetching the next page of results, if available. The returned token can be used with the <code>page\_token</code> query parameter.</td>
    </tr>
  </tbody>
</table>

##### User object

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>id</code></td>
      <td>string</td>
      <td>User UUID.</td>
    </tr>

    <tr>
      <td><code>email</code></td>
      <td>string</td>
      <td>User email address.</td>
    </tr>

    <tr>
      <td><code>display\_name</code></td>
      <td>string</td>
      <td>User display name.</td>
    </tr>

    <tr>
      <td><code>state</code></td>
      <td>string</td>
      <td>User state. Possible values: <code>STATE\_UNSPECIFIED</code>, <code>ACTIVE</code>, <code>SUSPENDED</code>.</td>
    </tr>

    <tr>
      <td><code>create\_time</code></td>
      <td>string</td>
      <td>Date and time when the user was created. Uses the <a href="https://datatracker.ietf.org/doc/html/rfc3339">RFC 3339 standard <Icon icon="arrow-up-right-from-square" /></a>.</td>
    </tr>

    <tr>
      <td><code>path</code></td>
      <td>string</td>
      <td>Resource path for the user. Format: <code>accounts/\<account\_id>/users/\<user\_id></code>.</td>
    </tr>
  </tbody>
</table>