1Password Connect Server API reference - 1Password Developer Docs

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:

Authorization: Bearer <access_token>
Content-type: application/json

List vaults

GET /v1/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

Get vault details

GET /v1/vaults/{vaultUUID}

Path parameters

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

Query parameters

No query parameters.

Responses

List items

GET /v1/vaults/{vaultUUID}/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

Add an item

POST /v1/vaults/{vaultUUID}/items

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

{
	"vault": {
	"id": "ftz4pm2xxwmwrsd7rjqn7grzfz"
	},
	"title": "Secrets Automation Item",
	"category": "LOGIN",
	"tags": [
	"connect",
	"\ud83d\udc27"
	],
	"sections": [
	{
		"label": "Security Questions",
		"id": "95cdbc3b-7742-47ec-9056-44d6af82d562"
	}
	],
	"fields": [
	{
		"value": "wendy",
		"purpose": "USERNAME"
	},
	{
		"purpose": "PASSWORD",
		"generate": true,
		"recipe":
		{
			"length": 55,
			"characterSets": [
			"LETTERS",
			"DIGITS"
			]
		}
	},
	{
		"section": {
		"id": "95cdbc3b-7742-47ec-9056-44d6af82d562"
		},
		"type": "CONCEALED",
		"generate": true,
		"label": "Recovery Key"
	},
	{
		"section": {
		"id": "95cdbc3b-7742-47ec-9056-44d6af82d562"
		},
		"type": "STRING",
		"generate": true,
		"label": "Random Text"
	},
	{
		"type": "URL",
		"label": "Example",
		"value": "https://example.com"
	}
	]
}

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

Get item details

GET /v1/vaults/{vaultUUID}/items/{itemUUID}

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

Replace an item

PUT /v1/vaults/{vaultUUID}/items/{itemUUID}

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

Delete an item

DELETE /v1/vaults/{vaultUUID}/items/{itemUUID}

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

Update a subset of item attributes

PATCH /v1/vaults/{vaultUUID}/items/{itemUUID}

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

List files

GET /v1/vaults/{vaultUUID}/items/{itemUUID}/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

Get File details

GET /v1/vaults/{vaultUUID}/items/{itemUUID}/files/{fileUUID}

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

Get file content

GET /v1/vaults/{vaultUUID}/items/{itemUUID}/files/{fileUUID}/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

List API activity

GET /v1/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

GET /heartbeat

Simple “ping” endpoint to check whether server is active.

Query parameters

No query parameters.

Responses

Server Health

GET /health

Query the state of the server and its service dependencies.

Query parameters

No query parameters.

Responses

Metrics

GET /metrics

Returns Prometheus metrics collected by the server.

Query parameters

No query parameters.

Responses

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

{
	status: 401,
	message: "Invalid or missing token"
}

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

Vault object

{
	"id": "ytrfte14kw1uex5txaore1emkz",
	"name": "Demo",
	"attributeVersion": 1,
	"contentVersion": 72,
	"items": 7,
	"type": "USER_CREATED",
	"createdAt": "2021-04-10T17:34:26Z",
	"updatedAt": "2021-04-13T14:33:50Z"
}

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

{
	"id": "2fcbqwe9ndg175zg2dzwftvkpa",
	"title": "Secrets Automation Item",
	"tags": [
		"connect",
		"\ud83d\udc27"
	],
	"vault": {
		"id": "ftz4pm2xxwmwrsd7rjqn7grzfz"
	},
	"category": "LOGIN",
	"sections": [
		{
			"id": "95cdbc3b-7742-47ec-9056-44d6af82d562",
			"label": "Security Questions"
		}
	],
	"fields": [
		{
			"id": "username",
			"type": "STRING",
			"purpose": "USERNAME",
			"label": "username",
			"value": "wendy"
		},
		{
			"id": "password",
			"type": "CONCEALED",
			"purpose": "PASSWORD",
			"label": "password",
			"value": "mjXehR*uCj!aoe!iktt9KMtWb",
			"entropy": 148.0838165283203,
			"passwordDetails": {
				"entropy": 148,
				"generated": true,
				"strength": "FANTASTIC",
				"history": [
					"U-Trxf98hT_GTgNmA.a!pQp3U",
					"_ciCJpYuCB*E7@oRTto4JB4.3"
				]
			}
		},
		{
			"id": "notesPlain",
			"type": "STRING",
			"purpose": "NOTES",
			"label": "notesPlain"
		},
		{
			"id": "a6cvmeqakbxoflkgmor4haji7y",
			"type": "URL",
			"label": "Example",
			"value": "https://example.com"
		},
		{
			"id": "boot3vsxwhuht6g7cmcx4m6rcm",
			"section": {
				"id": "95cdbc3b-7742-47ec-9056-44d6af82d562"
			},
			"type": "CONCEALED",
			"label": "Recovery Key",
			"value": "s=^J@GhHP_isYP>LCq?vv8u7T:*wBP.c"
		},
		{
			"id": "axwtgyjrvwfp5ij7mtkw2zvijy",
			"section": {
				"id": "95cdbc3b-7742-47ec-9056-44d6af82d562"
			},
			"type": "STRING",
			"label": "Random Text",
			"value": "R)D~KZdV!8?51QoCibDUse7=n@wKR_}]"
		}
	],
	"files": [
	{
		"id": "6r65pjq33banznomn7q22sj44e",
		"name": "testfile.txt",
		"size": 35,
		"content_path": "v1/vaults/ftz4pm2xxwmwrsd7rjqn7grzfz/items/2fcbqwe9ndg175zg2dzwftvkpa/files/6r65pjq33banznomn7q22sj44e/content",
	},
	{
		"id": "oyez5gf6xjfptlhc3o4n6o6hvm",
		"name": "samplefile.png",
		"size": 296639,
		"content_path": "v1/vaults/ftz4pm2xxwmwrsd7rjqn7grzfz/items/2fcbqwe9ndg175zg2dzwftvkpa/files/oyez5gf6xjfptlhc3o4n6o6hvm/content",
	}
	],
	"createdAt": "2021-04-10T17:20:05.98944527Z",
	"updatedAt": "2021-04-13T17:20:05.989445411Z"
}

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

