# 1Password SDK Documentation > 1Password SDK guides for Python, JavaScript, and Go. This file contains all documentation content in a single document following the llmstxt.org standard. ## Tutorial: Integrate 1Password SDKs with AI agents :::warning Security notice This article demonstrates how to use 1Password developer tools in conjunction with an agentic AI application. **It is not our recommended integration approach**. Exposing raw credentials directly to an AI model carries significant risks. Where possible, avoid passing secrets to the model. Instead, use short-lived, tightly scoped tokens, implement strong auditing practices, and minimize the model’s access to sensitive data. For more insight into our security recommendations and philosophy, please refer to our blog post: [Securing the Agentic Future](https://blog.1password.com/where-mcp-fits-and-where-it-doesnt/). ::: In this tutorial, you'll learn a workflow for providing credentials stored in 1Password to an AI agent using 1Password SDKs. We'll walk through the process using an example integration with [Anthropic Claude ](https://www.anthropic.com/claude) that automatically books a flight with your company credit card then submits an expense report in Ramp, all without hardcoding any secrets. By the end, you'll understand how to: - Follow the principle of least privilege to make sure your AI agent only has the minimum access needed to perform your task. - Create a 1Password Service Account with least privilege access to relevant items in your 1Password account. - Create secret reference URIs that point to where your credentials are stored in 1Password, so you can avoid hardcoding your secrets in plaintext. - Use the 1Password SDKs to fetch the secrets your AI agent needs at runtime. With this workflow, your AI agent can access only the secrets in 1Password it needs to authenticate into services. And you can see what items the agent accesses by creating a [service account usage report](https://support.1password.com/reports#create-a-usage-report-for-a-team-member-service-account-or-vault). ## Prerequisites 1. [1Password subscription](https://1password.com/pricing/password-manager). 2. [1Password desktop app](https://1password.com/downloads/). (Optional) 3. Basic knowledge of AI agents. 4. Basic knowledge of Python. 5. Familiarity with 1Password SDKs. To learn how to get started, see the [end-to-end setup tutorial](/docs/sdks/setup-tutorial). ## Part 1: Set up a 1Password Service Account scoped to a vault In the first part of this tutorial, you'll learn how to use 1Password to follow the security [principle of least privilege](https://blog.1password.com/guiding-principles-how-least-privilege-leads-to-more-security/), which requires that a process only be given the minimum level of access needed to complete its task. To do this, you'll create a vault in your 1Password account that only contains the secrets your AI agent needs. Then you'll create a service account that only has read access to the new vault, and can't access any other items in your account. When your agent authenticates to 1Password using the service account, it won't have any unnecessary access or permissions beyond the bare minimum. ### Step 1: Create a vault that only contains items required for the task First, create a vault that only contains the credentials you'll need to perform the task you want the AI agent to complete. For our example, we'll create a new vault `Tutorial` that contains our Navan and Ramp logins, and our travel credit card. 1. Open and unlock the [1Password app](https://1password.com/downloads/). 2. Select the plus button in the sidebar next to your account name. 3. Enter `Tutorial` for the vault name, then select **Create**. 4. [Move or copy](https://support.1password.com/move-copy-items/) the items you need for the task into the vault. ### Step 2: Create a service account scoped to the vault [Service accounts](/docs/service-accounts) are a token-based authentication method that you can scope to specific vaults and permissions. For this tutorial, we'll create a service account that only has read access in the `Tutorial` vault. :::tip If you don't see the option to create service accounts, ask your administrator to [give you access to create and manage service accounts](/docs/service-accounts/manage-service-accounts#manage-who-can-create-service-accounts). ::: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools/directory) in the sidebar. Or, if you already have active applications and services, select **Directory** at the top of the Developer page. 3. Under Access Tokens, select **Service Account**. 4. Give your service account a name. For example, `AI Agent Workflow Service Account`, then select **Next**. 6. On the next screen, you'll see a list of your 1Password vaults. Select the **Tutorial** vault you created in the previous step, then select the gear icon next to it. In the permissions dropdown, select **Read Items**. 7. Select **Create Account**. 8. On the next screen, select **Save in 1Password**, then save your newly-created service account token in the Tutorial vault. ## Part 2: Provide your credentials to the agent In the second part of this tutorial, you'll learn how to build an AI agent integration that fetches your credentials from 1Password at runtime. To do this, you'll use the `secrets.resolve()` method with secret reference URIs that point to where your credentials are stored in your 1Password account. When the agent runs, 1Password injects the actual secrets referenced by the URIs. This setup makes sure that your agent can only work with the credentials you explicitly provide as secret references in your non-dynamic controller code. This creates a clear boundary between your 1Password account and the AI agent, and prevents the agent from crafting its own requests to 1Password or accessing other credentials. :::tip Before you proceed Set up a project for your AI agent integration using 1Password SDKs. In the example below, we've created an integration using the Python SDK. Learn how to [get started with 1Password SDKs](/docs/sdks/setup-tutorial). ::: ### Step 1: Export your service account token Export the service account token you saved [in part one](#step-2-create-a-service-account-scoped-to-the-vault) to the `OP_SERVICE_ACCOUNT_TOKEN` environment variable. **Bash, Zsh, sh:** ```shell export OP_SERVICE_ACCOUNT_TOKEN= ``` **fish:** ```shell set -x OP_SERVICE_ACCOUNT_TOKEN ``` **PowerShell:** ```powershell $Env:OP_SERVICE_ACCOUNT_TOKEN = ``` ### Step 2: Define your credentials Define the credentials your AI agent will need using the `secrets.resolve()` method from the 1Password SDK. You can use placeholder secret references for now – we'll replace them with real secret references in the next step. In our example, we've defined: - Our Navan username and password. - Our travel credit card number, expiration date, and CVC. - Our Ramp username and password. ```python from browser_use import Agent from langchain_anthropic import ChatAnthropic from onepassword.client import Client async def main(): op_client = await Client.authenticate(os.getenv("OP_SERVICE_ACCOUNT_TOKEN"), "Claude Agent Demo", "v0.0.1") credentials = { "x_navan_username": await op_client.secrets.resolve("op://vault/item/field"), "x_navan_password": await op_client.secrets.resolve("op://vault/item/field"), "x_travel_credit_card_number": await op_client.secrets.resolve("op://vault/item/field"), "x_travel_credit_card_expiration": await op_client.secrets.resolve("op://vault/item/field"), "x_travel_credit_card_cvc": await op_client.secrets.resolve("op://vault/item/field"), "x_ramp_username": await op_client.secrets.resolve("op://vault/item/field"), "x_ramp_password": await op_client.secrets.resolve("op://vault/item/field") } ``` ### Step 3: Get secret references Get [secret reference URIs](/docs/cli/secret-reference-syntax) for your credentials, then paste them into your script in place of the placeholders from the previous step. 1. Open and unlock the [1Password desktop app](https://1password.com/downloads/). 2. Turn on the [integration with 1Password CLI](/docs/cli/app-integration). 3. Open the Tutorial vault and select an item that contains a credential you want to reference in your script. 4. Select the down arrow next to the field for the secret you want to reference, then select **Copy Secret Reference**. 5. Paste the secret reference into your code in place of `op://vault/item/field`. You can also create secret references using the [1Password for VS Code extension](/docs/vscode/). Here's our example updated with secret references: ```python from browser_use import Agent from langchain_anthropic import ChatAnthropic from onepassword.client import Client async def main(): op_client = await Client.authenticate(os.getenv("OP_SERVICE_ACCOUNT_TOKEN"), "1Password Integration", "v0.0.1") credentials = { "x_navan_username": await op_client.secrets.resolve("op://Tutorial/Navan/username"), "x_navan_password": await op_client.secrets.resolve("op://Tutorial/Navan/password"), "x_travel_credit_card_number": await op_client.secrets.resolve("op://Tutorial/Travel Card/credit_card_number"), "x_travel_credit_card_expiration": await op_client.secrets.resolve("op://Tutorial/Travel Card/credit_card_expiration"), "x_travel_credit_card_cvc": await op_client.secrets.resolve("op://Tutorial/Travel Card/credit_card_cvc"), "x_ramp_username": await op_client.secrets.resolve("op://Tutorial/Ramp/username"), "x_ramp_password": await op_client.secrets.resolve("op://Tutorial/Ramp/password") } ``` ### Step 4: Define your agent instructions Now, provide the AI agent instructions for how to use the credentials you fetched in the previous step. In our example, we instruct the agent to book a flight using our company credit card, then file an expense report for reimbursement. :::caution AI agents can make mistakes. Make sure to double check the results of your prompts. ::: ```python from browser_use import Agent from langchain_anthropic import ChatAnthropic from onepassword.client import Client async def main(): op_client = await Client.authenticate(os.getenv("OP_SERVICE_ACCOUNT_TOKEN"), "1Password Integration", "v0.0.1") credentials = { "x_navan_username": await op_client.secrets.resolve("op://Tutorial/Navan/username"), "x_navan_password": await op_client.secrets.resolve("op://Tutorial/Navan/password"), "x_travel_credit_card_number": await op_client.secrets.resolve("op://Tutorial/Travel Card/credit_card_number"), "x_travel_credit_card_expiration": await op_client.secrets.resolve("op://Tutorial/Travel Card/credit_card_expiration"), "x_travel_credit_card_cvc": await op_client.secrets.resolve("op://Tutorial/Travel Card/credit_card_cvc"), "x_ramp_username": await op_client.secrets.resolve("op://Tutorial/Ramp/username"), "x_ramp_password": await op_client.secrets.resolve("op://Tutorial/Ramp/password") } agent_instructions = f""" Book a round-trip flight for a business trip to San Francisco: - Arrival: Monday, April 28, 2025, before 1:00 PM - Return: Thursday, May 1, 2025, after 11:00 AM Use Navan to find and purchase the flight. Log in using x_navan_username and x_navan_password. Use the company credit card stored as x_travel_credit_card_number, x_travel_credit_card_expiration, and x_travel_credit_card_cvc. Then open Ramp and create a new expense report for the trip. Log in using x_ramp_username and x_ramp_password. Upload the flight receipt and submit the report for reimbursement. """ llm = ChatAnthropic( model_name="claude-3-5-sonnet-20240620", temperature=0.0, timeout=100 ) agent = Agent( task=agent_instructions, llm=llm, sensitive_data=credentials, ) result = await agent.run() print(result) asyncio.run(main()) ``` Run the script, and the agent will load your secrets from 1Password and perform the defined tasks. ## Conclusion In this tutorial, you learned how to provide an AI agent with access credentials to perform a specific task, without hardcoding any secrets or giving the agent unnecessary access permissions. You can modify the provided example to work with other AI agents or language models, and extend it to support a wide range of tasks. ## Learn more - [Tutorial: Get started with 1Password SDKs](/docs/sdks/setup-tutorial) - [Load secrets using 1Password SDKs](/docs/sdks/load-secrets) - [Manage items using 1Password SDKs](/docs/sdks/manage-items) --- ## 1Password SDK concepts ## Authentication 1Password SDKs support authentication with the [1Password desktop app](#1password-desktop-app) or with a [1Password Service Account](#1password-service-account). ### 1Password desktop app You can build local integrations between 1Password and local applications or scripts that allow end users to authorize access directly on their device with prompts from their [1Password desktop app](https://1password.com/downloads/). Local authorization prompts from the 1Password desktop app allow end users to approve requests from your integration the same way they unlock the app, like with biometrics, their 1Password account password, their identity provider, or other supported methods. Prompts from 1Password clearly detail which account the integration will access, the process requesting access, and the scope and duration of that access. If the user approves, they securely grant the integration temporary access to the entirety of the authorized 1Password account. Access expires after 10 minutes of inactivity or when the user locks their account in the app. This method allows end users to use your integration with minimal setup and no token management, and enables secure, human-in-the-loop approval for sensitive workflows. _[A screenshot of a Python script running with an authorization prompt from the 1Password desktop app.]_ ### 1Password Service Account Service accounts enable you to follow the [principle of least privilege ](https://csrc.nist.gov/glossary/term/least_privilege) in your project, and automate access without human approval. Service account tokens are scoped to specific vaults and [Environments](/docs/environments), and are restricted to specific permissions in each vault. Service accounts aren't tied to an individual account, and work well in shared environments. They can't access your built-in [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vaults, and they can only manage permissions for vaults created by the service account. ### Comparison Use the following table to decide which authentication method best suits your use case. | Use case | Recommended authentication method | Why this method | | --- | --- | -- | | Quick testing and exploration | Desktop app | Desktop app authentication allows you to get started testing the SDK with your existing account credentials, no token needed. | | Minimal setup required for end users | Desktop app | New users don't need to learn about service accounts, and can get started quickly with their existing account credentials. | | Local integrations | Desktop app | Uses local authorization prompts from the 1Password desktop app. | | Human-in-the-loop approval for sensitive workflows | Desktop app | Authorization prompts from the 1Password desktop app clearly detail which account the integration will access, the process requesting access, and the scope and duration of that access. | | Full account access required | Desktop app | Desktop app authentication grants access to all the vaults you have access to, including your built-in [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vaults. | | Least-privilege access | Service account | You can scope service account tokens to only the vaults, Environments, and permissions your integration needs. | | Automate vault management | Desktop app | With desktop app authentication, you can manage any vault you have the appropriate permissions in. Service accounts can only manage permissions for vaults created by the service account. | | User-specific auditing | Desktop app | With desktop app authentication, actions can be traced to individual users for compliance and security reviews. | | Automated access | Service account | Service accounts allow you to automate access with no user present. | | Shared building | Service account | Service account tokens aren't tied to an individual user. | ## Autofill behavior ### Which credentials 1Password suggests When you create a Login or Password item, use the following IDs and field types for the credentials you want 1Password to suggest and fill: | ID | fieldType | Description | | --- | --- | --- | | `username` | `Text` | The username associated with the login. | | `password` | `Concealed` | The password associated with the login. | See [an example of how to create a Login item](/docs/sdks/manage-items#create-an-item). ### Where a login is suggested and filled The `Item` struct for Login and Password items contains an optional list of websites, so you can manage where 1Password autofills your credentials. Autofill behavior options include: | Autofill behavior | Description | | --- | --- | | `AnywhereOnWebsite` | Default. 1Password autofills credentials on any page that’s part of the website, including subdomains. | | `ExactDomain` | 1Password autofills credentials only if the domain (hostname and port) is an exact match. | | `Never` | 1Password never autofills credentials on this website. | ## Environments [1Password Environments](/docs/environments) allow you to organize and manage your project secrets as environment variables, separately from the items in your 1Password vaults. You can then [read the variables from your Environments](/docs/sdks/environments) using 1Password SDKs. ## Item categories Items in 1Password have a category that determines some characteristics about the item, like the fields available by default and whether 1Password suggests the item when you sign in to a website. Learn more about [the different types of items you can save in 1Password](https://support.1password.com/item-categories/). See [supported item categories](/docs/sdks/manage-items#item-parameters). ## Item states `ItemOverview` exposes one of two states: `Active` or `Archived`. | Item state | Description | | --- | --- | | Active | An item located inside a vault. (Default) | | Archived | An item that has been moved to the Archive. 1Password doesn’t include archived items in search results or suggest them when you fill in apps and browsers. You can keep archived items as long as you’d like. | ## Field types 1Password SDKs currently support operations on the following field types. You can only retrieve and make changes to supported field types. | Field type | Description | | --- | --- | | `Address` | An address. Specify each part of the address [in the field's details](/docs/sdks/manage-items#address). Don't set or edit the address field's value directly. | | `Concealed` | A secret value that 1Password conceals by default, like a password, API key, or credit card PIN. | | `CreditCardNumber` | A credit card number. | | `CreditCardType` | Type of credit card. For example Visa, Mastercard, or American Express. | | `Date` | A date, formatted as `YYYY-MM-DD`. | | `Email` | An email address. | | `Menu` | A menu of predefined options included in certain item types, like Database, Server, Email Account, and Wireless Router items. | | `MonthYear` | A month-year combination, formatted as `MM/YYYY`. | | `Notes` | A note about an item. | | `Phone` | A phone number. | | `Text` | A text string. | | `Totp` | A one-time password field. Must be [either a valid TOTP URL or a one-time password seed](/docs/sdks/manage-items#totp). | | `Url` | A web address to copy or open in your default web browser, not used for autofill behavior. You can [add autofill websites](#where-a-login-is-suggested-and-filled) to set where 1Password suggests and fills a Login or Password item. | | `Reference` | The [valid ID](/docs/sdks/concepts#unique-identifiers) of another item in the same vault. | | `SSHKey` | Must be a valid SSH private key – [a decrypted, PEM-encoded string](/docs/sdks/manage-items#ssh-key). SSH key fields can only be added to items with the [SSH Key](https://support.1password.com/item-categories#ssh-key) category. You can add one SSH key field per item. 1Password will generate a public key, fingerprint, and key type which are stored in the SSH key field details. | If an item contains information saved in unsupported field types, you won't be able to update or delete the item. See [supported functionality](/docs/sdks/functionality/) for more information. ## Files ### Document file A document file is a file stored in 1Password as a [Document item](https://support.1password.com/item-categories#document). You can [read, save, and replace](/docs/sdks/files/) document files saved in 1Password using the SDKs. ### Field file A field file is a file attachment saved in a 1Password item. You can [read, save, and remove](/docs/sdks/files/) file attachments saved in 1Password using the SDKs. ## Query parameters ### `otp` You can use the `otp` (or `totp`) [attribute query parameter](/docs/cli/secret-reference-syntax#attribute-parameter) to retrieve one-time passwords with the [`Resolve` function](/docs/sdks/load-secrets/). Append the `?attribute=otp` query parameter to a secret reference that points to the field where your one-time password is stored. For example: ``` op://dev/gitlab/one-time password?attribute=otp ``` ### `ssh-format` You can use the `ssh-format` [attribute query parameter](/docs/cli/secret-reference-syntax#attribute-parameter) to fetch a private SSH key in OpenSSH format using the [`Resolve` function](/docs/sdks/load-secrets/). Append the `?ssh-format=openssh` query parameter to a secret reference that points to the field where your SSH private key is stored. For example: ``` op://vault//private key?ssh-format=openssh ``` ## Rate limits 1Password Service Accounts have hourly and daily rate limits. These also apply while using a service account with an SDK. Learn more about [service account rate limits](/docs/service-accounts/rate-limits). ## SDK client When you initialize an SDK, you create a 1Password SDK client instance and pass your configuration parameters to the SDK core. You can instantiate multiple SDK clients sequentially or in parallel using the same or different service account tokens. ## Secret references 1Password SDKs allow you to use [secret reference URIs](/docs/cli/secret-reference-syntax/) to avoid the risk of exposing plaintext secrets in your code. Secret references reflect changes you make in 1Password, so when you use the SDK to load a secret you get the latest value. Secret references use the following syntax: ``` op:////[section/]field[?attribute=] ``` [Learn more about secret references](/docs/cli/secret-reference-syntax/). ## State management The 1Password SDK client sets up an authenticated session with the 1Password servers and automatically refreshes it whenever it expires. As a result, you don't need to worry about managing your authentication and session keys. ## Unique identifiers A unique identifier (ID) is a string of 26 numbers and letters that can be used to identify a 1Password object, like a vault, item, section, or field. IDs only change if you move an item to a different vault. 1Password SDKs require you to use IDs rather than names to refer to 1Password objects while performing item management operations. You can get IDs by [listing vaults and items](/docs/sdks/list-vaults-items/). ## Vault permissions With [1Password Business](https://1password.com/business-security) and [1Password Teams](https://1password.com/product/teams-small-business-password-manager), you can manage the permissions groups have in vaults. In 1Password Business, all vault permissions have a hierarchical relationship in which narrower permissions require broader permissions to be granted alongside them. Learn more about [1Password Business vault permissions](/docs/sdks/vault-permissions#1password-business-vault-permissions). 1Password Teams includes three broad permission levels made up of collections of the granular vault permissions available in 1Password Business. You'll need to grant or revoke all the permissions for the desired permission level. Learn more about [1Password Teams vault permissions](/docs/sdks/vault-permissions#1password-teams-vault-permissions). --- ## 1Password SDK local integration security 1Password SDKs allow you to build integrations between 1Password and other local applications and scripts that authenticate using [authorization prompts from the 1Password desktop app](/docs/sdks/concepts#1password-desktop-app) on the user's device. Authorization prompts clearly detail the process that's requesting access, which account the process will access, and the scope and duration of that access. Users must approve the request using the same method they use to unlock their 1Password app, like with biometrics or their 1Password account password. The credential used to authenticate never leaves the 1Password app process. :::tip To learn about the security model for automated access, see our [1Password Service Account security model](/docs/service-accounts/security). For information about 1Password security practices, visit the [1Password Security homepage](https://1password.com/security). ::: ## Security model Local 1Password desktop app integrations rely on a human-in-the-loop authorization model. When the integration makes a request, the 1Password desktop app prompts the user to authorize the request the same way they unlock their 1Password account in the app, like with Touch ID, Windows Hello, system authentication, or their 1Password account password. After the user grants the integration access, the SDK can then send requests to 1Password, which provides responses until access expires. Local integrations can only access 1Password after a user provides explicit authorization. To enforce this, 1Password serves the user an authorization prompt that contains the name of the 1Password account where access is requested (for example, AgileBits or Wendy Appleseed's Family) and the process requesting access, as well as the scope and duration of access that the process will receive. The user must approve the prompt for the integration to be granted access to the account. After access is granted, authorization is time-bound to ten minutes of inactivity, limited to the approved account and process, and expires if the user locks their 1Password account in the app. ## Authorization model Authorization occurs on a per-account and per-process basis. If the user is signed in to multiple accounts, each account must be authorized separately. If the user runs multiple integrations, each process must be authorized separately. Authorization expires after ten minutes of inactivity, after which the user must re-authorize. Authorization also expires if the user locks their account in the 1Password desktop app. ## Technical design ### Communication After a user turns on the option to integrate with SDKs in the 1Password desktop app, the 1Password app spawns a platform-native Inter-Process Communication (IPC) channel – Mach ports on Mac, named pipes on Windows, and Unix domain sockets on Linux – to listen for incoming connections. These channels create a direct, local connection that cannot be hijacked or redirected once established. When a new process connects to the channel through the SDKs, the 1Password desktop app prompts the user for authorization using the same method they use to unlock the app. The user must explicitly approve the prompt with biometrics, their 1Password account password, or their identity provider before any sensitive data is exchanged. ### Process identification When a process using the SDK connects to the secure communication channel, the 1Password desktop app retrieves the Process ID (PID) of the caller. The PID is used to query the operating system for the executable's name and its absolute path on the file system. Because integrations are built by third parties, the 1Password app cannot verify a 1Password-issued code signature for these binaries. Instead, the app presents the discovered app name to the user in an authorization prompt. The user acts as the final validator, which makes sure that the application requesting access is the one they intended to run. ### Authorization and session persistence Authorization is granted on a per-process basis. A single approval grants the specific process access to the authorized 1Password account for a limited duration of up to ten minutes of inactivity. If the account in the 1Password app is locked, all existing SDK authorizations are immediately revoked. ## Accepted risks - A user or application with root or administrator-level privileges on the same system may be able to circumvent one or more security measures and could obtain access to 1Password accounts. - Users of integrations must trust that the integration is not malicious. If a user knowingly installs a malicious application and grants it access to their account, the SDK will fulfill its function and provide the requested data to the application. - The SDK relies on the integrity of the local 1Password desktop application. If an attacker replaces the legitimate 1Password app with a malicious impersonator, the SDK may inadvertently transmit newly created items or secrets directly to the attacker’s application. --- ## Read 1Password Environments using 1Password SDKs # Read 1Password Environments using 1Password SDKs (Beta) You can use [1Password SDKs](/docs/sdks) to programmatically read environment variables stored in [1Password Environments (beta)](/docs/environments) and use them in your applications. ## Requirements To use this feature, you'll need to install the beta version of the Go, JS, or Python SDK: **Go:** ```shell go get github.com/1password/onepassword-sdk-go@v0.4.1-beta.1 ``` **JavaScript:** ```shell npm install @1password/sdk@0.4.1-beta.1 ``` **Python:** ```python pip install onepassword-sdk==0.4.1b1 ``` ## Read environment variables **Go:** To read environment variables stored in an Environment, use the [`GetVariables()`](https://github.com/1Password/onepassword-sdk-go/blob/beta/environments.go#L14) method. Replace `` with the [Environment's ID](#get-an-environments-id). ```go res, err := client.Environments().GetVariables(context.Background(), "") if err != nil { panic(err) } for _, env := range res.Variables { fmt.Printf("Variable %s: %s (hidden: %t)\n", env.Name, env.Value, env.Masked) } ``` The method returns a [`GetVariablesResponse`](https://github.com/1Password/onepassword-sdk-go/blob/beta/types.go#L67) struct that contains a list of the environment variables stored in the Environment. ```go // Response containing the full set of environment variables from an Environment. type GetVariablesResponse struct { // List of environment variables. Variables []EnvironmentVariable `json:"variables"` } ``` Each [`EnvironmentVariable`](https://github.com/1Password/onepassword-sdk-go/blob/beta/types.go#L32) struct in the response contains the following: - **Name**: The environment variable's name (for example, `DB_HOST`). - **Value**: The environment variable's value. - **Masked**: A boolean that indicates whether the value is hidden by default in the 1Password app. ```go // Represents an environment variable (name:value pair) and its masked state type EnvironmentVariable struct { // An environment variable's name Name string `json:"name"` // An environment variable's value Value string `json:"value"` // An environment variable's masked state Masked bool `json:"masked"` } ``` **JavaScript:** To read environment variables stored in an Environment, use the [`getVariables()`](https://github.com/1Password/onepassword-sdk-js/blob/beta/client/src/environments.ts#L11) method. Replace `` with the [Environment's ID](#get-an-environments-id). ```js const res = await client.environments.getVariables(""); for (const env of res.variables) { console.log(`Variable ${env.name}: ${env.value} (hidden: ${env.masked})`); } ``` The method returns a [`GetVariablesResponse`](https://github.com/1Password/onepassword-sdk-js/blob/beta/client/src/types.ts#L68) object that contains a list of the environment variables stored in the Environment. ```js /** Response containing the full set of environment variables from an Environment. */ interface GetVariablesResponse { /** List of environment variables. */ variables: EnvironmentVariable[]; } ``` Each [`EnvironmentVariable`](https://github.com/1Password/onepassword-sdk-js/blob/beta/client/src/types.ts#L29) object in the response contains the following: - **Name**: The environment variable's name (for example, `DB_HOST`). - **Value**: The environment variable's value. - **Masked**: A boolean that indicates whether the value is hidden by default in the 1Password app. ```js /** Represents an environment variable (name:value pair) and its masked state */ export interface EnvironmentVariable { /** An environment variable's name */ name: string; /** An environment variable's value */ value: string; /** An environment variable's masked state */ masked: boolean; } ``` **Python:** To read environment variables stored in an Environment, use the [`get_variables()`](https://github.com/1Password/onepassword-sdk-python/blob/beta/src/onepassword/environments.py#L10) method. Replace `` with the [Environment's ID](#get-an-environments-id). ```python res = await client.environments.get_variables("") for env in res.variables: print(f"Environment {env.name}: {env.value} (hidden: {env.masked})") ``` The method returns a [`GetVariablesResponse`](https://github.com/1Password/onepassword-sdk-python/blob/beta/src/onepassword/types.py#L162) object that contains a list of the environment variables stored in the Environment. ```python class GetVariablesResponse(BaseModel): """ Response containing the full set of environment variables from an Environment. """ variables: List[EnvironmentVariable] """ List of environment variables. """ ``` Each [`EnvironmentVariable`](https://github.com/1Password/onepassword-sdk-python/blob/beta/src/onepassword/types.py#L91) object in the response contains the following: - **Name**: The environment variable's name (for example, `DB_HOST`). - **Value**: The environment variable's value. - **Masked**: A boolean that indicates whether the value is hidden by default in the 1Password app. ```python class EnvironmentVariable(BaseModel): """ Represents an environment variable (name:value pair) and its masked state """ name: str """ An environment variable's name """ value: str """ An environment variable's value """ masked: bool """ An environment variable's masked state """ ``` :::note 1Password Environment variables are masked by default. To change this: 1. Open and unlock the 1Password desktop app. 2. Select **Developer** > **View Environments**. 3. Choose the Environment, select **Edit**, then select the vertical ellipsis next to the variable and select **Show value by default**. ::: ## Appendix: Get an Environment's ID To read environment variables from a 1Password Environment, you'll need its unique identifier (ID). You can find this ID in the [1Password desktop app](https://1password.com/downloads/): 1. Open and unlock the 1Password desktop app. 2. Navigate to **Developer** > **View Environments**. 3. Select **View environment** next to the Environment you want to fetch. 4. Select **Manage environment** > **Copy environment ID**. --- ## Manage files using 1Password SDKs # Manage files in 1Password using 1Password SDKs 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](/docs/sdks#get-started) with a 1Password SDK. > **Tip** > } title="TIP"> See the examples folder in the 1Password [Go](https://github.com/1Password/onepassword-sdk-go/tree/main/example), [JavaScript](https://github.com/1Password/onepassword-sdk-js/tree/main/examples), or [Python](https://github.com/1Password/onepassword-sdk-python/tree/main/example) 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**](#field-file-operations): A file attachment stored as a custom field in any item. You can attach multiple field files to each item. - [**Document file**](#document-operations): A file stored as a [Document item](https://support.1password.com/item-categories#document). Document items can only store a single document file. ## Read a file **Go:** You can read any file saved in 1Password using the [`Items().Files().Read`](https://github.com/1Password/onepassword-sdk-go/blob/main/items_files.go#L51) method with the attributes of the file you want to retrieve, and the IDs for the [item and vault](/docs/sdks/list-vaults-items/) 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](/docs/sdks/manage-items#get-an-item). **File field:** **Document file:** **JavaScript:** You can read any file saved in 1Password using the [`items.files.read()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items_files.ts#L68) method with the attributes of the file you want to retrieve, and the IDs for the [item and vault](/docs/sdks/list-vaults-items/) 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](/docs/sdks/manage-items#get-an-item). **File field:** **Document file:** **Python:** You can read any file saved in 1Password using the [`items.files.read()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items_files.py#L37) method with the attributes of the file you want to retrieve, and the IDs for the [item and vault](/docs/sdks/list-vaults-items/) 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](/docs/sdks/manage-items#get-an-item). **File field:** **Document file:** ## 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:** **Go:** You can add files to a new item when you [create the item](/docs/sdks/manage-items#create-an-item) by including them in the [`ItemCreateParams`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L373) struct. **JavaScript:** You can add files to a new item when you [create the item](/docs/sdks/manage-items#create-an-item) by including them in the [`ItemCreateParams`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L304) object. **Python:** You can add files to a new item when you [create the item](/docs/sdks/manage-items#create-an-item) by including them in the [`ItemCreateParams`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L553) object. **Save a file in an existing item:** **Go:** To save a file in an existing item, use the [`Items().Files().Attach()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items_files.go#L34) method. **JavaScript:** To save a file in an existing item, use the [`items.files.attach()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items_files.ts#L46) method. **Python:** To save a file in an existing item, use the [`items.files.attach()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items_files.py#L13) method. ### Remove a file **Go:** You can delete field files using the [`Items().Files().Delete()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items_files.go#L69) 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. **JavaScript:** You can delete field files using the [`items.files.delete()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items_files.ts#L95) 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. **Python:** You can delete field files using the [`items.files.delete()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items_files.py#L60) 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. ## Document operations ### Save a document **Go:** To save a file in 1Password as a new Document item, read the file locally then pass the file contents to the [`Items().Create()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items.go#L63) method using the [`DocumentCreateParams`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L24) struct. Make sure to specify `Document` as the item category. **JavaScript:** To save a file in 1Password as a new Document item, read the file locally then pass the file contents to the [`items.create()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items.ts#L87) method using the [`DocumentCreateParams`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L21) object. Make sure to specify `Document` as the item category. **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()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items.py#L31) method using the [`DocumentCreateParams`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L76) 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. ### Replace a document **Go:** To replace the file in a Document item, read the new file locally then pass the file contents to the [`Items().Files().ReplaceDocument()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items_files.go#L87) method using the [`DocumentCreateParams`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L24) struct. **JavaScript:** To replace the file in a Document item, read the new file locally then pass the file contents to the [`items.files.replaceDocument()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items_files.ts#L122) method using the [`DocumentCreateParams`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L21) object. **Python:** To replace the file in a Document item, read the new file locally then pass the file contents to the [`items.files.replace_document()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items_files.py#L85) method using the [`DocumentCreateParams`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L76) 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. ## 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](https://support.1password.com/files/?mac#manage-who-can-save-files). ## Learn more - [Manage items using 1Password SDKs](/docs/sdks/manage-items) - [Share items using 1Password SDKs](/docs/sdks/share-items) - [List vaults and items using 1Password SDKs](/docs/sdks/list-vaults-items) - [End-to-end setup guide](/docs/sdks/setup-tutorial) --- ## Supported functionality 1Password SDKs are in active development. We're keen to hear what you'd like to see next. Let us know by upvoting or filing an issue in the [Go](https://github.com/1Password/onepassword-sdk-go/issues/new/choose) , [JavaScript](https://github.com/1Password/onepassword-sdk-js/issues/new/choose), or [Python](https://github.com/1Password/onepassword-sdk-python/issues/new/choose) SDK repo. ### Item management Operations: - [x] [Retrieve secrets](/docs/sdks/load-secrets) - [x] [Retrieve items](/docs/sdks/manage-items#get-an-item) - [x] [Create items](/docs/sdks/manage-items#create-an-item) - [x] [Update items](/docs/sdks/manage-items#update-an-item) - [x] [Delete items](/docs/sdks/manage-items#delete-an-item) - [x] [Archive items](/docs/sdks/manage-items#archive-an-item) - [x] [List items](/docs/sdks/list-vaults-items#list-items) - [x] [Add & update tags on items](/docs/sdks/manage-items#create-an-item) - [x] [Manage autofill websites and behavior](/docs/sdks/manage-items#create-an-item) - [x] [Generate passwords](/docs/sdks/manage-items#generate-a-password) - [x] [Share items](/docs/sdks/share-items/) - [x] [Manage items in bulk](/docs/sdks/manage-items#manage-items-in-bulk) Field types: - [x] API keys - [x] Passwords - [x] Concealed fields - [x] Text fields - [x] Notes - [x] SSH private keys, public keys, fingerprints, and key types - [x] One-time passwords - [x] URLs - [x] Phone numbers - [x] Credit card types - [x] Credit card numbers - [x] Emails - [x] References to other items - [x] Addresses - [x] Date - [x] MM/YY - [x] [Files attachments and Document items](/docs/sdks/files) - [x] Menus - [ ] Passkeys Learn about [supported field types](/docs/sdks/concepts#field-types). Query parameters: - [x] [`otp`](/docs/sdks/concepts#otp) - [x] [`ssh-format`](/docs/sdks/concepts#ssh-format) ### Vault management - [x] [Retrieve vaults](/docs/sdks/vaults#get-a-vault-overview) - [x] [Create vaults](/docs/sdks/vaults#create-a-vault) - [x] [Update vaults](/docs/sdks/vaults#update-a-vault) - [x] [Delete vaults](/docs/sdks/vaults#delete-a-vault) - [x] [List vaults](/docs/sdks/list-vaults-items#list-vaults) - [x] [Manage group vault permissions](/docs/sdks/vault-permissions) - [ ] Manage user vault permissions ### User & access management - [ ] Provision users - [ ] Retrieve users - [ ] List users - [ ] Suspend users - [x] [Retrieve groups](/docs/sdks/groups/) - [ ] List groups - [ ] Create groups - [ ] Update group membership ## Environments management - [x] [Read 1Password Environments](/docs/sdks/environments) (beta) ### Compliance & reporting - [ ] Watchtower insights - [ ] Travel mode - [ ] Events For now, use [1Password Events API](/docs/events-api/) directly. ### Authentication - [x] [1Password Service Accounts](/docs/service-accounts/get-started/) - [x] [User authentication](/docs/sdks/desktop-app-integrations/) - [ ] 1Password Connect For now, use the 1Password Connect SDK for [Go](https://github.com/1Password/connect-sdk-go), [JS](https://github.com/1Password/connect-sdk-js), or [Python](https://github.com/1Password/connect-sdk-python). --- ## Manage groups using 1Password SDKs If you have [1Password Business](https://1password.com/business-security) or [1Password Teams](https://1password.com/product/teams-small-business-password-manager), you can use 1Password SDKs to manage [groups](https://support.1password.com/groups/). > **Tip** > } title="TIP"> See the examples folder in the 1Password [Go](https://github.com/1Password/onepassword-sdk-go/tree/main/example), [JavaScript](https://github.com/1Password/onepassword-sdk-js/tree/main/examples), or [Python](https://github.com/1Password/onepassword-sdk-python/tree/main/example) SDK GitHub repository for full example code you can quickly clone and test in your project. ## Get a group **Go:** To fetch a group, use the [`Groups().Get()`](https://github.com/1Password/onepassword-sdk-go/blob/main/groups.go#L14) method. Replace `groupID` with the group's [unique identifier](/docs/sdks/concepts#unique-identifiers). **JavaScript:** To fetch a group, use the [`groups.get()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/groups.ts#L11) method. Replace `groupId` with the group's [unique identifier](/docs/sdks/concepts#unique-identifiers). **Python:** To fetch a group, use the [`groups.get()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/groups.py#L18) method. Replace `group_id` with the group's [unique identifier](/docs/sdks/concepts#unique-identifiers). --- ## List vaults and items using 1Password SDKs You can use 1Password SDKs to list vaults and items in a 1Password account. This is helpful if you need to get the [unique identifier (ID)](/docs/sdks/concepts#unique-identifiers) for an item or vault. Before you begin, [follow the steps to get started](/docs/sdks#get-started) with a 1Password SDK. > **Tip** > } title="TIP"> See the examples folder in the 1Password [Go](https://github.com/1Password/onepassword-sdk-go/tree/main/example), [JavaScript](https://github.com/1Password/onepassword-sdk-js/tree/main/examples), or [Python](https://github.com/1Password/onepassword-sdk-python/tree/main/example) SDK GitHub repository for example code you can quickly clone and test in your project. ## List vaults **Go:** The [`Vaults().List()`](https://github.com/1Password/onepassword-sdk-go/blob/main/vaults.go#L66) method gets all vaults in an account. **JavaScript:** The [`vaults.list()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/vaults.ts#L100) method gets all vaults in an account. **Python:** The [`vaults.list()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/vaults.py#L49) method gets all vaults in an account. ## List items **Go:** The [`Items().List()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items.go#L181) method gets all items in a vault and can return each item's ID, title, category, state, and the ID of the vault where it's stored. It only returns active items by default. The example below returns item IDs. To list items, specify a vault ID, or pass a vault ID from the results of an item or the results of [`Vaults().List()`](#list-vaults). **JavaScript:** The [`items.list()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items.ts#L70) method gets all items in a vault and can return each item's ID, title, category, state, and the ID of the vault where it's stored. It only returns active items by default. The example below returns item IDs. To list items, specify a vault ID, or pass a vault ID from the results of an item or the results of [`vaults.list()`](#list-vaults). **Python:** The [`items.list()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items.py#L188) method gets all items in a vault and can return each item's ID, title, category, state, and the ID of the vault where it's stored. It only returns active items by default. The example below returns item IDs. To list items, specify a vault ID, or pass a vault ID from the results of an item or the results of [`vaults.list()`](#list-vaults). ### Filter listed items by state You can filter listed items by their [state](/docs/sdks/concepts#item-states): `Active` or `Archived`. **Go:** To filter listed items so only archived items are returned, use the [`ItemListFilter`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L1082) struct: **JavaScript:** To filter listed items so only archived items are returned, use the [`ItemListFilter`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L630) type: **Python:** To filter listed items so only archived items are returned, use the [`ItemListFilter`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L1393) class: ## Learn more - [Secret reference syntax](/docs/cli/secret-reference-syntax/) - [Load secrets using 1Password SDKs](/docs/sdks/load-secrets/) - [Manage items using 1Password SDKs](/docs/sdks/manage-items/) - [Share items using 1Password SDKs](/docs/sdks/share-items/) --- ## Load secrets using 1Password SDKs You can use 1Password SDKs to securely load secrets into your code with [secret references](/docs/cli/secret-reference-syntax/). Before you begin, [follow the steps to get started](/docs/sdks#get-started) with a 1Password SDK. You can retrieve secrets from [supported field types](/docs/sdks/concepts#field-types). You can also retrieve one-time passwords using the [`otp` attribute parameter](/docs/sdks/concepts#query-parameters). A valid secret reference should use the syntax: ``` op:////[section/] ``` To get a one-time password, append the `?attribute=otp` query parameter to a secret reference that points to a one-time password field in 1Password: ``` op:////[section/]one-time password?attribute=otp ``` > **Tip** > } title="TIP"> See the examples folder in the 1Password [Go](https://github.com/1Password/onepassword-sdk-go/tree/main/example), [JavaScript](https://github.com/1Password/onepassword-sdk-js/tree/main/examples), or [Python](https://github.com/1Password/onepassword-sdk-python/tree/main/example) SDK GitHub repository for example code you can quickly clone and test in your project. ## Load a secret from 1Password Replace the placeholder [secret reference](/docs/sdks/concepts#secret-references) in the example with a secret reference URI that specifies the vault, item, section (if applicable), and field where the secret is saved in your 1Password account. If you have multiple vaults, items, or fields that share the same name, use a [unique identifier](/docs/sdks/concepts#unique-identifiers) instead of the name in the secret reference. **Go:** To retrieve a secret and print its value, use the [`Secrets().Resolve()`](https://github.com/1Password/onepassword-sdk-go/blob/main/secrets.go#L34) method. The SDK resolves the secret reference and returns the value of the 1Password field it references. You can then use this value in your code, like to authenticate to another service. **JavaScript:** To retrieve a secret and print its value, use the [`secrets.resolve()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/secrets.ts#L35) method. The SDK resolves the secret reference and returns the value of the 1Password field it references. You can then use this value in your code, like to authenticate to another service. **Python:** To retrieve a secret and print its value, use the [`secrets.resolve()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/secrets.py#L20) method. The SDK resolves the secret reference and returns the value of the 1Password field it references. You can then use this value in your code, like to authenticate to another service. ## Retrieve multiple secrets **Go:** Use the [`Secrets().ResolveAll()`](https://github.com/1Password/onepassword-sdk-go/blob/main/secrets.go#L50) method to retrieve secrets from 1Password in bulk, improving the performance of the operation. Replace the placeholder [secret references](/docs/sdks/concepts#secret-references) in the example with secret reference URIs that specify the vault, item, section (if applicable), and field where the secrets are saved in your 1Password account. **JavaScript:** Use the [`secrets.resolveAll()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/secrets.ts#L22) method to retrieve secrets from 1Password in bulk, improving the performance of the operation. Replace the placeholder [secret references](/docs/sdks/concepts#secret-references) in the example with secret reference URIs that specify the vault, item, section (if applicable), and field where the secrets are saved in your 1Password account. **Python:** Use the [`secrets.resolve_all()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/secrets.py#L39) method to retrieve secrets from 1Password in bulk, improving the performance of the operation. Replace the placeholder [secret references](/docs/sdks/concepts#secret-references) in the example with secret reference URIs that specify the vault, item, section (if applicable), and field where the secrets are saved in your 1Password account. ## Validate a secret reference **Go:** You can use the [`ValidateSecretReference()`](https://github.com/1Password/onepassword-sdk-go/blob/main/secrets.go#L66) method to make sure that your [secret reference](/docs/cli/secret-reference-syntax/) is formatted correctly. **JavaScript:** You can use the [`validateSecretReference()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/secrets.ts#L79) method to make sure that your [secret reference](/docs/cli/secret-reference-syntax/) is formatted correctly. **Python:** You can use the [`validate_secret_reference()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/secrets.py#L59) method to make sure that your [secret reference](/docs/cli/secret-reference-syntax/) is formatted correctly. If the secret reference is formatted incorrectly, the SDK will return an error that describes the syntax problem. Learn more about [secret references](/docs/cli/secret-reference-syntax). ## Learn more - [Secret reference syntax](/docs/cli/secret-reference-syntax/) - [Manage items using 1Password SDKs](/docs/sdks/manage-items/) - [List vaults and items using 1Password SDKs](/docs/sdks/list-vaults-items/) - [Share items using 1Password SDKs](/docs/sdks/share-items/) --- ## Manage items using 1Password SDKs You can use 1Password SDKs to read, write, and update secret values stored in your 1Password items. Before you begin, [follow the steps to get started](/docs/sdks#get-started) with a 1Password SDK. When managing items, you must use [unique identifiers (IDs)](/docs/sdks/concepts#unique-identifiers) in place of vault, item, section, and field names. You can get IDs by [listing vaults and items](/docs/sdks/list-vaults-items/). You can perform item management operations on [supported field types](/docs/sdks/concepts#field-types). Some field types have [special constraints](#appendix-field-type-constraints). > **Tip** > } title="TIP"> See the examples folder in the 1Password [Go](https://github.com/1Password/onepassword-sdk-go/tree/main/example), [JavaScript](https://github.com/1Password/onepassword-sdk-js/tree/main/examples), or [Python](https://github.com/1Password/onepassword-sdk-python/tree/main/example) SDK GitHub repository for example code you can quickly clone and test in your project. ## Create an item **Go:** To create a new item, specify the parameters for the item and pass the defined item to the [`Items().Create()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items.go#L63) method. The following example creates a Login item with a username, password, one-time password, and a website where 1Password will autofill the credentials. The value of the one-time password field can be either a one-time password secret or an [`otpauth://` URI](https://github.com/google/google-authenticator/wiki/Key-Uri-Format). In this example, the one-time password field is organized beneath a custom section. **JavaScript:** To create a new item, specify the parameters for the item and pass the defined item to the [`items.create()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items.ts#L87) method. The following example creates a Login item with a username, password, one-time password, and a website where 1Password will autofill the credentials. The value of the one-time password field can be either a one-time password secret or an [`otpauth://` URI](https://github.com/google/google-authenticator/wiki/Key-Uri-Format). In this example, the one-time password field is organized beneath a custom section. **Python:** To create a new item, specify the parameters for the item and pass the defined item to the [`items.create()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items.py#L31) method. The following example creates a Login item with a username, password, one-time password, and a website where 1Password will autofill the credentials. The value of the one-time password field can be either a one-time password secret or an [`otpauth://` URI](https://github.com/google/google-authenticator/wiki/Key-Uri-Format). In this example, the one-time password field is organized beneath a custom section. ### Item parameters Item parameters include: | Parameter | Definition | | --- | --- | | `Title` | The name of the item. | | `Category` | The [type of item](https://support.1password.com/item-categories/) you want to create. **Supported categories** `Login`, `SecureNote`, `CreditCard`, `CryptoWallet`, `Identity`, `Password`, `Document`, `ApiCredentials`, `BankAccount`, `Database`, `DriverLicense`, `Email`, `MedicalRecord`, `Membership`, `OutdoorLicense`, `Passport`, `Rewards`, `Router`, `Server`, `SshKey`, `SocialSecurityNumber`, `SoftwareLicense`, `Person` | | `Vault ID` | The ID of the vault where you want to create the item. | | `Fields` | The item fields. | | `Sections` | The item sections. | | `Notes` | The item notes. | | `Tags` | A list of tags to add to the item. | | `Websites` | An optional list of websites where 1Password will suggest and fill the login. Only available for Login and Password items. | A section organizes fields in an item under a section title. Section parameters include: | Parameter | Description | | --- | --- | | `Section ID` | A unique identifier for the section. | | `Section Title` | The name of the section. | Field parameters include: | Parameter | Description | | --- | --- | | `ID` | A unique identifier for the field. For fields that are specific to an item category, like `username` and `password` for a Login item, use the appropriate [built-in field](/docs/cli/item-fields#built-in-fields) ids. | | `Title` | The name of the field. | | `Field type` | The [type of field](/docs/sdks/concepts#field-types). Some field types have [special constraints](#appendix-field-type-constraints).**Supported fields** `Address`, `Concealed`, `CreditCardNumber`, `CreditCardType`, `Date`, `Email`, `Menu`, `MonthYear`, `Notes`, `Phone`, `Reference`, `Text`, `Totp`, `Url`, `SSHKey` | | `Value` | The value stored in the field. | | `Field Details` | Optional for most field types. Required for [Address fields](#address). | | `Section ID` | Organizes a field under a section. Required for all fields except built-in fields like `username` and `password`. If you create a custom field without a section, 1Password will create an empty section and assign the field to it. | Autofill website parameters include: | Parameter | Description | | --- | -- | | URL | The URL for the website. | | Label | The name of the website. | | Autofill behavior | When 1Password will autofill your credentials on the website. Options include:`AnywhereOnWebsite`: 1Password autofills credentials on any page that’s part of the website, including subdomains. `ExactMatch`: 1Password autofills credentials only if the domain (hostname and port) is an exact match.`Never`: 1Password never autofills credentials on this website. | :::tip To manage items that include files, [learn how to manage files using 1Password SDKs](/docs/sdks/files/). ::: ## Get an item **Go:** To get an item, pass the item ID and vault ID for the item to the [`Items().Get()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items.go#L96) method. To get the item [created in the first step](#create-an-item): **JavaScript:** To get an item, pass the item ID and vault ID for the item to the [`items.get()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items.ts#L37) method. To get the item [created in the first step](#create-an-item): **Python:** To get an item, pass the item ID and vault ID for the item to the [`items.get()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items.py#L74) method. To get the item [created in the first step](#create-an-item): ## Get a one-time password You can use 1Password SDKs to get the value stored in a field, like the six-digit one-time password code from a `Totp` field. **Go:** To retrieve and print a one-time password from the item [created in the first step](#create-an-item): **JavaScript:** To retrieve and print a one-time password from the item [created in the first step](#create-an-item): **Python:** To retrieve and print a one-time password from the item [created in the first step](#create-an-item): ## Update an item **Go:** To update an item, [fetch the item](#get-an-item) you want to update, specify the changes you want to make, then pass the updated item to the [`Items().Put()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items.go#L130) method. **JavaScript:** To update an item, [fetch the item](#get-an-item) you want to update, specify the changes you want to make, then pass the updated item to the [`items.put()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items.ts#L47) method. **Python:** To update an item, [fetch the item](#get-an-item) you want to update, specify the changes you want to make, then pass the updated item to the [`items.put()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items.py#L112) method. ## Archive an item **Go:** To archive an item, pass the item ID and vault ID for the item to the [`Items().Archive()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items.go#L172) method. **JavaScript:** To archive an item, pass the item ID and vault ID for the item to the [`items.archive()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items.ts#L65) method. **Python:** To archive an item, pass the item ID and vault ID for the item to the [`items.archive()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items.py#L170) method. ## Delete an item **Go:** To delete an item, pass the item ID and vault ID for the item to the [`Items().Delete()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items.go#L146) method. **JavaScript:** To delete an item, pass the item ID and vault ID for the item to the [`items.delete()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items.ts#L52) method. **Python:** To delete an item, pass the item ID and vault ID for the item to the [`items.delete()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items.py#L131) method. ## Generate a password **Go:** You can use the [`Secrets.GeneratePassword()`](https://github.com/1Password/onepassword-sdk-go/blob/main/secrets.go#L89) method to generate a password by passing a [`PIN`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L1155), [`Random`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L1161), or [`Memorable`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L1143) password recipe struct, depending on the type of password you want to generate. **PIN:** Generates a PIN code. You can specify the length of the generated code. **Random:** Generates a random password. You can choose: - Whether the password includes digits. - Whether the password includes symbols. - The length of the password. **Memorable:** Generates a memorable password. For example, `correct-horse-battery-staple`. You can choose: - The separator used between words. Options: `Spaces`, `Hyphens`, `Underscores`, `Periods`, `Commas` - Whether the memorable password is made up of full words or random syllables. Options: `FullWords`, `Syllables`, `ThreeLetters` - Whether to capitalize one section of the generated password. - The number of words included in the password. **JavaScript:** You can use the [`Secrets.generatePassword()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/secrets.ts#L97) method to generate a password by passing a [`PIN`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L653), [`Random`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L660), or [`Memorable`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L640) password recipe object, depending on the type of password you want to generate. **PIN:** Generates a PIN code. You can specify the length of the generated code. **Random:** Generates a random password. You can choose: - Whether the password includes digits. - Whether the password includes symbols. - The length of the password. **Memorable:** Generates a memorable password. For example, `correct-horse-battery-staple`. You can choose: - The separator used between words. Options: `Spaces`, `Hyphens`, `Underscores`, `Periods`, `Commas` - Whether the memorable password is made up of full words or random syllables. Options: `FullWords`, `Syllables`, `ThreeLetters` - Whether to capitalize one section of the generated password. - The number of words included in the password. **Python:** You can use the [`Secrets.generate_password()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/secrets.py#L77) method to generate a password by passing a [`PIN`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L1439), [`Random`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L1450), or [`Memorable`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L1414) password recipe object, depending on the type of password you want to generate. **PIN:** Generates a PIN code. You can specify the length of the generated code. **Random:** Generates a random password. You can choose: - Whether the password includes digits. - Whether the password includes symbols. - The length of the password. **Memorable:** Generates a memorable password. For example, `correct-horse-battery-staple`. You can choose: - The separator used between words. Options: `Spaces`, `Hyphens`, `Underscores`, `Periods`, `Commas` - Whether the memorable password is made up of full words or random syllables. Options: `FullWords`, `Syllables`, `ThreeLetters` - Whether to capitalize one section of the generated password. - The number of words included in the password. ## Manage items in bulk ### Create items **Go:** You can use the [`Items().CreateAll()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items.go#L79) method to batch create up to 100 items within a single vault. Learn more about [field type constraints](#appendix-field-type-constraints). The following example creates three example items in the vault specified with the `vaultId` variable. Make sure to set this variable to the [unique identifier](/docs/sdks/concepts#unique-identifiers) for the vault where you want to create the items. **JavaScript:** You can use the [`items.createAll()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items.ts#L108) method to batch create up to 100 items within a single vault. Learn more about [field type constraints](#appendix-field-type-constraints). The following example creates three example items in the vault specified with the `vault.id` variable. Make sure to set this variable to the [unique identifier](/docs/sdks/concepts#unique-identifiers) for the vault where you want to create the items. **Python:** You can use the [`items.create_all()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items.py#L52) method to batch create up to 100 items within a single vault. Learn more about [field type constraints](#appendix-field-type-constraints). The following example creates three example items in the vault specified with the `vault.id` variable. Make sure to set this variable to the [unique identifier](/docs/sdks/concepts#unique-identifiers) for the vault where you want to create the items. ### Get items **Go:** You can use the [`Items().GetAll()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items.go#L113) method to fetch up to 50 items from a specified vault using their [unique identifiers](/docs/sdks/concepts#unique-identifiers). To get the items you [created in the previous step](#create-items-): **JavaScript:** You can use the [`items.getAll()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items.ts#L155) method to fetch up to 50 items from a specified vault using their [unique identifiers](/docs/sdks/concepts#unique-identifiers). To get the items you [created in the previous step](#create-items-): **Python:** You can use the [`items.get_all()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items.py#L93) method to fetch up to 50 items from a specified vault using their [unique identifiers](/docs/sdks/concepts#unique-identifiers). To get the items you [created in the previous step](#create-items-): ### Delete items **Go:** You can use the [`Items().DeleteAll()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items.go#L155) method to batch delete a list of items from a specified vault using their [unique identifiers](/docs/sdks/concepts#unique-identifiers). Deleted items [remain available in Recently Deleted](https://support.1password.com/archive-delete-items/) for 30 days. To delete the items you [created in the previous step](#create-items-): **JavaScript:** You can use the [`items.deleteAll()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items.ts#L57) method to batch delete a list of items from a specified vault using their [unique identifiers](/docs/sdks/concepts#unique-identifiers). Deleted items [remain available in Recently Deleted](https://support.1password.com/archive-delete-items/) for 30 days. To delete the items you [created in the previous step](#create-items-): **Python:** You can use the [`items.delete_all()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items.py#L151) method to batch delete a list of items from a specified vault using their [unique identifiers](/docs/sdks/concepts#unique-identifiers). Deleted items [remain available in Recently Deleted](https://support.1password.com/archive-delete-items/) for 30 days. To delete the items you [created in the previous step](#create-items-): ## Appendix: Field type constraints Some [supported field types](/docs/sdks/concepts#field-types) have special requirements and constraints. ### Address For an `Address` type item field, the address field's value is built using the address field's details, because address string formats can differ according to the country. You must define which piece of the address each particular string corresponds to so that 1Password can properly create the address string. To change the value of an `Address` field, edit the item field details directly, not the field value. **Go:** **JavaScript:** **Python:** ### Date For a `Date` type item field, the date field's value must be a string formatted as `YYYY-MM-DD`. For example, `1998-03-15`. **Go:** **JavaScript:** **Python:** ### MonthYear For a `MonthYear` type item field, the value must be a string formatted as `MM/YYYY`. For example, `10/2000`. **Go:** **JavaScript:** **Python:** ### Reference For a `Reference` type item field, the reference field's value must be the [unique identifier (ID)](/docs/sdks/concepts#unique-identifiers) of another item that exists within the same vault. This ID should be a 26 character alphanumeric string. For example, `vhn2qfnmizg6rw4iqottczq3fy`. **Go:** **JavaScript:** **Python:** ### SSH Key For an `SSHKey` type item field, the SSH key field's value must be a valid SSH private key – a decrypted, PEM-encoded string. You can use private key strings generated from the source of your choice, or you can generate SSH keys in your SDK language using that language's native support. Currently, if you attempt to pass an encrypted private key, you'll see an error. SSH key fields can only be added to items with the [SSH Key](https://support.1password.com/item-categories#ssh-key) category. You can add one SSH key field per item. When you create an item with an SSH key field assigned to it, 1Password will generate a public key, fingerprint, and key type which are stored in the SSH key field details. **Go:** The following example shows how to generate a valid SSH private key in Go and adds it to a new SSH Key item in 1Password. **JavaScript:** The following example shows how to generate a valid SSH private key in JavaScript and adds it to a new SSH Key item in 1Password. **Python:** The following example shows how to generate a valid SSH private key in Python and adds it to a new SSH Key item in 1Password. ### TOTP For a `Totp` type item field, the TOTP field's value must either be a valid one-time password URL (for example, `otpauth://totp/rsnjfceadiejs?secret=e4dw4xrdq34wd3qw3&issuer=vfsrfesfes`), or a one-time password seed (for example, `e4dw4xrdq34wd3qw3`). **Go:** **JavaScript:** **Python:** ## Troubleshooting If you aren't able to create, edit, or delete items and see an error that you "don't have the right permissions to execute this argument," check your service account's permissions in the vault where the items are saved: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools) in the sidebar. 3. Choose the service account, then confirm that you see `Read & Write` next to the vault in the Vaults table. If your service account only has read access, you'll need to [create a new service account](/docs/service-accounts/get-started#create-a-service-account) with read and write permissions. _[1Password.com open to the details of a service account.]_ ## Learn more - [Secret reference syntax](/docs/cli/secret-reference-syntax/) - [Load secrets using 1Password SDKs](/docs/sdks/load-secrets/) - [Manage files using 1Password SDKs](/docs/sdks/files/) - [Share items using 1Password SDKs](/docs/sdks/share-items/) - [List vaults and items using 1Password SDKs](/docs/sdks/list-vaults-items/) --- ## 1Password SDKs 1Password SDKs allow you to build integrations that programmatically interact with 1Password using Go, JavaScript, or Python. With 1Password SDKs, you can: - **Secure your applications**: Load secrets into your code with [secret references](/docs/sdks/load-secrets) or read [environment variables](/docs/sdks/environments/) from 1Password Environments. - **Automate item management**: Programmatically [manage items](/docs/sdks/manage-items) in your 1Password account. - **Securely share items**: [Share items](/docs/sdks/share-items) with anyone, whether or not they have a 1Password account. - **Manage vaults and access**: [Manage your team's vaults](/docs/sdks/vaults) and the [permissions groups have](/docs/sdks/vault-permissions) in them. - **Support biometric authorization**: Build local integrations that users authorize with prompts from the [1Password desktop app](/docs/sdks/concepts#1password-desktop-app) for human-in-the-loop approval and minimal setup for end users. - **Support automated access**: Build integrations that authenticate with [service account tokens](/docs/sdks/concepts#1password-service-account) for least-privilege access and automated environments. See a full list of [supported functionality](/docs/sdks/functionality). ## Supported languages ## Example integrations See examples of how our partners have used SDKs to build integrations with 1Password: - ****: Securely load API keys and other secrets stored in 1Password into Postman without exposing any secrets in plaintext. Learn more - ****: Dynamically import secrets from 1Password into your environment. The provider will return a map of names to Secrets. Learn more ## About the current version 1Password SDKs are currently in version 0, which means they can meet the stability and scalability requirements of production use cases. During version 0, expect more frequent releases as we add additional features and languages. - There is a possibility of breaking changes when you upgrade from one version 0 release to another, for example 0.1.X to 0.2.0. Minor releases (0.1.X to 0.1.Y) will not include breaking changes. - Integration authors may need to update their code when updating the SDK version. Existing code and integrations won’t be affected, as these will have the SDK pinned at a specific version via package.json (JS), requirements.txt (Python), or go.mod (Go). - We will provide three months of support and security patches for version 0, so you can upgrade when it makes sense for your workflows and teams. You can find information about the latest releases in the [1Password SDK release notes](https://releases.1password.com/developers/sdks/). ## Get started Before you get started, you'll need to [sign up for a 1Password account](https://1password.com/pricing/password-manager). ### Step 1: Decide how you want to authenticate You can choose between two [authentication methods](/docs/sdks/concepts#authentication) for 1Password SDKs: local authorization prompts from the [1Password desktop app](/docs/sdks/concepts#1password-desktop-app) or automated authentication with a [1Password Service Account](/docs/sdks/concepts#1password-service-account). - **1Password desktop app**: Best for integrations that run locally on a user's machine. Use desktop app authentication if you want minimal setup for end users, human-in-the-loop approval for sensitive workflows, user-specific auditing, if you need access to your full account, or if you need to perform vault management operations. - **Service account**: Best for automated access. Use a service account if you want a token-based authentication method that isn't associated with an individual account to automate access, limit your integration to least privilege access, or for shared building. Service accounts can't access your built-in [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vault. **1Password desktop app:** 1. Install 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux). 2. Sign in to the account you want to use with your integration. 3. Select your account or collection at the top of the sidebar, then navigate to **Settings** > **[Developer](onepassword://settings/developers)**. 4. Under Integrate with the 1Password SDKs, select **Integrate with other apps**. 5. If you want to authenticate with biometrics, navigate to **Settings** > **[Security](onepassword://settings/security)**, then turn on the option to unlock using [Touch ID](https://support.1password.com/touch-id-mac/), [Windows Hello](https://support.1password.com/windows-hello/), or [system authentication](https://support.1password.com/system-authentication-linux/). _[The Integrate with other apps setting]_ **Service account:** Create a service account Create a [1Password Service Account](https://start.1password.com/developer-tools/infrastructure-secrets/serviceaccount/?source=dev-portal) and give it access to the vaults and [Environments](/docs/environments) you want your integration to be able to access. To allow your integration to update items, make sure to give the service account **both read and write permissions** in the appropriate vaults. To allow your integration to share items, also add the **share permission**. Provision your service account token We recommend provisioning your token from the environment. Use the following example to provision your token to an environment variable named `OP_SERVICE_ACCOUNT_TOKEN`. You can also provision your token in other ways, like by reading it from a file. **bash, sh, zsh:** ```shell export OP_SERVICE_ACCOUNT_TOKEN= ``` **fish:** ```shell set -x OP_SERVICE_ACCOUNT_TOKEN ``` **Powershell:** ```shell $Env:OP_SERVICE_ACCOUNT_TOKEN = "" ``` ### Step 2: Install the SDK Install the SDK in your project. **Go:** ```go go get github.com/1password/onepassword-sdk-go ``` **JavaScript:** ```shell npm install @1password/sdk ``` **Python:** ```python pip install onepassword-sdk ``` ### Step 3: Import the SDK Import the SDK into your project. **Go:** **JavaScript:** CommonJS ES Modules **Python:** ### Step 4: Initialize the SDK When you initialize the SDK, you create a client instance that contains your configuration parameters. For desktop app integrations, you'll need to provide your 1Password account name. For service account authentication, you'll need to provide your service account token. **1Password desktop app:** Replace your-account-name in the code below with your 1Password account name as it appears at the top of the left sidebar in the 1Password app. You can use the account ID that [1Password CLI](/docs/cli/get-started) returns with [`op account list --format json`](/docs/cli/reference/management-commands/account#account-list). Use the value in the `account_uuid` field. Make sure to specify a name and version for your application in place of `My 1Password Integration` and `v1.0.0`. _[The Integrate with other apps setting]_ **Go:** :::note This example prints an error message and exits if initialization fails. Because it writes the error to standard error, it uses Go’s `os` package, which you’ll need to import in your project. See the [complete example in Step 5](#step-5-start-building) for more context. ::: ```go [{ "color": "sunbeam", "lineNo": 4, "substr": "your-account-name" }] // Connects to the 1Password desktop app. client, err := onepassword.NewClient(context.Background(), // TODO: Set to your 1Password account name. onepassword.WithDesktopAppIntegration("your-account-name"), // TODO: Set to your own integration name and version. onepassword.WithIntegrationInfo("My 1Password Integration", "v1.0.0"), ) if err != nil { fmt.Fprintln(os.Stderr, "Initialization error:", err) os.Exit(1) } ``` **JavaScript:** :::note The 1Password JavaScript SDK is asynchronous and returns Promises. To make sure your code waits for 1Password to respond before moving to the next line, we recommend using the `await` keyword inside an `async` function. See the [complete example in Step 5](#step-5-start-building) for the full structure. ::: ```js [{ "color": "sunbeam", "lineNo": 4, "substr": "your-account-name" }] // Connects to the 1Password desktop app. const client = await sdk.createClient({ // TODO: Set to your 1Password account name. auth: new sdk.DesktopAuth("your-account-name"), // TODO: Set to your own integration name and version. integrationName: "My 1Password Integration", integrationVersion: "v1.0.0", }); ``` **Python:** :::note The Python SDK is asynchronous. To wait for a response from 1Password, use the `await` keyword inside an `async` function in your code. See the [complete example in Step 5](#step-5-start-building) for the full structure. ::: ```python [{ "color": "sunbeam", "lineNo": 5, "substr": "your-account-name" }] # Connects to the 1Password desktop app. client = await Client.authenticate( auth=DesktopAuth( # TODO: Set to your 1Password account name. account_name="your-account-name" ), # TODO: Set to your own integration name and version. integration_name="My 1Password Integration", integration_version="v1.0.0", ) ``` **Service account:** In the following example, the SDK gets the service account token string from the `OP_SERVICE_ACCOUNT_TOKEN` environment variable. Make sure to specify a name and version for your application in place of `My 1Password Integration` and `v1.0.0`. **Go:** **JavaScript:** **Python:** ### Step 5: Start building You can test your setup by building a simple integration that lists all the titles of all the vaults you or the service account has access to. **1Password desktop app:** **Go:** ```go title="main.go" package main "context" "fmt" "os" "github.com/1password/onepassword-sdk-go" ) func main() { // Connects to the 1Password desktop app. client, err := onepassword.NewClient(context.Background(), // TODO: Set to your 1Password account name. onepassword.WithDesktopAppIntegration("your-account-name"), // TODO: Set to your own integration name and version. onepassword.WithIntegrationInfo("My 1Password Integration", "v1.0.0"), ) if err != nil { fmt.Fprintln(os.Stderr, "Initialization error:", err) os.Exit(1) } // Lists vault titles vaults, err := client.Vaults().List(context.Background()) if err != nil { panic(err) } for _, vault := range vaults { fmt.Println(vault.Title) } } ``` ```shell go run main.go #code-result Development Production Private ``` **JavaScript:** ```js title="example.js" async function main() { // Connects to the 1Password desktop app. const client = await sdk.createClient({ // TODO: Set to your 1Password account name. auth: new sdk.DesktopAuth("your-account-name"), // TODO: Set to your own integration name and version. integrationName: "My 1Password Integration", integrationVersion: "v1.0.0", }); // Lists vault titles const vaults = await client.vaults.list({ decryptDetails: true }); for (const vault of vaults) { console.log(vault.title); } } main(); ``` ```shell node index.js #code-result Development Production Private ``` **Python:** ```python title="example.py" from onepassword import Client, DesktopAuth async def main(): # Connects to the 1Password desktop app. client = await Client.authenticate( auth=DesktopAuth( # TODO: Set to your 1Password account name. account_name="your-account-name" ), # TODO: Set to your own integration name and version. integration_name="My 1Password Integration", integration_version="v1.0.0", ) # Lists vault titles vaults = await client.vaults.list() for vault in vaults: print(vault.title) if __name__ == "__main__": asyncio.run(main()) ``` ``` python3 example.py #code-result Development Production Private ``` **Service account:** In the following example, the service account is scoped to a vault titled `Development`. **Go:** ```go title="main.go" package main "context" "fmt" "os" "github.com/1password/onepassword-sdk-go" ) func main() { // Gets your service account token from the environment. token := os.Getenv("OP_SERVICE_ACCOUNT_TOKEN") client, err := onepassword.NewClient(context.Background(), onepassword.WithServiceAccountToken(token), // TODO: Set to your own integration name and version. onepassword.WithIntegrationInfo("My 1Password Integration", "v1.0.0"), ) if err != nil { fmt.Fprintln(os.Stderr, "Initialization error:", err) os.Exit(1) } // Lists vault titles vaults, err := client.Vaults().List(context.Background()) if err != nil { panic(err) } for _, vault := range vaults { fmt.Println(vault.Title) } } ``` ```shell go run main.go #code-result Development ``` **JavaScript:** ```js title="index.js" async function main() { const client = await sdk.createClient({ // Gets your service account token from the environment. auth: process.env.OP_SERVICE_ACCOUNT_TOKEN, // TODO: Set to your own integration name and version. integrationName: "My 1Password Integration", integrationVersion: "v1.0.0", }); // Lists vault titles const vaults = await client.vaults.list({ decryptDetails: true }); for (const vault of vaults) { console.log(vault.title); } } main(); ``` ```shell node index.js #code-result Development ``` **Python:** ```python title="example.py" from onepassword import Client async def main(): # Gets your service account token from the environment. token = os.getenv("OP_SERVICE_ACCOUNT_TOKEN") client = await Client.authenticate( auth=token, # TODO: Set to your own integration name and version. integration_name="My 1Password Integration", integration_version="v1.0.0", ) # Lists vault titles vaults = await client.vaults.list() for vault in vaults: print(vault.title) if __name__ == "__main__": asyncio.run(main()) ``` ```shell python3 example.py #code-result Development ``` Visit the [Go](https://github.com/1Password/onepassword-sdk-go/tree/main/example), [JavaScript](https://github.com/1Password/onepassword-sdk-js/tree/main/examples), or [Python](https://github.com/1Password/onepassword-sdk-python/blob/main/example/example.py) SDK GitHub repositories for more examples. ## Get help To get help with 1Password SDKs, join our [Developer Slack workspace](https://developer.1password.com/joinslack) and ask a question in the `#sdk` channel. To request a new feature or report a bug, file an issue in the appropriate GitHub repo: - [Go](https://github.com/1Password/onepassword-sdk-go/issues/new/choose) - [JavaScript](https://github.com/1Password/onepassword-sdk-js/issues/new/choose) - [Python](https://github.com/1Password/onepassword-sdk-python/issues/new/choose) --- ## Tutorial: Get started with 1Password SDKs and 1Password Service Accounts In this tutorial, you'll build a simple JavaScript application that securely fetches a secret from your 1Password account. In the process, you'll learn how to: - Create a new test vault in your 1Password account. - Create a service account that can only access the test vault. - Save a secret in the test vault. - Set up your project, and install and configure the 1Password JS SDK. - Get a secret reference URI that points to the test secret you created. - Build a simple application that takes the secret reference as input and outputs the actual secret. :::tip This tutorial covers end-to-end setup for the [1Password JavaScript SDK](https://github.com/1Password/onepassword-sdk-js?tab=readme-ov-file#-get-started). Learn more about the [1Password Go SDK](https://github.com/1Password/onepassword-sdk-go?tab=readme-ov-file#-get-started) and the [1Password Python SDK](https://github.com/1Password/onepassword-sdk-python?tab=readme-ov-file#requirements). ::: ## Prerequisites 1. [1Password subscription](https://1password.com/pricing/password-manager). 2. (Optional) [1Password desktop app](https://1password.com/downloads/). 3. Basic knowledge of JavaScript. ## Part 1: Set up a 1Password Service Account In the first part of the tutorial, you'll create a vault and item in your 1Password account to use for testing, and set up a service account to authenticate the SDK. ### Step 1: Create a new vault First, create a new vault named Tutorial. You'll scope your service account to this vault, so it can only access the test item you create for this tutorial. 1. Open and unlock the [1Password desktop app](https://1password.com/downloads/). 2. Select the plus icon in the sidebar next to your account name. 3. Enter `Tutorial` for the vault name, then select **Create**. _[]_ ### Step 2: Create a service account Next, create a [1Password Service Account](/docs/service-accounts/get-started/). This is a token-based authentication method that you can scope to specific vaults and permissions, so your process only has the minimum required access to your account. 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools/directory) in the sidebar. Or, if you already have active applications and services, select **Directory** at the top of the Developer page. 3. Under Access Tokens, select **Service Account**. If you don't see the option to create service accounts, ask your administrator to [give you access to create and manage service accounts](/docs/service-accounts/manage-service-accounts#manage-who-can-create-service-accounts). 4. Give your service account a name. For this tutorial, use `Temp Service Account`. _[]_ 5. Select **Next**. 6. On the next screen, you'll see a list of your 1Password vaults. Select the **Tutorial** vault you created in the previous step, then select the gear icon next to it. In the permissions dropdown, check **Read Items** and **Write Items**. _[]_ 7. Select **Create Account**. 8. On the next screen, select **Save in 1Password**, then save your newly-created service account token in the Tutorial vault. _[]_ ### Step 3: Create a secret to retrieve with the SDK Next, create an example API credential item in the Tutorial vault. In the second half of the tutorial, you'll build a simple application to fetch the credential secret from this item. 1. Open and unlock the [1Password desktop app](https://1password.com/downloads/). 2. Select **+ New Item** to create a new item. 3. Select **API credential** for the item category. 4. For the purpose of this tutorial, enter `tutorial` for the username and `example credential` for the credential. 5. Select the Tutorial vault you created in step 1 from the dropdown next to the Save icon. 6. Select **Save** to create the item. You should now see the API credential item in your Tutorial vault. _[]_ ## Part 2: Install and configure a 1Password SDK In this part of the tutorial, you'll create a new folder for your project, set up a NodeJS runtime environment in it, then install and configure the 1Password JavaScript SDK. ### Step 1: Set up a NodeJS runtime environment Create a new folder for your project, then make sure you have NodeJS installed. 1. Open your terminal and create a new folder named Tutorial: ```shell mkdir Tutorial ``` 2. Change directories to the Tutorial folder, then check to make sure you have NodeJS version 18 or later installed: ```shell cd Tutorial && node -v #code-result v20.16.8 ``` If you don't see an existing NodeJS version, or if you have an earlier version installed, [learn how to install the latest version of NodeJS](https://nodejs.org/). Then, initialize a NodeJS project in your Tutorial folder: ```shell npm init -y #code-result Wrote to /Users/wendy.appleseed/Tutorial/package.json: { "name": "Tutorial", "version": "1.0.0", "description": "", "main": "index.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "keywords": [], "author": "", "license": "ISC" } ``` ### Step 2: Add support for Modules After you've initialized a NodeJS project for the tutorial, you'll need to edit the newly created `package.json` file to add support for Modules. Open the `package.json` file in the Tutorial folder and add `"type": "module",` on a new line after `“main”:”index.js”` on line #5. ```js {6} { "name": "Tutorial", "version": "1.0.0", "description": "", "main": "index.js", "type": "module", "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "keywords": [], "author": "", "license": "ISC" } ``` Save the file and exit. ### Step 3: Install the 1Password SDK Finally, return to your terminal and install the 1Password JS SDK in the Tutorial folder: ```shell npm install @1password/sdk ``` ## Part 3: Build a JS application to fetch a secret from 1Password In this part of the tutorial, you'll build a simple JavaScript application to securely fetch your API credential secret from 1Password. Your application will authenticate to 1Password using the service account token you created in the previous section. ### Step 1: Import the SDK 1. Create a new file `index.js` in the Tutorial folder: ```shell touch index.js ``` 2. Copy and paste the following code into it: ``` // Creates an authenticated client. const client = await sdk.createClient({ auth: process.env.OP_SERVICE_ACCOUNT_TOKEN, // Set the following to your own integration name and version. integrationName: "My 1Password Integration", integrationVersion: "v1.0.0", }); // Fetches a secret. const secret = await client.secrets.resolve("op://vault/item/field"); ``` 3. Save the file and return to the terminal. 4. Run the code: ```shell node index.js ``` You'll see an error because you haven't yet imported your service account token into the environment. This is necessary for 1Password SDKs to be able to access your vaults. ``` node:internal/process/esm_loader:40 internalBinding('errors').triggerUncaughtException( ^ missing field `serviceAccountToken` at line 1 column 252 (Use `node --trace-uncaught ...` to show where the exception was thrown) ``` ### Step 2: Import your service account token To import your service account token: 3. Copy and paste the following into your terminal to export the token to the environment. Don't run the code yet. **Bash, Zsh, sh:** ```shell export OP_SERVICE_ACCOUNT_TOKEN= ``` **fish:** ```shell set -x OP_SERVICE_ACCOUNT_TOKEN ``` **PowerShell:** ```powershell $Env:OP_SERVICE_ACCOUNT_TOKEN = ``` 2. Open and unlock the [1Password desktop app](https://1password.com/downloads/). 3. Navigate to the Tutorial vault and open the item for your service account token. 4. Select the service account token credential to copy it. 5. Paste the token into your terminal to complete the export command, then press Enter. **Bash, Zsh, sh:** ```shell export OP_SERVICE_ACCOUNT_TOKEN= ``` **fish:** ```shell set -x OP_SERVICE_ACCOUNT_TOKEN ``` **PowerShell:** ```powershell $Env:OP_SERVICE_ACCOUNT_TOKEN = "" ``` 6. Run the following command to confirm you successfully set the environment variable: **Bash, Zsh, sh:** ```shell echo $OP_SERVICE_ACCOUNT_TOKEN ``` **fish:** ```shell echo $OP_SERVICE_ACCOUNT_TOKEN ``` **PowerShell:** ```powershell $Env:OP_SERVICE_ACCOUNT_TOKEN ``` Now try running the code again: ```shell node index.js ``` You'll get a new error, in this case because you didn't provide a reference path to a secret. Think of this like a URL for a secret within your vault. ``` error resolving secret reference: no vault matched the secret reference query ``` ### Step 3: Get a secret reference and resolve the secret To fix the above error, get the [secret reference URI](/docs/cli/secret-reference-syntax/) for your API credential and paste it into the code in place of the placeholder secret reference. 1. Open and unlock the [1Password desktop app](https://1password.com/downloads/). 2. Open the Tutorial vault and select the API credential item you created earlier. 3. Select the down arrow next to the “credential" field, then select **Copy Secret Reference**. 4. In your `index.js` file, replace `op://vault/item/field` with the copied secret reference. _[]_ :::tip You can also get secret references with [1Password CLI](/docs/cli/secret-reference-syntax#with-1password-cli) and [1Password for VS Code](/docs/cli/secret-reference-syntax#with-1password-for-vs-code). ::: You should now see a secret reference that points to where the API credential is saved in your account: ```js {12} // Creates an authenticated client. const client = await sdk.createClient({ auth: process.env.OP_SERVICE_ACCOUNT_TOKEN, // Set the following to your own integration name and version. integrationName: "My 1Password Integration", integrationVersion: "v1.0.0", }); // Fetches a secret. const secret = await client.secrets.resolve("op://Tutorial/API Credential/credential"); ``` Save the file and run the code again: ```shell node index.js ``` This time you won't see any errors, but you also won't see any output. You can fix this by adding some simple console logging. :::caution Logging an example secret is useful for testing, but please don't do this with production code. ::: 1. Reopen the `index.js` file and append the following line to output the secret to the console. ```shell console.log("The secret is: " + secret); ``` 2. Save and close the file, then run the code for a final time: ```shell node index.js ``` You should now see your API credential returned: ``` The secret is: example credential ``` ## Conclusion In this tutorial, you learned how to create a 1Password vault, item, and service account, and how to access your newly-created vault and item using the 1Password JavaScript SDK. Now that you have the basics down, you can extend this application to include other functions, like [updating the secret](/docs/sdks/manage-items#update-an-item). ## Learn more - [Get started with service accounts](/docs/service-accounts/get-started/) - [Get started with the 1Password JS SDK](https://github.com/1Password/onepassword-sdk-js?tab=readme-ov-file#-get-started) - [Get started with the 1Password Go SDK](https://github.com/1Password/onepassword-sdk-go?tab=readme-ov-file#-get-started) - [Get started with the 1Password Python SDK](https://github.com/1Password/onepassword-sdk-python?tab=readme-ov-file#requirements) --- ## Share items using 1Password SDKs You can use 1Password SDKs to securely share a copy of a 1Password item with anyone, even if they don't have a 1Password account. When you share an item, you'll get a unique link that you can send to others. You can choose when the link expires and who it's available to: anyone with the link, or only people with specific email addresses or email domains. You can also choose whether you want the link to be viewable only once, or multiple times. :::tip Make sure to add the `Share items` permission when creating your [service account token](/docs/service-accounts/) to share items using the SDKs. ::: ### Step 1: Retrieve the 1Password item you want to share **Go:** To retrieve the item you want to share, use the [`Items().Get()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items.go#L96) method with the [unique identifiers (IDs)](/docs/sdks/concepts#unique-identifiers) for the item and the vault where the item is stored. **JavaScript:** To retrieve the item you want to share, use the [`items.get()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items.ts#L37) method with the [unique identifiers (IDs)](/docs/sdks/concepts#unique-identifiers) for the item and the vault where the item is stored. **Python:** To retrieve the item you want to share, use the [`items.get()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items.py#L74) method with the [unique identifiers (IDs)](/docs/sdks/concepts#unique-identifiers) for the item and the vault where the item is stored. ### Step 2: Fetch the item sharing account policy The item sharing account policy contains the allowed share settings that your account admin or owner has set. For individual and family accounts, these settings default to: - Unlimited views - All recipient types allowed - All share types allowed - Maximum share duration of 30 days - Default share duration of 7 days **Go:** To fetch the item sharing account policy, use the [`Items().Shares().GetAccountPolicy()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items_shares.go#L31) method with the [unique identifiers (IDs)](/docs/sdks/concepts#unique-identifiers) for the item and the vault where the item is stored. **JavaScript:** To fetch the item sharing account policy, use the [`items.shares.getAccountPolicy()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items_shares.ts#L47) method with the [unique identifiers (IDs)](/docs/sdks/concepts#unique-identifiers) for the item and the vault where the item is stored. **Python:** To fetch the item sharing account policy, use the [`items.shares.get_account_policy()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items_shares.py#L17) method with the [unique identifiers (IDs)](/docs/sdks/concepts#unique-identifiers) for the item and the vault where the item is stored. ### Step 3: (Optional) Validate the recipients You can validate recipients to make sure that the people you want to share the link with are allowed to receive it, based on your account policy or sharing parameters. This step is only required if the item sharing link is limited to specific email addresses or domains. If the share link is accessible to anyone with the link, you can skip validating the recipients. **Go:** To validate the recipients, use the [`Items().Shares().ValidateRecipients()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items_shares.go#L16) method. Replace `helloworld@agilebits.com` with the recipient's email address or domain in the example below. **JavaScript:** To validate the recipients, use the [`items.shares.validateRecipients()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items_shares.ts#L72) method. Replace `helloworld@agilebits.com` with the recipient's email address or domain in the example below. **Python:** To validate the recipients, use the [`items.shares.validate_recipients()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items_shares.py#L38) method. Replace `helloworld@agilebits.com` with the recipient's email address or domain in the example below. ### Step 4: Create the item sharing link :::tip Learn how to [view a shared item](https://support.1password.com/share-items#view-a-shared-item). ::: **Go:** Use the [`Items().Shares().Create()`](https://github.com/1Password/onepassword-sdk-go/blob/main/items_shares.go#L65) method to create a unique link you can send to others. This method requires an [`ItemShareParams`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L584) struct with the following fields: - `ExpireAfter`: How long the item link will remain accessible. Options include: `OneHour`, `OneDay`, `SevenDays`, `FourteenDays`, `ThirtyDays`. Not specifying this will default to the `DefaultShareDuration` in the account policy. - `Recipients`: The validated recipients of an item share, obtained through the recipient validation function. Leaving this parameter empty will allow everyone with the link to see the item. - `OneTimeOnly`: A boolean that determines if the link expires after one view. The SDK will create the link based on the configuration settings in the `ItemShareParams` struct. If you have a 1Password Business account, it will also validate the settings against the item sharing policy set by your account owner or administrator. The SDK returns a `shareLink` you can send to the person or people you want to share the item with. **JavaScript:** Use the [`items.shares.create()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/items_shares.ts#L30) method to create a unique link you can send to others. This method requires an [`ItemShareParams`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L445) object with the following properties: - `expireAfter`: How long the link will remain accessible. Options include: `OneHour`, `OneDay`, `SevenDays`, `FourteenDays`, `ThirtyDays`. Not specifying this will default to the `DefaultShareDuration` in the account policy. - `recipients`: An array of `ValidRecipient` objects. Leave empty to allow anyone with the link to view the shared item. - `oneTimeOnly:`: A boolean that determines if the link expires after a single view. The SDK will create the link based on the configuration settings in the `ItemShareParams` object. If you have a 1Password Business account, it will also validate the settings against the item sharing policy set by your account owner or administrator. The SDK returns a `share_link` you can send to the person or people you want to share the item with. **Python:** Use the [`items.shares.create()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/items_shares.py#L62) method to create a unique link you can send to others. This method requires an [`ItemShareParams`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L845) object with the following attributes: - `expireAfter`: How long the item share link will remain accessible. Options include: `OneHour`, `OneDay`, `SevenDays`, `FourteenDays`, `ThirtyDays`. Not specifying this will default to the `DefaultShareDuration` in the account policy. - `recipients`: An array of `ValidRecipient` objects. Leave empty to allow anyone with the link to view the shared item. - `oneTimeOnly:`: A boolean that determines if the link expires after a single view. The SDK will create your item share link based on the configuration settings in the `ItemShareParams` object. If you have a 1Password Business account, it will also validate the settings against the item sharing policy set by your account owner or administrator. The SDK returns a `share_link` you can send to the person or people you want to share the item with. --- ## 1Password SDK tutorials and examples ## Tutorials - **Set up the JS SDK and fetch a secret from 1Password**: Learn how to get started using a service account with the 1Password JavaScript SDK by building a simple app that securely fetches a secret from your 1Password account. Learn more - **Integrate 1Password SDKs with AI agents**: Learn a workflow for integrating 1Password SDKs with AI agents. Learn more ## Example projects - **Fetch an API key and authenticate to Twilio**: Build a simple app to read an API key from 1Password to use in your deployed services. Learn more - **Rotate an API key with AWS EventBridge**: Use 1Password SDKs with AWS EventBridge to automatically rotate secrets on a set schedule. Learn more - **Use 1Password as a backend for a web app**: Collect sensitive information using a web form, store it securely in 1Password, then display non-sensitive details on a webpage. Learn more - **Migrate data between 1Password tenants**: Create a web app that facilitates moving information between two 1Password accounts without writing any data to disk. Learn more - **Securely share files and markdown**: Create a 1Password item from files in a directory of your choice for the purposes of securely sharing source code and a README. Learn more - **Securely onboard employees to Okta**: Create a new Okta user and generate a strong password for their Okta account, then securely share the credentials with your new team member. Learn more --- ## Manage vault permissions using 1Password SDKs If you have [1Password Business](https://1password.com/business-security) or [1Password Teams](https://1password.com/product/teams-small-business-password-manager), you can manage your team members' vault access at the group level. We recommend authenticating with the [1Password desktop app](/docs/sdks/concepts#1password-desktop-app) to manage vault permissions. Service accounts can only manage permissions for vaults created by the service account. :::caution Some vault permissions require dependent permissions. You must grant or remove all required dependent permissions or the operation will fail. The permissions available to you depend on your account type. See [1Password Business vault permissions](#1password-business-vault-permissions) and [1Password Teams vault permissions](#1password-teams-vault-permissions) for more information. ::: > **Tip** > } title="TIP"> See the examples folder in the 1Password [Go](https://github.com/1Password/onepassword-sdk-go/tree/main/example), [JavaScript](https://github.com/1Password/onepassword-sdk-js/tree/main/examples), or [Python](https://github.com/1Password/onepassword-sdk-python/tree/main/example) SDK GitHub repository for full example code you can quickly clone and test in your project. ## Grant vault permissions **Go:** Use the [`Vaults().GrantGroupPermissions()`](https://github.com/1Password/onepassword-sdk-go/blob/main/vaults.go#L144) method to grant vault permissions to all team members who belong to a specific group. This method requires the following: - `vaultID`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault. - A slice of one or more [`GroupAccess`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L129) structs that each contain: - `GroupID`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the group. - `Permissions`: A bitmask of [vault permissions](#appendix-vault-permissions) to grant to the group. You can combine multiple permissions using the bitwise OR operator (`|`). **JavaScript:** Use the [`vaults.grantGroupPermissions()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/vaults.ts#L51) method to grant vault permissions to all team members who belong to a specific group. This method requires the following: - `vaultId`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault. - An array of one or more [`GroupAccess`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L133) objects that each contain: - `group_id`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the group. - `permissions`: A bitmask of [vault permissions](#appendix-vault-permissions) to grant to the group. You can combine multiple permissions using the bitwise OR operator (`|`). **Python:** Use the [`vaults.grant_group_permissions()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/vaults.py#L155) method to grant vault permissions to all team members who belong to a specific group. This method requires the following: - `vault_id`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault. - A list of one or more [`GroupAccess`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L245) objects that each contains: - `group_id`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the group. - `permissions`: A bitmask of [vault permissions](#appendix-vault-permissions) to grant to the group. You can combine multiple permissions using the bitwise OR operator (`|`). ## Update vault permissions :::caution Make sure to specify **all** the permissions the group should have in the vault. This method completely replaces all existing permissions. ::: **Go:** Use the [`Vaults().UpdateGroupPermissions()`](https://github.com/1Password/onepassword-sdk-go/blob/main/vaults.go#L153) method to replace a group's existing permissions in a vault. This method accepts a slice of one or more [`GroupVaultAccess`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L140) structs that each contains: - `VaultID`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault. - `GroupID`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the group. - `Permissions`: A bitmask of the complete set of updated [vault permissions](#appendix-vault-permissions). You can combine multiple permissions using the bitwise OR operator (`|`). **JavaScript:** Use the [`vaults.updateGroupPermissions()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/vaults.ts#L59) method to replace a group's existing permissions in a vault. This method accepts an array of one or more [`GroupVaultAccess`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L147) objects that each contains: - `vaultID`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault. - `groupID`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the group. - `permissions`: A bitmask of the complete set of updated [vault permissions](#appendix-vault-permissions). You can combine multiple permissions using the bitwise OR operator (`|`). **Python:** Use the [`vaults.update_group_permissions()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/vaults.py#L181) method to replace a group's existing permissions in a vault. This method accepts a list of one or more [`GroupVaultAccess`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L269) objects that each contains: - `vault_id`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault. - `group_id`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the group. - `permissions`: A bitmask of the complete set of updated [vault permissions](#appendix-vault-permissions). You can combine multiple permissions using the bitwise OR operator (`|`). ## Revoke vault permissions **Go:** Use the [`Vaults().RevokeGroupPermissions()`](https://github.com/1Password/onepassword-sdk-go/blob/main/vaults.go#L161) method to completely remove a group's access to a vault. This method requires the following: - `vaultID`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault. - `groupID`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the group whose permissions you want to revoke. **JavaScript:** Use the [`vaults.revokeGroupPermissions()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/vaults.ts#L66) method to completely remove a group's access to a vault. This method requires the following: - `vaultID`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault. - `groupID`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the group whose permissions you want to revoke. **Python:** Use the [`vaults.revoke_group_permissions()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/vaults.py#L204) method to completely remove a group's access to a vault. This method requires the following: - `vault_id`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault. - `group_id`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the group whose permissions you want to revoke. ## Appendix: Vault permissions The permissions available to you depend on your account type: [1Password Business](#1password-business-vault-permissions) or [1Password Teams](#1password-teams-vault-permissions). ### 1Password Business vault permissions In 1Password Business, all vault permissions have a hierarchical relationship in which narrower permissions require broader permissions to be granted alongside them. For example, to grant the narrower permission `DELETE_ITEMS` you must also grant the broader permissions `EDIT_ITEMS`, `REVEAL_ITEM_PASSWORD`, and `READ_ITEMS`. This is because you cannot delete items unless you can also view and edit them. Similarly, to revoke a broader permission like `READ_ITEMS`, any narrower dependent permissions like `DELETE_ITEMS` that have already been granted must also be revoked. | Permission | Description | Required dependencies | Integer | | --- | --- | --- | --- | | `READ_ITEMS` | View items in the vault. | None | 32 | | `CREATE_ITEMS` | Create items in the vault. | `READ_ITEMS` | 128 | | `REVEAL_ITEM_PASSWORD` | View and copy concealed password fields in the vault. | `READ_ITEMS` | 16 | | `UPDATE_ITEMS` | Edit items in the vault. | `READ_ITEMS`, `REVEAL_ITEM_PASSWORD` | 64 | | `ARCHIVE_ITEMS` | Move items in the vault to the Archive. | `READ_ITEMS`, `REVEAL_ITEM_PASSWORD`, `UPDATE_ITEMS` | 256 | | `DELETE_ITEMS` | Delete items in the vault. | `READ_ITEMS`, `REVEAL_ITEM_PASSWORD`, `UPDATE_ITEMS` | 512 | | `UPDATE_ITEM_HISTORY` | View and restore item history. | `READ_ITEMS`, `REVEAL_ITEM_PASSWORD` | 1024 | | `IMPORT_ITEMS` | Move or copy items into the vault. | `READ_ITEMS`, `CREATE_ITEMS` | 2097152 | | `EXPORT_ITEMS` | Save items in the vault to an unencrypted file that other apps can read. | `READ_ITEMS`, `REVEAL_ITEM_PASSWORD`, `UPDATE_ITEM_HISTORY` | 4194304 | | `SEND_ITEMS` | Copy and share items. | `READ_ITEMS`, `REVEAL_ITEM_PASSWORD`, `UPDATE_ITEM_HISTORY` | 1048576 | | `PRINT_ITEMS` | Print the contents of items in the vault. | `READ_ITEMS`, `REVEAL_ITEM_PASSWORD`, `UPDATE_ITEM_HISTORY` | 8388608 | | `MANAGE_VAULT` | Grant and revoke access to the vault, change permissions for others, and delete the vault. This permission doesn’t include any item viewing or editing permissions. | None | 2 | | `NO_ACCESS` | Grants a group access entry to a vault without any permissions in it. | | 0 | ### 1Password Teams vault permissions 1Password Teams includes three broad permission levels made up of collections of the [granular vault permissions](#1password-business-vault-permissions) available in 1Password Business. You'll need to grant or revoke all the permissions for the desired permission level. The permission levels have a hierarchical relationship. To grant `Allow editing`, you must also grant the permissions included in `Allow viewing`. | Permission | Description | Includes permissions | | --- | --- | --- | | Allow viewing | View items in a vault, view concealed passwords and copy them to the clipboard. | `READ_ITEMS`, `REVEAL_ITEM_PASSWORD`, `UPDATE_ITEM_HISTORY` | | Allow editing | Create, edit, move, print, copy, archive, and delete items in the vault. Requires the `Allow viewing` permission level to be granted. | `CREATE_ITEMS`, `UPDATE_ITEMS`, `ARCHIVE_ITEMS`, `DELETE_ITEMS`, `IMPORT_ITEMS`, `EXPORT_ITEMS`, `SEND_ITEMS`, `PRINT_ITEMS` | | Allow managing | Grant and revoke access to the vault, change permissions for others, and delete the vault. | `MANAGE_VAULT` | --- ## Manage vaults using 1Password SDKs You can use 1Password SDKs to manage [vaults](https://support.1password.com/1password-glossary#vault) in 1Password. You can only get information about vaults the authenticated user has access to, and you can only manage vaults where you have the [Manage Vault permission](/docs/sdks/vault-permissions#appendix-vault-permissions). We recommend authenticating with the [1Password desktop app](/docs/sdks/concepts#1password-desktop-app) to manage vaults. Service accounts are scoped to specific vaults, and must have explicit permission to create new vaults. Service accounts can't update existing vaults and can only delete vaults created by the service account. > **Tip** > } title="TIP"> See the examples folder in the 1Password [Go](https://github.com/1Password/onepassword-sdk-go/tree/main/example), [JavaScript](https://github.com/1Password/onepassword-sdk-js/tree/main/examples), or [Python](https://github.com/1Password/onepassword-sdk-python/tree/main/example) SDK GitHub repository for full example code you can quickly clone and test in your project. ## Create a vault :::tip If you're authenticating with a service account, make sure the service account has permission to create vaults. If it doesn't have permission to create vaults, you'll need to [create a new service account](/docs/service-accounts/get-started#create-a-service-account) with this permission or authenticate using [the 1Password desktop app](/docs/sdks/concepts#1password-desktop-app). ::: **Go:** Use the [`Vaults().Create()`](https://github.com/1Password/onepassword-sdk-go/blob/main/vaults.go#L50) method to create a new vault. This method requires a [`VaultCreateParams`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L1040) struct with the following fields: - `Title`: The name of the vault. - `Description`: An optional pointer to a string containing the vault's description. Returns: A [`Vault`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L1021) struct. **JavaScript:** Use the [`vaults.create()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/vaults.ts#L79) method to create a new vault. This method requires an options object with the following properties: - `title`: The name of the vault. - `description`: An optional description for the vault. Returns: A Promise that resolves to a [`Vault`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L568) object. **Python:** Use the [`vaults.create()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/vaults.py#L28) method to create a new vault. This method requires a [`VaultCreateParams`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L1310) object with the following parameters: - `title`: The name of the vault. - `description`: An optional description for the vault. - `allow_admins_access`: A boolean that determines whether people who belong to the [Administrators](https://support.1password.com/1password-glossary/#administrator) group can access the vault. Returns: A [`Vault`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L1269) object. ## Get a vault overview **Go:** Use the [`Vaults().GetOverview()`](https://github.com/1Password/onepassword-sdk-go/blob/main/vaults.go#L86) method with the [unique identifier (ID)](/docs/sdks/concepts#unique-identifiers) of a vault to retrieve high-level metadata about the vault. The following example gets the overview for the vault you created [in the previous step](#create-a-vault). **JavaScript:** Use the [`vaults.getOverview()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/vaults.ts#L31) method with the [unique identifier (ID)](/docs/sdks/concepts#unique-identifiers) of a vault to retrieve high-level metadata about the vault. The following example gets the overview for the vault you created [in the previous step](#create-a-vault). **Python:** Use the [`vaults.get_overview()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/vaults.py#L72) method with the [unique identifier (ID)](/docs/sdks/concepts#unique-identifiers) of a vault to retrieve high-level metadata about the vault. The following example gets the overview for the vault you created [in the previous step](#create-a-vault). ## Get vault details **Go:** Use the [`Vaults().Get()`](https://github.com/1Password/onepassword-sdk-go/blob/main/vaults.go#L102) method with the [unique identifier (ID)](/docs/sdks/concepts#unique-identifiers) of a vault to get the vault's full metadata. The following example gets details for the vault you retrieved [in the previous step](#get-a-vault-overview). **JavaScript:** Use the [`vaults.get()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/vaults.ts#L36) method with the [unique identifier (ID)](/docs/sdks/concepts#unique-identifiers) of a vault to get the vault's full metadata. The following example gets details for the vault you created [in the first step](#create-a-vault). **Python:** Use the [`vaults.get()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/vaults.py#L91) method with the [unique identifier (ID)](/docs/sdks/concepts#unique-identifiers) of a vault to get the vault's full metadata. ## Update a vault **Go:** Use the [`Vaults().Update()`](https://github.com/1Password/onepassword-sdk-go/blob/main/vaults.go#L119) method to modify the details of an existing vault. This method requires the following: - `vaultID`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault you want to update. - A [`VaultUpdateParams`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L1076) struct that contains the new vault details: - `Title`: The new name for the vault. - `Description`: An updated description for the vault. Returns: The updated [`Vault`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L1021) struct. The following example updates the name and description of the vault you created [in the first step](#create-a-vault). **JavaScript:** Use the [`vaults.update()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/vaults.ts#L167) method to modify the details of an existing vault. This method requires the following: - `vaultId`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault you want to update. - An object that contains the new vault details: - `title`: The new name for the vault. - `description`: An updated description for the vault. Returns: A Promise that resolves to the updated [`Vault`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L568) object. The following example updates the name and description of the vault you created [in the first step](#create-a-vault). **Python:** Use the [`vaults.update()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/vaults.py#L113) method to modify the details of an existing vault. This method requires the following: - `vault_id`: The [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault you want to update. - A [`VaultUpdateParams`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L1388) object that contains the new vault details: - `title`: The new name for the vault. - `description`: An updated description for the vault. Returns: The updated [`Vault`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L1269) object. The following example updates the name and description of the vault you created [in the first step](#create-a-vault). ## Delete a vault **Go:** To delete a vault, use the [`Vaults().Delete()`](https://github.com/1Password/onepassword-sdk-go/blob/main/vaults.go#L136) method with the [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault you want to delete. The following example deletes the vault you created [in the first step](#create-a-vault). **JavaScript:** To delete a vault, use the [`vaults.delete()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/vaults.ts#L46) method with the [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault you want to delete. The following example deletes the vault you created [in the first step](#create-a-vault). **Python:** To delete a vault, use the [`vaults.delete()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/vaults.py#L135) method with the [unique identifier](/docs/sdks/concepts#unique-identifiers) of the vault you want to delete. The following example deletes the vault you created [in the first step](#create-a-vault). :::tip You can also [batch create, get, and delete items](/docs/sdks/manage-items#manage-items-in-bulk) from a vault. ::: ## Learn more - [Manage items in bulk](/docs/sdks/manage-items#manage-items-in-bulk) - [Manage vault permissions](/docs/sdks/vault-permissions) - [List vaults and items](/docs/sdks/list-vaults-items)