openapi: "3.0.2"
info:
  title: 1Password Connect
  description: >-
    REST API interface for 1Password Connect.
  version: "1.1.1"
  contact:
    name: 1Password Integrations
    email: support@1password.com
    url: https://support.1password.com/
servers:
  - url: http://localhost:8080/v1

tags:
  - name: Items
    description: Access and manage items inside 1Password Vaults
  - name: Vaults
    description: Access 1Password Vaults
  - name: Activity
    description: Access API Request Activity

components:
  securitySchemes:
    ConnectToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    ErrorResponse:
      type: object
      properties:
        status:
          type: integer
          description: HTTP Status Code
        message:
          type: string
          description: A message detailing the error
    Vault:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        attributeVersion:
          type: integer
          description: The vault version
        contentVersion:
          type: integer
          description: The version of the vault contents
        items:
          description: Number of active items in the vault
          type: integer
        type:
          type: string
          enum:
            - USER_CREATED
            - PERSONAL
            - EVERYONE
            - TRANSFER
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
    GeneratorRecipe:
      description: The recipe is used in conjunction with the "generate" property to set the character set used to generate a new secure value
      type: object
      properties:
        length:
          type: integer
          description: Length of the generated value
          default: 32
          minimum: 1
          maximum: 64
        characterSets:
          type: array
          items:
            type: string
            enum:
              - LETTERS
              - DIGITS
              - SYMBOLS
          minimum: 0
          maximum: 3
          uniqueItems: true

    Item:
      type: object
      required:
        - vault
        - category
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        vault:
          type: object
          required:
            - id
          properties:
            id:
              type: string
              format: uuid
        category:
          type: string
          enum:
            - "LOGIN"
            - "PASSWORD"
            - "API_CREDENTIAL"
            - "SERVER"
            - "DATABASE"
            - "CREDIT_CARD"
            - "MEMBERSHIP"
            - "PASSPORT"
            - "SOFTWARE_LICENSE"
            - "OUTDOOR_LICENSE"
            - "SECURE_NOTE"
            - "WIRELESS_ROUTER"
            - "BANK_ACCOUNT"
            - "DRIVER_LICENSE"
            - "IDENTITY"
            - "REWARD_PROGRAM"
            - "DOCUMENT"
            - "EMAIL_ACCOUNT"
            - "SOCIAL_SECURITY_NUMBER"
            - "CUSTOM"
        urls:
          type: array
          items:
            type: object
            required:
              - href
            properties:
              primary:
                type: boolean
              href:
                type: string
                format: url
          example:
            - primary: true
              href: https://example.com
            - href: https://example.org
        favorite:
          type: boolean
          default: false
        tags:
          type: array
          items:
            type: string
        version:
          type: integer
        state:
          type: string
          readOnly: true
          enum:
            - "ARCHIVED"
            - "DELETED"
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
        lastEditedBy:
          type: string
          format: uuid
          readOnly: true
    FullItem:
      allOf:
        - $ref: "#/components/schemas/Item"
        - type: object
          properties:
            sections:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  label:
                    type: string
            fields:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  section:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                  type:
                    type: string
                    default: "STRING"
                    enum:
                      - "STRING"
                      - "EMAIL"
                      - "CONCEALED"
                      - "URL"
                      - "TOTP"
                      - "DATE"
                      - "MONTH_YEAR"
                      - "MENU"
                  purpose:
                    description: Some item types, Login and Password, have fields used for autofill. This property indicates that purpose and is required for some item types.
                    type: string
                    enum:
                      - ""
                      - "USERNAME"
                      - "PASSWORD"
                      - "NOTES"
                  label:
                    type: string
                  value:
                    type: string
                  generate:
                    description: If value is not present then a new value should be generated for this field
                    type: boolean
                    default: false
                  recipe:
                    $ref: "#/components/schemas/GeneratorRecipe"
                  entropy:
                    description: For fields with a purpose of `PASSWORD` this is the entropy of the value
                    type: number
                    readOnly: true
    APIRequest:
      description: Represents a request that was made to the API. Including what Token was used and what resource was accessed.
      type: object
      properties:
        requestId:
          description: The unique id used to identify a single request.
          type: string
          format: uuid
        timestamp:
          description: The time at which the request was processed by the server.
          type: string
          format: date-time
          readOnly: true
        action:
          type: string
          enum:
            - READ
            - CREATE
            - UPDATE
            - DELETE
        result:
          type: string
          enum:
            - SUCCESS
            - DENY
        actor:
          type: object
          properties:
            id:
              type: string
              format: uuid
            account:
              type: string
              format: uuid
            jti:
              type: string
              format: uuid
            userAgent:
              type: string
            requestIp:
              type: string
        resource:
          type: object
          properties:
            type:
              type: string
              enum:
                - ITEM
                - VAULT
            vault:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
            item:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
            itemVersion:
              type: integer
    Patch:
      type: array
      items:
        type: object
        properties:
          op:
            type: string
            enum: [add, remove, replace]
          path:
            type: string
            description: An RFC6901 JSON Pointer pointing to the Item document, an Item Attribute, and Item Field by Field ID, or an Item Field Attribute
            example: "/fields/vy09gd8EXAMPLE/label"
          value:
            type: {}
        required:
          - op
          - path

