> ## 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.
# Link an entitlement
> Create a change-of-channel entitlement to link an existing 1Password account.
Use this endpoint when a customer already has a 1Password account and is switching to purchasing 1Password through you as their distributor, instead of provisioning a new account with [create an entitlement](/accounts-api/create-entitlement).
Linking creates a change-of-channel entitlement that connects a customer's existing 1Password account to your distributor relationship.
The request must identify the existing account by its 1Password domain in the metadata (for example, `acme-corp.1password.com`), along with the [`product_id`](/accounts-api/list-products) to provision and the customer's `contact_info`.
Linking an entitlement works as follows:
1. The entitlement is created with a status of `pending` and an `expire_time` 5 days from creation.
2. 1Password sends an email to the customer with their entitlement code. The email includes your distributor name and the product name.
3. The customer claims the code for their existing 1Password account, which completes the link and transitions the entitlement to `active`.
If the customer doesn't complete linking within 5 days, the entitlement expires and its status transitions to `expired`.
If an entitlement for the product already exists for the customer, the request fails with a `409` error unless it has a `cancelled` or `expired` status.
If the existing entitlement is `cancelled` or `expired`, it's reactivated with a status of `pending`.
A reactivated entitlement keeps its original `id` and `create_time`, with the contact details from the new request.
## OpenAPI
````yaml openapi/accounts_api.yaml POST /v1/distributor-customers/{distributor-customer}/entitlements:link
openapi: 3.1.0
info:
title: 1Password Accounts API for Partners
version: v1
description: >-
The 1Password Accounts API for Partners lets distributors provision and
manage 1Password
product entitlements for their customers, retrieve usage data, and list the
products available to provision.
Resources are grouped into entitlements, usage, and products. The
conventions
for authentication, pagination, and filtering apply across the whole API.
contact:
name: 1Password
url: https://1password.com/contact-us
servers:
- url: https://api.1password.eu
description: 1Password.eu (Europe)
security:
- BearerAuth: []
tags:
- name: Entitlements
description: >-
Provision, update, cancel, and link 1Password product entitlements for a
customer.
x-group: Entitlements
- name: Usage
description: Retrieve product usage data for a distributor's customers.
x-group: Usage
- name: Products
description: List the 1Password products a distributor can provision.
x-group: Products
paths:
/v1/distributor-customers/{distributor-customer}/entitlements:link:
post:
tags:
- Entitlements
summary: Link an entitlement
description: >-
Create a change of channel entitlement to link an existing 1Password
account.
operationId: linkEntitlement
parameters:
- name: distributor-customer
in: path
description: The customer ID, as defined in the distributor's own system.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/distributor.v1.LinkEntitlementRequest'
example:
product_id: 1p-msp-us
contact_info:
email: admin@acme-corp.com
company_name: Acme Corporation
metadata:
one_password_domain: acme-corp.1password.com
required: true
responses:
'200':
description: The linked change of channel entitlement.
content:
application/json:
schema:
$ref: '#/components/schemas/distributor.v1.LinkEntitlementResponse'
example:
entitlement:
path: >-
distributor-customers/cust_789xyz/entitlements/ent_link789abc
id: ent_link789abc
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'
expire_time: '2026-09-20T10:30:00Z'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthenticated'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/AlreadyExists'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/Internal'
components:
schemas:
distributor.v1.LinkEntitlementRequest:
type: object
properties:
product_id:
type: string
minLength: 1
description: The ID of the 1Password product to provision.
contact_info:
$ref: '#/components/schemas/distributor.v1.DistributorContactInfo'
description: The customer details for account activation and setup.
metadata:
$ref: '#/components/schemas/distributor.v1.DistributorMetadata'
description: >-
The change of channel information. Required, and must include
`one_password_domain`.
required:
- contact_info
- metadata
- product_id
additionalProperties: false
description: The request body for linking an existing 1Password account.
distributor.v1.LinkEntitlementResponse:
type: object
properties:
entitlement:
$ref: '#/components/schemas/distributor.v1.DistributorEntitlement'
description: The linked entitlement.
additionalProperties: false
description: The response for a successful entitlement link.
distributor.v1.DistributorContactInfo:
type: object
properties:
email:
type: string
format: email
description: The customer's contact email for account activation.
company_name:
type: string
minLength: 1
description: The customer's organization name.
required:
- email
- company_name
additionalProperties: false
description: The customer contact details used for account setup.
x-aep-resource:
singular: distributorcontactinfo
distributor.v1.DistributorMetadata:
type: object
properties:
one_password_domain:
type: string
minLength: 1
description: >-
The 1Password domain of the customer's existing 1Password account
(for example, `acme-corp.1password.com`). The domain can only be
updated if the entitlement already has a domain set; it can't be
added or removed.
additionalProperties: false
description: Auxiliary fields for change-of-channel entitlement flows.
required:
- one_password_domain
x-aep-resource:
singular: distributormetadata
distributor.v1.DistributorEntitlement:
type: object
properties:
path:
type: string
description: >-
The canonical resource path of the entitlement (for example,
"distributor-customers/{customer_id}/entitlements/{id}"). Use the
IDs in this path to update or cancel the entitlement.
readOnly: true
id:
type: string
description: The unique identifier for this entitlement.
readOnly: true
customer_id:
type: string
description: >-
The ID of the marketplace customer who owns this entitlement. This
is the distributor-defined ID from the request path that created the
entitlement.
readOnly: true
product_id:
type: string
description: >-
The ID of the 1Password product. Required on create; immutable
thereafter.
status:
type: string
description: The entitlement lifecycle state.
enum:
- pending
- active
- cancelling
- cancelled
- expired
- suspended
readOnly: true
contact_info:
$ref: '#/components/schemas/distributor.v1.DistributorContactInfo'
description: The customer's contact details for account setup.
create_time:
description: The date and time the entitlement was created.
type: string
format: date-time
readOnly: true
expire_time:
description: >-
The date and time the entitlement expires. Set only for
change-of-channel entitlements created by linking an entitlement,
and omitted for standard entitlements. Customers have 5 days to
claim the emailed entitlement code against their existing 1Password
account. Claiming the code completes the link; otherwise, the
entitlement transitions to `expired` at this time.
type: string
format: date-time
readOnly: true
additionalProperties: false
description: A provisioned 1Password product entitlement for a distributor customer.
x-aep-resource:
singular: distributorentitlement
Error:
type: object
properties:
code:
type: string
description: Error code.
example: not_found
message:
type: string
description: Human-readable message.
example: The requested resource was not found.
required:
- code
- message
description: Standard error response format.
responses:
BadRequest:
description: Bad Request - Invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: invalid_argument
message: The 'email' field must be a valid email address.
Unauthenticated:
description: Unauthenticated - Missing or invalid credentials.
headers:
WWW-Authenticate:
description: The authentication scheme to use ("Bearer").
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: unauthenticated
message: Authentication required. Please provide a valid bearer token.
NotFound:
description: Not Found - Resource does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: not_found
message: The requested resource was not found.
AlreadyExists:
description: Conflict - Resource already exists.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: already_exists
message: An entitlement for this product already exists.
TooManyRequests:
description: >-
Too Many Requests - Limit is 1,000 requests per minute per distributor.
There is no separate hourly limit.
headers:
Retry-After:
description: How long to wait before retrying, in seconds.
schema:
type: string
content:
text/plain:
schema:
type: string
example: Too Many Requests
Internal:
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: internal
message: An internal error occurred. Please try again later.
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: >-
Bearer token authentication. When a distributor is registered, they
receive an opaque bearer token (prefixed `op_b_`). Include it in the
Authorization header of every request as `Bearer `.
````
## Related topics
- [Reference for the 1Password Accounts API for Partners](/accounts-api/reference.md)
- [1Password Accounts API for Partners](/accounts-api.md)
- [API conventions](/accounts-api/conventions.md)