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

# Request an OAuth 2.0 access token

Request an access token to authorize calls to the 1Password Users API for Partners (Public Preview) using the [OAuth 2.0 client credentials grant](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4).

<table>
  <thead>
    <tr>
      <th>HTTP Method</th>
      <th>Endpoint URL</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>POST</code></td>
      <td><code>\<base\_url>/v1beta1/users/oauth2/token</code></td>
    </tr>
  </tbody>
</table>

Replace `<base_url>` with the regional base URL for the account you want to access:

| Region        | Base URL                    |
| ------------- | --------------------------- |
| 1Password.com | `https://api.1password.com` |
| 1Password.ca  | `https://api.1password.ca`  |
| 1Password.eu  | `https://api.1password.eu`  |

## Make a request to get an access token

Access tokens authorize OAuth applications to send requests to the Users API resource endpoints. After obtaining an access token, include it in the `Authorization` header when calling Users API endpoints.

Requests to this endpoint require the client ID and client secret credentials that were generated when you [created the OAuth application](/users-api/get-started#step-1-create-an-oauth-application). Send those credentials using HTTP Basic authentication.

Learn more about how to [request an access token](/users-api/authorization#request-an-access-token).

### Request headers

Include the following request headers:

<table>
  <thead>
    <tr>
      <th>Header</th>
      <th>Value</th>
      <th>Required</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>Authorization</code></td>
      <td><code>Authorization: Basic \<base64(client\_id:client\_secret)></code></td>
      <td><span class="badge badge--primary">Yes</span></td>
      <td>The HTTP Basic authentication header. Your client credentials must be sent as a base64-encoded string with this header.</td>
    </tr>

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

### Request body parameters

<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Type</th>
      <th>Required</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>grant\_type</code></td>
      <td>string</td>
      <td><span class="badge badge--primary">Yes</span></td>
      <td>The OAuth 2.0 grant type. The value must be <code>client\_credentials</code>.</td>
    </tr>

    <tr>
      <td><code>scope</code></td>
      <td>string</td>
      <td><span class="badge badge--secondary">No</span></td>
      <td>The granted scope associated with the access token. 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 requests

Send the client ID and client secret as a [base64-encoded string using HTTP Basic authentication](/users-api/authorization#example-token-request). In a curl request, the `--user "<client_ID>:<client_secret>"` authorization parameter encodes and sends the `Authorization` header for you.

Request an access token using HTTP:

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

To request an access token using curl, the requested would be structured  as follows:

```shell theme={null}
curl --request POST \
  --url "<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"
```

For example:

```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"
```

## Receive a response

A successful response returns `200 OK` with a [TokenResponse object](#tokenresponse-object).

### Example response

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

Use the returned token to authorize subsequent requests to the Users API:

```
Authorization: Bearer <YOUR_ACCESS_TOKEN>
```

This flow doesn't support refresh tokens. When the token expires, request a new access token from the token endpoint.

### Response schemas

#### TokenResponse object

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>access\_token</code></td>
      <td>string</td>
      <td>The opaque OAuth 2.0 access token used to authorize API requests.</td>
    </tr>

    <tr>
      <td><code>expires\_in</code></td>
      <td>integer</td>
      <td>The lifetime of the access token in seconds. The default lifespan of a token is 900 seconds (15 minutes) unless it is revoked.</td>
    </tr>

    <tr>
      <td><code>scope</code></td>
      <td>string</td>
      <td>The granted scope for the access token. In the verified response example, this value will always be <code>openid</code>.</td>
    </tr>

    <tr>
      <td><code>token\_type</code></td>
      <td>string</td>
      <td>Type of token returned by the authorization server. This value is always <code>Bearer</code>.</td>
    </tr>
  </tbody>
</table>

If the request is malformed or contains invalid parameters, the server returns a standard OAuth 2.0 error response. Failed client authentication may return `401 Unauthorized`.

#### Error responses

The endpoint may return standard OAuth 2.0 error responses when the request cannot be processed.

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

  <tbody>
    <tr>
      <td><code>400 Bad Request</code></td>
      <td>The request has a missing or malformed parameter, or an unsupported grant type.</td>
    </tr>

    <tr>
      <td><code>401 Unauthorized</code></td>
      <td>The client credentials are invalid, or the client is inactive.</td>
    </tr>
  </tbody>
</table>