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

# OAuth API reference

> The authorize, token, and revoke endpoints for connecting a person's 1Password account to your integration.

Partner preview

1Password uses the OAuth 2.0 authorization code flow ([RFC 6749](https://www.rfc-editor.org/rfc/rfc6749)) with PKCE ([RFC 7636](https://www.rfc-editor.org/rfc/rfc7636)), plus an integration key delivered in the callback fragment. [Connect a user](/agentic-autofill/partners/connect.md) walks through the flow.

## Origins

| Web origin | API origin |
| - | - |
| `https://my.1password.com` | `https://api.1password.com` |

The development environment, `b5dev.eu`, can't show approval prompts with current 1Password app builds. Test on production.

## Scopes

Request both scopes, space-delimited:

| Scope | Allows |
| - | - |
| `brokered-credentials:request-access` | Creating access requests for the person |
| `brokered-credentials:read` | Using the logins the person grants |

## Authorize

```text theme={null}
GET {web origin}/oauth/authorize
```

Called from the person's browser. No version prefix.

| Query parameter | Required | Value |
| - | - | - |
| `response_type` | Yes | `code` |
| `client_id` | Yes | Your OAuth client ID |
| `redirect_uri` | Yes | An exact match for a redirect URI registered on your client |
| `scope` | Yes | `brokered-credentials:request-access brokered-credentials:read`, with the space encoded as `%20` |
| `state` | Yes | A unique, unpredictable value per attempt |
| `code_challenge` | Yes | `BASE64URL(SHA256(code_verifier))` |
| `code_challenge_method` | Yes | `S256` |

### Callback

| Outcome | Redirect |
| - | - |
| Approved, new integration key | `{redirect_uri}?code=...&state=...#integration_key=ops_...` |
| Approved, integration key still active | `{redirect_uri}?code=...&state=...` |
| Declined | `{redirect_uri}?error=access_denied&state=...` |

The query string can also include `iss` and `base_url`.

## Token

```text theme={null}
POST {api origin}/v1/oauth/token
Authorization: Basic base64(<client_id>:<client_secret>)
Content-Type: application/x-www-form-urlencoded
```

Called from your backend. Authenticate with HTTP Basic only. Sending `client_id` in the body as well returns `400 invalid_request`.

### Exchange a code

| Form parameter | Value |
| - | - |
| `grant_type` | `authorization_code` |
| `code` | The code from the callback |
| `redirect_uri` | The same redirect URI you sent to authorize |
| `code_verifier` | The PKCE code verifier |

### Refresh

| Form parameter | Value |
| - | - |
| `grant_type` | `refresh_token` |
| `refresh_token` | The current refresh token |
| `scope` | `brokered-credentials:request-access brokered-credentials:read` |

### Response

```json theme={null}
{
  "access_token": "op_o_u_<user-id>_<secret>",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "op_o_r_<user-id>_<secret>",
  "scope": "brokered-credentials:request-access brokered-credentials:read"
}
```

**access\_token** `string`

Bearer token for extension calls and revocation. Expires after `expires_in` seconds: 15 minutes.

**refresh\_token** `string`

Use once to get a new access token. Each refresh returns a new refresh token and invalidates the old one.

**user\_id** `string`

The person's user ID. Can be present in newer deployments.

Treat both token strings as opaque.

### Errors

| Status | `error` | Cause |
| - | - | - |
| 400 | `invalid_request` | A missing or malformed parameter, no HTTP Basic header (`missing client credentials`), or client credentials sent two ways (`multiple client authentication methods are not allowed`) |
| 400 | `invalid_grant` | The code was already used or has expired, the code verifier or redirect URI doesn't match, or the refresh token was rotated, revoked, or expired |
| 400 | `invalid_scope` | The requested scope isn't allowed |
| 401 | `invalid_client` | Wrong client ID or secret, or a client from another environment (`client authentication failed`) |
| 404 | | The path is missing `/v1`, or the host is the web origin instead of the API origin |

## Revoke

```text theme={null}
POST {api origin}/v1alpha1/oauth-integrations/self:revoke
Authorization: Bearer <access token>
Content-Type: application/json

{}
```

Called from your backend. Ends the person's entire connection to your integration: the consent, the tokens, and the integration key. The access token identifies the connection, so the body is empty.

| Status | Meaning |
| - | - |
| 200, body `{}` | The connection is revoked. Delete the stored tokens, integration key, and references. |
| 403 | The access token is expired or invalid. Refresh it, then retry. |

See [Disconnect a user](/agentic-autofill/partners/disconnect.md).


## Related topics

- [1Password Users API reference](/users-api/reference.md)
- [Authorize your integrations using OAuth 2.0](/users-api/authorization.md)
- [Request an access token](/users-api/request-access-token.md)