Teams and Businesses

1Password Connect API reference

Learn how to build your own Connect client using the 1Password Connect REST API.

Tip

If you’re new to 1Password Secrets Automation and 1Password Connect, 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


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

ParameterTypeDescription
filterstringFilter the item collection based on item title using SCIM-style filters . Optional.
For example: name eq "Demo Vault"

Query parameters

No query parameters.

Responses

200
Returns an array of Vault objects
401
Invalid or missing token

Get vault details

GET /v1/vaults/{vaultUUID}

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

GET /v1/vaults/{vaultUUID}/items

Path parameters

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

Query parameters

ParameterTypeDescription
filterstringFilter the item collection based on item title using SCIM-style filters . Optional.
For example: title eq "Example Item"

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

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"
    }
  ]
}
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"
  • "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"
  • "API_CREDENTIAL"

You can’t create items using the "CUSTOM" category.

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

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

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

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

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

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

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

Change item details

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.

NameTypeDescription
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

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

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

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

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

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

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

GET /health

Query the state of the server and its service dependencies.

Query parameters

No query parameters.

Responses

200
Returns a Server Health object

Metrics

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

NameTypeDescription
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

NameTypeDescription
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

NameTypeDescription
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

{
  status: 401,
  message: "Invalid or missing token"
}
NameTypeDescription
statusintegerThe HTTP status code.
messagestringA 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"
}
NameTypeDescription
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

{
  "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": "hLDegPkuMQqyQiyDZqRdWGoojiN5KYQtXuA0wBDe9z3Caj6FQGHpbGu",
      "entropy": 189.78359985351562
    },
    {
      "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"
}
NameTypeDescription
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"
  • "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"
  • "API_CREDENTIAL"

You can’t create items using the "CUSTOM" category.

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.
statestringThe state of the item. One of:
  • "ARCHIVED"
  • "DELETED"
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

{
  "section": {
    "id": "95cdbc3b-7742-47ec-9056-44d6af82d562"
  },
  "type": "STRING",
  "generate": true,
  "label": "Random Text"
}
NameTypeDescription
purpose
or type
stringUse 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"
  • "DATE"
  • "MONTH_YEAR"
  • "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

{
  "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"
  },
}
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

{
  "length": 55,
  "characterSets": [
    "LETTERS",
    "DIGITS"
  ]
}
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"

Item: Section object

{
  "id": "95cdbc3b-7742-47ec-9056-44d6af82d562"
  "label": "Security Questions",
}
NameTypeDescription
idstringA unique identifier for the section.
labelstringThe label for the section.

Item: URL object

{
  "primary": true,
  "href": "https://example.com"
}
NameTypeDescription
urlstringThe address.
primarybooleanWhether this is the primary URL for the item.

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"
    }
  ]
}
NameTypeDescription
namestringName of the server
versionstringVersion info of the 1Password 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.

Still need help?

If this article didn't answer your question, contact 1Password Support.

Published: