Skip to main content

1Password Partnership API reference

You can use the 1Password Partnership API to manage the provisioning and deprovisioning of third-party partner billing accounts for your customers. The API supports partner billing accounts for 1Password individual and family accounts. The Partnership API doesn't support 1Password team or business accounts.

note

To work with the 1Password Partnership API in another tool, download the API specification file: 1password-partnership-api.yml.

Prerequisites​

Before you can use the API to integrate with our partner billing service, you'll need to register as a 1Password partner. Registered partners are granted access to bearer tokens to authorize requests to the API billing servers.

To learn more about our partnership opportunities, visit the 1Password Partner Program website or contact the 1Password Partnerships team.

Information about the API​

The 1Password Partnership API is a REST-style API that follows the OpenAPI 3.0 specifications. All communication between clients and servers is over HTTPS.

You can use your preferred programming language and tools for testing and implementing the Partnership API. This reference uses curl on the command line to demonstrate example requests. You can replace the values in any request with your own to receive information about your customers' billing accounts.

Request methods​

You can use the following standard HTTP methods to make requests to the Partnership API:

  • POST: Create a third-party billing account for a customer through the partner billing service.
  • GET: Get details about a customer's billing account.
  • DELETE: Delete a customer's third-party billing account from the partner billing service.
  • PATCH: Update the date and time a customer's billing account is scheduled be removed from the partner billing service.

Batch requests are not supported.

Servers​

