Authorize your integrations using OAuth 2.0

The 1Password Users API for Partners (Public Preview) uses the OAuth 2.0 client credentials flow to authorize server-to-server integrations with 1Password Enterprise Password Manager (EPM). In this approach, an application authenticates using its client credentials to obtain a short-lived, scoped access token only when needed, rather than storing a static token for extended periods. This simplifies token rotation and reduces the impact if an access token is leaked.

How OAuth 2.0 authorization works

The OAuth 2.0 client credentials grant allows your integration to authenticate directly with its own credentials, so no end-user redirect or authorization code exchange is required during token creation. The main components of the authorization flow for authorizing requests to the Users API include:

Component	Description
OAuth token servers	The servers that host the endpoints to make OAuth authorization requests. You can call these endpoints to request and revoke OAuth 2.0 access tokens to use with your integrations: /v1beta1/users/oauth2/token /v1beta1/users/oauth2/revoke
Users API resource servers	The servers that host the Users API endpoints. These endpoints validate the access token before returning protected data or performing an action. List users: /v1beta1/accounts/<account_id>/users Get a single user: /v1beta1/accounts/<account_id>/users/<user_id> Suspend a user: /v1beta1/accounts/<account_id>/users/<user_id>:suspend Reactivate a user: /v1beta1/accounts/<account_id>/users/<user_id>:reactivate
1Password OAuth application	The OAuth application you configure in your 1Password EPM account for an integration. It generates the client credentials and defines what the integration can access.
Integration (client)	The application, service, or automation that uses your client credentials to request an access token, then uses that token to make calls to the Users API.
Client credentials	The client ID and client secret generated by the OAuth application in 1Password. These are used in calls to the /v1beta1/users/oauth2/token endpoint, to request an access token.
Access token	The opaque bearer token returned by the token request endpoint. Access tokens have a lifespan of 15 minutes (900 seconds). The access token is sent in the Authorization header in requests to the Users API. You can generate multiple tokens with the integration's client credentials. Access tokens can be revoked as needed.

Create an OAuth application in your 1Password Enterprise Password Manager account

To get started with the Users API, create an OAuth application in your 1Password EPM account. This will generate the client credentials your integration will use to request an access token.

1. Sign in to your 1Password EPM 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. For example: https://myapp.com/oauth/callback. The URL must use the HTTPS protocol. If you don't have a redirect URL, you can enter a placeholder (for example,https://example.com/callback), then add your URL later.
   • 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.

You can now use your generated client ID and client secret to request an access token using the OAuth 2.0 client credentials grant.

Scopes

Choose the least-privileged permissions your integration needs. The available scopes are:

Permission	Access level	Users API endpoint
List users	Read	GET /v1beta1/accounts/<account_id>/users
Get a user	Read	GET /v1beta1/accounts/<account_id>/users/<user_id>
Suspend a user	Write	POST /v1beta1/accounts/<account_id>/users/<user_id>:suspend
Reactivate a user	Write	POST /v1beta1/accounts/<account_id>/users/<user_id>:reactivate

Request an access token

After you create the OAuth application and save the client credentials in your 1Password EPM account, request an OAuth access token from the token request endpoint.

Authorization endpoints

The region of the OAuth token endpoint must be the same as the region of the 1Password EPM account.

Account domain	Request token endpoint	Revoke Token endpoint
1Password.com	https://api.1password.com/v1beta1/users/oauth2/token	https://api.1password.com/v1beta1/users/oauth2/revoke
1Password.ca	https://api.1password.ca/v1beta1/users/oauth2/token	https://api.1password.ca/v1beta1/users/oauth2/revoke
1Password.eu	https://api.1password.eu/v1beta1/users/oauth2/token	https://api.1password.eu/v1beta1/users/oauth2/revoke

Token request headers and body parameters

Use the following request headers and body parameters to request an access token:

Request element	Value	Required	Description
Header	Authorization: Basic <base64(client_id:client_secret)>	Yes	HTTP Basic Authentication header that includes your base64-encoded client credentials.
Header	Content-Type: application/x-www-form-urlencoded	Yes	Indicates that the request body is URL-form-encoded.
Body parameter	grant_type=client_credentials	Yes	Specifies the OAuth 2.0 client credentials grant.
Body parameter	scope=openid	No	(Optional) If included, the scope value must be openid. If omitted, the authorization server uses the default scope for the OAuth client, which will always be openid.

Example token request

Make a POST call to the v1beta1/users/oauth2/token endpoint to request an access token. Include your client ID and client secret, along with any required headers and request parameters.

HTTP request

If you use raw HTTP to send a request, you'll need to base64-encode your OAuth client credentials before you send the request.

1. Join your client ID and client secret as a single string, separated by a colon (:).

   For example, if your client id is 12345a67-bcde-89f0-123a-45bcdef678ga and your client secret is hIjKLm1NoP.Q~rstUVwXYZabcD the string would be:

2. Base64-encode your client credentials string using your preferred tool or utility. For example, from the command line you can use:

   See result...

3. Make a POST call to the v1beta1/users/oauth2/token endpoint to request an access token. Include any required headers and request parameters, and use the base64-encoded client credentials string in the Authorization header. For example:

Curl request

If you're using curl, you can pass the client credentials in the --user authorization parameter. Curl takes the raw client_id:client_secret string and automatically converts it to base64-encoded string and sends the encoded credentials string in the HTTP Basic authentication header.

1. Join your client ID and client secret as a single string, separated by a colon (:).

   For example, if your client id is 12345a67-bcde-89f0-123a-45bcdef678ga and your client secret is hIjKLm1NoP.Q~rstUVwXYZabcD the string would be:

2. Make a POST call to the v1beta1/users/oauth2/token endpoint to request an access token. Include any required headers and request parameters, and use the raw client_id:client_secret string in the --user authorization parameter. Access token request structure:

   Example request:

Receive an access token

A successful response returns an opaque bearer token that your integration can use with calls to the Users API. For example:

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

The OAuth client credential flow is designed so clients must handle token renewal by requesting a new access token whenever the current token expires. Refresh tokens aren't supported.

Use the access token with the Users API

Include the access token in the Authorization header for requests to the Users API.

Request structure:

Example request to retrieve a list of users in an account, with the access token included in the Authorization header:

Revoke an access token

You can revoke a token when it's no longer needed using the OAuth revoke token endpoint. You can also revoke a token by deleting the OAuth application in your 1Password EPM account or in your integration.

Use the revoke token endpoint

Use the /v1beta1/users/oauth2/revoke endpoint to revoke a token. For example:

A successful revocation request returns 200 OK. The endpoint may also return 200 OK if the submitted token was already invalid.

Revoke the integration in 1Password EPM

You can delete the OAuth application in your 1Password EPM account. This will remove the application from your active integrations and revoke all access tokens generated with the client credentials for that integration.

1. Sign in to your 1Password EPM account.
2. Select Integrations in the sidebar.
3. Select the active OAuth Application for your integration.
4. Select Revoke integration, then enter your account password and revoke the integration.

Delete the client

If you decommission an integration and delete the client, all access tokens for the integration are automatically revoked.