> ## 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.

# About the 1Password Users API for Partners (Public Preview)

The 1Password Users API for Partners (public preview) is an enterprise-grade API built on the [OAuth 2.0 authentication framework](https://datatracker.ietf.org/doc/html/rfc6749). With the Users API, you can build integrations that programmatically list users, retrieve user context, suspend users, and reactivate users, supporting modern security workflows and automation use cases.

The API supports standard HTTP methods and is [OpenAPI-compatible](https://spec.openapis.org/oas/v3.1.0.html). All communication between clients and servers is over HTTPS.

## Resource endpoints

The basic structure of an endpoint URL for the Users API includes the base URL and the endpoint path. The endpoint path includes the API endpoint version, the resource(s) you want to access, and any relevant path and query parameters.

### Base URLs

The base URL of an endpoint URL indicates the server that hosts the environment you want to work in.

| Base URL                    | Description                                                          |
| --------------------------- | -------------------------------------------------------------------- |
| `https://api.1password.com` | Server for working with accounts hosted in the 1Password.com region. |
| `https://api.1password.ca`  | Server for working with accounts hosted in the 1Password.ca region.  |
| `https://api.1password.eu`  | Server for working with accounts hosted in the 1Password.eu region.  |

Integrations should be designed to allow the base URL to be configurable to accommodate accounts in different regions.

### Paths and parameters

A basic API endpoint path includes the endpoint version, path resource(s), and any path parameters. For example, a request to fetch a list of users in a 1Password account would look like this:

```
GET https://api.1password.com/v1beta1/accounts/<account_id>/users
```

The path may also include a custom action operation, which is indicated by a colon (`:`) separator and followed by an action verb. For example: `:suspend` or `:reactivate`. Custom actions are placed at the end of the endpoint path and before any query parameters.

You can use query parameters in your API request as optional modifiers after the endpoint path. Use a query separator (`?`) at the end of the endpoint path, then add any query parameters you want to include. Multiple query parameters are separated by a query delimiter (`&`).

Check the [API reference documentation](/users-api/list-users) for more information about the available path and query parameters for each endpoint.

### Example endpoint URLs

This endpoint URL retrieves a list of users for an account in the 1Password.com region. Query filters indicate the response should only list active users in the account (`filter=user.isActive()`) and return a maximum of 100 users per page in the response (`max_page_size=100`).

```
GET https://api.1password.com/v1beta1/accounts/<account_id>/users?filter=user.isActive()&max_page_size=100
```

This example request suspends a specific user in an account in the 1Password.eu region:

```
POST https://api.1password.eu/v1beta1/accounts/<account_id>/users/<user_id>:suspend
```

### All resource endpoint paths and methods

The 1Password Users API for Partners (public preview) includes the following resource endpoint paths and HTTP methods:

<table>
  <thead>
    <tr>
      <th>HTTP method</th>
      <th>Endpoint path</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>GET</code></td>
      <td><code>/v1beta1/accounts/\<account\_id>/users</code><br />Retrieves a list of users in a 1Password account.</td>
    </tr>

    <tr>
      <td><code>GET</code></td>
      <td><code>/v1beta1/accounts/\<account\_id>/users/\<user\_id></code><br />Retrieves user details for a single user in a 1Password account.</td>
    </tr>

    <tr>
      <td><code>POST</code></td>
      <td><code>/v1beta1/accounts/\<account\_id>/users/\<user\_id>:suspend</code><br />Suspends a single user in a 1Password account.</td>
    </tr>

    <tr>
      <td><code>POST</code></td>
      <td><code>/v1beta1/accounts/\<account\_id>/users/\<user\_id>:suspend</code><br />Reactivates a single suspended user in a 1Password account.</td>
    </tr>
  </tbody>
</table>

## Authorization

The Users API uses the [OAuth 2.0 authorization framework](https://datatracker.ietf.org/doc/html/rfc6749) to allow an application to act on behalf of your organization. The authorization process uses the [client credentials grant](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) flow to issue access tokens to authenticated clients:

1. [Create an OAuth application](/users-api/authorization#create-an-oauth-application) in your 1Password account to generate scoped client credentials.
2. Make POST call to the [OAuth 2.0 token request endpoint](/users-api/request-access-token) that includes your client credentials to request a scoped access token.
3. Send the access token in the `Authorization` header when calling the Users API endpoints.
4. Request a new token when the current one expires, or revoke a token when it is no longer needed.

Access tokens have a limited lifespan of 15 minutes (900 seconds), after which the client needs to request a new access token.

Learn more about [how to authorize your integrations using OAuth 2.0](/users-api/authorization).

## Requests

### Request methods

The Users API uses the following standard HTTP request methods.

<table>
  <thead>
    <tr>
      <th>Method</th>
      <th>Used for</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>GET</code></td>
      <td>List users and retrieve a single user.</td>
    </tr>

    <tr>
      <td><code>POST</code></td>
      <td>Suspend and reactivate a user.</td>
    </tr>
  </tbody>
</table>

### Request headers

The following headers are supported in requests to the Users API:

<table>
  <thead>
    <tr>
      <th>Request header</th>
      <th>Required</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>Authorization</code></td>
      <td><span class="badge badge--primary">Yes</span></td>
      <td>All requests to the Users API must include this header with the access token for your OAuth application. For example:<br /><code>Authorization: Bearer \<YOUR\_ACCESS\_TOKEN></code></td>
    </tr>

    <tr>
      <td><code>User-Agent</code></td>
      <td><span class="badge badge--primary">No</span></td>
      <td>Partner integrations should send an identifiable <code>User-Agent</code> header so requests can be attributed to a specific integration. This helps with support and troubleshooting, and with analytics on integration usage. For example:<br /><code>-H "User-Agent: \<CompanyOrProductName>/\<version>"</code>, <code>User-Agent: AcmeSOAR/1.0.0</code>.</td>
    </tr>

    <tr>
      <td><code>Content-Type</code></td>
      <td><span class="badge badge--primary">Yes</span></td>
      <td>Required for requests to OAuth endpoints only. This header indicates that the token request parameters (`grant_type` and `scope`) are sent in the HTTP request body as URL-encoded form fields. For example:<br /><code>Content-Type: application/x-www-form-urlencoded</code>.</td>
    </tr>
  </tbody>
</table>

## Responses

All Users API endpoints described in this documentation return JSON responses. Responses may also include a `next_page_token` if there is more than one page of results.

## Pagination

The Users API for Partners uses token-based pagination passed in the query string.

If you make a call to an API endpoint that will return multiple results, you can use the `max_page_size` query parameter to set the maximum number of records (users) to return per page.

If more than one page of records is available, the JSON response will include an opaque token that identifies the next page of results to retrieve. For example: `"next_page_token": "CAIQAg"`. Include the returned token in the `page_token` query parameter in your next request to that endpoint. Repeat until the response no longer includes a `next_page_token`.

## Rate limits

Requests to the Users API are rate limited as follows:

* 100 requests per minute
* 6000 requests per hour

OAuth client management requests are rate limited as follows:

* Read operations:
  * up to 60 requests per minute
  * up to 3600 requests per hour
* Write operations (such as creating or deleting OAuth clients):
  * up to 10 requests per minute
  * 600 requests per hour

If you exceed the allowed rates, the API will return a `429 Too Many Requests` response with a `Retry-After` header.