{
	"section": {
		"id": "95cdbc3b-7742-47ec-9056-44d6af82d562"
	},
	"type": "STRING",
	"generate": true,
	"label": "Random Text"
}

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

{
	"id": "6r65pjq33banznomn7q22sj44e",
	"name": "testfile.txt",
	"size": 35,
	"content_path": "v1/vaults/ftz4pm2xxwmwrsd7rjqn7grzfz/items/2fcbqwe9ndg175zg2dzwftvkpa/files/6r65pjq33banznomn7q22sj44e/content",
	"content": "VGhlIGZ1dHVyZSBiZWxvbmdzIHRvIHRoZSBjdXJpb3VzLgo=",
	"section": {
		"id": "95cdbc3b-7742-47ec-9056-44d6af82d562"
	},
}

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.

{
	"length": 55,
	"characterSets": [
		"LETTERS",
		"DIGITS"
	]
}

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

{
    "entropy": 148,
    "generated": true,
    "strength": "FANTASTIC",
    "history": [
      "U-Trxf98hT_GTgNmA.a!pQp3U",
      "_ciCJpYuCB*E7@oRTto4JB4.3"
    ]
}

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

{
	"id": "95cdbc3b-7742-47ec-9056-44d6af82d562"
	"label": "Security Questions",
}

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

Item: URL object

{
	"label": "website",
	"primary": true,
	"href": "https://example.com"
}

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": "1Password Connect API",
	"version": "1.2.1",
		"dependencies": [
			{
				"service": "sync",
				"status": "TOKEN_NEEDED"
			},
			{
				"service": "sqlite",
				"status": "ACTIVE",
				"message": "Connected to  ~/1password.sqlite"
			}
		]
}

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.

Secrets Automation

​Requirements

​Request headers

​List vaults

​Path parameters

​Query parameters

​Responses

​Get vault details

​Path parameters

​Query parameters

​Responses

​List items

​Path parameters

​Query parameters

​Responses

​Add an item

​Path parameters

​Query parameters

​Responses

​Get item details

​Path parameters

​Query parameters

​Responses

​Replace an item

​Path parameters

​Query parameters

​Responses

​Delete an item

​Path parameters

​Query parameters

​Responses

​Update a subset of item attributes

​Path parameters

​Query parameters

​Responses

​List files

​Path parameters

​Query parameters

​Responses

​Get File details

​Path parameters

​Query parameters

​Responses

​Get file content

​Path parameters

​Query parameters

​Responses

​List API activity

​Query parameters

​Server Heartbeat

​Query parameters

​Responses

​Server Health

​Query parameters

​Responses

​Metrics

​Query parameters

​Responses

​Response object models

​APIRequest object

​APIRequest: Actor object

​APIRequest: Resource object

​ErrorResponse object

​Vault object

​Item object

​Item: Field object

​Item: File object

​Item: GeneratorRecipe object

​Item: PasswordDetails object

​Item: Section object

​Item: URL object

​Server Health object

​Server Health: Dependency object

Requirements

Request headers

List vaults

Path parameters

Query parameters

Responses

Get vault details

Path parameters

Query parameters

Responses

List items

Path parameters

Query parameters

Responses

Add an item

Path parameters

Query parameters

Responses

Get item details

Path parameters

Query parameters

Responses

Replace an item

Path parameters

Query parameters

Responses

Delete an item

Path parameters

Query parameters

Responses

Update a subset of item attributes

Path parameters

Query parameters

Responses

List files

Path parameters

Query parameters

Responses

Get File details

Path parameters

Query parameters

Responses

Get file content

Path parameters

Query parameters

Responses

List API activity

Query parameters

Server Heartbeat

Query parameters

Responses

Server Health

Query parameters

Responses

Metrics

Query parameters

Responses

Response object models

APIRequest object

APIRequest: Actor object

APIRequest: Resource object

ErrorResponse object

Vault object

Item object

Item: Field object

Item: File object

Item: GeneratorRecipe object

Item: PasswordDetails object

Item: Section object

Item: URL object

Server Health object

Server Health: Dependency object