Manage files using 1Password SDKs - 1Password Developer Docs

You can use 1Password SDKs to read, save, and delete files in your items in 1Password. Before you begin, follow the steps to get started with a 1Password SDK.

See the examples folder in the 1Password Go, JavaScript, or Python SDK GitHub repository for example code you can quickly clone and test in your project.

You can store files in Password in two ways:

Field file: A file attachment stored as a custom field in any item. You can attach multiple field files to each item.
Document file: A file stored as a Document item. Document items can only store a single document file.

Read a file

Go
JavaScript
Python

You can read any file saved in 1Password using the Items().Files().Read method with the attributes of the file you want to retrieve, and the IDs for the item and vault where the file is stored. 1Password returns the file content as an array of bytes.You can get the file attributes for a file from its parent item by retrieving it.

File field
Document file

// Read the file field from an item
retrievedFileContent, err := client.Items().Files().Read(context.Background(), item.VaultID, item.ID, item.Files[0].Attributes)
if err != nil {
	panic(err)
}

// Read the document item
content, err := client.Items().Files().Read(context.Background(), replacedDocItem.VaultID, replacedDocItem.ID, *replacedDocItem.Document)
if err != nil {
	panic(err)
}

You can read any file saved in 1Password using the items.files.read() method with the attributes of the file you want to retrieve, and the IDs for the item and vault where the file is stored. 1Password returns the file content as an array of bytes.You can get the file attributes for a file from its parent item by retrieving it.

File field
Document file

// Read the content of the file field on the Item
let content = await client.items.files.read(
  item.vaultId,
  item.id,
  item.files[0].attributes,
);

// Read the content of the Document Item
let content = await client.items.files.read(
  replacedDocumentItem.vaultId,
  replacedDocumentItem.id,
  replacedDocumentItem.document,
);

File field
Document file

# Read the file field from an item
content = await client.items.files.read(
    created_item.vault_id, created_item.id, created_item.files[0].attributes
)

# Read the document in the item
content = await client.items.files.read(
    replaced_item.vault_id, replaced_item.id, replaced_item.document
)

Field file operations

Save a file

You can save field files when you create an item or modify an existing item. To save a file in 1Password as a field file, you’ll need to read the file locally then pass the file contents and name using the FileCreateParams parameter. Field file parameters include:

Parameter	Description
Name	The name of the file.
Content	The file contents.
Section ID	The ID for the custom section where the file will be saved. If the section the ID points to does not exist in the item, a new section will be created.
Field ID	The ID for the field where the file will be saved. Must be unique within the `Fields` and `Files` of the item.

Save files in a new item
Save a file in an existing item

Go
JavaScript
Python

You can add files to a new item when you create the item by including them in the ItemCreateParams struct.

fileContent, err := os.ReadFile("./example/service_account/file.txt")
if err != nil {
	panic(err)
}
// Create the File Field item
item, err := client.Items().Create(context.Background(), onepassword.ItemCreateParams{
	Title:    "Login with File Field created with SDK",
	Category: onepassword.ItemCategoryLogin,
	VaultID:  vaultID,
	Sections: []onepassword.ItemSection{
		{
			ID: sectionID,
		},
	},
	Files: []onepassword.FileCreateParams{
		{
			Name:      "file.txt",
			Content:   fileContent,
			SectionID: sectionID,
			FieldID:   "file_field",
		},
	},
})
if err != nil {
	panic(err)
}

You can add files to a new item when you create the item by including them in the ItemCreateParams object.

// Create the file field item
let item = await client.items.create({
  title: "Login with File Field Item Created With JS SDK",
  category: sdk.ItemCategory.Login,
  vaultId: vaultId,
  fields: [
    {
      id: "username",
      title: "username",
      fieldType: sdk.ItemFieldType.Text,
      value: "my username",
    },
    {
      id: "password",
      title: "password",
      fieldType: sdk.ItemFieldType.Concealed,
      value: "my secret value",
    },
  ],
  sections: [
    {
      id: "custom section",
      title: "my section",
    },
  ],
  files: [
    {
      name: "file.txt",
      content: new Uint8Array(fs.readFileSync("file.txt")),
      sectionId: "custom section",
      fieldId: "file_field",
    },
  ],
});

You can add files to a new item when you create the item by including them in the ItemCreateParams object.

# Create a File Field Item
to_create = ItemCreateParams(
    title="FileField Item created with Python SDK",
    category=ItemCategory.LOGIN,
    vault_id=vault_id,
    fields=[
        ItemField(
            id="username",
            title="username",
            field_type=ItemFieldType.TEXT,
            value="mynameisjeff",
        ),
        ItemField(
            id="password",
            title="password",
            field_type=ItemFieldType.CONCEALED,
            value="jeff",
        ),
    ],
    sections=[
        ItemSection(id="", title=""),
    ],
    files=[
        FileCreateParams(
            name="file.txt",
            content=Path("./example/file.txt").read_bytes(),
            sectionId="",
            fieldId="file_field",
        )
    ],
)

created_item = await client.items.create(to_create)

Go
JavaScript
Python

To save a file in an existing item, use the Items().Files().Attach() method.

file2Content, err := os.ReadFile("./example/service_account/file2.txt")
if err != nil {
	panic(err)
}

// Attach a file field to an item
newItem, err := client.Items().Files().Attach(context.Background(), item, onepassword.FileCreateParams{
	Name:      "file2.txt",
	Content:   file2Content,
	SectionID: sectionID,
	FieldID:   "new_file_field",
})
if err != nil {
	panic(err)
}

To save a file in an existing item, use the items.files.attach() method.

