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. 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. 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 EPM account would look like this:

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

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

All resource endpoint paths and methods

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

HTTP method	Endpoint path
GET	/v1beta1/accounts/<account_id>/users Retrieves a list of users in a 1Password EPM account.
GET	/v1beta1/accounts/<account_id>/users/<user_id> Retrieves user details for a single user in a 1Password EPM account.
POST	/v1beta1/accounts/<account_id>/users/<user_id>:suspend Suspends a single user in a 1Password EPM account.
POST	/v1beta1/accounts/<account_id>/users/<user_id>:suspend Reactivates a single suspended user in a 1Password EPM account.

Authorization

The Users API uses the OAuth 2.0 authorization framework to allow an application to act on behalf of your organization. The authorization process uses the client credentials grant flow to issue access tokens to authenticated clients:

1. Create an OAuth application in your 1Password EPM account to generate scoped client credentials.
2. Make POST call to the OAuth 2.0 token request endpoint 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.

Requests

Request methods

The Users API uses the following standard HTTP request methods.

Method	Used for
GET	List users and retrieve a single user.
POST	Suspend and reactivate a user.

Request headers

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

Request header	Required	Description
Authorization	Yes	All requests to the Users API must include this header with the access token for your OAuth application. For example: Authorization: Bearer <YOUR_ACCESS_TOKEN>
User-Agent	No	Partner integrations should send an identifiable User-Agent header so requests can be attributed to a specific integration. This helps with support and troubleshooting, and with analytics on integration usage. For example: -H "User-Agent: <CompanyOrProductName>/<version>", User-Agent: AcmeSOAR/1.0.0.
Content-Type	Yes	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: Content-Type: application/x-www-form-urlencoded.

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.