1Password Connect Server API reference
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:
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: |
---|
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: |
---|
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: |
---|
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: 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. |
---|