// Attach a file field to the item
let attachedItem = await client.items.files.attach(item, {
  name: "file2.txt",
  content: new Uint8Array(fs.readFileSync("file2.txt")),
  sectionId: "custom section",
  fieldId: "new_file_field",
});

To save a file in an existing item, use the items.files.attach() method.

# Attach a file field to the item
attached_item = await client.items.files.attach(
    created_item,
    FileCreateParams(
        name="file2.txt",
        content=Path("./example/file2.txt").read_bytes(),
        sectionId="",
        fieldId="new_file_field",
    ),
)

Remove a file

Go
JavaScript
Python

You can delete field files using the Items().Files().Delete() method with the item, section, and field IDs for the file you want to delete. This will remove the file and return the modified item.

// Delete a file field from an item
updatedItemWithDeletedFile, err := client.Items().Files().Delete(context.Background(), newItem, newItem.Files[0].SectionID, newItem.Files[0].FieldID)
if err != nil {
	panic(err)
}

You can delete field files using the items.files.delete() method with the item, section, and field IDs for the file you want to delete. This will remove the file and return the modified item.

// Delete a file field from an item
let deletedItem = await client.items.files.delete(
  attachedItem,
  attachedItem.files[1].sectionId,
  attachedItem.files[1].fieldId,
);

You can delete field files using the items.files.delete() method with the item, section, and field IDs for the file you want to delete. This will remove the file and return the modified item.

# Delete a file field from an item
deleted_file_item = await client.items.files.delete(
    attached_item,
    attached_item.files[1].section_id,
    attached_item.files[1].field_id,
)

Document operations

Save a document

Go
JavaScript
Python

To save a file in 1Password as a new Document item, read the file locally then pass the file contents to the Items().Create() method using the DocumentCreateParams struct. Make sure to specify Document as the item category.

fileContent, err := os.ReadFile("./example/service_account/file.txt")
if err != nil {
	panic(err)
}
// Create the document item
documentItem, err := client.Items().Create(context.Background(), onepassword.ItemCreateParams{
	Title:    "Document Item Created With Go SDK",
	Category: onepassword.ItemCategoryDocument,
	VaultID:  vaultID,
	Document: &onepassword.DocumentCreateParams{
		Name:    "file.txt",
		Content: fileContent,
	},
})
if err != nil {
	panic(err)
}

// Create a Document Item
let item = await client.items.create({
  title: "Document Item Created With JS SDK",
  category: sdk.ItemCategory.Document,
  vaultId: vaultId,
  document: {
    name: "file.txt",
    content: new Uint8Array(fs.readFileSync("file.txt")),
  },
});

To save a file in 1Password as a new Document item, read the file locally then pass the file contents to the items.create() method using the DocumentCreateParams object. Make sure to specify Document as the item category.The example below uses a Path object from Python’s built-in pathlib module to specify the file path to the document on your computer. Make sure to import Path from pathlib at the top of your file.

# Create a Document Item
to_create = ItemCreateParams(
    title="Document Item Created with Python SDK",
    category=ItemCategory.DOCUMENT,
    vault_id=vault_id,
    sections=[
        ItemSection(id="", title=""),
    ],
    document=DocumentCreateParams(
        name="file.txt", content=Path("./example/file.txt").read_bytes()
    ),
)
created_item = await client.items.create(to_create)

Replace a document

Go
JavaScript
Python

To replace the file in a Document item, read the new file locally then pass the file contents to the Items().Files().ReplaceDocument() method using the DocumentCreateParams struct.

// Replace the document item
file2Content, err := os.ReadFile("./example/service_account/file2.txt")
if err != nil {
	panic(err)
}
replacedDocItem, err := client.Items().Files().ReplaceDocument(context.Background(), documentItem, onepassword.DocumentCreateParams{
	Name:    "file2.txt",
	Content: file2Content,
})
if err != nil {
	panic(err)
}

To replace the file in a Document item, read the new file locally then pass the file contents to the items.files.replaceDocument() method using the DocumentCreateParams object.

// Replace the document in the Document Item
let replacedDocumentItem = await client.items.files.replaceDocument(item, {
  name: "file2.txt",
  content: new Uint8Array(fs.readFileSync("file2.txt")),
});

To replace the file in a Document item, read the new file locally then pass the file contents to the items.files.replace_document() method using the DocumentCreateParams object.The example below uses a Path object from Python’s built-in pathlib module to specify the file path to the replacement document on your computer. Make sure to import Path from pathlib at the top of your file.

# Replace the document in the item
replaced_item = await client.items.files.replace_document(
    created_item,
    DocumentCreateParams(
        name="file2.txt", content=Path("./example/file2.txt").read_bytes()
    ),
)

Limitations

1Password SDKs currently have a maximum message size of 50 MB, which impacts the following file operations:

The SDK can’t create files larger than 50 MB.
The SDK can’t retrieve file contents exceeding 50 MB.
The SDK can’t create items containing more than 50 MB of file content.

Get help

1Password includes 1 GB of storage for individual accounts. Shared plans include:

Plan	Storage
1Password Families	1 GB per person
1Password Teams	1 GB per person
1Password Business	5 GB per person

If you aren’t able to save documents in a 1Password Business account, ask your administrator to turn on file storage for team members.

SDKs

​Read a file

​Field file operations

​Save a file

​Remove a file

​Document operations

​Save a document

​Replace a document

​Limitations

​Get help

​Learn more

Read a file

Field file operations

Save a file

Remove a file

Document operations

Save a document

Replace a document

Limitations

Get help

Learn more