Authorize your integrations using OAuth 2.0

The 1Password Users API uses the OAuth 2.0 client credentials flow to authorize server-to-server integrations with 1Password Business or 1Password Enterprise Password Manager. 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 API endpoints	The endpoints you call to request, check, and revoke OAuth 2.0 access tokens for your integrations: Request an access token: `POST /v1/oauth/token` Introspect an access token: `POST /v1/oauth/introspect` Revoke an access token: `POST /v1/oauth/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: `/v1/accounts/<account_id>/users` Get a single user: `/v1/accounts/<account_id>/users/<user_id>` Suspend a user: `/v1/accounts/<account_id>/users/<user_id>:suspend` Reactivate a user: `/v1/accounts/<account_id>/users/<user_id>:reactivate`
1Password OAuth application	The OAuth application you configure in your 1Password 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 `/v1/oauth/token` endpoint to request an access token.
Access token	The opaque bearer token returned by the token endpoint. Access tokens have a lifespan of 15 minutes (900 seconds) and carry the scopes configured for the OAuth application. 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 account

To get started with the Users API, create an OAuth application in your 1Password account. This will generate 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.

You can now use your generated client ID and client secret to request an access token using the OAuth 2.0 client credentials grant. The scopes of an OAuth application can’t be changed after it’s created. If your integration needs different scopes, create a new application. You can also rotate the client secret of an existing application without creating a new one.

Scopes

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

Scope	Permission	Access level	Users API endpoints
`users.view`	View users	Read	List users: `GET /v1/accounts/<account_id>/users` Get a user: `GET /v1/accounts/<account_id>/users/<user_id>`
`users.suspend`	Suspend user	Write	Suspend a user: `POST /v1/accounts/<account_id>/users/<user_id>:suspend`
`users.reactivate`	Reactivate user	Write	Reactivate a user: `POST /v1/accounts/<account_id>/users/<user_id>:reactivate`

The scopes granted to an access token are listed in the scope field of the token response. A request to a Users API endpoint that isn’t covered by the token’s scopes returns 403 Forbidden. Access tokens are also bound to the 1Password account that owns the OAuth application: a request whose path names a different account returns 403 Forbidden.

Rotate the client secret

If you need to replace your client secret, you can rotate it from the OAuth application in your 1Password account. The new client secret is only shown once, so save it before you continue. When you rotate a client secret, the previous secret stays valid for 6 hours. This grace period allows you to update your integration without downtime. If a client secret is compromised and you need to invalidate it immediately, you can revoke the OAuth application. This invalidates the client credentials and every access token issued to them. You can then create a new OAuth application to generate a new client secret.

Request an access token

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

Authorization endpoints

The OAuth API endpoints are hosted on the same base URL as the Users API. Use the base URL that matches the region of your 1Password account:

Account domain	Base URL
1Password.com	`https://api.1password.com`
1Password.ca	`https://api.1password.ca`
1Password.eu	`https://api.1password.eu`
ent.1password.com	`https://api.ent.1password.com`

Access tokens are specific to the region they were issued in. Request the token from the same base URL that your integration uses for Users API requests; a token issued by one region isn’t accepted by another. Append the endpoint path to the base URL: /v1/oauth/token to request an access token, /v1/oauth/introspect to check whether a token is active, and /v1/oauth/revoke to revoke a token.

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. Recommended. Alternatively, send the credentials as the `client_id` and `client_secret` body parameters instead of this header.
Header	`Content-Type: application/x-www-form-urlencoded`	Yes	Indicates that the request body is sent as URL-encoded form data.
Body parameter	`grant_type=client_credentials`	Yes	Specifies the OAuth 2.0 client credentials grant.
Body parameters	`client_id=<client_id>&client_secret=<client_secret>`	No	An alternative to the `Authorization` header for sending your client credentials. Don’t use both methods in the same request; the request is rejected if you do.

Every token request must include your client credentials. Send them either in the Authorization header (recommended) or as the client_id and client_secret body parameters, but not both.

You don’t request scopes when you request a token. Every access token is issued with the scopes configured for the OAuth application.

Example token request

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

HTTP request
Curl 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.

Join your client ID and client secret as a single string, separated by a colon (:).
<client_id>:<client_secret>
For example, if your client ID is H3WVOKGN4B7JXQYCQ6DJFAW5ZU and your client secret is kq7rV2mXt9pL4wZy8nB1cD6fG3hJ5sA0eUoQ2iR8tYv, the string would be:
H3WVOKGN4B7JXQYCQ6DJFAW5ZU:kq7rV2mXt9pL4wZy8nB1cD6fG3hJ5sA0eUoQ2iR8tYv

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

