OAuth API reference

1Password uses the OAuth 2.0 authorization code flow (RFC 6749) with PKCE (RFC 7636), plus an integration key delivered in the callback fragment. Connect a user 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

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

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

{
  "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"
}

string

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

string

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

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

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.

Get started

Build your integration

Reference

Launch

Origins

Scopes

Authorize

Callback

Token

Exchange a code

Refresh

Response

Errors

Revoke

​Origins

​Scopes

​Authorize

​Callback

​Token

​Exchange a code

​Refresh

​Response

​Errors

​Revoke

Origins

Scopes

Authorize

Callback

Token

Exchange a code

Refresh

Response

Errors

Revoke