There are two billing servers partners can use to work with the 1Password Partnership API that provide the base URLs of the API endpoints:

  • Test server (https://billing.b5test.eu): Use the test server URL as the base for all requests in the test environment. You can provision and deprovision test partner billing accounts for all domains from the test server: b5test.com, b5test.ca, and b5test.eu.
  • Production server (https://billing.1password.com): Use the production server URL as the base for all requests in the production environment. You can provision and deprovision partner billing accounts for all domains from the production server: 1password.com, 1password.ca, and 1password.eu.

Endpoints​

Each request to the API starts with the base URL of the server environment you want to work with (test or production), followed by the path (api/v1/partners/account). Path parameters, indicated with curly braces ({}), are required where defined. For example:

Structure of an API endpoint

Replace the base_URL and {parameters} placeholders with the server environment you're using and any path parameters specified for the request. The path is the same for all requests.

Example API endpoint without a path parameter

Example API endpoint with a path parameter

Authorization​

When you register with the 1Password Partner Program, the Partnership team will provide you with bearer tokens you'll need to authorize your calls to the Partnership API.

You'll receive separate tokens to use with the test and production environments. Make sure to use the token that has been authorized for the environment you're working in.

Contact the 1Password Partnerships team if you require a new bearer token for either environment.

Request headers​

Requests to the Partnership API use three types of headers:

  • Authorization: Each GET, POST, DELETE, and PATCH request to the Partnership API must be authorized with a bearer token.
  • Content-Type: Each POST and PATCH request requires a header to indicate the media (MIME) type of the request body.
  • Accept: Each GET, POST, and PATCH request to the Partnership API should include an accept header to indicate what kind of response the client can accept from the server.

All data is sent and received as JSON, so make sure to specify that in the headers.

If you don't have a bearer token, or if you receive an invalid auth token error when making requests to the API, contact the 1Password Partnerships team for help.

Request bodies​

Request bodies (also called request payloads) contain the JSON-formatted data clients send to create (POST) or update (PATCH) resources on the servers. A request body consists of an object that may include one or more of the following fields, as indicated:

  • The unique identifier (UID) for the customer's billing account. The UID is supplied by the partner. It can be up to 200 characters long with any combination of alphanumeric characters (A-Z, a-z, 0-9), hyphens (-), and periods/dots (.) .
  • The 1Password account type. Options are individual (I) or family (F). Team and business accounts aren't supported.
  • The domain the customer can use for their new or existing 1Password account. For the test server, options are: b5test.com, b5test.ca, or b5test.eu. For the production server, options are: 1password.com, 1password.ca, or 1password.eu.
  • The date and time the customer's billing account is scheduled to be removed. The date cannot be in the past. Format the date, time, and optional timezone in the ISO 8601 standard.

GET and DELETE calls don't contain request bodies.

Activation tokens​

Activation tokens are used to provision customers to third-party billing by linking 1Password accounts to partner billing accounts.

Make a POST call to the Partnership API to create a new partner billing account for a customer and generate their unique activation token.

Append the token returned in the POST response to a 1Password partnership redemption link to create the customer's partner billing link. Then provide the customer with their link.

The link will direct the customer to a promotional page where they'll be instructed to create a new 1Password account or sign in to an existing one. The billing for the customer's 1Password account will then be linked to their partner billing account.

To create a partner billing link for a customer, adjust the 1Password partnership redemption link (https://start.[1password_domain]/partnership/redeem) to use the desired 1Password domain. Then append a query string with the required parameters for the account type and the activation token. You can also include an optional language parameter.

Structure of a partner billing link for a 1Password account

PlaceholderValuesRequired
[1password_domain]Possible values are 1password.com, 1password.ca, or 1password.eu.Yes
{account_type}Possible values are individual or family.Yes
{activation_token}The value of the token returned in the POST response. For example: 4266474b-6385-56d4-7b75-648096593064.Yes
{language_code}Optional language code values are en, de, es, fr, it, ja, ko, nl, pt-BR, ru, zh-Hans, or zh-Hant.No

Replace the placeholders for the 1Password domain and the parameters with the appropriate values. For example:

Example partner billing link for an individual account on 1Password.eu with an optional language parameter

Example partner billing link for a family account on 1Password.com with an optional language parameter

If you're not sure which link(s) you need to create, contact the 1Password Partnerships team for help.

caution

For customers with existing 1Password accounts, partner billing links will only work if their 1Password account type and domain are the same as the ones specified in the POST request.

Customers can contact 1Password Support if they need help to change their existing account type or region.

Learn more about alternate link options.

The Partnership API also supports some alternate options for partner billing links. Depending on the details of your partnership, you might prefer to create links for:

If you provide a customer with one of these links, they'll only be able to use it to link their partner billing account to either a new account or an existing account, respectively.

You can also create one link of each type and provide your customers with both so they can choose the option they need. However, creating a single link that allows for both options may be a better solution.

To create a partner billing link for a customer to use with a new 1Password account only, adjust the 1Password sign-up link (https://start.[1password_domain]/sign-up/[account_type]) to use the desired 1Password domain and account type. Then append a query string with the required activation token parameter. You can also include an optional language parameter. For example:

Structure of a partner billing link for a new 1Password account

Replace the placeholders for the 1Password domain, account type, and the parameters with the appropriate values. For example:

Example partner billing link for a new individual account on 1Password.eu with an optional language parameter

Example partner billing link for a new family account on 1Password.com with an optional language parameter

To create a partner billing link for a customer to use with an existing 1Password account only, adjust the 1Password account sign-in link (https://my.[1password_domain]/partnership/link) to use the desired 1Password domain. Then append a query string with the required activation token parameter. You can also include an optional language parameter. For example:

Structure of a partner billing link for an existing 1Password account

Replace the placeholders for the 1Password domain and the parameters with the appropriate values. For example:

Example partner billing link for an existing account on 1Password.com with an optional language parameter

This link doesn't include an account type because it directs the customer to sign in to the 1Password account they already have.

Placeholder reference​
PlaceholderValuesRequired
[1password_domain]Possible values are 1password.com, 1password.ca, or 1password.eu.Yes
[account_type]The account type is only used with links to create a new 1Password account. Possible values are individual or family.Yes

For new accounts only

{activation_token}The value of the token returned in the POST response. For example: 4266474b-6385-56d4-7b75-648096593064.

Yes
{language_code}Optional language code values are en, de, es, fr, it, ja, ko, nl, pt-BR, ru, zh-Hans, or zh-Hant.No

Language code parameters​

Learn more about optional language code parameters.

Language codes are an optional parameter that can be added to a partner billing link to take the customer to the appropriate landing page for that language. Customers will be directed to the default landing page (English) if no language parameter is included.

The following language codes can be used with the language parameter:

LanguageCode
Englishen
Deutschde
Españoles
Françaisfr
Italianoit
日本語ja
LanguageCode
한국어ko
Nederlandsnl
Portuguêspt-BR
Русскийru
简体中文zh-Hans
繁體中文zh-Hant

Create a billing account​

A POST call creates a new third-party billing account for a customer through the partner billing service and returns the activation token you'll use to create a partner billing link for the customer to complete provisioning.

Path parameters​

No path parameters.

Request​

Use the endpoint URL with your bearer token and the required request headers. Include an object as a request body that contains:

  • The customer's account UID.
  • The eligible 1Password account type.
  • The domain the customer can use for their new or existing 1Password account.
  • (Optional) The date and time you want to remove the customer's account from the partner billing service. This value cannot be in the past. You can also update this field with a PATCH request.

Success response​

A 201 response returns an Account object containing the unique activation token that's used to link the customer's 1Password account with their partner billing account.

Error responses​

400 Returned on bad requests.
403 Returned when the authorization header is missing from the request body or an invalid token is specified.
404 Returned when a resource or dependency of a resource isn't found.
500 Returned on unexpected errors.

Get billing account information​

A GET call retrieves information about a customer's billing account. Make sure to include the customer's account UID as a path parameter.

Path Parameters​

ParameterTypeDescription
customer_account_uid

Required

stringThe unique ID of the customer's billing account.

Request​

Use the endpoint URL with your bearer token and the required request headers to request a customer's billing account information. The GET request doesn't include a body, so the Content-type header isn't used.

Success response​

A 200 response returns an Account object that provides information about the customer's third-party billing account.

Error responses​

403 Returned when the authorization header is missing or an invalid token is specified.
404 Returned when a resource or dependency of a resource isn't found.
410 Returned when a resource has been removed.
500 Returned on unexpected errors.

Delete a billing account​

A DELETE call removes a customer's third-party billing account from the partner billing service. Make sure to include the customer's account UID as a path parameter.

Path Parameters​

ParameterTypeDescription
customer_account_uid

Required

stringThe unique ID of the customer billing account to remove.

Request​

Use the endpoint URL with your bearer token for the required request header to remove a customer's billing account. The DELETE request and subsequent response don't include a body, so the Content-type and Accept headers aren't used.

Success response​

A 204 response is returned on successful deactivation and removal of a customer billing account. A GET request will no longer return account information for the customer account UID because the billing account has been deleted.

Error responses​

403 Returned when the authorization header is missing or an invalid token is specified.
404 Returned when a resource or dependency of a resource isn't found.
500 Returned on unexpected errors.

Update a billing account end date​

A PATCH call lets you add, edit, or remove the end date for a customer's billing account. Make sure to include the customer's account UID as a path parameter.

Path Parameters​

ParameterTypeDescription
customer_account_uid

Required

stringThe unique ID of the customer's billing account.

Request​

Use the endpoint URL with your bearer token and the required request headers. Include an object as a request body that contains the ends_at field.

To add or update the date and time a customer's billing account is scheduled to be removed from the partnership billing service, include a new date and time as the ends_at value, in the format defined by RFC 3339.

To remove the end date and time from a customer's billing account, use an empty string ("") or null as the value.

Success response​

A 200 response returns an Account object that provides information about the customer's third-party billing account, including the end date that has been added, edited, or removed from the billing account.

Error responses​

403 Returned when the authorization header is missing or an invalid token is specified.
404 Returned when a resource or dependency of a resource isn't found.
410 Returned when a resource has been removed.
500 Returned on unexpected errors.

Was this page helpful?