openapi: 3.0.0
info:
  version: 2.0.0
  title: 1Password Partnership API

  contact:
    name: 1Password Partnerships
    url: https://www.1password.partners/English/
    email: partners@1password.com

servers:
  - url: https://billing.b5test.eu
  - url: https://billing.1password.com

paths:
  /api/v1/partners/accounts:
    post:
      security:
        - bearerAuth: []
      description: Begins provisioning process for a new partner associated 1Password account.
      operationId: createPartnerAccount
      requestBody:
        description: Request to initialize a partner account.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreatePartnerAccountRequest"
            examples:
              Creating an Individual account on b5test.com:
                value:
                  customer_account_uid: aabee51b-0be2-4a0c-aa39-5bbcbb903d1b
                  account_type: I
                  domain: b5test.com
              Creating a Family account on b5test.eu:
                value:
                  customer_account_uid: aabee51b-0be2-4a0c-aa39-5bbcbb903d1b
                  account_type: F
                  domain: b5test.eu
              Creating an Individual account with a specified ends_at field:
                value:
                  customer_account_uid: aabee51b-0be2-4a0c-aa39-5bbcbb903d1b
                  account_type: I
                  domain: b5test.com
                  ends_at: 2050-02-05T13:00:00Z
              Creating a Family account with a specified ends_at and timezone:
                value:
                  customer_account_uid: aabee51b-0be2-4a0c-aa39-5bbcbb903d1b
                  account_type: F
                  domain: b5test.com
                  ends_at: 2050-02-05T13:00:00-05:00

      responses:
        "201":
          description: An Account object is returned upon successful initialization of a partner account.
          headers:
            location:
              description: Location of the newly created resource.
              schema:
                type: string
                example: /api/v1/partners/accounts/aabee51b-0be2-4a0c-aa39-5bbcbb903d1b
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Account"
              examples:
                Creating an Individual account without an ends_at date:
                  value:
                    customer_account_uid: aabee51b-0be2-4a0c-aa39-5bbcbb903d1b
                    account_type: I
                    activation_token: PNS-DEFG1234
                    domain: b5test.com
                    status: entitled
                    deployed_members: 0
                    created_at: 2023-01-23T15:55:58Z
                    updated_at: 2023-01-23T15:55:58Z
                    ends_at: null
                Creating a Family account with an ends_at date:
                  value:
                    customer_account_uid: aabee51b-0be2-4a0c-aa39-5bbcbb903d1b
                    account_type: F
                    activation_token: PNS-DEFG1234
                    domain: b5test.com
                    status: entitled
                    deployed_members: 0
                    created_at: 2023-01-23T15:55:58Z
                    updated_at: 2023-01-23T15:55:58Z
                    ends_at: 2050-02-05T13:00:00Z
                Creating an Individual account with an ends_at date with specified time zone:
                  value:
                    customer_account_uid: aabee51b-0be2-4a0c-aa39-5bbcbb903d1b
                    account_type: I
                    activation_token: PNS-DEFG1234
                    domain: b5test.com
                    status: entitled
                    deployed_members: 0
                    created_at: 2023-01-23T15:55:58Z
                    updated_at: 2023-01-23T15:55:58Z
                    ends_at: 2050-02-05T18:00:00Z

        "403":
          description: Returned when the Authorization header is missing or an invalid token is specified.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: 403
                error: forbidden
                description: Invalid auth token.

        "400":
          description: Returned on bad requests.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: 400
                error: bad_request
                description: Account type B is not supported.

        "404":
          description: Returned when a resource or dependency of a resource is not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: 404
                error: not_found
                description: Domain not found.

        "500":
          description: Returned on unexpected errors.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: 500
                error: internal_server_error
                description: Internal server error

  /api/v1/partners/accounts/{customer_account_uid}:
    get:
      security:
        - bearerAuth: []
      description: Returns an account based on an UID.
      operationId: getAccountByPartnerAccountUID
      parameters:
        - name: customer_account_uid
          in: path
          description: Unique ID of an account to retrieve.
          required: true
          schema:
            type: string

      responses:
        "200":
          description: An Account object is returned upon successful retrieval of a partner account.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Account"
              examples:
                Getting an account without a specified ends_at time:
                  value:
                    customer_account_uid: aabee51b-0be2-4a0c-aa39-5bbcbb903d1b
                    account_type: I
                    activation_token: PNS-DEFG1234
                    domain: b5test.com
                    status: provisioned
                    deployed_members: 1
                    created_at: 2023-01-23T15:55:58Z
                    updated_at: 2023-01-23T15:58:22Z
                    ends_at: null
                Getting an account with a specified ends_at time:
                  value:
                    customer_account_uid: aabee51b-0b
                    account_type: I
                    activation_token: PNS-DEFG1234
                    domain: b5test.com
                    status: provisioned
                    deployed_members: 1
                    created_at: 2023-01-23T15:55:58Z
                    updated_at: 2023-01-23T15:58:22Z
                    ends_at: 2030-01-23T15:58:22Z

        "403":
          description: Returned when the Authorization header is missing or an invalid token is specified.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: 403
                error: forbidden
                description: Invalid auth token.

        "404":
          description: Returned when a resource or dependency of a resource is not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: 404
                error: not_found
                description: Failed to find the requested account.

        "410":
          description: Returned when a resource has been removed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: 410
                error: gone
                description: The requested account is gone.

        "500":
          description: Returned on unexpected errors.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: 500
                error: internal_server_error
                description: Internal server error

    delete:
      security:
        - bearerAuth: []
      description: Removes an account from the partnership domain.
      operationId: deleteAccount
      parameters:
        - name: customer_account_uid
          in: path
          description: Unique ID of partner_account to delete.
          required: true
          schema:
            type: string

      responses:
        "204":
          description: Returned upon successful deactivation of a partnership account.

        "403":
          description: Returned when the Authorization header is missing or an invalid token is specified.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: 403
                error: forbidden
                description: Invalid auth token.

        "404":
          description: Returned when a resource or dependency of a resource is not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: 404
                error: not_found
                description: Failed to find the requested account.

        "500":
          description: Returned on unexpected errors.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: 500
                error: internal_server_error
                description: Internal server error

    patch:
      security:
        - bearerAuth: []
      description: Updates the ends_at attribute of an account based on an UID.
      operationId: updateAccountByID
      parameters:
        - name: customer_account_uid
          in: path
          description: Unique ID of partner_account to update.
          required: true
          schema:
            type: string
      requestBody:
        description: Request to update the ends_at attribute of a partner account.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdatePartnerAccountRequest"
            examples:
              Setting an ends_at time:
                value:
                  ends_at: 2030-01-23T15:55:58Z
              Removing an ends_at time with empty string:
                value:
                  ends_at: ""
              Removing an ends_at time with NULL:
                value:
                  ends_at: NULL

      responses:
        "200":
          description: An Account object is returned upon successful update of a partner account.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Account"
              examples:
                Setting an ends_at time:
                  value:
                    customer_account_uid: aabee51b-0be2-4a0c-aa39-5bbcbb903d1b
                    account_type: I
                    activation_token: PNS-DEFG1234
                    domain: b5test.com
                    status: provisioned
                    deployed_members: 1
                    created_at: 2023-01-23T15:55:58Z
                    updated_at: 2023-01-23T15:58:22Z
                    ends_at: 2030-01-23T15:55:58Z
                Removing an ends_at time:
                  value:
                    customer_account_uid: aabee51b-0be2-4a0c-aa39-5bbcbb903d1b
                    account_type: I
                    activation_token: PNS-DEFG1234
                    domain: b5test.com
                    status: provisioned
                    deployed_members: 1
                    created_at: 2023-01-23T15:55:58Z
                    updated_at: 2023-01-23T15:58:22Z
                    ends_at: null

        "400":
          description: Returned upon validation failures
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                Invalid ends_at date format:
                  value:
                    code: 400
                    error: bad_request
                    description: Invalid ends_at date format - it must adhere to RFC-3339, e.g. 2006-01-02T15:04:05-07:00.
                ends_at date in the past:
                  value:
                    code: 400
                    error: bad_request
                    description: Invalid ends_at date - it cannot be in the past.
                Deactivated partner cannot be modified:
                  value:
                    code: 400
                    error: bad_request
                    description: Invalid account - partner account deleted.

        "403":
          description: Returned when the Authorization header is missing or an invalid token is specified.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: 403
                error: forbidden
                description: Invalid auth token.

        "404":
          description: Returned when a resource or dependency of a resource is not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: 404
                error: not_found
                description: Failed to find the requested account.

        "500":
          description: Returned on unexpected errors.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                code: 500
                error: internal_server_error
                description: Internal server error

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    CreatePartnerAccountRequest:
      type: object
      required:
        - customer_account_uid
        - account_type
        - domain
      properties:
        customer_account_uid:
          type: string
          description: A unique identifier for the end user's account to be provisioned. It can be up to 80 chars long and consist of alphanumeric characters and hyphens.
        account_type:
          type: string
          description: Specifies the type of 1Password account plan to provision - 'I' for Individual, or 'F' for family.
        domain:
          type: string
          description: Specifies the 1Password domain to provision the account for. For testing it can be one of 'b5test.com', 'b5test.ca', or 'b5test.eu'. For production, it can be one of '1password.com', '1password.ca', or '1password.eu'. Note that domains can only be used after promotions have been created for a given partnership in the specific domain.
        ends_at:
          type: string
          format: date-time
          description: Specifies when the 1Password account will be frozen, formatted in RFC-3339.

    UpdatePartnerAccountRequest:
      type: object
      required:
        - ends_at
      properties:
        ends_at:
          type: string
          format: date-time
          description: Specifies when the 1Password account will be frozen, formatted in RFC-3339.

    Account:
      type: object
      properties:
        customer_account_uid:
          type: string
          description: The unique identifier for the end user's account. It can be up to 80 chars long and consist of alphanumeric characters and hyphens.
        account_type:
          type: string
          description: The current type of the 1Password account - 'I' for Individual, or 'F' for family.
        activation_token:
          type: string
          description: The activation token is a coupon code to link a new or existing 1Password account to a partnership promotion. For example, it can be used for 1Password account creation at https://start.{{1password_domain}}/partnership/redeem?t={{account_type}}&c={{activation_token}} during end-user signup.
        domain:
          type: string
          description: The 1Password domain for which the account was provisioned for. For testing domains, it can be one of 'b5test.com', 'b5test.ca', or 'b5test.eu'. For production, it can be one of '1password.com', '1password.ca', or '1password.eu'.
        status:
          type: string
          description: The provisioning status of the partner account. It can be either 'entitled' for accounts that have been initialized but have not completed 1Password signup, or 'provisioned' for accounts that have completed the 1Password signup process.
        deployed_members:
          type: integer
          description: The number of provisioned users for the 1Password account.
        created_at:
          type: string
          format: date-time
          description: The timestamp of when the partnership account was created, formatted in RFC-3339.
        updated_at:
          type: string
          format: date-time
          description: The timestamp of when the partner account was last updated, formatted in RFC-3339. This field will be updated during account status changes.
        ends_at:
          type: string
          format: date-time
          description: The timestamp of when the partner account will be frozen, formatted in RFC-3339.

    Error:
      type: object
      properties:
        code:
          type: integer
          description: The HTTP response code of the error.
        error:
          type: string
          description: A machine parsable string that represents the code.
        description:
          type: string
          description: A description of the error.

security:
  - bearerAuth: []
