openapi: 3.1.0 info: title: 1Password Connect Server API description: The 1Password Connect Server API provides secure access to 1Password items and vaults in your company's apps and cloud infrastructure through a private REST API. Connect Servers bridge the gap between 1Password and your infrastructure by enabling programmatic access to secrets stored in shared vaults. You can create, read, update, and delete items, manage vaults, and retrieve files attached to items. version: 1.8.1 contact: name: 1Password Support url: https://support.1password.com/ termsOfService: https://1password.com/legal/terms-of-service/ license: name: MIT url: https://github.com/1Password/connect/blob/main/LICENSE externalDocs: description: 1Password Connect Server API Reference url: https://developer.1password.com/docs/connect/api-reference/ servers: - url: http://localhost:8080 description: Local Connect Server (default port 8080) tags: - name: Activity description: Operations for listing API requests made to the Connect server. - name: Files description: Operations for listing and retrieving files attached to items. - name: Health description: Operations for checking the health and status of the Connect server. - name: Items description: Operations for creating, reading, updating, and deleting items within vaults. - name: Metrics description: Operations for retrieving Prometheus-style metrics from the Connect server. - name: Vaults description: Operations for listing and retrieving vaults available to the Connect server. security: - bearerAuth: [] paths: /v1/vaults: get: operationId: listVaults summary: 1Password List Vaults description: Returns a list of all vaults the Connect server has been authorized to access. Each vault includes its unique identifier, name, description, and attribute version. tags: - Vaults parameters: - $ref: '#/components/parameters/filterParam' responses: '200': description: Successfully retrieved vaults content: application/json: schema: type: array items: $ref: '#/components/schemas/Vault' '401': $ref: '#/components/responses/Unauthorized' x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/vaults/{vaultUuid}: get: operationId: getVaultById summary: 1Password Get Vault Details description: Returns detailed information about a specific vault identified by its UUID, including its name, description, attribute version, content version, and item count. tags: - Vaults parameters: - $ref: '#/components/parameters/vaultUuidParam' responses: '200': description: Successfully retrieved vault details content: application/json: schema: $ref: '#/components/schemas/Vault' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/vaults/{vaultUuid}/items: get: operationId: listItems summary: 1Password List Items in a Vault description: Returns a list of items stored in the specified vault. Results can be filtered by title using the filter query parameter. Each returned item includes basic metadata but not the full item details or field values. tags: - Items parameters: - $ref: '#/components/parameters/vaultUuidParam' - $ref: '#/components/parameters/filterParam' responses: '200': description: Successfully retrieved items content: application/json: schema: type: array items: $ref: '#/components/schemas/Item' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' x-microcks-operation: delay: 0 dispatcher: FALLBACK post: operationId: createItem summary: 1Password Create a New Item description: Creates a new item in the specified vault. The request body must include a FullItem object containing the information needed to create the item, including the vault reference, category, title, and fields. tags: - Items parameters: - $ref: '#/components/parameters/vaultUuidParam' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/FullItem' responses: '200': description: Successfully created item content: application/json: schema: $ref: '#/components/schemas/FullItem' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/vaults/{vaultUuid}/items/{itemUuid}: get: operationId: getItemById summary: 1Password Get Item Details description: Returns the full details of an item identified by its UUID within the specified vault. This includes all fields, sections, URLs, and associated metadata. tags: - Items parameters: - $ref: '#/components/parameters/vaultUuidParam' - $ref: '#/components/parameters/itemUuidParam' responses: '200': description: Successfully retrieved item details content: application/json: schema: $ref: '#/components/schemas/FullItem' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' x-microcks-operation: delay: 0 dispatcher: FALLBACK put: operationId: replaceItem summary: 1Password Replace an Item description: Replaces an entire item with new fields and values in the specified vault. The request body must include a complete FullItem object that will replace the existing item. tags: - Items parameters: - $ref: '#/components/parameters/vaultUuidParam' - $ref: '#/components/parameters/itemUuidParam' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/FullItem' responses: '200': description: Successfully replaced item content: application/json: schema: $ref: '#/components/schemas/FullItem' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' x-microcks-operation: delay: 0 dispatcher: FALLBACK patch: operationId: patchItem summary: 1Password Update an Item description: Applies an add, remove, or replace operation on an item or the fields of an item using the RFC6902 JSON Patch document standard. This allows partial updates to items without replacing the entire object. tags: - Items parameters: - $ref: '#/components/parameters/vaultUuidParam' - $ref: '#/components/parameters/itemUuidParam' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/JsonPatch' responses: '200': description: Successfully updated item content: application/json: schema: $ref: '#/components/schemas/FullItem' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' x-microcks-operation: delay: 0 dispatcher: FALLBACK delete: operationId: deleteItem summary: 1Password Delete an Item description: Permanently deletes an item identified by its UUID from the specified vault. This action cannot be undone. tags: - Items parameters: - $ref: '#/components/parameters/vaultUuidParam' - $ref: '#/components/parameters/itemUuidParam' responses: '204': description: Successfully deleted item '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/vaults/{vaultUuid}/items/{itemUuid}/files: get: operationId: listFiles summary: 1Password List Files Attached to an Item description: Returns a list of all files attached to the specified item within the given vault. Each file entry includes its unique identifier, name, size, and content path. tags: - Files parameters: - $ref: '#/components/parameters/vaultUuidParam' - $ref: '#/components/parameters/itemUuidParam' - name: inline_files in: query description: When set to true, file content is included inline in the response. required: false schema: type: boolean default: false responses: '200': description: Successfully retrieved files content: application/json: schema: type: array items: $ref: '#/components/schemas/File' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/vaults/{vaultUuid}/items/{itemUuid}/files/{fileUuid}: get: operationId: getFileById summary: 1Password Get File Details description: Returns the metadata for a specific file attached to an item within the specified vault. tags: - Files parameters: - $ref: '#/components/parameters/vaultUuidParam' - $ref: '#/components/parameters/itemUuidParam' - $ref: '#/components/parameters/fileUuidParam' - name: inline_files in: query description: When set to true, file content is included inline in the response. required: false schema: type: boolean default: false responses: '200': description: Successfully retrieved file details content: application/json: schema: $ref: '#/components/schemas/File' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/vaults/{vaultUuid}/items/{itemUuid}/files/{fileUuid}/content: get: operationId: getFileContent summary: 1Password Get File Content description: Returns the raw content of a specific file attached to an item within the specified vault. The response is the binary file content. tags: - Files parameters: - $ref: '#/components/parameters/vaultUuidParam' - $ref: '#/components/parameters/itemUuidParam' - $ref: '#/components/parameters/fileUuidParam' responses: '200': description: Successfully retrieved file content content: application/octet-stream: schema: type: string format: binary '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' x-microcks-operation: delay: 0 dispatcher: FALLBACK /v1/activity: get: operationId: listActivity summary: 1Password List API Activity description: Returns a list of API requests that have been made to the Connect server. Each activity entry includes the request method, path, timestamp, and result status. tags: - Activity parameters: - name: limit in: query description: Maximum number of activity records to return. required: false schema: type: integer default: 50 - name: offset in: query description: Number of activity records to skip before returning results. required: false schema: type: integer default: 0 responses: '200': description: Successfully retrieved activity log content: application/json: schema: type: array items: $ref: '#/components/schemas/APIRequest' '401': $ref: '#/components/responses/Unauthorized' x-microcks-operation: delay: 0 dispatcher: FALLBACK /heartbeat: get: operationId: getHeartbeat summary: 1Password Check Server Status description: Returns a simple response to indicate that the Connect server is active and responding to requests. This endpoint does not require authentication. tags: - Health security: [] responses: '200': description: Server is active content: text/plain: schema: type: string example: . x-microcks-operation: delay: 0 dispatcher: FALLBACK /health: get: operationId: getHealth summary: 1Password Get Server Health description: Returns detailed information about the state of the Connect server and its service dependencies, including the 1Password service connectivity status. tags: - Health security: [] responses: '200': description: Server is healthy content: application/json: schema: $ref: '#/components/schemas/ServerHealth' x-microcks-operation: delay: 0 dispatcher: FALLBACK /metrics: get: operationId: getMetrics summary: 1Password Get Server Metrics description: Returns Prometheus-compatible metrics about the Connect server including request counts, latencies, and resource usage. tags: - Metrics security: [] responses: '200': description: Successfully retrieved metrics content: text/plain: schema: type: string x-microcks-operation: delay: 0 dispatcher: FALLBACK components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: A Connect server access token generated from 1Password. Each request must include this token in the Authorization header. parameters: vaultUuidParam: name: vaultUuid in: path description: The UUID of the vault. required: true schema: type: string format: uuid itemUuidParam: name: itemUuid in: path description: The UUID of the item. required: true schema: type: string format: uuid fileUuidParam: name: fileUuid in: path description: The UUID of the file. required: true schema: type: string format: uuid filterParam: name: filter in: query description: A SCIM-style filter to narrow results. For example, use title eq "Example" to filter items by title. required: false schema: type: string responses: BadRequest: description: Bad request due to invalid input content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Authentication credentials are missing or invalid content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The requested resource was not found content: application/json: schema: $ref: '#/components/schemas/Error' schemas: Vault: type: object description: Represents a 1Password vault that contains items. Vaults are used to organize and control access to secrets. properties: id: type: string format: uuid description: The unique identifier for the vault. name: type: string description: The name of the vault. description: type: string description: A description of the vault's purpose. attributeVersion: type: integer description: The version of the vault attributes. contentVersion: type: integer description: The version of the vault contents. items: type: integer description: The number of items in the vault. type: type: string description: The type of the vault. enum: - USER_CREATED - PERSONAL - EVERYONE - TRANSFER createdAt: type: string format: date-time description: The date and time the vault was created. updatedAt: type: string format: date-time description: The date and time the vault was last updated. Item: type: object description: Represents a summary of a 1Password item with basic metadata. Use the get item endpoint to retrieve full details. properties: id: type: string format: uuid description: The unique identifier for the item. title: type: string description: The title of the item. vault: $ref: '#/components/schemas/VaultRef' category: type: string description: The category of the item. 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 - MEDICAL_RECORD - SSH_KEY - CUSTOM urls: type: array description: URLs associated with the item. items: $ref: '#/components/schemas/Url' favorite: type: boolean description: Whether the item is marked as a favorite. tags: type: array description: Tags applied to the item. items: type: string version: type: integer description: The version number of the item. state: type: string description: The state of the item. enum: - ARCHIVED - DELETED createdAt: type: string format: date-time description: The date and time the item was created. updatedAt: type: string format: date-time description: The date and time the item was last updated. lastEditedBy: type: string format: uuid description: The UUID of the user who last edited the item. FullItem: type: object description: Represents a complete 1Password item including all fields, sections, and associated metadata. Used for creating and updating items. allOf: - $ref: '#/components/schemas/Item' - type: object properties: fields: type: array description: The fields of the item containing secrets and metadata. items: $ref: '#/components/schemas/Field' sections: type: array description: Sections used to organize fields within the item. items: $ref: '#/components/schemas/Section' Field: type: object description: Represents a field within an item that stores a value such as a username, password, or other data. properties: id: type: string description: The unique identifier for the field. section: $ref: '#/components/schemas/SectionRef' type: type: string description: The type of the field. enum: - STRING - EMAIL - CONCEALED - URL - TOTP - DATE - MONTH_YEAR - MENU purpose: type: string description: The purpose of the field, indicating its role within the item. enum: - USERNAME - PASSWORD - NOTES label: type: string description: The human-readable label for the field. value: type: string description: The value stored in the field. generate: type: boolean description: Whether the field value should be auto-generated. entropy: type: number description: The entropy (strength) of the generated value. recipe: $ref: '#/components/schemas/GeneratorRecipe' GeneratorRecipe: type: object description: Configuration for generating a random value for a field, such as password length and character types. properties: length: type: integer description: The length of the generated value. minimum: 1 maximum: 64 characterSets: type: array description: The character sets to use when generating the value. items: type: string enum: - LETTERS - DIGITS - SYMBOLS excludeCharacters: type: string description: Characters to exclude from the generated value. Section: type: object description: Represents a section within an item used to organize fields into logical groups. properties: id: type: string description: The unique identifier for the section. label: type: string description: The human-readable label for the section. SectionRef: type: object description: A reference to a section within an item. properties: id: type: string description: The unique identifier of the referenced section. VaultRef: type: object description: A reference to a vault. properties: id: type: string format: uuid description: The unique identifier of the referenced vault. Url: type: object description: Represents a URL associated with an item. properties: primary: type: boolean description: Whether this is the primary URL for the item. href: type: string format: uri description: The URL value. File: type: object description: Represents a file attached to an item in a vault. properties: id: type: string format: uuid description: The unique identifier for the file. name: type: string description: The name of the file. size: type: integer description: The size of the file in bytes. content_path: type: string description: The API path to retrieve the file content. section: $ref: '#/components/schemas/SectionRef' content: type: string format: byte description: The base64-encoded file content, included when inline_files is true. JsonPatch: type: array description: A JSON Patch document as defined by RFC 6902 for applying partial modifications to items. items: type: object required: - op - path properties: op: type: string description: The operation to perform. enum: - add - remove - replace path: type: string description: A JSON Pointer to the target location in the item. value: description: The value to use in the operation. Required for add and replace. APIRequest: type: object description: Represents a record of an API request made to the Connect server. properties: requestId: type: string format: uuid description: The unique identifier for the API request. timestamp: type: string format: date-time description: When the request was made. action: type: string description: The HTTP method of the request. result: type: string description: The result status of the request. enum: - SUCCESS - DENY actor: type: object description: The actor who made the request. properties: id: type: string format: uuid description: The unique identifier of the actor. account: type: string description: The account associated with the actor. jti: type: string description: The JWT token identifier. userAgent: type: string description: The user agent string of the client. requestIp: type: string description: The IP address of the client. resource: type: object description: The resource that was accessed. properties: type: type: string description: The type of resource. vault: $ref: '#/components/schemas/VaultRef' item: type: object properties: id: type: string format: uuid description: The unique identifier of the item. itemVersion: type: integer description: The version of the item. ServerHealth: type: object description: Represents the health status of the Connect server and its dependencies. properties: name: type: string description: The name of the Connect server. version: type: string description: The version of the Connect server. dependencies: type: array description: The health status of server dependencies. items: type: object properties: service: type: string description: The name of the dependency service. status: type: string description: The status of the dependency. enum: - ACTIVE - INACTIVE - ERROR message: type: string description: Additional information about the dependency status. Error: type: object description: Represents an error response from the Connect server. properties: status: type: integer description: The HTTP status code. message: type: string description: A human-readable error message.