Skip to main content

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:

To view the API in another tool, download the API specification file: 1password-connect-api.yaml

Requirements

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

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

ParameterTypeDescription
filterstringFilter 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

ParameterTypeDescription
vaultUUIDstringThe 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

ParameterTypeDescription
vaultUUIDstringThe UUID of the vault to get the details of.

Query parameters

ParameterTypeDescription
filterstringFilter 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:

ParameterTypeDescription
titlestringThe title of the item.
vaultobjectAn object containing an id property whose value is the UUID of the vault the item is in.
categorystringThe 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.

urlsarrayArray of URL objects containing URLs for the item.
favoritebooleanMark the item as a favorite.
tagsstringAn array of strings of the tags assigned to the item.
fieldsarrayAn array of Field objects of the fields to include with the item.
sectionsarrayAn array of Section objects of the sections to include with the item.

Path parameters

ParameterTypeDescription
vaultUUIDstringThe 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

ParameterTypeDescription
vaultUUIDstringThe UUID of the vault to retrieve the item from.
itemUUIDstringThe 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

ParameterTypeDescription
vaultUUIDstringThe UUID of the vault to retrieve the item from.
itemUUIDstringThe 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

ParameterTypeDescription
vaultUUIDstringThe UUID of the vault to retrieve the item from.
itemUUIDstringThe 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.

ParameterTypeDescription
opstringThe kind of operation to perform. One of:
  • add
  • remove
  • replace
pathstringAn 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"
valueanyThe new value to apply at the path.

Path parameters

ParameterTypeDescription
vaultUUIDstringThe UUID of the vault the item is in.
itemUUIDstringThe 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

ParameterTypeDescription
vaultUUIDstringThe UUID of the vault to get the details of.
itemUUIDstringThe UUID of the item to retrieve.

Query parameters

ParameterTypeDescription
inline_contentbooleanWhether 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

ParameterTypeDescription
vaultUUIDstringThe UUID of the vault to retrieve the item from.
itemUUIDstringThe UUID of the item to retrieve the file from.
fileUUIDstringThe UUID of the file to retrieve.

Query parameters

ParameterTypeDescription
inline_contentbooleanWhether 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

ParameterTypeDescription
vaultUUIDstringThe UUID of the vault to retrieve the item from.
itemUUIDstringThe UUID of the item to retrieve the file from.
fileUUIDstringThe 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

ParameterTypeDescription
limitintegerHow many API Events should be retrieved in a single request. Optional.
offsetintegerHow 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

ParameterTypeDescription
requestIDstringThe UUID for the request.
timestampdateTimeDate and time of the request.
actionstringThe action taken. One of:
  • "READ"
  • "CREATE"
  • "UPDATE"
  • "DELETE"
resultstringThe result of the action. One of:
  • "SUCCESS"
  • "DENY"
actorobjectAn Actor object.
resourceobjectA Resource object.

APIRequest: Actor object

ParameterTypeDescription
idstringThe UUID of the Connect server that made the request.
accountstringThe UUID of the 1Password account the request went to.
jtistringThe UUID of the access token used to authenticate the request.
userAgentstringThe user agent string specified in the request.
ipstringThe IP address the request originated from.

APIRequest: Resource object

ParameterTypeDescription
typestringThe resource requested. One of:
  • "ITEM"
  • "VAULT"
vaultobjectAn object containing an id property with the value of the UUID of the vault requested.
itemobjectAn object containing an id property with the value of the UUID of the item requested.
itemVersionintegerThe version of the item.

ErrorResponse object

ParameterTypeDescription
statusintegerThe HTTP status code.
messagestringA message detailing the error.

Vault object

ParameterTypeDescription
idstringThe UUID of the vault.
namestringThe name of the vault.
descriptionstringThe description for the vault.
attributeVersionintegerThe version of the vault metadata.
contentVersionintegerThe version of the vault contents.
itemsintegerNumber of active items in the vault.
typestringThe 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.
createdAtdateTimeDate and time when the vault was created.
updatedAtdateTimeDate and time when the vault or its contents were last changed.

Item object

ParameterTypeDescription
idstringThe UUID of the item.
titlestringThe title of the item.
vaultobjectAn object containing an id property whose value is the UUID of the vault the item is in.
categorystringThe 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.

urlsarrayArray of URL objects containing URLs for the item.
favoritebooleanWhether the item is marked as a favorite.
tagsarrayAn array of strings of the tags assigned to the item.
versionintegerThe version of the item.
createdAtdateTimeDate and time when the item was created.
updatedAtdateTimeDate and time when the vault or its contents were last changed.
lastEditedBystringUUID of the account that last changed the item.

Item: Field object

ParameterTypeDescription
purpose or typestringUse 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"
valuestringThe 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.

generatebooleanGenerate 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.
recipeobjectA GeneratorRecipe object.
sectionobjectAn object containing the UUID of a section in the item.

Item: File object

NameTypeDescription
idstringThe UUID of the file.
namestringThe name of the file.
sizeintegerThe size of the file in bytes.
content_pathstringThe path to download the contents of the file.
contentstringThe Base64-encoded contents of the file, if inline_files is set to true.
sectionobjectAn 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

NameTypeDescription
lengthintegerThe length of the password to generate. Optional.
characterSetsarrayAn array containing of the kinds of characters to include. Optional. Possible values:
  • "LETTERS"
  • "DIGITS"
  • "SYMBOLS"
excludeCharactersstring A list of all characters that should be excluded from generated passwords. Optional.

Item: Section object

NameTypeDescription
idstringA unique identifier for the section.
labelstringThe label for the section.

Item: URL object

NameTypeDescription
labelstringThe label for the URL.
primarybooleanWhether this is the primary URL for the item.
hrefstringThe address.

Server Health object

NameTypeDescription
namestringName of the server
versionstringVersion info of the Connect server
dependenciesarrayAn array of Service Dependencies.

Server Health: Dependency object

NameTypeDescription
servicestringName of the dependency
statusstringThe service's reported status
messagestringExtra information about the dependency's status. Optional.

Was this page helpful?