API conventions - 1Password Developer

The following conventions apply across the 1Password Accounts API for Partners.

Authentication

The Accounts API authorizes requests with a bearer token. When your organization registers as a distributor, you’ll receive an opaque bearer token, prefixed with op_b_. Include this token in the Authorization header of every request, prefixed with Bearer:

Authorization: Bearer <YOUR_API_TOKEN>

For example:

curl --request GET \
  --url "https://api.1password.eu/v1/distributor-products" \
  --header "Authorization: Bearer <YOUR_API_TOKEN>"

Treat your bearer token like a password. Store it securely (for example, in a 1Password vault) and never expose it in client-side code, logs, or source control.

If you need a new bearer token, contact 1Password.

Endpoints

The basic structure of an endpoint URL for the Accounts API includes the base URL and the endpoint path. The endpoint path includes the API endpoint version, the resource(s) you want to access, and any relevant path parameters.

Base URL

All requests to the Accounts API use the 1Password.eu base URL, https://api.1password.eu, regardless of the region of your 1Password account or your customers’ accounts. The product_id you provision determines the region where a customer’s 1Password account is created. All communication with the API is over HTTPS.

Endpoint path

The endpoint path is appended to the base URL and includes the endpoint version, target resource path, and any path parameters. For example, the endpoint path to list usage for a specific customer would look like this:

/v1/distributor-customers/{distributor-customer}/usage

The {distributor-customer} path parameter is your own identifier for the customer, as defined in your marketplace system — 1Password doesn’t validate it against a customer registry. Some list endpoints also accept - as a wildcard to query across all of your customers. See the API reference documentation for more information about each endpoint.

Requests

Request methods

Requests to the Accounts API use standard HTTP methods:

Method	Usage
`GET`	Retrieve resources. For example: list entitlements, customer usage, or products.
`POST`	Create resources. For example: create or link an entitlement.
`PATCH`	Update specific fields of a resource. For example: update a pending entitlement.
`DELETE`	Initiate removal of a resource. For example: cancel an entitlement.

Request headers

Authorization: Bearer <YOUR_API_TOKEN>
Content-Type: application/json

Authorization: Required on every request. Use this header with your bearer token to authenticate your API requests.
Content-Type: application/json: Required for POST and PATCH requests. Use this header for requests that send a JSON body. GET and DELETE requests don’t include a body.

Request bodies

POST and PATCH requests send a JSON object in the request body. Check the API reference documentation for the fields each endpoint accepts. The API silently ignores unknown fields in request bodies, so make sure your field names are correct. A misspelled field name is ignored without an error and the value isn’t applied. GET and DELETE requests don’t include a request body.

Query parameters

You can use query parameters in your API request as optional modifiers after the endpoint path. Use a ? query separator at the end of the endpoint path, then add any query parameters you want to include, separated by a & query delimiter. For example, if you want to retrieve a list of product usage data for all customers, you could use query parameters to filter the results by billing cycle and set the maximum number of results to return per page:

GET https://api.1password.eu/v1/distributor-customers/-/usage?filter=billing_cycle == '2026-04'&max_page_size=20

Make sure your client URL-encodes query parameter values. Filter expressions contain spaces and special characters, so the request above is sent as:

GET https://api.1password.eu/v1/distributor-customers/-/usage?filter=billing_cycle%20%3D%3D%20%272026-04%27&max_page_size=20

Check the API reference documentation to discover which query parameters are available for each endpoint.

Filtering

The following list endpoints accept a filter query parameter that uses Common Expression Language (CEL) syntax:

List entitlements: Filters on entitlement fields. For example, status == 'active' returns only active entitlements. When omitted, entitlements of all statuses are returned. See the entitlement statuses section to learn about all the possible status values.
List customer usage: Filters by billing cycle using billing_cycle == 'YYYY-MM'. For example, billing_cycle == '2026-04'. When omitted, usage defaults to the current billing cycle in UTC. There’s no lookback limit on historical billing cycles.

Pagination

curl --request GET \
  --url "https://api.1password.eu/v1/distributor-products?max_page_size=20&page_token=<NEXT_PAGE_TOKEN>" \
  --header "Authorization: Bearer <YOUR_API_TOKEN>"

