> ## 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.
# Create an entitlement
> Provision a new 1Password product entitlement for a distributor customer.
Use this endpoint to create a new 1Password product entitlement for a customer. The entitlement starts off as `pending` until the customer activates it.
Creating an entitlement works as follows:
1. The entitlement is created with a status of `pending`.
2. 1Password sends an email to the customer with an activation link. The email includes your distributor name and the product name.
3. The customer selects the activation link and sets up their new 1Password account, which activates the entitlement and transitions it to `active`.
Poll the [list of entitlements](/accounts-api/list-entitlements) to check the entitlement's status.
Pending entitlements don't expire. An entitlement stays `pending` until the customer activates it or you [cancel](/accounts-api/cancel-entitlement) it. Only pending entitlements can be [updated](/accounts-api/update-entitlement).
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.
The `distributor-customer` ID in the request path is your own identifier for the customer, as defined in your system, and isn't validated when you create an entitlement. Make sure your integration passes customer IDs consistently.
[Retrieve a list of available 1Password products](/accounts-api/list-products) to find the `product_id` value to use when creating an entitlement.
## OpenAPI
````yaml openapi/accounts_api.yaml POST /v1/distributor-customers/{distributor-customer}/entitlements
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:
post:
tags:
- Entitlements
summary: Create an entitlement
description: >-
Provision a new 1Password product entitlement for a distributor
customer.
operationId: CreateDistributorEntitlement
parameters:
- name: distributor-customer
in: path
description: The customer ID, as defined in the distributor's own system.
required: true
schema:
type: string
requestBody:
required: true
description: The entitlement resource to create.
content:
application/json:
schema:
$ref: '#/components/schemas/distributor.v1.DistributorEntitlement'
example:
product_id: 1p-msp-us
contact_info:
email: admin@acme-corp.com
company_name: Acme Corporation
responses:
'200':
description: The newly created entitlement, with status `pending`.
content:
application/json:
schema:
$ref: '#/components/schemas/distributor.v1.DistributorEntitlement'
example:
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'
'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.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
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
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
- [Link an entitlement](/accounts-api/link-entitlement.md)
- [Reference for the 1Password Accounts API for Partners](/accounts-api/reference.md)
- [1Password Accounts API for Partners](/accounts-api.md)