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

# Authorize your integrations using OAuth 2.0

The 1Password Users API for Partners (Public Preview) uses the [OAuth 2.0 client credentials flow](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) to authorize server-to-server integrations with 1Password Enterprise Password Manager (1Password Business tier). 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:

<table>
  <thead>
    <tr>
      <th>Component</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>OAuth token servers</td>

      <td>
        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:

        <ul>
          <li><code>/v1beta1/users/oauth2/token</code></li>
          <li><code>/v1beta1/users/oauth2/revoke</code></li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>Users API resource servers</td>

      <td>
        The servers that host the Users API endpoints. These endpoints validate the access token before returning protected data or performing an action.

        <ul>
          <li>List users: <code>/v1beta1/accounts/\<account\_id>/users</code></li>
          <li>Get a single user: <code>/v1beta1/accounts/\<account\_id>/users/\<user\_id></code></li>
          <li>Suspend a user: <code>/v1beta1/accounts/\<account\_id>/users/\<user\_id>:suspend</code></li>
          <li>Reactivate a user: <code>/v1beta1/accounts/\<account\_id>/users/\<user\_id>:reactivate</code></li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>1Password OAuth application</td>

      <td>
        The OAuth application you configure in your 1Password account for an integration. It generates
        the client credentials and defines what the integration can access.
      </td>
    </tr>

    <tr>
      <td>Integration (client)</td>

      <td>
        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.
      </td>
    </tr>

    <tr>
      <td>Client credentials</td>

      <td>
        The client ID and client secret generated by the OAuth application in 1Password. These are used in calls to the <code>/v1beta1/users/oauth2/token</code> endpoint, to request an access token.
      </td>
    </tr>

    <tr>
      <td>Access token</td>

      <td>
        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 <code>Authorization</code> header in requests to the Users API. You can generate multiple tokens with the integration's client credentials. [Access tokens can be revoked](#revoke-an-access-token) as needed.
      </td>
    </tr>
  </tbody>
</table>

<h2 id="create-an-oauth-application">
  Create an OAuth application in your 1Password account
</h2>

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.