paths:
  /activity:
    get:
      operationId: GetApiActivity
      tags:
        - Activity
      summary: Retrieve a list of API Requests that have been made.
      security:
        - ConnectToken: []
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            example: 10
            default: 50
          description: How many API Events should be retrieved in a single request.
        - in: query
          name: offset
          schema:
            type: integer
            example: 50
            default: 0
          description: How far into the collection of API Events should the response start
      responses:
        "200":
          description: OK
          headers:
            Content-Range:
              description: An decription of what part of the collection has been returned as well as the total size.
              schema:
                type: string
                example: 1-50/1134
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/APIRequest"
        "401":
          description: Invalid or missing token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: 401
                message: Invalid token signature
  /vaults:
    get:
      operationId: GetVaults
      tags:
        - Vaults
      summary: Get all Vaults
      security:
        - ConnectToken: []
      parameters:
        - in: query
          name: filter
          schema:
            type: string
            example: name eq "Some Vault Name"
          description: Filter the Vault collection based on Vault name using SCIM eq filter
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Vault"
        "401":
          description: Invalid or missing token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: 401
                message: Invalid token signature
  /vaults/{vaultUuid}:
    get:
      operationId: GetVaultById
      tags:
        - Vaults
      summary: Get Vault details and metadata
      security:
        - ConnectToken: []
      parameters:
        - in: path
          name: vaultUuid
          schema:
            type: string
            format: uuid
          required: true
          description: The UUID of the Vault to fetch Items from
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Vault"
        "401":
          description: Invalid or missing token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: 401
                message: Invalid token signature
        "403":
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: 403
                message: vault {vaultUuid} is not in scope
        "404":
          description: Vault not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: 404
                message: vault {itemUuid} not found
  /vaults/{vaultUuid}/items:
    get:
      operationId: GetVaultItems
      tags:
        - Items
      summary: Get all items for inside a Vault
      security:
        - ConnectToken: []
      parameters:
        - in: path
          name: vaultUuid
          schema:
            type: string
            format: uuid
          required: true
          description: The UUID of the Vault to fetch Items from
        - in: query
          name: filter
          schema:
            type: string
            example: title eq "Some Item Name"
          description: Filter the Item collection based on Item name using SCIM eq filter
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Item"
        "401":
          description: Invalid or missing token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: 401
                message: Invalid token signature
        "404":
          description: Vault not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: 404
                message: vault {vaultUuid} not found
    post:
      operationId: CreateVaultItem
      tags:
        - Items
      summary: Create a new Item
      security:
        - ConnectToken: []
      parameters:
        - in: path
          name: vaultUuid
          schema:
            type: string
            format: uuid
          required: true
          description: The UUID of the Vault to create an Item in
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FullItem"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FullItem"
        "400":
          description: Unable to create item due to invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: 400
                message: Invalid item category
        "401":
          description: Invalid or missing token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: 401
                message: Invalid token signature
        "403":
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: 403
                message: vault {vaultUuid} is not in scope
        "404":
          description: Item not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                vaultNotFound:
                  summary: Vault not found
                  value:
                    status: 404
                    message: vault {vaultUuid} not found
  /vaults/{vaultUuid}/items/{itemUuid}:
    get:
      operationId: GetVaultItemById
      tags:
        - Items
      summary: Get the details of an Item
      security:
        - ConnectToken: []
      parameters:
        - in: path
          name: vaultUuid
          schema:
            type: string
            format: uuid
          required: true
          description: The UUID of the Vault to fetch Item from
        - in: path
          name: itemUuid
          schema:
            type: string
            format: uuid
          required: true
          description: The UUID of the Item to fetch
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FullItem"
        "401":
          description: Invalid or missing token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: 401
                message: Invalid token signature
        "403":
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: 403
                message: vault {vaultUuid} is not in scope
        "404":
          description: Item not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                itemNotFound:
                  summary: Item not found
                  value:
                    status: 404
                    message: item {itemUuid} not found
                vaultNotFound:
                  summary: Vault not found
                  value:
                    status: 404
                    message: vault {vaultUuid} not found
    put:
      operationId: UpdateVaultItem
      tags:
        - Items
      summary: Update an Item
      security:
        - ConnectToken: []
      parameters:
        - in: path
          name: vaultUuid
          schema:
            type: string
            format: uuid
          required: true
          description: The UUID of the Item's Vault
        - in: path
          name: itemUuid
          schema:
            type: string
            format: uuid
          required: true
          description: The UUID of the Item to update
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FullItem"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FullItem"
        "400":
          description: Unable to create item due to invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: 400
                message: The item doesn't have a {example field name} field.
        "401":
          description: Invalid or missing token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: 401
                message: Invalid token signature
        "403":
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: 403
                message: vault {vaultUuid} is not in scope
        "404":
          description: Item not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                itemNotFound:
                  summary: Item not found
                  value:
                    status: 404
                    message: item {itemUuid} not found
                vaultNotFound:
                  summary: Vault not found
                  value:
                    status: 404
                    message: vault {vaultUuid} not found
    delete:
      operationId: DeleteVaultItem
      tags:
        - Items
      summary: Delete an Item
      security:
        - ConnectToken: []
      parameters:
        - in: path
          name: vaultUuid
          schema:
            type: string
            format: uuid
          required: true
          description: The UUID of the Vault the item is in
        - in: path
          name: itemUuid
          schema:
            type: string
            format: uuid
          required: true
          description: The UUID of the Item to update
      responses:
        "204":
          description: Successfully deleted an item
        "401":
          description: Invalid or missing token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: 401
                message: Invalid token signature
        "403":
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: 403
                message: vault {vaultUuid} is not in scope
        "404":
          description: Item not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                vaultNotFound:
                  summary: Vault not found
                  value:
                    status: 404
                    message: vault {vaultUuid} not found
    patch:
      description: >
        Applies a modified [RFC6902 JSON Patch](https://tools.ietf.org/html/rfc6902) document to an Item or ItemField. This endpoint only supports `add`, `remove` and `replace` operations.


        When modifying a specific ItemField, the ItemField's ID in the `path` attribute of the operation object: `/fields/{fieldId}`

      operationId: PatchVaultItem
      tags:
        - Items
      summary: Update a subset of Item attributes
      security:
        - ConnectToken: [ ]
      parameters:
        - in: path
          name: vaultUuid
          schema:
            type: string
            format: uuid
          required: true
          description: The UUID of the Vault the item is in
        - in: path
          name: itemUuid
          schema:
            type: string
            format: uuid
          required: true
          description: The UUID of the Item to update
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Patch"
            examples:
              ReplaceAllAttributes:
                value:
                  -
                    op: replace
                    path: "/"
                    value: { "title": "New Title", "favorite": true, "tags": ["tag1", "tag2"], "...":"Any attr from FullItem schema" }
                summary: Replace an entire Item with new fields. Equivalent to a PUT request.
              PatchItemAttr:
                value:
                  -
                    op: "replace"
                    path: "/favorite"
                    value: true
                  -
                    op: "remove"
                    path: "/tags/1"
                summary: Update specific Item attributes
              PatchItemField:
                value:
                  -
                    op: "add"
                    path: "/fields"
                    value: {"label": "New Field", "type": "string", "value": "hunter2"}
                summary: Add a new ItemField to the Item
              PatchItemFieldWithID:
                value:
                  -
                    op: "replace"
                    path: "/fields/h4we9a4fEXAMPLE00"
                    value: {"label": "Replacement Title", "type": "string", "value": "new value"}
                  -
                    op: "remove"
                    path: "/fields/inm42xcf0EXAMPLE02"
                summary: Modify or remove an ItemField.
              PatchItemFieldAttr:
                value:
                  -
                    op: "add"
                    path: "/fields/vy09gd8EXAMPLE/label"
                    value: "New field name"
                  - op: "remove"
                    path: "/fields/vy09gd8EXAMPLE/value"
                summary: Modify a specific ItemField attribute.

      responses:
        "200":
          description: OK - Item updated. If no Patch operations were provided, Item is unmodified.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FullItem"
        "401":
          description: Invalid or missing token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: 401
                message: Invalid token signature
        "403":
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                status: 403
                message: vault {vaultUuid} is not in scope
        "404":
          description: Item not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                itemNotFound:
                  summary: Item not found
                  value:
                    status: 404
                    message: item {itemUuid} not found
                vaultNotFound:
                  summary: Vault not found
                  value:
                    status: 404
                    message: vault {vaultUuid} not found