Get started with the 1Password Users API

You can use the 1Password Users API as part of your SOC workflows. Allow an external system, such as a security automation platform, to take access remediation actions in 1Password Enterprise Password Manager (EPM) as part of your incident response process. The Users API can be used to list users, retrieve a user’s details, and suspend or reactivate a user in a 1Password account. This guide walks you through making your first authenticated request.

Requirements

Before you get started with the Users API, you’ll need:

A 1Password Business or 1Password Enterprise Password Manager account (not included with 1Password Teams)
Permissions to manage integrations in your 1Password account (for example, as an owner, administrator, or member of the Security group)

Integrations with the Users API are not currently supported if you use automated provisioning with your 1Password account. You can manage actions, like suspending and reactivating users, through your identity provider.

Step 1: Create an OAuth application in your 1Password account

To call the Users API, you’ll first create an OAuth application in your 1Password account, which generates the client credentials your integration will use to request an access token.

Sign in to your 1Password account.
Select Integrations in the sidebar. If you’ve set up other integrations in your account, you’ll also need to select Directory on the Integrations page.
Select OAuth Application.
Select Client credentials as the grant type, then select Next.
Configure your OAuth application:
- Application name: Enter a name to help you identify the integration.
- Scopes: Select one or more of the scopes from the “Select scopes” list, according to the access required for your integration: view users, suspend user, and reactivate user.
- Description: (Optional) Add a description with additional information about your OAuth application.
When you’re finished, select Next to generate your client ID and client secret.
Select Save in 1Password and choose the vault where you want to save your client credentials. Then select View integration.
The client secret is only shown once, so make sure to save it before you continue.

The scopes of an OAuth application can’t be changed after it’s created. If your integration needs different scopes, you can create a new application. Learn more about how to manage OAuth 2.0 authorization.

Step 2: Request an access token

After you create the OAuth application in your 1Password account, you’ll need an access token to make your first call to the Users API. Using curl on the command line, make a POST call to the /v1/oauth/token endpoint. Pass your client ID and client secret in the --user option so that curl will encode your credentials and send them in the HTTP Basic header. For example:

curl -X POST https://api.1password.com/v1/oauth/token \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --user "<client_id>:<client_secret>" \
  --data "grant_type=client_credentials"

See the example token request in the OAuth authorization guide for more information.

A successful response will return an access token, along with the scopes granted to it. For example:

{
  "access_token": "op_o_c_H3WVOKGN4B7JXQYCQ6DJFAW5ZU_Q2s4ZmVnaGprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1Njc4OWFi",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "users.view users.suspend users.reactivate"
}

Learn more about OAuth 2.0 authorization in the Users API.

Step 3: Send a test request to the Users API

Use your access token in the Authorization header to authorize a request to the Users API. Make sure the endpoint you call can be used with the scopes you set for the access token. For example, if your access token is scoped to list all users, you can make a call to the /v1/accounts/{account}/users endpoint. Make sure the base URL you use in the endpoint matches the region of your 1Password account. To limit the number of results per page, use the max_page_size query parameter. For example:

curl -X GET \
  "https://api.1password.com/v1/accounts/<account_id>/users?max_page_size=5" \
  --header "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  --header "User-Agent: <CompanyOrProductName>/<version>"

A successful request will return a JSON response with an array of users. If additional pages of results are available, the response will also include a next_page_token. For example:

{
  "results": [
    {
      "id": "IR7VJHJ36JHINBFAD7V2T5MP3E",
      "email": "wendy_appleseed@agilebits.com",
      "display_name": "Wendy Appleseed",
      "state": "ACTIVE",
      "create_time": "2024-01-15T10:30:00Z",
      "path": "accounts/WX52YXL2MVEPBK43P3R4XMWKXI/users/IR7VJHJ36JHINBFAD7V2T5MP3E"
    },
    ...
  ],
  "next_page_token": "CAIQAg"
}

If you have more pages of results, take the next_page_token from the response, then use it with the page_token query parameter to fetch the next page of results. Learn more about pagination in the Users API.

Step 4: Connect your 1Password account to an integration

When you can successfully authenticate calls, you can use the API to build your own client that connects your 1Password account with your security automation platform. See the API reference and API conventions to learn more about working with the API. You can also try out one of the connectors built by 1Password partners that leverage the Users API. Check if your preferred platform is in the list of partner integrations.

Try out more examples

You can use the API reference to find more code examples for each endpoint. You can also access the interactive API playground on the reference pages for any of the user endpoints (list, get, suspend, and reactivate). Select Try it in the endpoint header, enter your own values in the input fields, then send requests directly from the playground.

Requests you send from the API playground are routed through the documentation platform’s proxy service. If you prefer to keep your access tokens strictly between your systems and 1Password, copy a code example and run it with your own tools instead.

To use the examples with another tool, select the dropdown menu on a code example and choose which language option you want, select copy , then paste the example code into your preferred testing tool. You can also download the OpenAPI specification files for the Users API and the OAuth API , then use them to feed into code-generation tools, create mock servers, or import into API clients.

​Requirements

​Step 1: Create an OAuth application in your 1Password account

​Step 2: Request an access token

​Step 3: Send a test request to the Users API

​Step 4: Connect your 1Password account to an integration

​Try out more examples

​Learn more

Requirements

Step 1: Create an OAuth application in your 1Password account

Step 2: Request an access token

Step 3: Send a test request to the Users API

Step 4: Connect your 1Password account to an integration

Try out more examples

Learn more