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:


If you want to view the API in another tool, you can 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

Parameter Type Description
filter string Filter 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

Parameter Type Description
vaultUUID string The UUID of the vault to fetch 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

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

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

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

Path parameters

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

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

Parameter Type Description
vaultUUID string The UUID of the vault to fetch 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

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

Path parameters

Parameter Type Description
vaultUUID string The UUID of the vault to fetch 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

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.

Name 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 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

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

Name 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

Name 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

Name 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"
}
Name 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"
}
Name 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": "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_}]"
    }
  ],
  "createdAt": "2021-04-10T17:20:05.98944527Z",
  "updatedAt": "2021-04-13T17:20:05.989445411Z"
}
Name 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"
  • "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.

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.
state string The state of the item. One of:
  • "ARCHIVED"
  • "DELETED"
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"
}
Name 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"
  • "DATE"
  • "MONTH_YEAR"
  • "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: 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"

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

{
  "primary": true,
  "url": "https://example.com"
}
Name Type Description
url string The address.
primary boolean Whether 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"
    }
  ]
}
Name Type Description
name string Name of the server
version string Version info of the 1Password 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.
Published: