1Password Connect Server API reference

info

If you're new to 1Password Secrets Automation and 1Password Connect Server, learn how to get started with a Secrets Automation workflow.

You can use the Connect API to work with the vaults and items in your account, and to list API activity on a Connect server:

• List vaults
• Get vault details
• List items
• Add an item
• Get item details
• Replace an item
• Delete an item
• Update a subset of item attributes
• List files
• Get file details
• Get file content
• List API activity

To view the API in another tool, download the 1Password Connect API specification file (1.8.1).

Requirements

Before you can use the 1Password Connect Server API, you'll need to:

• Sign up for 1Password.
• Set up a Secrets Automation workflow..
• Deploy 1Password Connect in your infrastructure.

Request headers

Each request to the API has to be authenticated with an access token. Provide it and specify the content type:

List vaults

Path parameters

No path parameters

Query parameters

Parameter	Type	Description
filter	string	Filter the vault collection using SCIM-style filters. Vaults can only be filtered by name. Optional. For example: name eq "Demo Vault"

Responses

200

Returns an array of vault names and IDs

401

Invalid or missing token

Get vault details

Path parameters

Parameter	Type	Description
vaultUUID	string	The UUID of the vault to retrieve items from.

Query parameters

No query parameters.

Responses

200

Returns a Vault object

401

Invalid or missing token

403

Unauthorized access

404

Vault not found

List items

Path parameters

Parameter	Type	Description
vaultUUID	string	The UUID of the vault to get the details of.

Query parameters

Parameter	Type	Description
filter	string	Filter the item collection using SCIM-style filters . Items can only be filtered by title or tag. Optional. For example: title eq "Example Item" or tag eq "banking"

Responses

200

Returns an array of Item objects that don't include sections and fields

401

Invalid or missing token

404

Vault not found

Add an item

The request must include a FullItem object, containing the information to create the item. For example:

Parameter	Type	Description
title	string	The title of the item.
vault	object	An object containing an id property whose value is the UUID of the vault the item is in.
category	string	The category of the item. One of: "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" "EMAIL_ACCOUNT" "SOCIAL_SECURITY_NUMBER" "MEDICAL_RECORD" "SSH_KEY" You can't create items using the "CUSTOM" or "DOCUMENT" categories.
urls	array	Array of URL objects containing URLs for the item.
favorite	boolean	Mark the item as a favorite.
tags	string	An array of strings of the tags assigned to the item.
fields	array	An array of Field objects of the fields to include with the item.
sections	array	An array of Section objects of the sections to include with the item.

Path parameters

Parameter	Type	Description
vaultUUID	string	The UUID of the vault to create an item in.

Query parameters

No query parameters.

Responses

200

Returns Item object containing the new item

400

Unable to create item due to invalid input

401

Invalid or missing token

403

Unauthorized access

404

Item not found

Get item details

Path parameters

Parameter	Type	Description
vaultUUID	string	The UUID of the vault to retrieve the item from.
itemUUID	string	The UUID of the item to retrieve.

Query parameters

No query parameters.

Responses

200

Returns an Item object

401

Invalid or missing token

403

Unauthorized access

404

Item not found

Replace an item

Path parameters

Parameter	Type	Description
vaultUUID	string	The UUID of the vault to retrieve the item from.
itemUUID	string	The UUID of the item to replace.

Query parameters

No query parameters.

Responses

200

Returns an Item object

400

Unable to create item due to invalid input

401

Invalid or missing token

403

Unauthorized access

404

Item not found

Delete an item

Path parameters

Parameter	Type	Description
vaultUUID	string	The UUID of the vault to retrieve the item from.
itemUUID	string	The UUID of the item to delete.

Query parameters

No query parameters.

Responses

204

Successfully deleted an item

401

Invalid or missing token

403

Unauthorized access

404

Item not found

Update a subset of item attributes

Applies an add, remove, or replace operation on an item or the fields of an item. Uses the RFC6902 JSON Patch document standard.

Parameter	Type	Description
op	string	The kind of operation to perform. One of: add remove replace
path	string	An RFC6901 JSON Pointer to the item, an item attribute, an item field by field ID, or an item field attribute. For example: "/fields/vy09gd8EXAMPLE/label"
value	any	The new value to apply at the path.

Path parameters

Parameter	Type	Description
vaultUUID	string	The UUID of the vault the item is in.
itemUUID	string	The UUID of the item to update.

Query parameters

No query parameters.

Responses

200

Returns an Item object of the updated item.

401

Invalid or missing token

403

Unauthorized access

404

Item not found

List files

Path parameters

Parameter	Type	Description
vaultUUID	string	The UUID of the vault to get the details of.
itemUUID	string	The UUID of the item to retrieve.

Query parameters

Parameter	Type	Description
inline_content	boolean	Whether to return the Base-64 encoded file content. The file size must be less than OP_MAX_INLINE_FILE_SIZE_KB, or 100 kilobytes if the file size isn't defined. Optional.

Responses

200

Returns an array of File objects

401

Invalid or missing token

404

Item not found

413

File too large to display inline

Get File details

Path parameters

Parameter	Type	Description
vaultUUID	string	The UUID of the vault to retrieve the item from.
itemUUID	string	The UUID of the item to retrieve the file from.
fileUUID	string	The UUID of the file to retrieve.

Query parameters

Parameter	Type	Description
inline_content	boolean	Whether to return the Base-64 encoded file content. The file size must be less than OP_MAX_INLINE_FILE_SIZE_KB, or 100 kilobytes if the file size isn't defined. Optional.

Responses

200

Returns a File object

401

Invalid or missing token

403

Unauthorized access

404

File not found

413

File too large to display inline

Get file content

Path parameters

Parameter	Type	Description
vaultUUID	string	The UUID of the vault to retrieve the item from.
itemUUID	string	The UUID of the item to retrieve the file from.
fileUUID	string	The UUID of the file to retrieve.

Query parameters

No query parameters.

Responses

200

Returns the content of the file

401

Invalid or missing token

403

Unauthorized access

404

File not found

List API activity

Retrieve a list of API Requests that have been made.

Query parameters

Parameter	Type	Description
limit	integer	How many API Events should be retrieved in a single request. Optional.
offset	integer	How far into the collection of API Events should the response start. Optional.

Server Heartbeat

Simple "ping" endpoint to check whether server is active.

Query parameters

No query parameters.

Responses

200

Returns a text/plain response with a single "."

Server Health

Query the state of the server and its service dependencies.

Query parameters

No query parameters.

Responses

200

Returns a Server Health object

Metrics

Returns Prometheus metrics collected by the server.

Query parameters

No query parameters.

Responses

200

Returns a plaintext list of Prometheus metrics. See the Prometheus documentation for specifics.

Response object models

APIRequest object

Parameter	Type	Description
requestID	string	The UUID for the request.
timestamp	dateTime	Date and time of the request.
action	string	The action taken. One of: "READ" "CREATE" "UPDATE" "DELETE"
result	string	The result of the action. One of: "SUCCESS" "DENY"
actor	object	An Actor object.
resource	object	A Resource object.

APIRequest: Actor object

Parameter	Type	Description
id	string	The UUID of the Connect server that made the request.
account	string	The UUID of the 1Password account the request went to.
jti	string	The UUID of the access token used to authenticate the request.
userAgent	string	The user agent string specified in the request.
ip	string	The IP address the request originated from.

APIRequest: Resource object

Parameter	Type	Description
type	string	The resource requested. One of: "ITEM" "VAULT"
vault	object	An object containing an id property with the value of the UUID of the vault requested.
item	object	An object containing an id property with the value of the UUID of the item requested.
itemVersion	integer	The version of the item.

ErrorResponse object

Parameter	Type	Description
status	integer	The HTTP status code.
message	string	A message detailing the error.

Vault object

Parameter	Type	Description
id	string	The UUID of the vault.
name	string	The name of the vault.
description	string	The description for the vault.
attributeVersion	integer	The version of the vault metadata.
contentVersion	integer	The version of the vault contents.
items	integer	Number of active items in the vault.
type	string	The type of vault. One of: "EVERYONE": The team Shared vault. "PERSONAL": The Private vault for the Connect server. "USER_CREATED": A vault created by a user.
createdAt	dateTime	Date and time when the vault was created.
updatedAt	dateTime	Date and time when the vault or its contents were last changed.

Item object

Parameter	Type	Description
id	string	The UUID of the item.
title	string	The title of the item.
vault	object	An object containing an id property whose value is the UUID of the vault the item is in.
category	string	The category of the item. One of: "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" You can't create items using the "CUSTOM" or "DOCUMENT" categories.
urls	array	Array of URL objects containing URLs for the item.
favorite	boolean	Whether the item is marked as a favorite.
tags	array	An array of strings of the tags assigned to the item.
version	integer	The version of the item.
createdAt	dateTime	Date and time when the item was created.
updatedAt	dateTime	Date and time when the vault or its contents were last changed.
lastEditedBy	string	UUID of the account that last changed the item.

Item: Field object

Parameter	Type	Description
purpose or type	string	Use purpose for the username, password, and notes fields. Possible values: "USERNAME" "PASSWORD" "NOTES" Use type for all other fields. Possible values are: "STRING" "EMAIL" "CONCEALED" "URL" "OTP" (format: otpauth://) "DATE" (format: YYYY-MM-DD) "MONTH_YEAR" (format: YYYYMM or YYYY/MM) "MENU"
value	string	The value to save for the field. You can specify a generate field instead of value to create a password or other random information for the value.
generate	boolean	Generate a password and save in the value for the field. By default, the password is a 32-characters long, made up of letters, numbers, and symbols. To customize the password, include a recipe field.
recipe	object	A GeneratorRecipe object.
section	object	An object containing the UUID of a section in the item.

Item: File object

Name	Type	Description
id	string	The UUID of the file.
name	string	The name of the file.
size	integer	The size of the file in bytes.
content_path	string	The path to download the contents of the file.
content	string	The Base64-encoded contents of the file, if inline_files is set to true.
section	object	An object containing the UUID of a section in the item.

Item: GeneratorRecipe object

The recipe is used in conjunction with the "generate" property to set the character set used to generate a new secure value.

Name	Type	Description
length	integer	The length of the password to generate. Optional.
characterSets	array	An array containing of the kinds of characters to include. Optional. Possible values: "LETTERS" "DIGITS" "SYMBOLS"
excludeCharacters	string	A list of all characters that should be excluded from generated passwords. Optional.

Item: PasswordDetails object

Name	Type	Description
entropy	integer	The unpredictability of the password, measured in bits.
generated	boolean	Whether the password was generated using the password generator.
strength	string	The strength of the password. One of: "TERRIBLE" "WEAK" "FAIR" "GOOD" "VERY_GOOD" "EXCELLENT" "FANTASTIC"
history	array	An array of strings containing the previous passwords of the item.

Item: Section object

Name	Type	Description
id	string	A unique identifier for the section.
label	string	The label for the section.

Item: URL object

Name	Type	Description
label	string	The label for the URL.
primary	boolean	Whether this is the primary URL for the item.
href	string	The address.

Server Health object

Name	Type	Description
name	string	Name of the server
version	string	Version info of the Connect server
dependencies	array	An array of Service Dependencies.

Server Health: Dependency object

Name	Type	Description
service	string	Name of the dependency
status	string	The service's reported status
message	string	Extra information about the dependency's status. Optional.