1. [Sign in](https://start.1password.com/signin) to your 1Password account.
2. Select [**Integrations**](https://start.1password.com/integrations/directory) 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](#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](#request-an-access-token) using the OAuth 2.0 client credentials grant.

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.

### Scopes

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

<table>
  <thead>
    <tr>
      <th>Permission</th>
      <th>Access level</th>
      <th>Users API endpoint</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>List users</td>
      <td>Read</td>
      <td><code>GET /v1beta1/accounts/\<account\_id>/users</code></td>
    </tr>

    <tr>
      <td>Get a user</td>
      <td>Read</td>
      <td><code>GET /v1beta1/accounts/\<account\_id>/users/\<user\_id></code></td>
    </tr>

    <tr>
      <td>Suspend a user</td>
      <td>Write</td>
      <td><code>POST /v1beta1/accounts/\<account\_id>/users/\<user\_id>:suspend</code></td>
    </tr>

    <tr>
      <td>Reactivate a user</td>
      <td>Write</td>
      <td><code>POST /v1beta1/accounts/\<account\_id>/users/\<user\_id>:reactivate</code></td>
    </tr>
  </tbody>
</table>

## 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 request endpoint](/users-api/request-access-token).

### Authorization endpoints

The region of the OAuth token endpoint must be the same as the [region of the 1Password account](https://support.1password.com/regions/).

| 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:

<table>
  <thead>
    <tr>
      <th>Request element</th>
      <th>Value</th>
      <th>Required</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Header</td>
      <td><code>Authorization: Basic \<base64(client\_id:client\_secret)></code></td>
      <td><span class="badge badge--primary">Yes</span></td>
      <td>HTTP Basic Authentication header that includes your base64-encoded client credentials.</td>
    </tr>

    <tr>
      <td>Header</td>
      <td><code>Content-Type: application/x-www-form-urlencoded</code></td>
      <td><span class="badge badge--primary">Yes</span></td>
      <td>Indicates that the request body is URL-form-encoded.</td>
    </tr>

    <tr>
      <td>Body parameter</td>
      <td><code>grant\_type=client\_credentials</code></td>
      <td><span class="badge badge--primary">Yes</span></td>
      <td>Specifies the OAuth 2.0 client credentials grant.</td>
    </tr>

    <tr>
      <td>Body parameter</td>
      <td><code>scope=openid</code></td>
      <td><span class="badge badge--secondary">No</span></td>
      <td>(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`.</td>
    </tr>
  </tbody>
</table>

### Example token request

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

<Tabs queryString="authorization-header" groupId="authorization">
  <Tab title="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 (`:`).

       ```
       <client_id>:<client_secret>
       ```

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

       ```
       12345a67-bcde-89f0-123a-45bcdef678ga:hIjKLm1NoP.Q~rstUVwXYZabcD
       ```

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

       ```shell theme={null}
       printf '%s' "12345a67-bcde-89f0-123a-45bcdef678ga:hIjKLm1NoP.Q~rstUVwXYZabcD" | base64
       #code-result
       MTIzNDVhNjctYmNkZS04OWYwLTEyM2EtNDViY2RlZjY3OGdhOmhJaktMbTFOb1AuUX5yc3RVVndYWVphYmNE
       ```

    3. Make a POST call to the [`v1beta1/users/oauth2/token` endpoint](/users-api/request-access-token) 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:

       ```http theme={null}
       POST /v1beta1/users/oauth2/token HTTP/1.1
       Host: api.1password.com
       Content-Type: application/x-www-form-urlencoded
       Authorization: Basic MTIzNDVhNjctYmNkZS04OWYwLTEyM2EtNDViY2RlZjY3OGdhOmhJaktMbTFOb1AuUX5yc3RVVndYWVphYmNE

       grant_type=client_credentials&scope=openid
       ```
  </Tab>

  <Tab title="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 (`:`).

       ```
       <client_id>:<client_secret>
       ```

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

       ```
       12345a67-bcde-89f0-123a-45bcdef678ga:hIjKLm1NoP.Q~rstUVwXYZabcD
       ```

    2. Make a POST call to the [`v1beta1/users/oauth2/token` endpoint](/users-api/request-access-token) 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:

       ```shell theme={null}
       curl -X POST <base_url>/v1beta1/users/oauth2/token \
         --header "Content-Type: application/x-www-form-urlencoded" \
         --user "<client_ID>:<client_secret>" \
         --data "grant_type=client_credentials&scope=openid"
       ```

       Example request:

       ```shell theme={null}
       curl -X POST https://api.1password.com/v1beta1/users/oauth2/token \
         --header "Content-Type: application/x-www-form-urlencoded" \
         --user "12345a67-bcde-89f0-123a-45bcdef678ga:hIjKLm1NoP.Q~rstUVwXYZabcD" \
         --data "grant_type=client_credentials&scope=openid"
       ```
  </Tab>
</Tabs>

## 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:

```json theme={null}
{
  "access_token": "ory_at_...",
  "expires_in": 900,
  "scope": "openid",
  "token_type": "bearer"
}
```

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:

```shell theme={null}
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](/users-api/list-users) in an account, with the access token included in the `Authorization` header:

```shell theme={null}
curl --request GET \
  --url "https://api.1password.com/v1beta1/accounts/1AB2CDEFGHZYXWVUTSRHGFEDCBAMN/users" \
  --header "Authorization: Bearer ory_at_..." \
  --header "User-Agent: Acme/1.0.0"
```

## 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 account or in your integration.

### Use the revoke token endpoint

Use the [`/v1beta1/users/oauth2/revoke` endpoint](/users-api/revoke-access-token) to revoke a token. For example:

```shell theme={null}
curl -X POST https://api.1password.com/v1beta1/users/oauth2/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`. The endpoint may also return `200 OK` if the submitted token was already invalid.

### Revoke the integration in your 1Password account

You can delete 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.

1. [Sign in](https://start.1password.com/signin) to your 1Password account.
2. Select [**Integrations**](https://start.1password.com/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.