All list endpoints (entitlements, customer usage, and products) support pagination. Use these query parameters to page through results:

max_page_size: The maximum number of results to return per page. Defaults to 100; values above 100 are clamped to 100. Omitting the parameter or setting it to 0 uses the default.
page_token: The token that identifies the page of results to return.

Each list response includes an opaque next_page_token. To retrieve the next page, send the same request with page_token set to that value. When next_page_token is empty, there are no more results. The API uses cursor-based pagination. Each token marks where the previous page left off, so paging stays consistent even if results change between page requests. Items already returned aren’t repeated on later pages, and items aren’t skipped if others are created or cancelled while you page.

Responses

The API returns JSON for all responses, except rate-limit errors, which return plain text. A successful request returns 200 OK. Create, update, and cancel operations return the affected entitlement in the response body, so you can read back its server-assigned fields, such as id, create_time, and the current status. Link operations return the entitlement inside an entitlement object. For example, a successful create request returns:

HTTP/2 200
date: Fri, 30 Oct 2026 12:34:56 GMT
content-type: application/json

{
  "path": "distributor-customers/cust_789xyz/entitlements/ent_abc123def456",
  "id": "ent_abc123def456",
  "customer_id": "cust_789xyz",
  "product_id": "1p-msp-us",
  "status": "pending",
  "contact_info": {
    "email": "admin@acme-corp.com",
    "company_name": "Acme Corporation"
  },
  "create_time": "2026-09-15T10:30:00Z"
}

List operations return a results array and a next_page_token. For example:

{
  "results": [
    {
      "path": "distributor-customers/cust_789xyz/entitlements/ent_abc123def456",
      "id": "ent_abc123def456",
      "customer_id": "cust_789xyz",
      "product_id": "1p-msp-us",
      "status": "active",
      "contact_info": {
        "email": "admin@acme-corp.com",
        "company_name": "Acme Corporation"
      },
      "create_time": "2026-09-15T10:30:00Z",
      "expire_time": "2026-09-20T10:30:00Z"
    }
  ],
  "next_page_token": ""
}

When a list request matches no results, the response returns an empty results array and an empty next_page_token.

{
  "results": [],
  "next_page_token": ""
}

Learn more about error responses and paginated list responses.

Dates and times

Timestamps are returned in RFC 3339 format, for example 2026-01-23T15:55:58Z.

Rate limits

Requests to the Accounts API are rate limited to 1,000 requests per minute, per distributor. There’s no separate hourly limit. If you exceed the allowed rate, the API returns a 429 Too Many Requests response with a Retry-After header that indicates how long to wait before retrying. Unlike other error responses, the 429 response body is plain text, not JSON.

Errors

The API uses standard HTTP status codes to indicate the result of a request. A 2xx code indicates success. A 4xx code indicates a problem with the request (for example, missing authentication or invalid input). A 5xx code indicates an unexpected server error. Most error responses include a JSON body with a machine-readable code and a human-readable message:

{
  "code": "not_found",
  "message": "The requested resource was not found."
}

The error response format, including the code and message fields, is provisional and may change in a future release. Use the HTTP status code to handle errors in your integration, and don’t rely on the text of the message field.

Status	Code	Meaning
`400`	`invalid_argument`	A request parameter or body field is invalid.
`401`	`unauthenticated`	Missing or invalid credentials.
`404`	`not_found`	The resource doesn’t exist.
`409`	`already_exists`	The resource already exists — for example, an entitlement for the product already exists.
`500`	`internal`	An internal error occurred. Retry the request later.

429 Too Many Requests responses don’t use this JSON format. See the rate limits section for more information about this error response.

Entitlement statuses

An entitlement’s status field reflects its position in the lifecycle:

Status	Meaning
`pending`	The entitlement has been created and is waiting for the customer to activate it (or, for linked entitlements, claim the entitlement code). Only pending entitlements can be updated.
`active`	The entitlement is active and the product is provisioned.
`cancelling`	Cancellation has been initiated. Background processing completes it and transitions the status to `cancelled`.
`cancelled`	The entitlement has been cancelled.
`expired`	A change-of-channel entitlement whose entitlement code wasn’t claimed within 5 days of creation.