printf '%s' "H3WVOKGN4B7JXQYCQ6DJFAW5ZU:kq7rV2mXt9pL4wZy8nB1cD6fG3hJ5sA0eUoQ2iR8tYv" | base64
#code-result
SDNXVk9LR040QjdKWFFZQ1E2REpGQVc1WlU6a3E3clYybVh0OXBMNHdaeThuQjFjRDZmRzNoSjVzQTBlVW9RMmlSOHRZdg==

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

POST /v1/oauth/token HTTP/1.1
Host: api.1password.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic SDNXVk9LR040QjdKWFFZQ1E2REpGQVc1WlU6a3E3clYybVh0OXBMNHdaeThuQjFjRDZmRzNoSjVzQTBlVW9RMmlSOHRZdg==

grant_type=client_credentials

If you’re using curl, you can pass the client credentials in the --user option. Curl takes the raw client_id:client_secret string, base64-encodes it, and sends the encoded string in the HTTP Basic authentication header.

Join your client ID and client secret as a single string, separated by a colon (:).
<client_id>:<client_secret>
For example, if your client ID is H3WVOKGN4B7JXQYCQ6DJFAW5ZU and your client secret is kq7rV2mXt9pL4wZy8nB1cD6fG3hJ5sA0eUoQ2iR8tYv, the string would be:
H3WVOKGN4B7JXQYCQ6DJFAW5ZU:kq7rV2mXt9pL4wZy8nB1cD6fG3hJ5sA0eUoQ2iR8tYv

Make a POST call to the /v1/oauth/token endpoint to request an access token. Include the required headers and request parameters, and use the raw client_id:client_secret string in the --user option. Access token request structure:

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

Example request:

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

Receive an access token

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

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

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 credentials 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. Token and introspection responses include Cache-Control: no-store and Pragma: no-cache headers. Make sure your integration doesn’t cache access tokens beyond their lifespan, and store them securely.

Use the access token with the Users API

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

curl --request METHOD \
  --url "<base_url>/<endpoint_path>" \
  --header "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  --header "User-Agent: <CompanyOrProductName>/<version>"

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

curl --request GET \
  --url "https://api.1password.com/v1/accounts/WX52YXL2MVEPBK43P3R4XMWKXI/users" \
  --header "Authorization: Bearer op_o_c_H3WVOKGN4B7JXQYCQ6DJFAW5ZU_Q2s4ZmVnaGprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1Njc4OWFi" \
  --header "User-Agent: Acme/1.0.0"

Check whether an access token is active

If your integration stores access tokens between tasks, you can check whether a token is still active before you use it by calling the /v1/oauth/introspect endpoint with your client credentials. The response includes the token’s scopes and expiry time, or "active": false if the token has expired or been revoked.

Revoke an access token

You can revoke a token when it’s no longer needed using the OAuth revoke endpoint. You can also revoke all tokens for an integration by revoking the OAuth application in your 1Password account.

Use the revoke endpoint

Use the /v1/oauth/revoke endpoint to revoke a token. Authenticate with the client credentials of the OAuth application the token was issued to. For example:

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

A successful revocation request returns 200 OK with an empty body. The endpoint also returns 200 OK if the submitted token was already expired, revoked, or unknown, so revocation requests are safe to retry.

Revoke the integration in your 1Password account

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

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

Delete your integration’s client

If you decommission an integration and delete the client on your own platform, you should also revoke the OAuth application in your 1Password account. Access tokens already issued remain valid until they expire, and the client credentials remain valid until the OAuth application is revoked.

​How OAuth 2.0 authorization works

​Create an OAuth application in your 1Password account

​Scopes

​Rotate the client secret

​Request an access token

​Authorization endpoints

​Token request headers and body parameters

​Example token request

​Receive an access token

​Use the access token with the Users API

​Check whether an access token is active

​Revoke an access token

​Use the revoke endpoint

​Revoke the integration in your 1Password account

​Delete your integration’s client

How OAuth 2.0 authorization works

Create an OAuth application in your 1Password account

Scopes

Rotate the client secret

Request an access token

Authorization endpoints

Token request headers and body parameters

Example token request

Receive an access token

Use the access token with the Users API

Check whether an access token is active

Revoke an access token

Use the revoke endpoint

Revoke the integration in your 1Password account

Delete your integration’s client