Skip to main content

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.

Public preview features are not guaranteed. The Users API is currently in public preview. During the public preview, functionality may be added, changed, or removed at any time. If you’re having trouble, you can contact 1Password support for help.
You can use the 1Password Users API for Partners (public preview) 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 user details, and suspend or reactivate users in a 1Password account.

​
Requirements

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

​
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.
  1. Sign in to your 1Password account.
  2. 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.
  3. Select OAuth Application.
  4. Configure your OAuth application:
    • Application name: Enter a name to help you identify the integration.
    • Description: (Optional) Add a description with additional information about your OAuth application.
    • Redirect URL: Enter the redirect URL registered with your OAuth provider for your integration. The URL must use the HTTPS protocol. For example: https://myapp.com/oauth/callback.
    • Scopes: Select one or more of the scopes from the “Select scopes” list, according to the access required for your integration: get user, list users, suspend users, and reactivate users.
  5. Select Generate credentials to generate your client ID and client secret.
  6. Select Save in 1Password, then select the vault where you want to save your client credentials. The client secret is only shown once, so make sure to save it before you continue.
The content of the OAuth application can’t be updated after it’s created. If you need to change the redirect URL, scopes, or any other information, you can create a new application.

​
Step 2: Request an access token

After you create the OAuth application in your 1Password account, use your generated client ID and client secret to request an access token using the OAuth 2.0 client credentials grant. Make a POST call to the v1beta1/users/oauth2/token endpoint and include any required headers and request parameters. Send your client ID and client secret in the HTTP Basic authentication header as a base64-encoded string. If you use curl , you can pass the client credentials in the --user authorization parameter. Curl will then encode your credentials and send them in the HTTP Basic header. For example: 
curl -X POST https://api.1password.com/v1beta1/users/oauth2/token \
--header "Content-Type: application/x-www-form-urlencoded" \
--user "<client_ID>:<client_secret>" \
--data "grant_type=client_credentials&scope=openid"
A successful response will return an access token. For example: 
{
  "access_token": "ory_at_...",
  "expires_in": 900,
  "scope": "openid",
  "token_type": "bearer"
}
Learn more about OAuth 2.0 authorization in the Users API.

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

Send a request to the API to confirm everything works. Include your access token in the Authorization header. Make sure the endpoint you call can be used with the scopes set for the access token, and include any required headers and parameters. For example, if your access token is scoped to list all users, the following API call will retrieve a list of users for your specified 1Password account. Use the max_page_size query parameter if you want to limit the number of results per page: 
curl -X GET \
"https://api.1password.com/v1beta1/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. Use the token with the page_token query parameter to fetch the next page of results. For example: 
{
"results": [
{
"id": "USER1234567890ABCDEF12",
"email": "wendy.appleseed@agilebits.com",
"display_name": "Wendy Appleseed",
"state": "ACTIVE",
"create_time": "2024-01-15T10:30:00Z",
"path": "accounts/ACCOUNT123/users/USER1234567890ABCDEF12"
},
...
],
"next_page_token": "CAIQAg"
}

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

Use the 1Password Users API for Partners (public preview) to build your own client that connects your 1Password account with your security automation platform. See the API reference and documentation about the public preview API to learn more. 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.

​
Learn more