# 1Password Academy Source: https://www.1password.dev/academy # 1Password Accounts API for Partners Source: https://www.1password.dev/accounts-api Overview of the 1Password Accounts API for Partners for provisioning and managing 1Password product entitlements, usage, and products for distributor customers. The 1Password Accounts API for Partners is a REST-style API for distribution partners. The API allows distributors to provision and manage 1Password product entitlements for their customers, retrieve usage data, and see which products are available to provision. The Accounts API is organized around three resource groups: > [card] [Entitlements](/accounts-api/list-entitlements) > > Provision, update, cancel, and link 1Password product entitlements for a customer. > [card] [Usage](/accounts-api/list-customer-usage) > > Retrieve product usage data for your customers by billing cycle. > [card] [Products](/accounts-api/list-products) > > List the 1Password products you can provision. ## Become a partner Before you can use the Accounts API, you'll need to have a registered distributor account with 1Password. If you don't have a distributor account, [contact 1Password](mailto:msp@1password.com) to register. To learn more about our partnership opportunities, visit the [1Password Partner Program page](https://1password.com/partnerships). ## Quickstart To make your first request to the Accounts API, [start here](/accounts-api/get-started). ## Guides Read the [API conventions](/accounts-api/conventions) to learn how to authenticate, structure requests, and interpret responses and errors. ## Reference documentation Use the [API reference](/accounts-api/reference) to learn more about each endpoint. ### Entitlements * [List entitlements](/accounts-api/list-entitlements) * [Create an entitlement](/accounts-api/create-entitlement) * [Update an entitlement](/accounts-api/update-entitlement) * [Cancel an entitlement](/accounts-api/cancel-entitlement) * [Link an entitlement](/accounts-api/link-entitlement) ### Usage * [List customer usage](/accounts-api/list-customer-usage) ### Products * [List products](/accounts-api/list-products) # Cancel an entitlement Source: https://www.1password.dev/accounts-api/cancel-entitlement openapi/accounts_api.yaml DELETE /v1/distributor-customers/{distributor-customer}/entitlements/{entitlement} Initiate cancellation of a 1Password product entitlement for a distributor customer. When you initiate cancellation of an entitlement, its status immediately transitions to `cancelling`. Background processing then completes the cancellation and transitions the status to `cancelled`. Poll [list entitlements](/accounts-api/list-entitlements) to check for completion. Cancellation requests are idempotent. Repeating the request for an entitlement that's already `cancelling` or `cancelled` returns a `200` response with the entitlement's current state, so it's safe to retry a request that timed out or failed. See [API conventions](/accounts-api/conventions) for more information about authentication, resource paths, pagination, filtering, and error handling. # API conventions Source: https://www.1password.dev/accounts-api/conventions Conventions used across the 1Password Accounts API for Partners, including authentication, resource paths, pagination, filtering, and error handling. The following conventions apply across the 1Password Accounts API for Partners. ## Authentication The Accounts API authorizes requests with a bearer token. When your organization registers as a distributor, you'll receive an opaque bearer token, prefixed with `op_b_`. Include this token in the `Authorization` header of every request, prefixed with `Bearer`: ``` Authorization: Bearer ``` For example: ```shell theme={null} curl --request GET \ --url "https://api.1password.eu/v1/distributor-products" \ --header "Authorization: Bearer " ``` > [!WARNING] > > Treat your bearer token like a password. Store it securely (for example, in a 1Password vault) and never expose it in client-side code, logs, or source control. If you need a new bearer token, [contact 1Password](mailto:msp@1password.com). ## Endpoints The basic structure of an endpoint URL for the Accounts API includes the [base URL](#base-url) and the [endpoint path](#endpoint-path). The endpoint path includes the API endpoint version, the resource(s) you want to access, and any relevant path parameters. ### Base URL All requests to the Accounts API use the 1Password.eu base URL, `https://api.1password.eu`, regardless of the [region of your 1Password account](https://support.1password.com/regions/) or your customers' accounts. The [`product_id`](/accounts-api/list-products) you provision determines the region where a customer's 1Password account is created. All communication with the API is over HTTPS. ### Endpoint path The endpoint path is appended to the base URL and includes the endpoint version, target resource path, and any path parameters. For example, the endpoint path to list usage for a specific customer would look like this: ``` /v1/distributor-customers/{distributor-customer}/usage ``` The `{distributor-customer}` path parameter is your own identifier for the customer, as defined in your marketplace system — 1Password doesn't validate it against a customer registry. Some list endpoints also accept `-` as a wildcard to query across all of your customers. See the [API reference documentation](/accounts-api/reference) for more information about each endpoint. ## Requests ### Request methods Requests to the Accounts API use standard HTTP methods: | Method | Usage | | - | - | | `GET` | Retrieve resources. For example: [list entitlements](/accounts-api/list-entitlements), [customer usage](/accounts-api/list-customer-usage), or [products](/accounts-api/list-products). | | `POST` | Create resources. For example: [create](/accounts-api/create-entitlement) or [link](/accounts-api/link-entitlement) an entitlement. | | `PATCH` | Update specific fields of a resource. For example: [update a pending entitlement](/accounts-api/update-entitlement). | | `DELETE` | Initiate removal of a resource. For example: [cancel an entitlement](/accounts-api/cancel-entitlement). | ### Request headers ``` Authorization: Bearer Content-Type: application/json ``` * **`Authorization`**: Required on every request. Use this header with your bearer token to authenticate your API requests. * **`Content-Type: application/json`**: Required for `POST` and `PATCH` requests. Use this header for requests that send a JSON body. `GET` and `DELETE` requests don't include a body. ### Request bodies `POST` and `PATCH` requests send a JSON object in the request body. Check the [API reference documentation](/accounts-api/reference) for the fields each endpoint accepts. The API silently ignores unknown fields in request bodies, so make sure your field names are correct. A misspelled field name is ignored without an error and the value isn't applied. `GET` and `DELETE` requests don't include a request body. ## Query parameters You can use query parameters in your API request as optional modifiers after the endpoint path. Use a `?` query separator at the end of the endpoint path, then add any query parameters you want to include, separated by a `&` query delimiter. For example, if you want to retrieve a list of product usage data for all customers, you could use query parameters to [filter the results](#filtering) by billing cycle and set the maximum number of results to return per [page](#pagination): ```text theme={null} GET https://api.1password.eu/v1/distributor-customers/-/usage?filter=billing_cycle == '2026-04'&max_page_size=20 ``` Make sure your client URL-encodes query parameter values. Filter expressions contain spaces and special characters, so the request above is sent as: ```text theme={null} GET https://api.1password.eu/v1/distributor-customers/-/usage?filter=billing_cycle%20%3D%3D%20%272026-04%27&max_page_size=20 ``` Check the [API reference documentation](/accounts-api/reference) to discover which query parameters are available for each endpoint. ### Filtering The following list endpoints accept a `filter` query parameter that uses [Common Expression Language (CEL)](https://github.com/google/cel-spec) syntax: * [List entitlements](/accounts-api/list-entitlements): Filters on entitlement fields. For example, `status == 'active'` returns only active entitlements. When omitted, entitlements of all statuses are returned. See the [entitlement statuses](#entitlement-statuses) section to learn about all the possible `status` values. * [List customer usage](/accounts-api/list-customer-usage): Filters by billing cycle using `billing_cycle == 'YYYY-MM'`. For example, `billing_cycle == '2026-04'`. When omitted, usage defaults to the current billing cycle in UTC. There's no lookback limit on historical billing cycles. ### Pagination ```shell theme={null} curl --request GET \ --url "https://api.1password.eu/v1/distributor-products?max_page_size=20&page_token=" \ --header "Authorization: Bearer " ``` All list endpoints (entitlements, customer usage, and products) support pagination. Use these query parameters to page through results: * `max_page_size`: The maximum number of results to return per page. Defaults to 100; values above 100 are clamped to 100. Omitting the parameter or setting it to `0` uses the default. * `page_token`: The token that identifies the page of results to return. Each list response includes an opaque `next_page_token`. To retrieve the next page, send the same request with `page_token` set to that value. When `next_page_token` is empty, there are no more results. The API uses cursor-based pagination. Each token marks where the previous page left off, so paging stays consistent even if results change between page requests. Items already returned aren't repeated on later pages, and items aren't skipped if others are created or cancelled while you page. ## Responses The API returns JSON for all responses, except [rate-limit](#rate-limits) errors, which return plain text. A successful request returns `200 OK`. Create, update, and cancel operations return the affected entitlement in the response body, so you can read back its server-assigned fields, such as `id`, `create_time`, and the current `status`. Link operations return the entitlement inside an `entitlement` object. For example, a successful create request returns: ```json theme={null} HTTP/2 200 date: Fri, 30 Oct 2026 12:34:56 GMT content-type: application/json { "path": "distributor-customers/cust_789xyz/entitlements/ent_abc123def456", "id": "ent_abc123def456", "customer_id": "cust_789xyz", "product_id": "1p-msp-us", "status": "pending", "contact_info": { "email": "admin@acme-corp.com", "company_name": "Acme Corporation" }, "create_time": "2026-09-15T10:30:00Z" } ``` List operations return a `results` array and a `next_page_token`. For example: ```json theme={null} { "results": [ { "path": "distributor-customers/cust_789xyz/entitlements/ent_abc123def456", "id": "ent_abc123def456", "customer_id": "cust_789xyz", "product_id": "1p-msp-us", "status": "active", "contact_info": { "email": "admin@acme-corp.com", "company_name": "Acme Corporation" }, "create_time": "2026-09-15T10:30:00Z", "expire_time": "2026-09-20T10:30:00Z" } ], "next_page_token": "" } ``` When a list request matches no results, the response returns an empty `results` array and an empty `next_page_token`. ```json theme={null} { "results": [], "next_page_token": "" } ``` Learn more about [error responses](#errors) and [paginated list responses](#pagination). ### Dates and times Timestamps are returned in [RFC 3339 format](https://datatracker.ietf.org/doc/html/rfc3339), for example `2026-01-23T15:55:58Z`. ## Rate limits Requests to the Accounts API are rate limited to 1,000 requests per minute, per distributor. There's no separate hourly limit. If you exceed the allowed rate, the API returns a `429 Too Many Requests` response with a `Retry-After` header that indicates how long to wait before retrying. Unlike other error responses, the `429` response body is plain text, not JSON. ## Errors The API uses standard HTTP status codes to indicate the result of a request. A `2xx` code indicates success. A `4xx` code indicates a problem with the request (for example, missing authentication or invalid input). A `5xx` code indicates an unexpected server error. Most error responses include a JSON body with a machine-readable `code` and a human-readable `message`: ```json theme={null} { "code": "not_found", "message": "The requested resource was not found." } ``` > [!WARNING] > > The error response format, including the `code` and `message` fields, is provisional and may change in a future release. Use the HTTP status code to handle errors in your integration, and don't rely on the text of the `message` field. | Status | Code | Meaning | | - | - | - | | `400` | `invalid_argument` | A request parameter or body field is invalid. | | `401` | `unauthenticated` | Missing or invalid credentials. | | `404` | `not_found` | The resource doesn't exist. | | `409` | `already_exists` | The resource already exists — for example, an entitlement for the product already exists. | | `500` | `internal` | An internal error occurred. Retry the request later. | `429 Too Many Requests` responses don't use this JSON format. See the [rate limits](#rate-limits) section for more information about this error response. ## Entitlement statuses An entitlement's `status` field reflects its position in the lifecycle: | Status | Meaning | | - | - | | `pending` | The entitlement has been created and is waiting for the customer to activate it (or, for [linked entitlements](/accounts-api/link-entitlement), claim the entitlement code). Only pending entitlements can be [updated](/accounts-api/update-entitlement). | | `active` | The entitlement is active and the product is provisioned. | | `cancelling` | [Cancellation](/accounts-api/cancel-entitlement) has been initiated. Background processing completes it and transitions the status to `cancelled`. | | `cancelled` | The entitlement has been cancelled. | | `expired` | A [change-of-channel entitlement](/accounts-api/link-entitlement) whose entitlement code wasn't claimed within 5 days of creation. | # Create an entitlement Source: https://www.1password.dev/accounts-api/create-entitlement openapi/accounts_api.yaml POST /v1/distributor-customers/{distributor-customer}/entitlements Provision a new 1Password product entitlement for a distributor customer. Use this endpoint to create a new 1Password product entitlement for a customer. The entitlement starts off as `pending` until the customer activates it. Creating an entitlement works as follows: 1. The entitlement is created with a status of `pending`. 2. 1Password sends an email to the customer with an activation link. The email includes your distributor name and the product name. 3. The customer selects the activation link and sets up their new 1Password account, which activates the entitlement and transitions it to `active`. Poll the [list of entitlements](/accounts-api/list-entitlements) to check the entitlement's status. > [!NOTE] > > Pending entitlements don't expire. An entitlement stays `pending` until the customer activates it or you [cancel](/accounts-api/cancel-entitlement) it. Only pending entitlements can be [updated](/accounts-api/update-entitlement). > > If an entitlement for the product already exists for the customer, the request fails with a `409` error unless it has a `cancelled` or `expired` status. > > If the existing entitlement is `cancelled` or `expired`, it's reactivated with a status of `pending`. > > A reactivated entitlement keeps its original `id` and `create_time`, with the contact details from the new request. The `distributor-customer` ID in the request path is your own identifier for the customer, as defined in your system, and isn't validated when you create an entitlement. Make sure your integration passes customer IDs consistently. [Retrieve a list of available 1Password products](/accounts-api/list-products) to find the `product_id` value to use when creating an entitlement. See [API conventions](/accounts-api/conventions) for more information about authentication, resource paths, pagination, filtering, and error handling. # Get started with the 1Password Accounts API for Partners Source: https://www.1password.dev/accounts-api/get-started Learn how to authenticate and make your first requests to the 1Password Accounts API for Partners. The 1Password Accounts API for Partners allows distributors to provision and manage 1Password product entitlements for their customers. This guide walks you through making your first authenticated request. ## Requirements Before you begin, you'll need a registered distributor account with 1Password. If you don't have a distributor account, [contact 1Password](mailto:msp@1password.com) to register. ## Step 1: Get your bearer token The Accounts API authorizes requests with a bearer token. When your organization registers as a distributor, you receive an opaque bearer token, prefixed with `op_b_`. You'll include this token in the `Authorization` header of every request. See the [authentication section](/accounts-api/conventions#authentication) in the API conventions guide for more information. ## Step 2: Make your first API call For your first call to the Accounts API, you can use [curl](https://curl.se/) on the command line to send a request to the [`/v1/distributor-products`](/accounts-api/list-products) endpoint. This will let you confirm that your bearer token is valid and which products your distributor account can provision. Open your terminal and run the following command, replacing `` with your bearer token from Step 1. ```shell theme={null} curl --request GET \ --url https://api.1password.eu/v1/distributor-products \ --header "Authorization: Bearer " ``` A successful request will return a JSON response with an array of products. For example: ```json theme={null} { "results": [ { "name": "1Password MSP", "product_id": "1p-msp-us" } ], "next_page_token": "" } ``` If additional pages of results are available, the response will also include a `next_page_token`. You can use that token with the `page_token` query parameter to fetch the next page. Learn more about [pagination](/accounts-api/conventions#pagination) in the API. ## Step 3: Try out more examples You can use the [API reference](/accounts-api/reference) to find more code examples for each endpoint. Select **Try it** in any endpoint header to open the interactive API playground. You can enter your own values in the input boxes and send requests directly from the playground. > [!WARNING] > > Requests you send from the API playground are routed through the documentation platform's proxy service. If you prefer to keep your bearer token strictly between your systems and 1Password, copy a code example and run it with your own tools instead. To use the examples with another tool, select the dropdown menu on a code example and choose which language option you want, select copy , then paste the example code into your preferred testing tool. You can also download the [ OpenAPI specification YAML file](/static/files/accounts-api/1password-accounts-api_v1_2026-10-01.yaml), then use it to feed into code-generation tools, create mock servers, or import into API clients. ## Learn more * [API conventions](/accounts-api/conventions) * [API reference](/accounts-api/reference) # Link an entitlement Source: https://www.1password.dev/accounts-api/link-entitlement openapi/accounts_api.yaml POST /v1/distributor-customers/{distributor-customer}/entitlements:link Create a change-of-channel entitlement to link an existing 1Password account. Use this endpoint when a customer already has a 1Password account and is switching to purchasing 1Password through you as their distributor, instead of provisioning a new account with [create an entitlement](/accounts-api/create-entitlement). Linking creates a change-of-channel entitlement that connects a customer's existing 1Password account to your distributor relationship. The request must identify the existing account by its 1Password domain in the metadata (for example, `acme-corp.1password.com`), along with the [`product_id`](/accounts-api/list-products) to provision and the customer's `contact_info`. Linking an entitlement works as follows: 1. The entitlement is created with a status of `pending` and an `expire_time` 5 days from creation. 2. 1Password sends an email to the customer with their entitlement code. The email includes your distributor name and the product name. 3. The customer claims the code for their existing 1Password account, which completes the link and transitions the entitlement to `active`. > [!WARNING] > > If the customer doesn't complete linking within 5 days, the entitlement expires and its status transitions to `expired`. > [!NOTE] > > If an entitlement for the product already exists for the customer, the request fails with a `409` error unless it has a `cancelled` or `expired` status. > > If the existing entitlement is `cancelled` or `expired`, it's reactivated with a status of `pending`. > > A reactivated entitlement keeps its original `id` and `create_time`, with the contact details from the new request. See [API conventions](/accounts-api/conventions) for more information about authentication, resource paths, pagination, filtering, and error handling. # List customer usage Source: https://www.1password.dev/accounts-api/list-customer-usage openapi/accounts_api.yaml GET /v1/distributor-customers/{distributor-customer}/usage Retrieve paginated product usage data for a distributor's customers. Use a customer ID in the path to scope results to one customer, or use the wildcard `distributor-customers/-` to list across all of your customers. To retrieve a past billing cycle, set the `filter` query parameter, for example: `billing_cycle == '2026-04'`. There's no lookback limit for this filter. If you omit the filter, usage defaults to the current billing cycle in UTC. See [filtering](/accounts-api/conventions#filtering) for details. This endpoint also supports [pagination](/accounts-api/conventions#pagination). See [API conventions](/accounts-api/conventions) for more information about authentication, resource paths, pagination, filtering, and error handling. # List entitlements Source: https://www.1password.dev/accounts-api/list-entitlements openapi/accounts_api.yaml GET /v1/distributor-customers/{distributor-customer}/entitlements Retrieve a paginated list of 1Password product entitlements for a distributor customer. Retrieve entitlements under a customer. Use a customer ID in the path to scope results to one customer, or the wildcard `distributor-customers/-` to list across all of your customers. This endpoint supports [pagination and filtering](/accounts-api/conventions#query-parameters). For example, filter on status with `status == 'active'`. Learn more about [entitlement statuses](/accounts-api/conventions#entitlement-statuses) and the possible values. See [API conventions](/accounts-api/conventions) for more information about authentication, resource paths, pagination, filtering, and error handling. # List products Source: https://www.1password.dev/accounts-api/list-products openapi/accounts_api.yaml GET /v1/distributor-products Retrieve the 1Password products a distributor can provision. Retrieve all products available to your distributor account. Use the `product_id` returned by this endpoint when [creating](/accounts-api/create-entitlement) or [linking](/accounts-api/link-entitlement) entitlements. This endpoint supports [pagination](/accounts-api/conventions#pagination). See [API conventions](/accounts-api/conventions) for more information about authentication, resource paths, pagination, filtering, and error handling. # Reference for the 1Password Accounts API for Partners Source: https://www.1password.dev/accounts-api/reference Complete reference documentation for the 1Password Accounts API for Partners. This reference documents every endpoint for the 1Password Accounts API for Partners. Each endpoint reference page includes the parameters, request and response schemas, and an interactive playground you can use to send requests. Select **Try it** in any endpoint header to open the playground, enter your own values in the input boxes, then send requests directly from the page. > [!WARNING] > > Requests you send from the API playground are routed through the documentation platform's proxy service. If you prefer to keep your bearer token strictly between your systems and 1Password, copy a code example and run it with your own tools instead. For more information about authentication and how the Accounts API works, review the [API conventions](/accounts-api/conventions). ## Endpoint references ### Entitlements * [List entitlements](/accounts-api/list-entitlements) * [Create an entitlement](/accounts-api/create-entitlement) * [Update an entitlement](/accounts-api/update-entitlement) * [Cancel an entitlement](/accounts-api/cancel-entitlement) * [Link an entitlement](/accounts-api/link-entitlement) ### Usage * [List customer usage](/accounts-api/list-customer-usage) ### Products * [List products](/accounts-api/list-products) ## OpenAPI specification The 1Password Accounts API for Partners specification follows [OpenAPI 3.1.0 standards.](https://spec.openapis.org/oas/v3.1.0.html) To work with the API in another tool, download the specification file: * [ 1Password Accounts API for Partners (v1) specification](/static/files/accounts-api/1password-accounts-api_v1_2026-10-01.yaml) # Update an entitlement Source: https://www.1password.dev/accounts-api/update-entitlement openapi/accounts_api.yaml PATCH /v1/distributor-customers/{distributor-customer}/entitlements/{entitlement} Update a pending 1Password product entitlement for a distributor customer. Only entitlements with a status of `pending` can be updated. Attempting to update an entitlement in any other state returns an error. Use the optional `update_mask` query parameter to specify exactly which fields to update. See the `update_mask` parameter reference for the supported values. See [API conventions](/accounts-api/conventions) for more information about authentication, resource paths, pagination, filtering, and error handling. # Search and read 1Password developer documentation with AI Source: https://www.1password.dev/ai-readable-docs Search and read 1Password developer documentation from AI tools using a curated `llms.txt` index, per-page Markdown, `llms-full.txt`, and an MCP search server. > [!NOTE] > > These options read documentation only. To give agents access to secrets or integrate with 1Password APIs, see [Secure AI access](/get-started/secure-ai-access) and [Build integrations](/get-started/build-integrations). ## Quickstart Give your LLM one of these URLs depending on what you need: | What you need | URL | | - | - | | **Curated list** of key articles with descriptions | [`/llms.txt`](https://www.1password.dev/llms.txt) | | **All documentation** in a single file | [`/llms-full.txt`](https://www.1password.dev/llms-full.txt) | | **Any single page** as Markdown | Append `.md` to the URL of any article | | **MCP server** to search and retrieve docs in AI tools | [`/mcp`](https://www.1password.dev/mcp) | ## Choose how you use AI Choose the setup that matches your AI tool. > [card] [Ask in a chatbot](#ask-in-a-chatbot) > > Use ChatGPT, Claude, Perplexity, or similar web chat to ask questions about 1Password developer tools. > [card] [Code with an AI agent or IDE](#code-with-an-ai-agent-or-ide) > > Connect Claude Code, Cursor, Windsurf, VS Code, or another coding assistant so it can search docs while you write code. > [card] [Build a custom agent or pipeline](#build-a-custom-agent-or-pipeline) > > Fetch documentation over HTTP for custom RAG pipelines, embedding indexes, or agent frameworks you run yourself. ## Ask in a chatbot In web chat, share a documentation URL or paste content from an article. ### Ask about one page On any article, select the down arrow next to "Copy page", then: * Select **Open in ChatGPT**, **Open in Claude**, or **Open in Perplexity** to ask questions about that page. * Copy the article as Markdown and paste it into your conversation. You can also share the article's Markdown URL by appending `.md` to the page URL. For example, [`https://www.1password.dev/cli/get-started.md`](https://www.1password.dev/cli/get-started.md). ### Ask about the docs site Share a URL and ask the model to read it: * [`https://www.1password.dev/llms.txt`](https://www.1password.dev/llms.txt): Curated index of quickstarts, workflow guides, and key entry points. A good default when you want the assistant to orient itself, then fetch linked pages as needed. * [`https://www.1password.dev/llms-full.txt`](https://www.1password.dev/llms-full.txt): All published documentation in one file. Use when you need exhaustive coverage in a single request and have a large enough context window. ## Code with an AI agent or IDE This section covers AI tools that help you write code, not standalone web chat. Setup depends on your tool: * **Terminal agent:** Run an AI from your terminal, like [Claude Code.](https://code.claude.com/docs/en/overview) It edits files, runs commands, and answers questions from the shell. * **AI-native editor:** Use built-in AI chat or agent mode in your editor, like [Cursor](https://cursor.com/home) Agent or [Windsurf](https://windsurf.com/) Cascade. * **IDE extension:** Add AI to a traditional editor, like VS Code with GitHub Copilot or [Claude.](https://claude.ai/) > [tab] Claude Code > > **With MCP:** > > Connect to the public documentation search server at `https://www.1password.dev/mcp` using [Model Context Protocol (MCP).](https://modelcontextprotocol.io/) The server is public and requires no authentication. Your tool can search and retrieve documentation as Markdown during a session. > > On any article, select **Copy page** → **Copy MCP Server** to copy the server URL. > > Run this command in your terminal: > > ```shell theme={null} > claude mcp add --transport http 1password-dev https://www.1password.dev/mcp > ``` > > **Without MCP:** > > * Share [`/llms.txt`](https://www.1password.dev/llms.txt) in a Claude Code session and ask it to read the docs. > * For exhaustive coverage, share [`/llms-full.txt`](https://www.1password.dev/llms-full.txt). > * Select **Copy page** to copy the current article, or select **Open in Claude** to ask questions about the page. > [tab] Cursor > > **With MCP:** > > Connect to the public documentation search server at `https://www.1password.dev/mcp` using [Model Context Protocol (MCP).](https://modelcontextprotocol.io/) The server is public and requires no authentication. Your tool can search and retrieve documentation as Markdown during a session. > > On any article, select **Copy page** → **Connect to Cursor** or **Copy MCP Server** to install the server or copy the URL. > > In Cursor, add an entry to `.cursor/mcp.json`: > > ```json theme={null} > { > "mcpServers": { > "1password-dev": { > "url": "https://www.1password.dev/mcp" > } > } > } > ``` > > **Without MCP:** > > * In Cursor, use `@Docs` to add `https://www.1password.dev/llms.txt` as a documentation source. > * For exhaustive coverage, paste `https://www.1password.dev/llms-full.txt` in a chat or agent prompt. > * Select **Copy page** to copy the current article. > [tab] Windsurf > > **With MCP:** > > Connect to the public documentation search server at `https://www.1password.dev/mcp` using [Model Context Protocol (MCP).](https://modelcontextprotocol.io/) The server is public and requires no authentication. Your tool can search and retrieve documentation as Markdown during a session. > > On any article, select **Copy page** → **Copy MCP Server** to copy the server URL. > > In Windsurf, add an entry to `~/.codeium/windsurf/mcp_config.json`. Open the file from **Windsurf Settings** → **Cascade** → **MCP Servers**, or see [Cascade MCP integration.](https://docs.windsurf.com/windsurf/cascade/mcp) > > ```json theme={null} > { > "mcpServers": { > "1password-dev": { > "serverUrl": "https://www.1password.dev/mcp" > } > } > } > ``` > > **Without MCP:** > > * Share `https://www.1password.dev/llms.txt` in a Cascade chat or agent prompt. > * For exhaustive coverage, paste `https://www.1password.dev/llms-full.txt` in a chat or agent prompt. > * Select **Copy page** to copy the current article. > [tab] VS Code > > **With MCP:** > > Connect to the public documentation search server at `https://www.1password.dev/mcp` using [Model Context Protocol (MCP).](https://modelcontextprotocol.io/) The server is public and requires no authentication. Your tool can search and retrieve documentation as Markdown during a session. > > On any article, select **Copy page** → **Connect to VS Code** or **Copy MCP Server** to install the server or copy the URL. > > Add to `.vscode/mcp.json`: > > ```json theme={null} > { > "servers": { > "1password-dev": { > "type": "http", > "url": "https://www.1password.dev/mcp" > } > } > } > ``` > > See your extension's documentation if your setup uses a different config path. > > **Without MCP:** > > * Share `https://www.1password.dev/llms.txt` in a chat or agent prompt. > * For exhaustive coverage, paste `https://www.1password.dev/llms-full.txt` in a chat or agent prompt. > * Select **Copy page** to copy the current article. ## Build a custom agent or pipeline If you're building an agent or automation pipeline and control how documentation is fetched, use HTTP retrieval or MCP. ### Direct HTTP retrieval Use this when you manage retrieval yourself, such as custom RAG pipelines, embedding indexes, or batch jobs that don't use MCP. * Start from [`/llms.txt`](https://www.1password.dev/llms.txt) for a curated map of entry points, then fetch linked pages as Markdown. * Append `.md` to any article URL to fetch a specific page. For example, [https://www.1password.dev/cli/get-started.md](https://www.1password.dev/cli/get-started.md). * Use [`/llms-full.txt`](https://www.1password.dev/llms-full.txt) when you need all published pages in one request. ### MCP If your agent framework supports HTTP MCP servers, register `https://www.1password.dev/mcp` so the agent can search and retrieve documentation during a run. Agents can also discover the server using [`/.well-known/mcp.json`](https://www.1password.dev/.well-known/mcp.json). ## Documentation formats Not every format includes the same pages. [`llms.txt`](https://www.1password.dev/llms.txt) is a curated map of entry points; `llms-full.txt`, per-page `.md`, and MCP give you access to the full published documentation. [`llms.txt`](https://www.1password.dev/llms.txt) is the source of truth for what is in the curated map. | Format | Coverage | URL | Best for | | - | - | - | - | | `llms.txt` | Curated entry points: quickstarts, workflow guides, and key overviews per product | [`https://www.1password.dev/llms.txt`](https://www.1password.dev/llms.txt) | Orienting an AI, then fetching linked pages for depth | | `llms-full.txt` | All published pages (regenerated on every deploy) | [`https://www.1password.dev/llms-full.txt`](https://www.1password.dev/llms-full.txt) | Exhaustive coverage in a single request; requires a large context window | | Per-page `.md` | One article | Append `.md` to any article URL | A specific topic. Also available from **Copy page** → **View as Markdown** | | MCP | Search all published pages | [`https://www.1password.dev/mcp`](https://www.1password.dev/mcp) | Search and retrieve docs in AI tools and agents. See [Code with an AI agent or IDE](#code-with-an-ai-agent-or-ide) and [Build a custom agent or pipeline](#build-a-custom-agent-or-pipeline). Discoverable at [`/.well-known/mcp.json`](https://www.1password.dev/.well-known/mcp.json) | ## About the llms.txt standard The [`llms.txt` standard](https://llmstxt.org/) is an open specification for making website content accessible to LLMs. It provides a structured, machine-readable Markdown index at a well-known URL (`/llms.txt`), so AI systems can discover and consume documentation without parsing HTML. The standard recommends curation over dumping an entire site into one file. # Set up 1Password Credential Broker to allow your team to access secrets in their workflows (public preview) Source: https://www.1password.dev/brokered-access Learn how to set up a supported integration in 1Password Business, so your team can use 1Password to access secrets in their machine workflows. Public Preview With [1Password Credential Broker](https://1password.com/blog/introducing-1password-credential-broker), administrators can set up a supported integration in their 1Password Business account to allow team members to use secrets from their [1Password Environments](/environments) in machine workflows. [Credential Broker Product Experience Tour](https://www.youtube.com/embed/Mq4ZyUEF8eY) First, an administrator sets up an integration, which defines a trust policy to control how and where the integration can be used. Team members can then connect Environments to their workflows using the configured integrations. When a team member runs a workflow, 1Password validates the identity of the workload using an [OIDC token.](https://openid.net/developers/how-connect-works/) Secrets are only accessible after a workload has been verified, and only remain accessible for the duration of the workflow. Every request for access is recorded in your [audit log](https://support.1password.com/activity-log/). ## Add an integration Before team members can connect their Environments to machine workflows, an administrator must set up an integration in 1Password Business. To set up an integration: 1. As an administrator, [sign in](https://start.1password.com/signin) on 1Password.com, then select [**Developer**](https://start.1password.com/developer-tools) in the sidebar. 2. Select the [**Agents & workflows** tab](https://start.1password.com/developer-tools/active/agents-workloads), then select **Set up integrations**. > [!TIP] > > If you've already set up an integration and want to add another, select **Manage integrations** > **Add Integration**. 3. Choose one of the available integrations, then follow the steps for your integration below. > [tab] GitHub Actions > > Before you connect your 1Password Business account to your GitHub organization, review the following requirements: > > * Your [GitHub organization](https://docs.github.com/organizations/collaborating-with-groups-in-organizations/about-organizations) must be hosted on GitHub.com. GitHub organizations hosted on [GitHub Enterprise Server](https://docs.github.com/enterprise-server@latest/admin/overview/about-github-enterprise-server) or [GitHub Enterprise Cloud with data residency](https://docs.github.com/enterprise-cloud@latest/admin/data-residency/about-github-enterprise-cloud-with-data-residency) aren't currently supported. > * If you use [GitHub Free for organizations](https://docs.github.com/get-started/learning-about-github/githubs-plans#github-free-for-organizations), your team won't be able to use this integration for workflows in private repositories. > > If your GitHub organization meets the requirements, follow these steps: > > 1. Enter a name for the integration and the name of the GitHub organization you want to connect, then select **Create integration**. > 2. The token value is your integration key, which is required to decrypt secrets in your team's workflows. Save this key in 1Password for future reference, then follow the steps to [add a new secret for your GitHub organization.](https://docs.github.com/en/codespaces/managing-codespaces-for-your-organization/managing-development-environment-secrets-for-your-repository-or-organization#adding-secrets-for-an-organization) Set the secret name to `OP_INTEGRATION_KEY` and the value to your integration key. > [tab] Custom Workflow (OIDC) > > 1. Enter a name for the integration, then enter your OIDC provider's issuer URL. > 2. Select **Verify**. If your JWKS endpoint isn't detected automatically, enter the URL manually, then select **Continue**. > 3. Define the identity requirements (claims) that must be met to verify a workload. All configured claims must match to verify the workload's identity. For example, you can use them to restrict secrets to [GitLab CI/CD jobs running in a specific project, branch, environment, etc.](https://docs.gitlab.com/ci/secrets/id_token_authentication/#token-payload) > 4. Make note of the expected audience value. Your team members will need to declare this when their workflows request an OIDC token. > 5. The token value is your integration key, which is required to decrypt secrets in your team's workflows. Save this key in 1Password for future reference, then configure the key as a secret that can be retrieved at runtime. For example, you can configure it as a [CI/CD variable in a GitLab group](https://docs.gitlab.com/ci/variables/#for-a-group), so the team members in that group can retrieve it with its variable name. After you've set up an integration, your team can start connecting their 1Password Environments to their workflows: ### GitHub Actions Learn how to configure GitHub Actions workflows to retrieve secrets from 1Password Environments at runtime. [Learn more](/brokered-access/github-actions/) ### Custom workflow Learn how to configure custom workflows to retrieve secrets from 1Password Environments at runtime. [Learn more](/brokered-access/custom-workflow/) ## Delete an integration If you want to delete an integration so your team members can no longer use it to access secrets in their workflows, follow these steps: 1. As an administrator, [sign in](https://start.1password.com/signin) on 1Password.com, then select [**Developer**](https://start.1password.com/developer-tools) in the sidebar. 2. Select the [**Agents & workflows** tab](https://start.1password.com/developer-tools/active/agents-workloads), then select **Manage integrations**. 3. Select **View All Integrations** under the type of integration you want to delete. 4. Select the vertical ellipsis for the integration you want to delete, then select **Delete integration**. After you delete an integration, any of your team member's workflows associated with the integration will no longer run successfully. ## Learn more * 1Password Blog: [1Password Credential Broker is now in public preview](https://1password.com/blog/1password-credential-broker-public-preview) * [1Password Environments](/environments) # Use 1Password Credential Broker to access secrets in custom workflows at runtime (public beta) Source: https://www.1password.dev/brokered-access/custom-workflow Learn how to configure custom workflows to retrieve secrets from 1Password Environments at runtime. Beta If an administrator has [connected an OIDC provider to your 1Password Business account](/brokered-access), you can use 1Password to access secrets from your 1Password Environments in your custom workflows at runtime. ## Step 1: Set up an Environment To configure the secrets you need to use in a custom workflow, make sure you have the [latest beta release of the 1Password desktop app](https://support.1password.com/betas/#install-a-prerelease-version-of-the-1password-app), then create a new [1Password Environment](/environments#create-an-environment) with your secrets or [add your secrets](/environments#add-secrets-to-an-environment) to an existing Environment. ## Step 2. Connect your Environment to your workflow After you've set up an Environment and added your secrets, you can connect the Environment to your workflow: 1. Open your Environment, then select **Connect** in the "Custom workflow (OIDC)" section. > [!TIP] > > If you've already connected your Environment to a workflow, select > **Connect** instead, then select **Connect** in the "Custom workflow (OIDC)" section. 2. Enter a name for your workflow, then choose the integration for the OIDC provider you need to use. 3. (Optional) Define any additional access conditions you want to enforce. You'll also see any inherited conditions your administrator configured for the integration. 4. Select **Connect**. ## Step 3: Use your Environment in your workflow After you've connected your Environment to a custom workflow, you'll need to create a [1Password SDK](/sdks) client configured with a custom function to fetch your OIDC token. The client authenticates using your OIDC token, workload ID, and the [integration key configured by your administrator](/brokered-access#custom-workflow-oidc), then uses a function to retrieve secrets from your Environment using the Environment ID. > [!NOTE] > > 1Password Credential Broker is only supported in the [1Password JavaScript SDK](https://github.com/1Password/onepassword-sdk-js) at this time. ## Usage example The following example shows how you can use a 1Password JavaScript SDK client to call a function that fetches your OIDC token, then uses it alongside the other required variables to retrieve secrets from your Environment in a [GitLab CI/CD job.](https://docs.gitlab.com/ci/jobs/) > [tab] 1Password SDK client example > > ```javascript op-client-example.js theme={null} > const sdk = require("@1password/sdk"); > const { spawn } = require("node:child_process"); > > async function fetchOidcToken() { > return process.env.GITLAB_SUBJECT_TOKEN; > } > > function loginToDockerCLI(username, token) { > return new Promise((resolve, reject) => { > const login = spawn( > "docker", > ["login", "--username", username, "--password-stdin"], > { stdio: ["pipe", process.stderr, process.stderr] }, > ); > > login.on("error", reject); > login.on("close", (code) => { > if (code === 0) { > resolve(); > return; > } > reject(new Error(`docker login exited with status ${code}`)); > }); > login.stdin.end(token); > }); > } > > async function loginWithEnvironmentCredentials() { > const client = await sdk.createClient({ > integrationName: "GitLab CI", > integrationVersion: "v1.0.0", > oidcFetcher: fetchOidcToken, > workloadDetails: { > workloadUuid: process.env.OP_WORKLOAD_ID, > // SDK 0.5.0-beta.1 only accepts unpadded integration keys. > customerManagedSecret: process.env.OP_INTEGRATION_KEY.replace(/=+$/, ""), > }, > }); > > const { variables } = await client.environments.getVariables( > process.env.OP_ENVIRONMENT_ID, > ); > const dockerHubUsername = variables.find( > ({ name }) => name === "DOCKERHUB_USERNAME", > ).value; > const dockerHubToken = variables.find( > ({ name }) => name === "DOCKERHUB_TOKEN", > ).value; > > await loginToDockerCLI(dockerHubUsername, dockerHubToken); > process.stdout.write(dockerHubUsername); > } > > loginWithEnvironmentCredentials().catch((error) => { > console.error(error); > process.exitCode = 1; > }); > ``` > [tab] GitLab CI/CD job example > > ```yaml .gitlab-ci.yml theme={null} > build-and-push: > image: docker:27-cli > services: > - docker:27-dind > id_tokens: > GITLAB_SUBJECT_TOKEN: > aud: $OP_OIDC_AUDIENCE > variables: > DOCKER_TLS_CERTDIR: "/certs" > before_script: > - apk add --no-cache nodejs npm > - npm ci > script: > # Authenticate Docker CLI with credentials stored in 1Password environment. > - DOCKERHUB_USERNAME="$(node ./op-client-example.js)" > > # Build and push the Docker image to Docker Hub. > - DOCKER_IMAGE="$DOCKERHUB_USERNAME/$DOCKERHUB_REPOSITORY:$CI_COMMIT_SHA" > - docker build --tag "$DOCKER_IMAGE" . > - docker push "$DOCKER_IMAGE" > ``` ## Get help If you don't see "Custom workflow (OIDC)" as a destination in the 1Password desktop app, make sure your administrator has [connected an OIDC provider to your 1Password account](/brokered-access#custom-workflow-oidc). ## Learn more * [1Password Environments](/environments) * [1Password Credential Broker](/brokered-access) * [1Password SDKs](/sdks) # Use 1Password Credential Broker to access secrets in GitHub Actions at runtime (public preview) Source: https://www.1password.dev/brokered-access/github-actions Learn how to configure GitHub Actions workflows to retrieve secrets from 1Password Environments at runtime. Public Preview If an administrator has [connected your GitHub organization to your 1Password Business account](/brokered-access), you can use 1Password to access secrets from your 1Password Environments in your organization's GitHub Actions workflows at runtime. ## Step 1: Set up an Environment To configure the secrets you need to use in a GitHub Actions workflow, make sure you have the [latest version of the 1Password desktop app](https://support.1password.com/update-1password/), then create a new [1Password Environment](/environments#create-an-environment) with your secrets or [add your secrets](/environments#add-secrets-to-an-environment) to an existing Environment. ## Step 2: Connect your Environment to your GitHub Actions workflow After you've set up an Environment and added your secrets, you can connect the Environment to your GitHub Actions workflow: 1. Open your Environment, then select **Connect** in the GitHub Actions section. > [!TIP] > > If you've already connected your Environment to a workflow, select > **Connect** instead, then select **Connect** in the GitHub Actions section. 2. Select the integration field, then choose the integration for the GitHub organization you need. 3. Enter the name of the repository where your workflow needs to run. 4. (Optional) Specify if you want to restrict access to a specific GitHub Actions workflow, environment, or branch in your repository. 5. Select **Add workflow**. ## Step 3: Modify your GitHub Actions workflow After you've connected your Environment to GitHub Actions, copy the snippet from the 1Password desktop app and include it in a GitHub Actions workflow in order to reference any secrets in your Environment. You can choose from two methods to reference variables in your workflow: * If you include `export-env: "true"` as an [import parameter](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepswith) to the step you copied into your workflow, you can reference the variables with the following structure: `${{ env. }}` * If you add a [unique identifier](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepsid) to the step you copied into your workflow, you can reference the variables with the following structure: `${{ steps..outputs. }}` The specific steps you'll need to follow will vary depending on your workflow setup. Refer to the [GitHub Actions documentation](https://docs.github.com/actions/) for more information on how to use workflows. ## Usage example The following example shows how to use 1Password Credential Broker to load a username and token secret from an Environment, then use them to sign in to Docker Hub. ```yaml config.yml theme={null} on: push name: Deploy app jobs: test: runs-on: ubuntu-latest permissions: id-token: write contents: read steps: - uses: actions/checkout@v3 - name: Load Docker credentials id: load-docker-credentials uses: 1password/load-secrets-action@v5 with: export-env: true env: OP_WORKLOAD_ID: OP_ENVIRONMENT_ID: OP_INTEGRATION_KEY: ${{ secrets.OP_INTEGRATION_KEY }} - name: Login to Docker Hub uses: docker/login-action@v1 with: username: ${{ env.DOCKERHUB_USERNAME }} password: ${{ env.DOCKERHUB_TOKEN }} - name: Build and push Docker image uses: docker/build-push-action@v2 with: push: true tags: acme/app:latest ``` ## Get help If you don't see GitHub Actions as a destination in the 1Password desktop app, make sure your administrator has [connected your GitHub organization to your 1Password account](/brokered-access#github-actions). If you see an OIDC-related error in your workflow log in GitHub, make sure you have `id-token: write` set in the `permissions` [within your workflow.](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#permissions) This permission allows GitHub to generate a short-lived token that 1Password uses to identify your workflow before supplying your secrets at runtime. ## Learn more * [1Password Environments](/environments) * [1Password Credential Broker](/brokered-access) * [Load Secrets from 1Password - GitHub Action](https://github.com/1password/load-secrets-action) # 1Password CI/CD Integrations Source: https://www.1password.dev/ci-cd Load secrets from 1Password into CI/CD pipelines like GitHub Actions, CircleCI, and Jenkins, without plaintext secrets in your code or pipeline config. You can use 1Password integrations to securely access secrets from 1Password in your CI/CD pipeline without exposing any plaintext secrets in code, and rotate secrets without having to update your CI/CD environment. > [card] [Using 1Password across your full deployment stack?](/get-started/developer-quickstart) > > The [secure your deployments workflow guide](/get-started/secure-deployment) covers how to load secrets into CI/CD pipelines, containers, and production applications without exposing any secrets in plaintext. ## Get started Select the CI/CD tool you use to get started. All integrations support authentication with both [1Password Connect Servers](/connect/) and [1Password Service Accounts](/service-accounts/). [CircleCI](/ci-cd/circle-ci/) [GitHub Actions](/ci-cd/github-actions/) [Jenkins](/ci-cd/jenkins/) # Load secrets from 1Password into CircleCI Source: https://www.1password.dev/ci-cd/circle-ci With the [1Password Secrets orb for CircleCI](https://circleci.com/developer/orbs/orb/onepassword/secrets), you can securely load secrets from 1Password into CircleCI CI/CD pipelines using [secret references](/cli/secret-reference-syntax). Secret references sync automatically with 1Password and remove the risk of exposing plaintext secrets in code. [CircleCI orbs](https://circleci.com/docs/orb-intro/) are packages containing YAML configuration files. Using an orb allows you to refer to these configurations with a single line of code. > [!NOTE] > > The [1Password Secrets orb for CircleCI](https://github.com/1password/secrets-orb) is officially supported and maintained by 1Password, but community contributions are welcome. You can use the orb with a [1Password Connect Server](/connect/) or a [1Password Service Account](/service-accounts/). See the video below for a brief introduction to using 1Password Service Accounts with CircleCI and Docker. [Using 1Password Service Accounts with CircleCI and Docker](https://www.youtube.com/embed/xnv5qBjfisU) ## Requirements The requirements for getting started with the 1Password for CircleCI orb vary depending on whether you use a service account or Connect server. > [tab] Service account > > Before you use 1Password for CircleCI with a service account, you need to: > > * [Sign up for 1Password.](https://1password.com/pricing/password-manager) > * [Create a service account.](/service-accounts/) > * Create a [CircleCI](https://circleci.com/) account. > [tab] Connect > > Before you use 1Password for CircleCI with a Connect server, you need to: > > * [Sign up for 1Password.](https://1password.com/pricing/password-manager) > * [Create and deploy a Connect server.](/connect/get-started/#step-1) > * Create a [CircleCI](https://circleci.com/) account. > [!WARNING] > > Connect credentials take precedence over service account credentials. > > If you've set the `OP_CONNECT_HOST` or `OP_CONNECT_TOKEN` environment variables alongside `OP_SERVICE_ACCOUNT_TOKEN`, the Connect credentials take precedence over the provided service account token. You must unset the Connect environment variables to make sure the action uses the service account token. ## Get started > [tab] Service account > > 1. Set the service account token environment variable in CircleCI. > > On the [CircleCI settings page](https://circleci.com/docs/introduction-to-the-circleci-web-app/#project-settings), set the `OP_SERVICE_ACCOUNT_TOKEN` environment variable to token of the service account to use to load secrets. > > 2. Edit the CircleCI configuration file and make the following updates: > > * Update the [CircleCI `config.yml` file](https://circleci.com/docs/config-intro/) to use the 1Password for CircleCI orb. > > * Specify the version number or use `volatile` to use the latest version number. > > Add the `onepassword/secrets` orb to your `config.yml` file. > > ```yaml config.yml theme={null} > orbs: > 1password: onepassword/secrets@1.0.0 > ``` > > To use the *latest* version of 1Password Secrets orb in your project, set `volatile` as the version number. > > ```yaml config.yml theme={null} > orbs: > 1password: onepassword/secrets@volatile > ``` > > 3. Install 1Password CLI version **2.18.0 or later** as the first step of a CircleCI job using the `1password/install-cli` [command](#commands). You must install the CLI in the pipeline for the 1Password CircleCI orb to function. Earlier versions of 1Password CLI don't support service accounts. > > Find the latest version number in the [1Password CLI release notes](https://releases.1password.com/developers/cli/). > > ```yaml config.yml theme={null} > steps: > - 1password/install-cli: > version: 2.x.x > ``` > > 4. Use 1Password CLI commands in subsequent steps in the pipeline. > > See the following example `config.yml` files. Make sure to update `2.x.x` to [1Password CLI version 2.18.0 or later](https://releases.1password.com/developers/cli/). > > > [tab] Example 1 > > > > ```yaml config.yml theme={null} > > version: 2.1 > > orbs: > > 1password: onepassword/secrets@1.0.0 > > jobs: > > deploy: > > machine: > > image: ubuntu-2204:current > > steps: > > - 1password/install-cli: > > version: 2.x.x > > - checkout > > - run: > > shell: op run -- /bin/bash > > environment: > > AWS_ACCESS_KEY_ID: op://company/app/aws/access_key_id > > AWS_SECRET_ACCESS_KEY: op://company/app/aws/secret_access_key > > command: | > > echo "This value will be masked: $AWS_ACCESS_KEY_ID" > > echo "This value will be masked: $AWS_SECRET_ACCESS_KEY" > > ./deploy-my-app.sh > > workflows: > > deploy: > > jobs: > > - deploy > > ``` > > > [tab] Example 2 > > > > ```yaml config.yml theme={null} > > 'og:description': Install 1Password CLI within a job and make it useable for all the commands following the installation. > > usage: > > version: 2.1 > > orbs: > > 1password: onepassword/secrets@1.0.0 > > jobs: > > deploy: > > machine: > > image: ubuntu-2204:current > > steps: > > - 1password/install-cli: > > version: 2.x.x > > - checkout > > - run: | > > docker login -u $(op read op://company/docker/username) -p $(op read op://company/docker/password) > > docker build -t company/app:${CIRCLE_SHA1:0:7} . > > docker push company/app:${CIRCLE_SHA1:0:7} > > workflows: > > deploy: > > jobs: > > - deploy > > ``` > [tab] Connect > > 1. Set the Connect server environment variables in CircleCI. > > On the [CircleCI settings page](https://circleci.com/docs/introduction-to-the-circleci-web-app/#project-settings), set the `OP_CONNECT_HOST` and `OP_CONNECT_TOKEN` environment variables for the Connect server to use to load secrets: > > * Set `OP_CONNECT_TOKEN` to the Connect server token. > > * Set `OP_CONNECT_HOST` to the Connect server hostname or IP address. > > 2. Edit the CircleCI configuration file. > > Update the [CircleCI `config.yml` file](https://circleci.com/docs/config-intro/) to use the 1Password for CircleCI orb. Make sure to specify the version number or use `volatile` to use the latest version number. > > Add the `onepassword/secrets` orb to your `config.yml` file. > > ```yaml config.yml theme={null} > orbs: > 1password: onepassword/secrets@1.0.0 > ``` > > To use the *latest* version of 1Password Secrets orb in your project, set `volatile` as the version number. > > ```yaml config.yml theme={null} > orbs: > 1password: onepassword/secrets@volatile > ``` > > 3. Install 1Password CLI. > > You must install [1Password CLI](/cli/) in the pipeline for the 1Password CircleCI orb to function: > > * Install the CLI as the first step of a CircleCI job using the `1password/install-cli` [command](#commands). > * Use 1Password CLI commands in subsequent steps in the pipeline. > > See the following example `config.yml` files. > > > [tab] Example 1 > > > > ```yaml config.yml theme={null} > > version: 2.1 > > orbs: > > 1password: onepassword/secrets@1.0.0 > > jobs: > > deploy: > > machine: > > image: ubuntu-2204:current > > steps: > > - 1password/install-cli > > - checkout > > - run: > > shell: op run -- /bin/bash > > environment: > > AWS_ACCESS_KEY_ID: op://company/app/aws/access_key_id > > AWS_SECRET_ACCESS_KEY: op://company/app/aws/secret_access_key > > command: | > > echo "This value will be masked: $AWS_ACCESS_KEY_ID" > > echo "This value will be masked: $AWS_SECRET_ACCESS_KEY" > > ./deploy-my-app.sh > > workflows: > > deploy: > > jobs: > > - deploy > > ``` > > > [tab] Example 2 > > > > ```yaml config.yml theme={null} > > 'og:description': Install 1Password CLI within a job and make it useable for all the commands following the installation. > > usage: > > version: 2.1 > > orbs: > > 1password: onepassword/secrets@1.0.0 > > jobs: > > deploy: > > machine: > > image: ubuntu-2204:current > > steps: > > - 1password/install-cli > > - checkout > > - run: | > > docker login -u $(op read op://company/docker/username) -p $(op read op://company/docker/password) > > docker build -t company/app:${CIRCLE_SHA1:0:7} . > > docker push company/app:${CIRCLE_SHA1:0:7} > > workflows: > > deploy: > > jobs: > > - deploy > > ``` ## Reference The following sections document the 1Password for CircleCI orb [commands](#commands) and the [secret reference syntax](#secret-reference-syntax). ### Commands There are three commands to use when you configure your orb: `1password/install-cli`, `1password/exec`, and `1password/export`. > [!WARNING] > > Only some commands mask secrets. > > Both the `1password/exec` orb command and the [`op run`](/cli/reference/commands/run/) shell wrapper automatically mask secrets from the CircleCI log output. If secrets accidentally get logged, 1Password replaces them with ``. The `1password/export` command doesn't mask secrets. | Command | Description | Masks secrets | | - | - | - | | `1password/install-cli` | Installs 1Password CLI. You must use this command as a step to use 1Password CLI commands in subsequent steps. | N/A | | `1password/exec` | Loads secrets on demand and executes the commands requiring secrets. See [loading secrets with the `exec` command](#load-exec). | Yes | | `1password/export` | Loads secrets with references exported in the environment and makes them available to subsequent steps of the job. See [loading secrets with the `export` command](#load-export). | No | ### Secret reference syntax You can make secrets available to CircleCI jobs and steps by including references to them in the environment using secret references. Secret reference URIs point to where a secret is saved in your 1Password account using the names (or [unique identifiers](/cli/reference/#unique-identifiers-ids)) of the vault, item, section, and field where the information is stored. ```shell theme={null} op://vault-name/item-name/[section-name/]field-name ``` Visit the [secret reference syntax](/cli/secret-reference-syntax/) documentation to access examples and learn more about referencing secrets. ## Usage examples Explore the following sections to learn about specific use case examples for the 1Password CircleCI orb. * [Load secrets with `exec`](#load-exec) * [Load secrets with `export`](#load-export) ### Load secrets with the `exec` command To load secrets with the `1password/exec` command: 1. Install 1Password CLI with `1password/install-cli`. If you're using a service account, make sure to set the [1Password CLI version](https://releases.1password.com/developers/cli/) to `2.18.0` or later. 2. Use the `1password/exec` command to load secrets on demand and execute commands that require secrets. After you add the `1password/exec` command as a step in your job, subsequent steps of the job can access secrets. The following example shows how to use the `1password/exec` command to resolve variables at the job level. The `exec` command automatically masks any secrets or sensitive values that might be accidentally logged. ```yaml config.yml theme={null} version: 2.1 orbs: 1password: onepassword/secrets@1.0.0 jobs: deploy: machine: image: ubuntu-2204:current environment: AWS_ACCESS_KEY_ID: op://company/app/aws/access_key_id AWS_SECRET_ACCESS_KEY: op://company/app/aws/secret_access_key steps: - checkout - 1password/install-cli: version: 2.x.x - 1password/exec: command: | echo "This value will be masked: $AWS_ACCESS_KEY_ID" echo "This value will be masked: $AWS_SECRET_ACCESS_KEY" ./deploy-my-app.sh workflows: deploy: jobs: - deploy ``` ### Load secrets with the `export` command To load secrets with the `1password/export` command: 1. Install 1Password CLI with `1password/install-cli`. If you're using a service account, make sure to set the [1Password CLI version](https://releases.1password.com/developers/cli/) to `2.18.0` or later. 2. Use the `1password/export` command to load the [secret references](#secret-reference-syntax) exported in the environment. 3. Access secrets in subsequent steps of the job. The following example shows how to use the `1password/export` command to resolve variables at the job level. ```yaml config.yml theme={null} version: 2.1 orbs: 1password: onepassword/secrets@1.0.0 jobs: deploy: machine: image: ubuntu-2204:current steps: - checkout - 1password/install-cli version: 2.x.x - 1password/export: var-name: AWS_ACCESS_KEY_ID secret-reference: op://company/app/aws/access_key_id - 1password/export: var-name: AWS_SECRET_ACCESS_KEY secret-reference: op://company/app/aws/secret_access_key - run: command: | echo "This value will not be masked: $AWS_ACCESS_KEY_ID" echo "This value will not be masked: $AWS_SECRET_ACCESS_KEY" ./deploy-my-app.sh workflows: deploy: jobs: - deploy ``` # Load secrets from 1Password into GitHub Actions Source: https://www.1password.dev/ci-cd/github-actions With the [Load secrets from 1Password GitHub Action](https://github.com/marketplace/actions/load-secrets-from-1password), you can securely load secrets from 1Password into GitHub Actions using [secret references](/cli/secret-reference-syntax). Secret references sync automatically with 1Password and remove the risk of exposing plaintext secrets in code. You can authenticate `load-secrets-action` with a [1Password Connect Server](/connect/) or a [1Password Service Account](/service-accounts/). See the video below for a brief introduction to using the GitHub Action with a service account. [Using 1Password Service Accounts with GitHub actions](https://www.youtube.com/embed/kVBl5iQYgSA) > [!NOTE] > > Similar to regular [GitHub repository secrets](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions), 1Password automatically masks sensitive fields that appear in GitHub Actions logs. If one of these values accidentally gets printed, it's replaced with `***`. ## Requirements You can configure the action to authenticate to 1Password with either a [service account](/service-accounts/) or a [Connect server](/connect/). > [tab] Service account > > Before using the [Load secrets from 1Password GitHub Action](https://github.com/marketplace/actions/load-secrets-from-1password) with a service account, you must: > > * [Sign up for 1Password.](https://1password.com/pricing/password-manager) > * [Create a service account.](/service-accounts/) > * Have the service account token on hand. > [tab] Connect > > Before using the [Load secrets from 1Password GitHub Action](https://github.com/marketplace/actions/load-secrets-from-1password) with a Connect server, you must: > > * [Sign up for 1Password.](https://1password.com/pricing/password-manager) > * [Create and deploy a Connect server](/connect/get-started/#step-1) in your infrastructure. > * Have the Connect server hostname and Connect server token on hand. ## Get started The steps to get started vary depending on whether you use a service account or a Connect server. > [tab] Service account > > 1. Add the [Load secrets from 1Password GitHub Action](https://github.com/marketplace/actions/load-secrets-from-1password) to your workflow. > > See [Adding an action to your workflow.](https://docs.github.com/en/actions/learn-github-actions/finding-and-customizing-actions#adding-an-action-to-your-workflow) > > 2. Add the service account token to your workflow. > > Create a secret for your GitHub repository named `OP_SERVICE_ACCOUNT_TOKEN` and set it to the service account token value. > > Visit [Using secrets in GitHub Actions](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions) to learn how. > > 3. Configure your workflow. > > Use the `1password/load-secrets-action/configure` action to specify the token of the service account you plan to get secrets from. > > The following example uses the `configure` command to set the `service-account-token` to the `OP_SERVICE_ACCOUNT_TOKEN` secret. > > ```yaml config.yml theme={null} > uses: 1password/load-secrets-action/configure@v4 > with: > service-account-token: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }} > ``` > > > [!TIP] > > > > Setting the `service-account-token` in the `configure` step makes the value available to all subsequent steps. You can limit step access to the service account token by only using the service account token in specific steps. > > > > To use the service account token in a specific step, set it in the `env` variables for that step. > > > > ```yaml config.yml theme={null} > > env: > > OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }} > > ``` > > 4. Load a secret. > > Use the `1password/load-secrets-action` action to set an environment variable to a [secret reference URI](#secret-reference-syntax) that points to where a secret is stored in your 1Password account. > > The following example sets the `SECRET` environment variable to the value of a field titled `secret` within an item titled `hello-world` saved in a vault titled `app-cicd`. > > ```yaml config.yml theme={null} > uses: 1password/load-secrets-action@v4 > env: > SECRET: op://app-cicd/hello-world/secret > ``` > > The action makes the referenced secret available as the `SECRET` environment variable for the next steps. > [tab] Connect > > 1. Add the [Load secrets from 1Password GitHub Action](https://github.com/marketplace/actions/load-secrets-from-1password) (`load-secrets-action`) to your workflow. > > See [Adding an action to your workflow.](https://docs.github.com/en/actions/learn-github-actions/finding-and-customizing-actions#adding-an-action-to-your-workflow) > > 2. Add the Connect server token to your workflow. > > Create a secret named `OP_CONNECT_TOKEN` in your repository and set it to the Connect server token value. > > Visit [Using secrets in GitHub Actions](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions) to learn how. > > 3. Configure your workflow. > > Use the `1password/load-secrets-action/configure` action to specify the Connect server environment variable. > > The following example uses the configure command to: > > * Set the `connect-host` to the Connect server hostname (`OP_CONNECT_HOST`). > > * Set the `connect-token` to the `OP_CONNECT_TOKEN` secret.\ > \\ > > ```yaml config.yml theme={null} > uses: 1password/load-secrets-action/configure@v4 > with: > connect-host: OP_CONNECT_HOST > connect-token: ${{ secrets.OP_CONNECT_TOKEN }} > ``` > > > [!TIP] > > > > Setting the `connect-token` in the configure step makes the value available to all subsequent steps. You can limit step access to the service account token by only using the service account token in specific steps. > > > > To use the service account token in a specific step, set it in the `env` variables for that step. > > > > ```yaml config.yml theme={null} > > env: > > OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }} > > ``` > > 4. Load a secret. > > Use the `1password/load-secrets-action` action to set an environment variable to a [secret reference URI](#secret-reference-syntax) that points to where a secret is stored in your 1Password account. > > The following example sets the `SECRET` environment variable to the value of a field titled `secret` within an item titled `hello-world` saved in a vault titled `app-cicd`. > > ```yaml config.yml theme={null} > uses: 1password/load-secrets-action@v4 > env: > SECRET: op://app-cicd/hello-world/secret > ``` > > The action makes the referenced secret available as the `SECRET` environment variable for the next steps. ## Reference The following sections document the [action inputs](#action-inputs) and [secret reference syntax](#secret-reference-syntax) for the [Load secrets from 1Password GitHub Action.](https://github.com/marketplace/actions/load-secrets-from-1password) ### Action inputs The following table contains the available `configure` action inputs. | Action input | Environment variable | Description | | - | - | - | | `connect-host` | `OP_CONNECT_HOST` | The Connect server, hostname, IP address, or instance URL. | | `connect-token` | `OP_CONNECT_TOKEN` | The Connect server token. | | `service-account-token` | `OP_SERVICE_ACCOUNT_TOKEN` | The service account token. | ### Secret reference syntax Secret reference URIs point to where a secret is saved in your 1Password account using the names (or [unique identifiers](/cli/reference/#unique-identifiers-ids)) of the vault, item, section, and field where the information is stored. ```shell theme={null} op://vault-name/item-name/[section-name/]field-name ``` Set an environment variable to a secret reference in your workflow YAML file, and the action will make the referenced secret available as the environment variable for the next steps. #### Example The following example shows how to reference the `secret-access-key` field of the `aws` item in the `app-cicd` vault. ```yaml config.yml theme={null} - name: Load secret uses: 1password/load-secrets-action@v4 env: SECRET: op://app-cicd/aws/secret-access-key ``` * **Vault:** `app-cicd` * **Item:** `aws` * **Field:** `secret-access-key` ## Usage examples You can load secrets using the action in two ways: 1. [Use secrets from the action's output](#use-secrets-from-the-actions-output) 2. [Export secrets as environment variables](#export-secrets-as-environment-variables) ### Use secrets from the action's output You can use the [Load secrets from 1Password GitHub Action](https://github.com/marketplace/actions/load-secrets-from-1password) to access secrets as environment variables. > [tab] Service account > > The following examples show how to load a secret from a service account and print the output when a `push` event occurs. > > You need to set an ID for the step to access its outputs. See [`outputs.`.](https://docs.github.com/actions/creating-actions/metadata-syntax-for-github-actions#outputsoutput_id) > > > [tab] Simple example > > > > The following example shows how to use a service account to load (and print) a secret (as the `SECRET` env variable) from 1Password. When you print a secret, 1Password automatically replaces it with `***`. > > > > ```yaml config.yml theme={null} > > on: push > > jobs: > > hello-world: > > runs-on: ubuntu-latest > > steps: > > - uses: actions/checkout@v3 > > > > - name: Load secret > > id: op-load-secret > > uses: 1password/load-secrets-action@v4 > > with: > > export-env: false > > env: > > OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }} > > SECRET: op://app-cicd/hello-world/secret > > > > - name: Print masked secret > > run: 'echo "Secret: ${{ steps.op-load-secret.outputs.SECRET }}"' > > # Prints: Secret: *** > > ``` > > > [tab] Advanced example > > > > The following example shows how to use a service account to load the `username` and `token` fields from the `docker` secret in 1Password (as `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN`), then use them to log into Docker Hub. > > > > ```yaml config.yml theme={null} > > on: push > > name: Deploy app > > > > jobs: > > test: > > runs-on: ubuntu-latest > > steps: > > - uses: actions/checkout@v3 > > > > - name: Configure 1Password Service Account > > uses: 1password/load-secrets-action/configure@v4 > > with: > > # Persist the 1Password Service Account Authorization token > > # for next steps. > > # Keep in mind that every single step in the job is now > > # able to access the token. > > service-account-token: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }} > > > > - name: Load Docker credentials > > id: load-docker-credentials > > uses: 1password/load-secrets-action@v4 > > with: > > export-env: false > > env: > > DOCKERHUB_USERNAME: op://app-cicd/docker/username > > DOCKERHUB_TOKEN: op://app-cicd/docker/token > > > > - name: Login to Docker Hub > > uses: docker/login-action@v1 > > with: > > username: ${{ steps.load-docker-credentials.outputs.DOCKERHUB_USERNAME }} > > password: ${{ steps.load-docker-credentials.outputs.DOCKERHUB_TOKEN }} > > > > - name: Build and push Docker image > > uses: docker/build-push-action@v2 > > with: > > push: true > > tags: acme/app:latest > > ``` > [tab] Connect > > The following examples show how to load a secret from a Connect server and print the output when a `push` event occurs. > > > [tab] Simple example > > > > The following example shows how to use a Connect server to load (and print) a secret (as the `SECRET` env variable) from 1Password. When you print a secret, 1Password automatically replaces it with `***`. > > > > ```yaml config.yml theme={null} > > on: push > > jobs: > > hello-world: > > runs-on: ubuntu-latest > > steps: > > - uses: actions/checkout@v3 > > > > - name: Load secret > > id: op-load-secret > > uses: 1password/load-secrets-action@v4 > > with: > > export-env: false > > env: > > OP_CONNECT_HOST: connect-host > > OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }} > > SECRET: op://app-cicd/hello-world/secret > > > > - name: Print masked secret > > run: 'echo "Secret: ${{ steps.op-load-secret.outputs.SECRET }}"' > > # Prints: Secret: *** > > ``` > > > [tab] Advanced example > > > > The following example shows how to use a Connect server to load the `username` and `token` fields from the `docker` secret in 1Password (as `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN`), then use them to log into Docker Hub. > > > > ```yaml config.yml theme={null} > > on: push > > name: Deploy app > > > > jobs: > > test: > > runs-on: ubuntu-latest > > steps: > > - uses: actions/checkout@v3 > > > > - name: Configure 1Password Connect > > uses: 1password/load-secrets-action/configure@v4 > > with: > > # Persist the 1Password Connect URL for next steps. You can also persist > > # the Connect token using input `connect-token`, but keep in mind that > > # every single step in the job would then be able to access the token. > > connect-host: OP_CONNECT_HOST > > - name: Load Docker credentials > > id: load-docker-credentials > > uses: 1password/load-secrets-action@v4 > > with: > > export-env: false > > env: > > OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }} > > DOCKERHUB_USERNAME: op://app-cicd/docker/username > > DOCKERHUB_TOKEN: op://app-cicd/docker/token > > > > - name: Login to Docker Hub > > uses: docker/login-action@v1 > > with: > > username: ${{ steps.load-docker-credentials.outputs.DOCKERHUB_USERNAME }} > > password: ${{ steps.load-docker-credentials.outputs.DOCKERHUB_TOKEN }} > > > > - name: Build and push Docker image > > uses: docker/build-push-action@v2 > > with: > > push: true > > tags: acme/app:latest > > ``` ### Export secrets as environment variables You can use the [Load secrets from 1Password GitHub Action](https://github.com/marketplace/actions/load-secrets-from-1password) to use loaded secret outputted from the `steps.step-id.outputs.secret-name`. > [tab] Service account > > The following examples show how to use a service account to load a 1Password secret as an environment variable. > > > [tab] Simple example > > > > The following example shows how to use a service account to load a secret as an environment variable named `SECRET`. When you print a secret, 1Password automatically replaces it with `***`. > > > > ```yaml config.yml theme={null} > > on: push > > jobs: > > hello-world: > > runs-on: ubuntu-latest > > steps: > > - uses: actions/checkout@v3 > > > > - name: Load secret > > uses: 1password/load-secrets-action@v4 > > with: > > # Export loaded secrets as environment variables > > export-env: true > > env: > > OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }} > > SECRET: op://app-cicd/hello-world/secret > > > > - name: Print masked secret > > run: 'echo "Secret: $SECRET"' > > # Prints: Secret: *** > > ``` > > > [tab] Advanced example > > > > The following example shows how to use a service account to load the `username` and `token` fields from the `docker` secret in 1Password as environment variables named `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN`, then uses them to log into Docker Hub. > > > > It also loads the `access-key-id` and `secret-access-key` fields from the `aws` secret in 1Password as environment variables named `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`, then uses them to deploy to AWS. > > > > ```yaml config.yml theme={null} > > on: push > > name: Deploy app > > > > jobs: > > test: > > runs-on: ubuntu-latest > > steps: > > - uses: actions/checkout@v3 > > > > - name: Configure 1Password Service Account > > uses: 1password/load-secrets-action/configure@v4 > > with: > > # Persist the 1Password Service Account Authorization token > > # for next steps. > > # Keep in mind that every single step in the job is now able > > # to access the token. > > service-account-token: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }} > > > > - name: Load Docker credentials > > uses: 1password/load-secrets-action@v4 > > with: > > # Export loaded secrets as environment variables > > export-env: true > > env: > > DOCKERHUB_USERNAME: op://app-cicd/docker/username > > DOCKERHUB_TOKEN: op://app-cicd/docker/token > > > > - name: Login to Docker Hub > > uses: docker/login-action@v1 > > with: > > username: ${{ env.DOCKERHUB_USERNAME }} > > password: ${{ env.DOCKERHUB_TOKEN }} > > > > - name: Print environment variables with masked secrets > > run: printenv > > > > - name: Build and push Docker image > > uses: docker/build-push-action@v2 > > with: > > push: true > > tags: acme/app:latest > > > > - name: Load AWS credentials > > uses: 1password/load-secrets-action@v4 > > with: > > # Export loaded secrets as environment variables > > export-env: true > > # Remove local copies of the Docker credentials, which are not needed anymore > > unset-previous: true > > env: > > AWS_ACCESS_KEY_ID: op://app-cicd/aws/access-key-id > > AWS_SECRET_ACCESS_KEY: op://app-cicd/aws/secret-access-key > > > > - name: Deploy app > > # This script expects AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY to be set, which was > > # done automatically by the step above > > run: ./deploy.sh > > ``` > [tab] Connect > > The folowing examples show how to use a Connect server to load a secret from 1Password as an environment variable. > > > [tab] Simple example > > > > The following example shows how to use a Connect server to load a secret as an environment variable named `SECRET`. When you print a secret, 1Password automatically replaces it with `***`. > > > > ```yaml config.yml theme={null} > > on: push > > jobs: > > hello-world: > > runs-on: ubuntu-latest > > steps: > > - uses: actions/checkout@v3 > > > > - name: Load secret > > uses: 1password/load-secrets-action@v4 > > with: > > # Export loaded secrets as environment variables > > export-env: true > > env: > > OP_CONNECT_HOST: connect-host > > OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }} > > SECRET: op://app-cicd/hello-world/secret > > > > - name: Print masked secret > > run: 'echo "Secret: $SECRET"' > > # Prints: Secret: *** > > ``` > > > [tab] Advanced example > > > > The following example shows how to use a Connect server to load the `username` and `token` fields from the `docker` secret in 1Password as environment variables named `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN`, then uses them to log into Docker Hub. > > > > It also loads the `access-key-id` and `secret-access-key` fields from the `aws` secret in 1Password as environment variables named `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`, then uses them to deploy to AWS. > > > > ```yaml config.yml theme={null} > > on: push > > name: Deploy app > > > > jobs: > > test: > > runs-on: ubuntu-latest > > steps: > > - uses: actions/checkout@v3 > > > > - name: Configure 1Password Connect > > uses: 1password/load-secrets-action/configure@v4 > > with: > > # Persist the 1Password Connect hostname for next steps. > > # You can also persist the Connect token using input > > # `connect-token`, but keep in mind that every single > > # step in the job would then be able to access the token. > > connect-host: OP_CONNECT_HOST > > > > - name: Load Docker credentials > > uses: 1password/load-secrets-action@v4 > > with: > > # Export loaded secrets as environment variables > > export-env: true > > env: > > OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }} > > DOCKERHUB_USERNAME: op://app-cicd/docker/username > > DOCKERHUB_TOKEN: op://app-cicd/docker/token > > > > - name: Login to Docker Hub > > uses: docker/login-action@v1 > > with: > > username: ${{ env.DOCKERHUB_USERNAME }} > > password: ${{ env.DOCKERHUB_TOKEN }} > > > > - name: Print environment variables with masked secrets > > run: printenv > > > > - name: Build and push Docker image > > uses: docker/build-push-action@v2 > > with: > > push: true > > tags: acme/app:latest > > > > - name: Load AWS credentials > > uses: 1password/load-secrets-action@v4 > > with: > > # Export loaded secrets as environment variables > > export-env: true > > # Remove local copies of the Docker credentials, which are not needed anymore > > unset-previous: true > > env: > > OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }} > > AWS_ACCESS_KEY_ID: op://app-cicd/aws/access-key-id > > AWS_SECRET_ACCESS_KEY: op://app-cicd/aws/secret-access-key > > > > - name: Deploy app > > # This script expects AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY to be set, which was > > # done automatically by the step above > > run: ./deploy.sh > > ``` ## Troubleshooting If you try to create items using 1Password CLI in your GitHub pipelines (without using `load-secrets-action`), the command fails with the following error: ```text theme={null} Failed to create item: invalid JSON ``` For example, the following results in an error: ```shell theme={null} op item create --category=login --title='My Example Item' --vault='Test' \ --url https://www.acme.com/login \ --generate-password=20,letters,digits \ username=jane@acme.com \ 'Test Field 1=my test secret' \ 'Test Section 1.Test Field2[text]=Jane Doe' \ 'Test Section 1.Test Field3[date]=1995-02-23' \ 'Test Section 2.Test Field4[text]='$myNotes ``` The pipeline environment is in piped mode. This triggers the CLI's pipe detection, which expects a piped input. To create items in this environment, use a [JSON template](/cli/item-template-json/) with your item details. 1. Get the template for the category of item you want to create: ```shell theme={null} op item template get --out-file=new-item.json ``` 2. Edit [the template](/cli/item-template-json/) to add your information. 3. Pipe the item content to the command: ```shell theme={null} cat new-item.json | op item create --vault ``` # Load secrets from 1Password into Jenkins Source: https://www.1password.dev/ci-cd/jenkins With the [1Password Secrets plugin for Jenkins](https://plugins.jenkins.io/onepassword-secrets/), you can securely load secrets from 1Password as environment variables in a Jenkins CI/CD pipeline using [secret references](/cli/secret-reference-syntax/). Secret references sync automatically with 1Password and remove the risk of exposing plaintext secrets in code. You can authenticate the plugin with a [1Password Service Account](/service-accounts/) or a [1Password Connect Server](/connect/). > [!NOTE] > > The 1Password Jenkins plugin is officially supported and maintained by 1Password. Community contributions are welcome. [View the repository on GitHub.](https://github.com/jenkinsci/onepassword-secrets-plugin) ## Requirements You can use the 1Password Secrets plugin for Jenkins with either a [service account](/service-accounts/get-started/) or a [Connect server](/connect/get-started/#step-1). If you configure both a service account and a Connect server, the Connect server takes precedence. > [tab] Service account > > * [Sign up for 1Password.](https://1password.com/pricing/password-manager) > * [Create a service account.](/service-accounts/get-started/) > * [Have a Jenkins instance up and running.](https://www.jenkins.io/doc/) > [tab] Connect server > > * [Sign up for 1Password.](https://1password.com/pricing/password-manager) > * [Create and deploy a Connect server](/connect/get-started/#step-1). > * [Have a Jenkins instance up and running.](https://www.jenkins.io/doc/) ## Get started To get started with the 1Password Secrets plugin for Jenkins: 1. [Install the 1Password Secrets plugin for Jenkins.](#install-plugin) 2. [Install 1Password CLI.](#step-2-install-1password-cli) 3. [Configure the 1Password Secrets plugin for Jenkins.](#configure-plugin) ### Step 1: Install the 1Password Secrets plugin for Jenkins You have several available options to install the 1Password Secrets plugin for Jenkins. You can use the Jenkins GUI (graphical user interface), the Jenkins CLI tool, or a direct upload. > [tab] Jenkins GUI > > To install the 1Password Secrets plugin for Jenkins using the GUI: > > 1. Sign in to your Jenkins instance. > 2. From your Jenkins dashboard, go to **Manage Jenkins** > **Plugins**. > 3. Select the **Available plugins** tab. > 4. Search for *onepassword-secrets*. > 5. Select the 1Password Secrets plugin for Jenkins, then select **Install**. > > Refer to [Use the GUI](https://www.jenkins.io/doc/book/managing/plugins/#from-the-web-ui) for more detailed instructions. > [tab] Jenkins CLI tool > > To install the 1Password Secrets plugin for Jenkins using the CLI tool: > > 1. Follow the [Use the CLI tool](https://github.com/jenkinsci/plugin-installation-manager-tool) instructions. > 2. Run the following command. Make sure to replace `1.0.0` with the correct version. > > ```sh theme={null} > jenkins-plugin-cli --plugins onepassword-secrets:1.0.0 > ``` > [tab] Direct upload > > To install the 1Password Secrets plugin for Jenkins using a direct upload: > > 1. Download one of the [releases.](https://plugins.jenkins.io/onepassword-secrets/#releases) > 2. From your Jenkins dashboard, go to **Manage Jenkins** > **Plugins**. > 3. Select the **Advanced** tab. > 4. Select the `.hpi` file you downloaded from the release. > 5. Select **Deploy**. > > Refer to [Use direct upload](https://www.jenkins.io/doc/book/managing/plugins/#advanced-installation) for more detailed instructions. ### Step 2: Install 1Password CLI The 1Password Secrets plugin for Jenkins relies on 1Password CLI. You must install 1Password CLI on the same machine that runs the Jenkins CI/CD pipeline. You can install 1Password CLI using a [Jenkinsfile](https://www.jenkins.io/doc/book/pipeline/jenkinsfile/) or using a Freestyle job. Either of these methods can install 1Password CLI in the same pipeline as the 1Password Secrets plugin for Jenkins or in a separate pipeline. > [!NOTE] > > If you install 1Password CLI in the same pipeline, you will need to add the 1Password CLI installation script before you make any calls to the plugin. > > If you install 1Password CLI in a separate pipeline, you will need to set the **1Password CLI path** to the workspace where you performed the installation in your [configuration](#configuration). > [tab] Jenkinsfile > > To install 1Password CLI using a Jenkinsfile: > > 1. Sign in to your Jenkins instance. > > 2. Select **New Item**. > > 3. Enter the job details, then select **Pipeline**. > > 4. Configure the job details. > > 5. Scroll to **Advanced Project Options** > **Pipeline**. > > 6. Select **Pipeline script**. > > 7. Add the code to install 1Password CLI to the **Script** field. > > You can install 1Password CLI with a Jenkinsfile using declarative or scripted [Jenkins pipeline syntax.](https://www.jenkins.io/doc/book/pipeline/syntax/) > > > [!NOTE] > > > > The following examples show how to install 1Password CLI version 2.24 on a Linux amd64 machine. Make sure to change the example scripts to match your platform and use the [latest release of 1Password CLI](https://app-updates.agilebits.com/product_history/CLI2). > > > [tab] Declarative Jenkinsfile > > > > ```groovy Declarative Jenkinsfile theme={null} > > pipeline { > > agent any > > stages { > > stage('Install 1Password CLI') { > > steps { > > sh 'curl -sSfLo op.zip "https://cache.agilebits.com/dist/1P/op2/pkg/v2.24.0/op_linux_amd64_v2.24.0.zip"' > > sh 'unzip -o op.zip -d op-dir' > > sh 'mv -f op-dir/op /usr/local/bin' > > sh 'rm -r op.zip op-dir' > > } > > } > > } > > } > > # code-result > > [Pipeline] Start of Pipeline > > [Pipeline] node > > Running on Jenkins in /config/workspace/Example > > [Pipeline] { > > [Pipeline] stage > > [Pipeline] { (Install 1Password CLI) > > [Pipeline] sh > > + curl -sSfLo op.zip https://cache.agilebits.com/dist/1P/op2/pkg/v2.24.0/op_linux_amd64_v2.24.0.zip > > [Pipeline] sh > > + unzip -o op.zip -d op-dir > > Archive: op.zip > > extracting: op-dir/op.sig > > inflating: op-dir/op > > [Pipeline] sh > > + mv -f op-dir/op /usr/local/bin > > [Pipeline] sh > > + rm -r op.zip op-dir > > [Pipeline] } > > [Pipeline] // stage > > [Pipeline] } > > [Pipeline] // node > > [Pipeline] End of Pipeline > > Finished: SUCCESS > > ``` > > > [tab] Scripted Jenkinsfile > > > > ```groovy Scripted Jenkinsfile theme={null} > > node { > > stage('Install 1Password CLI') { > > sh ''' > > ARCH="amd64" > > curl -sSfLo op.zip "https://cache.agilebits.com/dist/1P/op2/pkg/v2.24.0/op_linux_${ARCH}_v2.24.0.zip" > > unzip -o op.zip -d op-dir > > mv -f op-dir/op /usr/local/bin > > rm -r op.zip op-dir > > ''' > > } > > } > > # code-result > > [Pipeline] Start of Pipeline > > [Pipeline] node > > Running on Jenkins in /config/workspace/Test 1Password Secrets > > [Pipeline] { > > [Pipeline] stage > > [Pipeline] { (Install 1Password CLI) > > [Pipeline] sh > > + ARCH=amd64 > > + curl -sSfLo op.zip https://cache.agilebits.com/dist/1P/op2/pkg/v2.24.0/op_linux_amd64_v2.24.0.zip > > + unzip -o op.zip -d op-dir > > Archive: op.zip > > extracting: op-dir/op.sig > > inflating: op-dir/op > > + mv -f op-dir/op /usr/local/bin > > + rm -r op.zip op-dir > > [Pipeline] } > > [Pipeline] // stage > > [Pipeline] } > > [Pipeline] // node > > [Pipeline] End of Pipeline > > Finished: SUCCESS > > ``` > > 8. Save the build. > [tab] Freestyle job > > > [!WARNING] > > > > Freestyle jobs don't let you set both the configuration and secrets at the job level. 1Password recommends using a Jenkinsfile rather than a Freestyle job. See [Migrating from chained Freestyle jobs to Pipelines.](https://www.jenkins.io/blog/2016/06/29/from-freestyle-to-pipeline/) > > To install 1Password CLI using a Freestyle job: > > 1. Sign in to your Jenkins instance. > > 2. Select **New Item**. > > 3. Enter the job name, then select **Freestyle project**. > > 4. Configure the job details. > > 5. Scroll to **Build Steps**, then select **Add build step** > **Execute shell**. > > 6. Add the following commands to the **Execute shell** build step. > > ```shell theme={null} > ARCH="amd64" > curl -sSfLo op.zip "https://cache.agilebits.com/dist/1P/op2/pkg/v2.24.0/op_linux_${ARCH}_v2.24.0.zip" > unzip -o op.zip -d op-dir > mv -f op-dir/op /usr/local/bin > rm -r op.zip op-dir > # code-result > Running as SYSTEM > Building in workspace /config/workspace/Example > [Test 1Password Secrets Freestyle] $ /bin/sh -xe /tmp/jenkins14763651031574634007.sh > + ARCH=amd64 > + curl -sSfLo op.zip https://cache.agilebits.com/dist/1P/op2/pkg/v2.24.0/op_linux_amd64_v2.24.0.zip > + unzip -o op.zip -d op-dir > Archive: op.zip > extracting: op-dir/op.sig > inflating: op-dir/op > + mv -f op-dir/op /usr/local/bin > + rm -r op.zip op-dir > Finished: SUCCESS > ``` > > 7. Save the build. ### Step 3: Configure the 1Password Secrets plugin for Jenkins You can configure the 1Password Secrets plugin for Jenkins from the Jenkins dashboard: 1. Login to your Jenkins instance. 2. Select **Manage Jenkins** > **System**. 3. Scroll to **1Password Secrets**. 4. Set the **1Password CLI path** to the location of the 1Password CLI executable. \ The example script uses `/usr/local/bin/op`. The remaining configuration steps depend on whether you use a service account or a Connect server. > [tab] Service account > > You must add at least one Service Account Credential to use a service account with the 1Password Secrets plugin for Jenkins. > > 1. Select **Add** > **Jenkins** under the Service Account Credential. > 2. Set the **Domain**. > 3. Set the **Kind** to **Secret text**.\ > The plugin only supports [secret text.](https://www.jenkins.io/doc/book/pipeline/jenkinsfile/#secret-text) > 4. Set the **Scope**. > 5. Set the **Secret** to the service account token. > 6. You can leave the **ID** and **Description** empty. > 7. Select **Add**. > [tab] Connect server > > You must specify the Connect Host value and add at least one Connect Credential to use a service account with the 1Password Secrets plugin for Jenkins. > > 1. Set **Connect Host** to the IP address, hostname, or URL of the Connect server. > 2. Select **Add** > **Jenkins** under the Connect Credential. > 3. Set the **Domain**. > 4. Set the **Kind** to **Secret text**.\ > The plugin only supports [secret text.](https://www.jenkins.io/doc/book/pipeline/jenkinsfile/#secret-text) > 5. Set the **Scope**. > 6. Set the **Secret** to the Connect server token. > 7. You can leave the **ID** and **Description** empty. > 8. Select **Add**. For example configurations and pipeline scripts, go to [Usage examples](#usage-examples). > [!NOTE] > > If you configure both a Connect server and a service account, the Connect server takes precedence. ## Configuration The following sections document the available [configuration options](#configuration-options) and [configuration scopes](#configuration-scope). > [!NOTE] > > If you install 1Password CLI in the same pipeline, you will need to add the 1Password CLI installation script before you make any calls to the plugin. > > If you install 1Password CLI in a separate pipeline, you will need to set the **1Password CLI path** to the workspace where you performed the installation in your [configuration](#configuration). ### Configuration options The 1Password Secrets plugin for Jenkins has configuration options for 1Password CLI, Connect servers, and service accounts. | Setting | Description | | - | - | | **Connect Host** | The hostname, IP address, or URL of the Connect server. | | **Connect Credential** | The [Connect server token](/connect/security#connect-server-access-tokens) to authenticate with the Connect server. This setting is a [Jenkins secret text credential.](https://www.jenkins.io/doc/book/using/using-credentials/) | | **Service Account Credential** | The [service account token](/service-accounts/security/#service-accounts-and-token-generation) to authenticate with the service account. This setting is a [Jenkins secret text credential.](https://www.jenkins.io/doc/book/using/using-credentials) | | **1Password CLI path** | The path to the 1Password CLI executable. The default location is `/usr/local/bin/op` | ### Configuration scope You can configure the 1Password Secrets plugin for Jenkins globally, per folder, or per job. | Level | Description | | - | - | | Global | Global-level configurations impact all jobs in all folders. To configure the 1Password Secrets plugin for Jenkins globally, add it to your global configuration. | | Folder | Folder-level configurations impact all jobs within the folder. To configure the 1Password Secrets plugin for Jenkins for a specific folder, add it to the folder configuration. | | Job | Job-level configurations only impact the jobs you configure. To configure the 1Password Secrets plugin for Jenkins for a single job, configure the plugin in the Jenkinsfile or Freestyle job. | The configuration priority is highest for job-level configurations and lowest for global configurations. The more specific the level, the higher the priority. This means you can have a default configuration at a broader level and override it at more specific levels. For example, if you configure a service account (service account A) globally, but override it with a different service account (service account B) in a job-level configuration, the job will use the second service account (service account B). > [!NOTE] > > If you configure both a Connect server and a service account, the Connect server takes precedence. ## Usage examples The following sections cover several use case examples for the 1Password Secrets plugin for Jenkins: * [Use with a Jenkinsfile](#use-with-a-jenkinsfile) * [Use with environment variables](#use-with-environment-variables) * [Use in a Freestyle job](#use-in-a-freestyle-job) ### Use with a Jenkinsfile You can access secrets within the Jenkins pipeline using [secret references](/cli/secret-reference-syntax/) with the `withSecrets` function. This function receives the configuration and list of 1Password secrets and loads them as parameters. Explore the following examples to learn how to use the `withSecrets` function in various contexts. > [accordion] About the configuration step... > > > [tab] Service account > > > > The configuration at the beginning of the Jenkinsfile to configure the service account and 1Password CLI is optional. If you don't provide a configuration, the 1Password Secrets plugin uses a [more broadly scoped configuration](#configuration-scope). > > > > Make sure to replace `service-account-token` with the service account token and `op-cli-path` with the path you installed the 1Password CLI to (if you used a custom location). See [Configuration](#configuration). > > > > ```groovy theme={null} > > def config = [ > > serviceAccountCredentialId: 'service-account-token', > > opCLIPath: 'op-cli-path' > > ] > > ``` > > > [tab] Connect > > > > The configuration at the beginning of the Jenkinsfile to configure the Connect server and 1Password CLI is optional. If you don't provide a configuration, the 1Password Secrets plugin uses a [more broadly scoped configuration](#configuration-scope). > > > > Make sure to replace `connect-server-token` with the Connect server token, `connect-host` with the Connect server IP address, and `op-cli-path` with the path you installed the 1Password CLI to (if you used a custom location). See [Configuration](#configuration). > > > > ```groovy theme={null} > > def config = [ > > connectHost: 'connect-host', > > connectCredentialId: 'connect-server-token', > > opCLIPath: 'op-cli-path' > > ] > > ``` > [tab] Service account > > The following examples show how to use the `withSecrets` function in a Jenkinsfile with a 1Password Service Account. > > > [tab] Declarative Jenkinsfile > > > > The following [declarative Jenkinsfile](https://www.jenkins.io/doc/book/pipeline/syntax/#declarative-pipeline) shows how to use the `withSecrets` function with a service account. It first defines environment variables to hold the secret values, then uses the `withSecrets` function to access and assign the values. > > > > ```groovy Declarative Jenkinsfile theme={null} > > // Configure 1Password CLI and the service account. > > def config = [ > > serviceAccountCredentialId: 'service-account-token', > > opCLIPath: 'op-cli-path' > > ] > > // Define the environment variables for the values of the secrets. > > // Use the secret reference syntax: `op:///[/section]/`. > > def secrets = [ > > [envVar: 'DOCKER_USERNAME', secretRef: 'op://vault/item/username'], > > [envVar: 'DOCKER_PASSWORD', secretRef: 'op://vault/item/password'] > > ] > > pipeline { > > agent any > > stages{ > > stage('Push latest docker image') { > > steps { > > // Use the `withSecrets` function to access secrets. > > withSecrets(config: config, secrets: secrets) { > > docker.withRegistry('http://somehost:5100') { > > sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100' > > def image = docker.build('somebuild') > > image.push 'latest' > > } > > } > > } > > } > > } > > } > > ``` > > > [tab] Scripted Jenkinsfile > > > > The following [scripted Jenkinsfile](https://www.jenkins.io/doc/book/pipeline/syntax/#scripted-pipeline) shows how to use the `withSecrets` function with a service account. It first defines environment variables to hold the secret values, then uses the `withSecrets` function to access and assign the values. > > > > ```groovy Scripted Jenkinsfile theme={null} > > node { > > // Configure 1Password CLI and the service account > > def config = [ > > serviceAccountCredentialId: 'service-account-token', > > opCLIPath: 'op-cli-path' > > ] > > // Define the environment variables for the values of the secrets. > > // Use the secret reference syntax: `op:///[/section]/`. > > def secrets = [ > > [envVar: 'DOCKER_USERNAME', secretRef: 'op://vault/item/username'], > > [envVar: 'DOCKER_PASSWORD', secretRef: 'op://vault/item/password'] > > ] > > stage('Push latest docker image') { > > // Use the `withSecrets` function to access secrets. > > withSecrets(config: config, secrets: secrets) { > > docker.withRegistry('http://somehost:5100') { > > sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100' > > def image = docker.build('somebuild') > > image.push 'latest' > > } > > } > > } > > } > > ``` > [tab] Connect server > > The following examples show how to use the `withSecrets` function in a Jenkinsfile with a 1Password Connect Server. > > > [tab] Declarative Jenkinsfile > > > > The following [declarative Jenkinsfile](https://www.jenkins.io/doc/book/pipeline/syntax/#declarative-pipeline) shows how to use the `withSecrets` function with a Connect server. It first defines environment variables to hold the secret values, then uses the `withSecrets` function to access and assign the values. > > > > ```groovy Declarative Jenkinsfile theme={null} > > // Configure 1Password CLI and the Connect server. > > def config = [ > > connectHost: 'connect-host', > > connectCredentialId: 'connect-server-token', > > opCLIPath: 'op-cli-path' > > ] > > // Define the environment variables for the values of the secrets. > > // Use the secret reference syntax: `op:///[/section]/`. > > def secrets = [ > > [envVar: 'DOCKER_USERNAME', secretRef: 'op://vault/item/username'], > > [envVar: 'DOCKER_PASSWORD', secretRef: 'op://vault/item/password'] > > ] > > pipeline { > > agent any > > stages{ > > stage('Push latest docker image') { > > steps { > > // Use the `withSecrets` function to access secrets. > > withSecrets(config: config, secrets: secrets) { > > docker.withRegistry('http://somehost:5100') { > > sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100' > > def image = docker.build('somebuild') > > image.push 'latest' > > } > > } > > } > > } > > } > > } > > ``` > > > [tab] Scripted Jenkinsfile > > > > The following [scripted Jenkinsfile](https://www.jenkins.io/doc/book/pipeline/syntax/#scripted-pipeline) shows how to use the `withSecrets` function with a Connect server. It first defines environment variables to hold the secret values, then uses the `withSecrets` function to access and assign the values. > > > > ```groovy Scripted Jenkinsfile theme={null} > > node { > > // Configure 1Password CLI and the Connect server. > > def config = [ > > connectHost: 'connect-host', > > connectCredentialId: 'connect-server-token', > > opCLIPath: 'op-cli-path' > > ] > > // Define the environment variables for the values of the secrets. > > // Use the secret reference syntax: `op:///[/section]/`. > > def secrets = [ > > [envVar: 'DOCKER_USERNAME', secretRef: 'op://vault/item/username'], > > [envVar: 'DOCKER_PASSWORD', secretRef: 'op://vault/item/password'] > > ] > > stage('Push latest docker image') { > > // Use the `withSecrets` function to access secrets. > > withSecrets(config: config, secrets: secrets) { > > docker.withRegistry('http://somehost:5100') { > > sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100' > > def image = docker.build('somebuild') > > image.push 'latest' > > } > > } > > } > > } > > ``` > [!TIP] > > **Jenkins Pipeline Syntax helper** > > You can also use the [Jenkins Pipeline Syntax helper](#use-in-a-freestyle-job) to create a pipeline script. ### Use with environment variables The 1Password Secrets plugin for Jenkins lets you use [environment variables](https://www.jenkins.io/doc/pipeline/tour/environment/#using-environment-variables) to get configuration and secrets. The following examples show how to use environment variables with the 1Password Secrets plugin for Jenkins. You must set the environment variables in the `environment` block. The following table describes each environment variable. | Variable | Required | Description | | - | - | - | | `OP_CLI_PATH` | Always required. | The path where you installed the 1Password CLI. If you followed the 1Password CLI installation instruction, set this value to `/usr/local/bin`. The example scripts on this page set this value to `op-cli-path`. | | `OP_SERVICE_ACCOUNT_TOKEN` | Required if using a service account. | The service account token of the service account to use. The example scripts on this page set this value to `service-account-token` variable. | | `OP_CONNECT_HOST` | Required if using a Connect server. | The IP address, hostname, or URL of the Connect server to use. The example scripts on this page set this value to `connect-server-host`. | | `OP_CONNECT_TOKEN` | Required if using a Connect server. | The Connect server token of the Connect server to use. The example scripts on this page set this value to `connect-server-token`. | If you don't configure these environment variables, the 1Password Secrets plugin uses a [more broadly scoped configuration](#configuration-scope). > [tab] Service account > > The following examples show how to use a service account with environment variables in a Jenkinsfile. > > > [tab] Declarative Jenkinsfile > > > > ```groovy Declarative Jenkinsfile theme={null} > > pipeline { > > agent any > > environment { > > // Configure 1Password CLI and the service account. > > OP_SERVICE_ACCOUNT_TOKEN = credentials('service-account-token') > > OP_CLI_PATH = 'op-cli-path' > > // Define the environment variables using the secret reference `op:///[/section]/`. > > DOCKER_USERNAME = 'op://vault/item/username' > > DOCKER_PASSWORD = 'op://vault/item/password' > > } > > stages{ > > stage('Push latest docker image') { > > steps { > > // Access 1Password secrets. > > withSecrets() { > > docker.withRegistry('http://somehost:5100') { > > sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100' > > def image = docker.build('somebuild') > > image.push 'latest' > > } > > } > > } > > } > > } > > } > > ``` > > > [tab] Scripted Jenkinsfile > > > > ```groovy Scripted Jenkinsfile theme={null} > > node { > > def environment = [ > > // Configure 1Password CLI. > > 'OP_CLI_PATH = op-cli-path', > > // Define the environment variables for the values of the secrets. > > // Use the secret reference syntax: `op:///[/section]/`. > > 'DOCKER_USERNAME=op://vault/item/username', > > 'DOCKER_PASSWORD=op://vault/item/password' > > ] > > // Define the service account token. > > def credentials = [ > > string(credentialsId: 'service-account-token', variable: 'OP_SERVICE_ACCOUNT_TOKEN') > > ] > > withEnv(environment) { > > withCredentials(credentials) { > > stage('Push latest docker image') { > > // Use the `withSecrets` function to access secrets. > > withSecrets() { > > docker.withRegistry('http://somehost:5100') { > > sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100' > > def image = docker.build('somebuild') > > image.push 'latest' > > } > > } > > } > > } > > } > > } > > ``` > [tab] Connect server > > The following examples show how to use a Connect server with environment variables in a Jenkinsfile. > > > [tab] Declarative Jenkinsfile > > > > ```groovy Declarative Jenkinsfile theme={null} > > pipeline { > > agent any > > environment { > > // Configure 1Password CLI and the Connect server. > > OP_CONNECT_HOST = 'connect-host' > > OP_CONNECT_TOKEN = credentials('connect-server-token') > > OP_CLI_PATH = 'op-cli-path' > > // Define the environment variables for the values of the secrets. > > // Use the secret reference syntax: `op:///[/section]/`. > > DOCKER_USERNAME = 'op://vault/item/username' > > DOCKER_PASSWORD = 'op://vault/item/password' > > } > > stages{ > > stage('Push latest docker image') { > > steps { > > // Use the `withSecrets` function to access secrets. > > withSecrets() { > > docker.withRegistry('http://somehost:5100') { > > sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100' > > def image = docker.build('somebuild') > > image.push 'latest' > > } > > } > > } > > } > > } > > } > > ``` > > > [tab] Scripted Jenkinsfile > > > > ```groovy Scripted Jenkinsfile theme={null} > > node { > > def environment = [ > > // Configure 1Password CLI and the Connect server. > > 'OP_CONNECT_HOST=connect-host', > > 'OP_CLI_PATH = op-cli-path', > > // Define the environment variables for the values of the secrets. > > // Use the secret reference syntax: `op:///[/section]/`. > > 'DOCKER_USERNAME=op://vault/item/username', > > 'DOCKER_PASSWORD=op://vault/item/password' > > ] > > def credentials = [ > > string(credentialsId: 'connect-server-token', variable: 'OP_CONNECT_TOKEN') > > ] > > withEnv(environment) { > > withCredentials(credentials) { > > stage('Push latest docker image') { > > // Use the `withSecrets` function to access secrets. > > withSecrets() { > > docker.withRegistry('http://somehost:5100') { > > sh 'docker login -u ${DOCKER_USERNAME} -p ${DOCKER_PASSWORD} http://somehost:5100' > > def image = docker.build('somebuild') > > image.push 'latest' > > } > > } > > } > > } > > } > > } > > ``` ### Use in a Freestyle Job You can use the Jenkins Pipeline Syntax helper to set [environment variables](https://www.jenkins.io/doc/pipeline/tour/environment/#using-environment-variables) and access secrets in a Freestyle job. > [tab] Service account > > Use the Jenkins Pipeline Syntax helper to use a service account in a Freestyle job: > > 1. From the Freestyle job in Jenkins, go to the **Steps** section. > 2. Set **1Password CLI path** to the location where you installed 1Password CLI. \ > The example script uses `/usr/local/bin/op`. > 3. Set **Service Account Credential** to the service account token. > 4. Select **Add a 1Password secret**. > 5. Set the **Environment variable** for the secret. > 6. Set **Secret reference**. \ > Use the [secret reference syntax](/cli/secret-reference-syntax/) to point to the 1Password secret. > 7. Select **Generate Pipeline Script**. > [tab] Connect server > > Use the Jenkins Pipeline Syntax helper to use a Connect server in a Freestyle job: > > 1. From the Freestyle job in Jenkins, go to the **Steps** section. > 2. Set **1Password CLI path** to the location where you installed 1Password CLI. \ > The example script uses `/usr/local/bin/op`. > 3. Set **Connect Host** to the Connect server IP address or hostname. > 4. Set **Connect Credential** to the Connect server token. > 5. Select **Add a 1Password secret**. > 6. Set the **Environment variable** for the secret. > 7. Set **Secret reference**. \ > Use [secret references](/cli/secret-reference-syntax/) to point to the 1Password secret. > 8. Select **Generate Pipeline Script**. # 1Password CLI Source: https://www.1password.dev/cli 1Password CLI brings 1Password to your terminal. Read and write items, load secrets into scripts and apps, generate SSH keys, and manage your team from the command line. 1Password CLI brings 1Password to your terminal. Sign in with your fingerprint, then read and write items, generate SSH keys, run scripts, and manage your team, all without copying secrets out of 1Password or storing them in plaintext. 1Password CLI works alongside the rest of the 1Password developer toolset: load project secrets from [Environments](/environments), authenticate third-party tools with [Shell Plugins](/cli/shell-plugins), or call the same operations from [1Password SDKs](/sdks) when you need them in application code instead of a script. ## Use cases ### Eliminate plaintext secrets in code Inject secrets from 1Password Environments anywhere you need them. [Learn more](/cli/use-cases#secrets) ### Automate administrative tasks Use scripts to manage items and provision team members at scale. [Learn more](/cli/use-cases#automate) ### Sign in to any CLI with your fingerprint Store API keys for your favorite CLIs in 1Password. [Learn more](/cli/use-cases#shell-plugins) ## Quickstart If you're installing 1Password CLI for the first time, [start here](/cli/get-started/). ## Guides ### Manage items and users * [Create and retrieve items](/cli/item-create/). * [Add and remove team members](/cli/provision-users/). * [Manage your team members' vault permissions](/cli/grant-revoke-vault-permissions/). * [Manage your team members' group permissions](/cli/reference/management-commands/group/). ### Provision secrets * [Securely load secrets from the environment into your applications](/cli/secrets-environment-variables/) using secret references. * [Access secrets in your code with secret references](/cli/secret-references/) instead of plaintext secrets. Secret references are replaced with the actual secrets they reference in 1Password at runtime. * [Securely inject secrets into configuration files](/cli/secrets-config-files/) using secret references. ### Authenticate with biometrics * [Use shell plugins to securely authenticate third-party CLIs](/cli/shell-plugins/) with biometrics. * [Build your own shell plugin](/cli/shell-plugins/contribute/) if the CLI you want to authenticate isn't already supported. ### Use 1Password CLI with other tools * Use [1Password for VS Code](/vscode/) to bring 1Password CLI functionality to VS Code. * Use [1Password Service Accounts](/service-accounts/get-started/#create-a-service-account) to limit the vaults 1Password CLI can access or run automated scripts if your personal account uses SSO or MFA. * Use with [1Password Environments](/environments) to quickly load your project secrets from 1Password. * Use a [1Password Connect Server](/connect/cli/) with 1Password CLI to securely access your items in your company's apps and cloud infrastructure using a private REST API. * Use [1Password CI/CD Integrations](/ci-cd/) with 1Password CLI to allow jobs in your pipeline to securely access secrets stored in 1Password. * Use the [1Password Events API](/events-api/generic-scripts#usage) with 1Password CLI to provision bearer tokens at runtime using [secret references](/cli/secret-references/). ## Reference documentation * Read the full [command reference](/cli/reference/) to learn about all 1Password CLI commands and how they can be used. * Learn about [CLI best practices](/cli/best-practices). * Learn about the [1Password app integration](/cli/app-integration/). * Learn about the [shell plugins security model](/cli/shell-plugins/security/). ## Get help Running into an error, or not sure which command to use? Check [1Password app integration troubleshooting](/cli/app-integration/#troubleshooting), search the [command reference](/cli/reference/), or ask in the [Developer community](/community) or [Developer Slack](/joinslack). # Use the 1Password desktop app to sign in to 1Password CLI Source: https://www.1password.dev/cli/app-integration Turn on the 1Password app integration to sign in to 1Password CLI with Touch ID, Windows Hello, or Linux system authentication, and fix common sign-in problems. You can use the [1Password desktop app](https://1password.com/downloads) integration to quickly and securely sign in to [1Password CLI](/cli/get-started/). The app integration allows you to: * Seamlessly sign to the 1Password accounts you've added to the app in your terminal. * Authenticate 1Password CLI the same way you unlock your device, like with your fingerprint, face, Apple Watch, Windows Hello PIN, or device user password. * Track recent 1Password CLI activity from your 1Password app. > [!TIP] > > **Installing inside WSL?** The desktop app integration authenticates over a local connection to the 1Password app on your Windows host, so it isn't available to a CLI binary installed inside the Linux side of WSL. Install 1Password CLI on Windows, then call the Windows `op.exe` from your WSL shell (or add it to your WSL `PATH`) — the same approach used by the [1Password SSH agent WSL integration](/ssh/integrations/wsl/). ## Requirements > [tab] Mac > > * [1Password subscription](https://1password.com/pricing/password-manager) > * [1Password for Mac](https://1password.com/downloads/mac) > [tab] Windows > > * [1Password subscription](https://1password.com/pricing/password-manager) > * [1Password for Windows](https://1password.com/downloads/windows) > [tab] Linux > > * [1Password subscription](https://1password.com/pricing/password-manager) > * [1Password for Linux](https://1password.com/downloads/linux) > * [PolKit](https://gitlab.freedesktop.org/polkit/polkit) (included in many popular distributions) > * A PolKit authentication agent running ## Set up the app integration ### Step 1: Turn on the app integration > [tab] Mac > > 1. Open and unlock the [1Password app](https://1password.com/downloads/). > 2. Select your account or collection at the top of the sidebar. > 3. Navigate to **Settings** > **Developer**. [Open Developer settings](onepassword://settings/developers) if 1Password is installed on this device. > 4. Select **Integrate with 1Password CLI**. > 5. If you want to authenticate 1Password CLI with your fingerprint, turn on **[Touch ID](https://support.1password.com/touch-id-mac/)** in the app. > > ![The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.](/static/img/developer-integrations-cli-light.png) > ![The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.](/static/img/developer-integrations-cli-dark.png) > [tab] Windows > > 1. Open and unlock the [1Password app](https://1password.com/downloads/). > 2. Select your account or collection at the top of the sidebar. > 3. Turn on **[Windows Hello](https://support.1password.com/windows-hello/)** in the app. > 4. Navigate to **Settings** > **Developer**. [Open Developer settings](onepassword://settings/developers) if 1Password is installed on this device. > 5. Select **Integrate with 1Password CLI**. > > ![The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.](/static/img/developer-integrations-cli-light.png) > ![The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.](/static/img/developer-integrations-cli-dark.png) > [tab] Linux > > 1. Open and unlock the [1Password app](https://1password.com/downloads/). > 2. Select your account or collection at the top of the sidebar. > 3. Navigate to **Settings** > **Security**. [Open Security settings](onepassword://settings/security) if 1Password is installed on this device. > 4. Turn on **[Unlock using system authentication](https://support.1password.com/system-authentication-linux/)**. > 5. Navigate to **Settings** > **Developer**. [Open Developer settings](onepassword://settings/developers) if 1Password is installed on this device. > 6. Select **Integrate with 1Password CLI**. > > ![The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.](/static/img/developer-integrations-cli-light.png) > ![The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.](/static/img/developer-integrations-cli-dark.png) ### Step 2: Enter any command to sign in After you've turned on the app integration, enter any command and you'll be prompted to authenticate. For example, run this command to see all the vaults in your account: ```shell theme={null} op vault list ``` #### If you have multiple accounts If you've added multiple 1Password accounts to your desktop app, you can use [`op signin`](/cli/reference/commands/signin/) to select an account to sign in to with 1Password CLI. Use the arrow keys to choose from the list of all accounts added to your 1Password app. ```shell highlight={2} theme={null} op signin #code-result Select account [Use arrows to move, type to filter] > ACME Corp (acme.1password.com) AgileBits (agilebits.1password.com) Add another account ``` You can also [select an account on a per-command basis using the `--account` flag](/cli/use-multiple-accounts/#specify-an-account-per-command-with-the-account-flag) with your account's sign-in address or ID. ```shell theme={null} op vault ls --account my.1password.com ``` If you're signed in to multiple accounts in the app but only want to use a specific account with 1Password CLI, you can [set the `OP_ACCOUNT` environment variable](/cli/use-multiple-accounts/#set-an-account-with-the-op_account-environment-variable) to your account's sign-in address or ID. ### Optional: Remove previously added account details > [!WARNING] > > Make sure you have access to your Secret Key and account password before removing account details from your configuration file. If you previously [added an account to 1Password CLI manually](/cli/sign-in-manually/) and now want to exclusively use the 1Password app to sign in, you can remove your account details from your configuration file. Your configuration file is in one of the following locations: * `~/.op/config` * `~/.config/op/config` * `~/.config/.op/config` Use the [account forget](/cli/reference/management-commands/account/#account-forget) command to remove all existing account information from your configuration file. This won't impact the accounts added to your 1Password app. ```shell theme={null} op account forget --all ``` ### Optional: Set the biometric unlock environment variable You can use the `OP_BIOMETRIC_UNLOCK_ENABLED` environment variable to temporarily toggle the app integration on or off. To turn on the integration: export OP\_BIOMETRIC\_UNLOCK\_ENABLED=true set -x OP\_BIOMETRIC\_UNLOCK\_ENABLED true \$Env:OP\_BIOMETRIC\_UNLOCK\_ENABLED = "true" To turn off the integration: export OP\_BIOMETRIC\_UNLOCK\_ENABLED=false set -x OP\_BIOMETRIC\_UNLOCK\_ENABLED false \$Env:OP\_BIOMETRIC\_UNLOCK\_ENABLED = "false" ## Track 1Password CLI activity You can track 1Password CLI activity authenticated with the 1Password app, including the command, when it was run, the application where it was run, and the name of the account accessed. To see your 1Password CLI activity log: 1. Open and unlock the 1Password desktop app. 2. Select **Developer** in the sidebar. 3. Select **View CLI**. ![The 1Password CLI activity log.](https://mintcdn.com/ab-634991b8/pfc4yDcmGyZA8XDs/static/img/cli/activity-log-light.png?fit=max\&auto=format\&n=pfc4yDcmGyZA8XDs\&q=85\&s=a26e769819da6c13bbb76a359d8c83e5) You'll see a table with your recent 1Password CLI activity. Your activity log data is encrypted on your device. Older entries get purged regularly, and you can manually clear your activity log data at any time. If you don’t want to use activity logging, turn off **Record and display activity** in the [1Password Developer settings](onepassword://settings/developers). ## Troubleshooting ### If you're prompted for your Secret Key instead of your fingerprint If running a command prompts you for your email, Secret Key, and password instead of a fingerprint or system authentication prompt, the CLI is trying to sign in directly instead of using the app integration. Check that: * **Integrate with 1Password CLI** is turned on in the app under **Settings > Developer**. * Your device isn't managed by an organization policy that restricts the app integration — if it is, check with your 1Password administrator. ### If `op signin` doesn't list your account `op signin` returns a list of all accounts you've added to the 1Password desktop app. To sign in to 1Password CLI with a new 1Password account, you'll need to [add the account to the app](https://support.1password.com/add-account/). ### If you see "No accounts configured" on macOS 27 Golden Gate If you updated to macOS 27 Golden Gate and 1Password CLI commands return `No accounts configured for use with 1Password CLI`, even though you've turned on the app integration, macOS may be blocking your terminal from accessing data from the 1Password app. To allow access: 1. Open **System Settings** > **Privacy & Security** > **Files & Folders**. 2. Select the app you use to run commands, like Terminal, iTerm, or Ghostty. If you use a terminal built into an editor, like Visual Studio Code or Cursor, select the editor. 3. Turn on the setting that starts with "Data shared by 1Password". The rest of the name depends on which 1Password apps you've installed. 4. Quit and reopen your terminal, then try your command again. If you don't see the "Data shared by 1Password" setting, run a 1Password CLI or SSH command in that terminal and select **Allow** when macOS asks to access data from other apps. Then check again. If you use more than one terminal, turn on the setting for each one. ### If you see a lost connection, no accounts configured, or connection reset error If you see a `LostConnectionToApp`, `connectionreset` or `No accounts configured for use with 1Password CLI` error when you run a 1Password CLI command: > [tab] Mac > > Make sure the app integration is turned on: > > 1. Open and unlock the 1Password desktop app. > 2. Select your account or collection at the top of the sidebar. > 3. Select **Settings** > **[Developer](onepassword://settings/developers)** and make sure **Integrate with 1Password CLI** is selected. > > Then make sure the option to keep 1Password in the menu bar is turned on: > > 3. Select **Settings** > **General**. > 4. Make sure "Keep 1Password in the menu bar" is selected. > > Restart the 1Password desktop app, then run your 1Password CLI command again. > [tab] Windows > > Make sure the app integration is turned on: > > 1. Open and unlock the 1Password desktop app. > 2. Select your account or collection at the top of the sidebar. > 3. Select **Settings** > **[Developer](onepassword://settings/developers)** and make sure **Integrate with 1Password CLI** is selected. > > Then, make sure the option to keep 1Password in the notification area is turned on: > > 1. Open and unlock the 1Password desktop app. > 2. Select your account or collection at the top of the sidebar. > 3. Select **Settings** > **General**. > 4. Make sure "Keep 1Password in the notification area" is selected. > > Restart the 1Password desktop app, then run your 1Password CLI command again. > [tab] Linux > > Make sure the app integration is turned on: > > 1. Open and unlock the 1Password desktop app. > 2. Select your account or collection at the top of the sidebar. > 3. Select **Settings** > **[Developer](onepassword://settings/developers)** and make sure **Integrate with 1Password CLI** is selected. > > Then, make sure the option to keep 1Password in the system tray is turned on: > > 1. Open and unlock the 1Password desktop app. > 2. Select your account or collection at the top of the sidebar. > 3. Select **Settings** > **General**. > 4. Make sure "Keep 1Password in the system tray" is selected. > > Restart the 1Password desktop app, then run your 1Password CLI command again. If you see a `connectionreset` error, also try the following: > [tab] Mac > > Open **System Settings** > **General** > **Login Items** and make sure **Allow in background** is turned on for 1Password. > > If you still see an error, try the following: > > 1. Make sure you're using the latest version of the 1Password desktop app. > 2. Restart the app. > > If you're using 1Password for Mac version 8.10.12 or earlier, the 1Password CLI binary must be located in the `/usr/local/bin/` directory. > [tab] Windows > > 1. Make sure you're using the latest version of the 1Password desktop app. > 2. Restart the app. > [tab] Linux > > 1. Make sure you're using the latest version of the 1Password desktop app. > 2. Restart the app. ### If you aren't prompted to authenticate with your preferred method If you've turned on the app integration, but aren't prompted to sign in to 1Password CLI with your expected authentication method: > [tab] Mac > > Make sure you've set up [Touch ID](https://support.1password.com/touch-id-mac/) or an [Apple Watch](https://support.1password.com/apple-watch-mac/) to unlock 1Password on your Mac. > [tab] Windows > > Make sure you've set up [Windows Hello](https://support.1password.com/windows-hello/) to unlock 1Password on your Windows PC. > [tab] Linux > > 1. Make sure you've set up [system authentication](https://support.1password.com/system-authentication-linux/) to unlock 1Password on your Linux computer. > 2. Update the authentication method in your Linux settings to use a [fingerprint](https://help.ubuntu.com/stable/ubuntu-help/session-fingerprint.html.en) or other biometrics instead of your Linux user password. ## Learn more * [Use multiple 1Password accounts with 1Password CLI](/cli/use-multiple-accounts/) * [Add accounts to the 1Password app](https://support.1password.com/add-account/) * [1Password app integration security](/cli/app-integration-security/) # 1Password app integration security Source: https://www.1password.dev/cli/app-integration-security ## Security model [Integrating 1Password CLI with the 1Password app](/cli/app-integration/) allows you to use accounts you've added to the 1Password desktop app with 1Password CLI. Every time you use 1Password CLI in a new terminal window or tab, you'll be asked to authorize with biometrics. This authorization establishes a 10-minute session that automatically refreshes on each use. 1Password accounts can only be accessed through 1Password CLI after the user provides explicit biometric authorization and authorization is limited to an single account at a time. The user is shown a prompt containing the 1Password account display name (for example, `AgileBits` or `Wendy Appleseed's Family`) and the process being authorized (for example, `iTerm2` or `Terminal`). The user must confirm the prompt for 1Password CLI to be granted access to the requested account details. Authorizing use of 1Password CLI while the 1Password app is locked will result in the 1Password app unlocking. When the 1Password app is locked, all prior authorization is revoked. Any new invocation of 1Password CLI will require new authorization. If a process is running at the moment authorization is revoked or expires, it will be able to finish its task and exit. ## Authorization model Authorization in 1Password CLI occurs on a per-account basis. If you sign in to multiple accounts, each account must be authorized separately. Authorization expires after 10 minutes of inactivity in the terminal session. There's a hard limit of 12 hours, after which you must reauthorize. Each time you use a 1Password CLI command in a new terminal window or tab, you'll need to authorize your account again: * On macOS and Linux, authorization is confined to a terminal session but extends to sub-shell processes in that window. * On Windows, commands executed in a sub-shell require separate authorization. ## Accepted risks * A user or application with root/administrator level privileges on the same system may be able to circumvent one or more security measures and could obtain access to 1Password accounts through 1Password CLI without authorization if (and only if) the 1Password app is unlocked. * Applications that are granted accessibility permissions on macOS may be able to circumvent the authorization prompt. ## Technical design ### Session credentials Session credentials are used to identify the terminal window or application where 1Password CLI is invoked. The goal is to restrict the granted authorization to a single terminal. If a user authorizes `account X` in one terminal window, using `account y` in another terminal window requires another approval from the user. These credentials don't consist of any sensitive or secret information. > [tab] Mac > > The session credential for macOS is an ID that's based on the current `tty`, plus the start time. This way every session credential is unique, even after an ID gets reused. > [tab] Linux > > The session credential for Linux is an ID that's based on the current `tty`, plus the start time. This way every session credential is unique, even after an ID gets reused. > [tab] Windows > > The session credential for Windows is an ID that's based on the PID of the process that invokes 1Password CLI, plus the start time. This way every session credential is unique, even after an ID gets reused. ### How does 1Password CLI communicate with the 1Password app? 1Password CLI uses inter-process communication to reach out to the 1Password app to obtain access to the accounts stored in the app. > [tab] Mac > > The `NSXPCConnection` XPC API is used for IPC. The 1Password app sets up a service (`1Password Browser Helper`) that acts as an XPC server. Both 1Password CLI and the 1Password app connect to this server. Authenticity of both is confirmed by verifying the code signature. The `1Password Browser Helper` acts as a message relay between the 1Password app and 1Password CLI. > [tab] Linux > > 1Password CLI connects to a Unix socket opened by the 1Password app. The socket is owned by the current user/group, allowing any process started by this user to connect to it. 1Password CLI is owned by the `onepassword-cli` group and has the `set-gid` bit set on Linux. The 1Password app verifies the authenticity of 1Password CLI by checking if the GID of the process connecting on the unix socket is equal to that of the `onepassword-cli` group. If the GID doesn't match, the connection is reset before any messages are accepted. > [tab] Windows > > 1Password CLI connects to a named pipe opened by the 1Password app. The app verifies the authenticity of the process connecting on the named pipe by verifying the Authenticode signature of the process's executable. 1Password CLI verifies the 1Password app's authenticity in the same way. ### Authorization prompts The user is prompted for authorization to confirm that they actually want to allow an account to be accessible through 1Password CLI. > [tab] Mac > > On macOS the OS's default biometrics prompt is used to request authorization, if available. Either TouchID or an Apple Watch can be used to confirm this prompt. If biometrics are not available a prompt confirming the user's device password is used instead. > [tab] Linux > > On Linux, PolKit is used to spawn a prompt that includes an authentication challenge for the user (commonly fingerprint or the user's OS password). > [tab] Windows > > On Windows, Windows Hello is used to spawn a prompt that includes an authentication challenge for the user (commonly fingerprint, face, or the user's OS password). Without Windows Hello, biometrics cannot be used with 1Password CLI. # 1Password CLI best practices Source: https://www.1password.dev/cli/best-practices 1Password CLI brings 1Password to your terminal. The following are best practices we recommend when using 1Password CLI. ### Use the latest version of 1Password CLI Practice good software update hygiene and regularly update to the [latest version of the 1Password CLI](https://app-updates.agilebits.com/product_history/CLI2). You can check for available updates with [`op update`](/cli/reference/commands/update). ### Apply the principle of least privilege to your infrastructure secrets You can follow the [principle of least privilege](https://csrc.nist.gov/glossary/term/least_privilege) with [1Password Service Accounts](/service-accounts), which support restricting 1Password CLI access to only the items required for a given purpose. Use dedicated vaults with service accounts that are properly scoped for secrets management use cases. Do not grant access to more vaults than needed. Learn more about [managing group and vault permissions using the principle of least privilege](https://support.1password.com/business-security-practices/#access-management-and-the-principle-of-least-privilege). ### Use template files when creating items that contain sensitive values When creating items with [`op item create`](/cli/reference/management-commands/item#item-create) we recommend using a [JSON template](/cli/item-create#with-an-item-json-template) to enter any sensitive values. # How 1Password CLI detects configuration directories Source: https://www.1password.dev/cli/config-directories 1Password CLI configuration directories default to: * `${XDG_CONFIG_HOME}/op` when `${XDG_CONFIG_HOME}` is set * `~/.config/op` when `${XDG_CONFIG_HOME}` is not set 1Password CLI detects the configuration directory to read or write to in this order of precedence: 1. A directory specified with `--config` 2. A directory set with the `OP_CONFIG_DIR` environment variable. 3. `~/.op` (following [go-homedir](https://github.com/mitchellh/go-homedir) to determine the home directory) 4. `${XDG_CONFIG_HOME}/.op` 5. `~/.config/op` (following [go-homedir](https://github.com/mitchellh/go-homedir) to determine the home directory) 6. `${XDG_CONFIG_HOME}/op` # 1Password CLI environment variables Source: https://www.1password.dev/cli/environment-variables You can use the following environment variables with 1Password CLI: | Environment variable | Description | | - | - | | `OP_ACCOUNT` | Specifies a default 1Password account to execute commands. Accepts an [account sign-in address or ID](/cli/use-multiple-accounts/#find-an-account-sign-in-address-or-id). An account specified with the `--account` flag takes precedence. | | `OP_BIOMETRIC_UNLOCK_ENABLED` | Toggles the [1Password app integration](/cli/app-integration#optional-set-the-biometric-unlock-environment-variable) on or off. Options: `true`, `false`. | | `OP_CACHE` | Toggles the option to [store and use cached information](/cli/reference#cache-item-and-vault-information) on or off. Options: `true`, `false`. Default: `true`. | | `OP_CONFIG_DIR` | Specifies a [configuration directory](/cli/config-directories) to read and write to. A directory specified with the `--config` flag takes precedence. | | `OP_CONNECT_HOST` | Sets a [Connect server instance host URL](/connect/cli/) to use with 1Password CLI. | | `OP_CONNECT_TOKEN` | Sets a [Connect server token](/connect/cli/) to use with 1Password CLI. | | `OP_DEBUG` | Toggles debug mode on or off. Options: `true`, `false`. Default: `false`. | | `OP_FORMAT` | Sets the output format for 1Password CLI commands. Options: `human-readable`, `json`. Default: `human-readable`. | | `OP_INCLUDE_ARCHIVE` | Allows items in the archive to be retrieved with [`op item get`](/cli/reference/management-commands/item#item-get) and [`op document get`](/cli/reference/management-commands/document#document-get) commands. Options: `true`, `false`. Default: `false`. | | `OP_ISO_TIMESTAMPS` | Toggles the option to format timestamps according to ISO 8601 and RFC 3339 standards on or off. Options: `true`, `false`. Default: `false`. | | `OP_RUN_NO_MASKING` | Toggles masking off for the output of [`op run`](/cli/reference/commands/run). | | `OP_SESSION` | Stores a session token when you [sign in to 1Password CLI manually](/cli/sign-in-manually). | | `OP_SERVICE_ACCOUNT_TOKEN` | Configures 1Password CLI to [authenticate with a service account](/service-accounts/use-with-1password-cli). | # Get started with 1Password CLI Source: https://www.1password.dev/cli/get-started Install 1Password CLI on Mac, Windows, or Linux, turn on the 1Password app integration, and sign in with Touch ID, Windows Hello, or system authentication. 1Password CLI brings 1Password to your terminal. Learn how to install the CLI, then integrate it with your 1Password app and sign in with Touch ID, Windows Hello, or another system authentication option. ## Step 1: Install 1Password CLI > [accordion] Requirements > > > [tab] Mac > > > > * [1Password subscription](https://1password.com/pricing/password-manager) > > * [1Password for Mac](https://1password.com/downloads/mac)\* > > * macOS Big Sur 11.0.0 or later > > > > Supported shells: Bash, Zsh, sh, fish > > > > \*Required to integrate 1Password CLI with the 1Password app. > > > [tab] Windows > > > > * [1Password subscription](https://1password.com/pricing/password-manager) > > * [1Password for Windows](https://1password.com/downloads/windows) > > > > Supported shells: PowerShell > > > [tab] Linux > > > > * [1Password subscription](https://1password.com/pricing/password-manager) > > * [1Password for Linux](https://1password.com/downloads/linux)\* > > * [PolKit](https://github.com/polkit-org/polkit)\* > > * A PolKit authentication agent running\* > > > > Supported shells: Bash, Zsh, sh, fish > > > > \*Required to integrate 1Password CLI with the 1Password app. > [tab] Mac > > > [tab] homebrew > > > > 1. Use [Homebrew](https://brew.sh/) to install 1Password CLI: > > ```shell theme={null} > > brew install 1password-cli > > ``` > > 2. Check that 1Password CLI installed successfully: > > ```shell theme={null} > > op --version > > #code-result > > 2.31.1 > > ``` > > > > The > > > > [1Password Homebrew cask](https://formulae.brew.sh/cask/1password-cli) > > > > is maintained by both Homebrew and 1Password developers in the open-source > > > > [Homebrew Cask repository.](https://github.com/Homebrew/homebrew-cask) > > > > 1Password CLI downloads from our CDN on agilebits.net/.com domains. > > > [tab] Manual > > > > To manually install 1Password CLI on macOS: > > > > 1. Download [the latest release of 1Password CLI](https://app-updates.agilebits.com/product_history/CLI2).\ > > Learn how to [verify its authenticity](/cli/verify/). > > 2. * **Package file**: Open `op.pkg` and install 1Password CLI in the default location (`usr/local/bin`). > > * **ZIP file**: Open `op.zip` and unzip the file, then move `op` to `usr/local/bin`. > > 3. Check that 1Password CLI was installed successfully: > > ```shell theme={null} > > op --version > > ``` > [tab] Windows > > > [tab] winget > > > > 1. To install 1Password CLI with winget: > > ```powershell theme={null} > > winget install 1password-cli > > ``` > > 2. Check that 1Password CLI installed successfully: > > ```powershell theme={null} > > op --version > > ``` > > > [tab] Manual > > > > To manually install 1Password CLI on Windows: > > > > 1. Download [the latest release of 1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) and extract `op.exe`.\ > > Learn how to [verify its authenticity](/cli/verify/). > > 2. Open PowerShell **as an administrator**. > > 3. Create a folder to move `op.exe` into. For example, `C:\Program Files\1Password CLI`. > > ```powershell theme={null} > > mkdir "C:\Program Files\1Password CLI" > > ``` > > 4. Move the `op.exe` file to the new folder. > > ```powershell theme={null} > > mv ".\op.exe" "C:\Program Files\1Password CLI" > > ``` > > 5. > [accordion] Add the folder containing the op.exe file to your PATH. > > > > > > **Windows 10 and later** > > > > > >
    > > >
  1. Search for **Advanced System Settings** in the Start menu.
  2. > > >
  3. Select **Environment Variables**.
  4. > > >
  5. In the System Variables section, select the **PATH** environment variable and select **Edit**.
  6. > > >
  7. In the prompt, select **New** and add the directory where `op.exe` is located.
  8. > > >
  9. Sign out and back in to Windows for the change to take effect.
  10. > > >
> > 6. Check that 1Password CLI installed successfully: > > ```shell theme={null} > > op --version > > ``` > > > > If you'd rather install 1Password CLI with a single block of commands, run the following in PowerShell as an administrator. On ARM devices, use winget to install 1Password CLI instead. > > > > ```powershell theme={null} > > $arch = if ($env:PROCESSOR_ARCHITEW6432) { $env:PROCESSOR_ARCHITEW6432 } else { $env:PROCESSOR_ARCHITECTURE } > > switch ($arch) { > > 'AMD64' { $opArch = 'amd64'; break } > > 'x86' { $opArch = '386'; break } > > 'ARM64' { Write-Error "On ARM devices, install 1Password CLI with winget instead: winget install 1password-cli" -ErrorAction Stop } > > Default { Write-Error "Sorry, your operating system architecture '$arch' is unsupported" -ErrorAction Stop } > > } > > $installDir = Join-Path -Path $env:ProgramFiles -ChildPath '1Password CLI' > > $opVersion = "v" + (Invoke-RestMethod -Uri 'https://app-updates.agilebits.com/check/1/0/CLI2/en/2.0.0/N').version > > if ($opVersion -notmatch '^v\d+\.\d+\.\d+$') { throw "Couldn't determine the latest 1Password CLI version" } > > Invoke-WebRequest -Uri "https://cache.agilebits.com/dist/1P/op2/pkg/$opVersion/op_windows_$($opArch)_$opVersion.zip" -OutFile op.zip > > Expand-Archive -Path op.zip -DestinationPath $installDir -Force > > $envMachinePath = [System.Environment]::GetEnvironmentVariable('PATH','machine') > > if ($envMachinePath -split ';' -notcontains $installDir){ > > [Environment]::SetEnvironmentVariable('PATH', "$envMachinePath;$installDir", 'Machine') > > } > > Remove-Item -Path op.zip > > ``` > [tab] Linux > > > [tab] APT > > > > To install 1Password CLI using APT on Debian- and Ubuntu-based distributions: > > > > 1. Run the following command: > > ```shell theme={null} > > curl -sS https://downloads.1password.com/linux/keys/1password.asc | \ > > sudo gpg --dearmor --output /usr/share/keyrings/1password-archive-keyring.gpg && \ > > echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/1password-archive-keyring.gpg] https://downloads.1password.com/linux/debian/$(dpkg --print-architecture) stable main" | \ > > sudo tee /etc/apt/sources.list.d/1password.list && \ > > sudo mkdir -p /etc/debsig/policies/AC2D62742012EA22/ && \ > > curl -sS https://downloads.1password.com/linux/debian/debsig/1password.pol | \ > > sudo tee /etc/debsig/policies/AC2D62742012EA22/1password.pol && \ > > sudo mkdir -p /usr/share/debsig/keyrings/AC2D62742012EA22 && \ > > curl -sS https://downloads.1password.com/linux/keys/1password.asc | \ > > sudo gpg --dearmor --output /usr/share/debsig/keyrings/AC2D62742012EA22/debsig.gpg && \ > > sudo apt update && sudo apt install 1password-cli > > ``` > > > [accordion] See a step-by-step version of the script > > > > > > 1. Add the key for the 1Password `apt` repository: > > > ```shell theme={null} > > > curl -sS https://downloads.1password.com/linux/keys/1password.asc | \ > > > sudo gpg --dearmor --output /usr/share/keyrings/1password-archive-keyring.gpg > > > ``` > > > 2. Add the 1Password `apt` repository: > > > ```shell theme={null} > > > echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/1password-archive-keyring.gpg] https://downloads.1password.com/linux/debian/$(dpkg --print-architecture) stable main" | > > > sudo tee /etc/apt/sources.list.d/1password.list > > > ``` > > > 3. Add the debsig-verify policy: > > > ```shell theme={null} > > > sudo mkdir -p /etc/debsig/policies/AC2D62742012EA22/ > > > curl -sS https://downloads.1password.com/linux/debian/debsig/1password.pol | \ > > > sudo tee /etc/debsig/policies/AC2D62742012EA22/1password.pol && \ > > > sudo mkdir -p /usr/share/debsig/keyrings/AC2D62742012EA22 && \ > > > curl -sS https://downloads.1password.com/linux/keys/1password.asc | \ > > > sudo gpg --dearmor --output /usr/share/debsig/keyrings/AC2D62742012EA22/debsig.gpg > > > ``` > > > 4. Install 1Password CLI: > > > ```shell theme={null} > > > sudo apt update && sudo apt install 1password-cli > > > ``` > > 2. Check that 1Password CLI installed successfully: > > ```shell theme={null} > > op --version > > ``` > > > > Alternatively, download the latest 1Password CLI `.deb` package directly from one of the following links: > > > > * [amd64](https://downloads.1password.com/linux/debian/amd64/stable/1password-cli-amd64-latest.deb) > > * [386](https://downloads.1password.com/linux/debian/386/stable/1password-cli-386-latest.deb) > > * [arm](https://downloads.1password.com/linux/debian/arm/stable/1password-cli-arm-latest.deb) > > * [arm64](https://downloads.1password.com/linux/debian/arm64/stable/1password-cli-arm64-latest.deb) > > > [tab] YUM > > > > To install 1Password CLI using YUM on RPM-based distributions: > > > > 1. Run the following commands: > > ```shell theme={null} > > sudo rpm --import https://downloads.1password.com/linux/keys/1password.asc > > sudo sh -c 'echo -e "[1password]\nname=1Password Stable Channel\nbaseurl=https://downloads.1password.com/linux/rpm/stable/\$basearch\nenabled=1\ngpgcheck=1\nrepo_gpgcheck=1\ngpgkey=\"https://downloads.1password.com/linux/keys/1password.asc\"" > /etc/yum.repos.d/1password.repo' > > sudo dnf check-update -y 1password-cli && sudo dnf install 1password-cli > > ``` > > > [accordion] The above script is comprised of the following steps > > > > > > 1. Import the public key: > > > ```shell theme={null} > > > sudo rpm --import https://downloads.1password.com/linux/keys/1password.asc > > > ``` > > > 2. Configure the repository information: > > > ```shell theme={null} > > > sudo sh -c 'echo -e "[1password]\nname=1Password Stable Channel\nbaseurl=https://downloads.1password.com/linux/rpm/stable/\$basearch\nenabled=1\ngpgcheck=1\nrepo_gpgcheck=1\ngpgkey=\"https://downloads.1password.com/linux/keys/1password.asc\"" > /etc/yum.repos.d/1password.repo' > > > ``` > > > 3. Install 1Password CLI: > > > ```shell theme={null} > > > sudo dnf check-update -y 1password-cli && sudo dnf install 1password-cli > > > ``` > > 2. Check that 1Password CLI installed successfully: > > ```shell theme={null} > > op --version > > ``` > > > > Alternatively, download the latest 1Password CLI `.rpm` package directly from one of the following links: > > > > * [x86\_64](https://downloads.1password.com/linux/rpm/stable/x86_64/1password-cli-latest.x86_64.rpm) > > * [i386](https://downloads.1password.com/linux/rpm/stable/i386/1password-cli-latest.i386.rpm) > > * [aarch64](https://downloads.1password.com/linux/rpm/stable/aarch64/1password-cli-latest.aarch64.rpm) > > * [armv7l](https://downloads.1password.com/linux/rpm/stable/armv7l/1password-cli-latest.armv7l.rpm) > > > [tab] Alpine > > > > To install 1Password CLI on Alpine x86\_64 distributions: > > > > 1. Run the following commands: > > ```shell theme={null} > > echo https://downloads.1password.com/linux/alpinelinux/stable/ >> /etc/apk/repositories > > wget https://downloads.1password.com/linux/keys/alpinelinux/support@1password.com-61ddfc31.rsa.pub -P /etc/apk/keys > > apk update && apk add 1password-cli > > ``` > > > [accordion] The above script is comprised of the following steps > > > > > > 1. Add Password CLI to your list of repositories: > > > ```shell theme={null} > > > echo https://downloads.1password.com/linux/alpinelinux/stable/ >> /etc/apk/repositories > > > ``` > > > 2. Add the public key to validate the APK to your keys directory: > > > ```shell theme={null} > > > wget https://downloads.1password.com/linux/keys/alpinelinux/support@1password.com-61ddfc31.rsa.pub -P /etc/apk/keys > > > ``` > > > 3. Install 1Password CLI: > > > ```shell theme={null} > > > apk update && apk add 1password-cli > > > ``` > > 2. Check that 1Password CLI installed successfully: > > ```shell theme={null} > > op --version > > ``` > > > [tab] NixOS > > > > > [!WARNING] > > > > > > The Nix package is available from the NixOS open source community. > > > > To install 1Password CLI on your NixOS system: > > > > 1. Add 1Password to your `/etc/nixos/configuration.nix` file, or `flake.nix` if you're using a flake. For example, the following snippet includes 1Password CLI and the 1Password app: > > ```nix theme={null} > > # NixOS has built-in modules to enable 1Password > > # along with some pre-packaged configuration to make > > # it work nicely. You can search what options exist > > # in NixOS at https://search.nixos.org/options > > # Enables the 1Password CLI > > programs._1password = { enable = true; }; > > # Enables the 1Password desktop app > > programs._1password-gui = { > > enable = true; > > # this makes system auth etc. work properly > > polkitPolicyOwners = [ "" ]; > > }; > > ``` > > 2. After you make changes to your configuration file, apply them: > > * If you added 1Password to `/etc.nixos/configuration.nix`, run: > > ```shell theme={null} > > sudo nixos-rebuild switch > > ``` > > * If you added 1Password to `flake.nix`, replace `` with the directory your flake is in and `` with the name of the flake output containing your system configuration, then run the command. > > ```shell theme={null} > > sudo nixos-rebuild switch --flake .# > > ``` > > 3. Check that 1Password CLI installed successfully: > > ```shell theme={null} > > op --version > > ``` > > > > Learn more about [using 1Password on NixOS.](https://nixos.wiki/wiki/1Password) > > > [tab] Manual > > > > You can run the following block of commands in your terminal to install 1Password CLI on Linux without a package manager. > > > > Before you run it, replace `` on the highlighted line. If you're not sure which one you need, run `uname -m`, then use the table to find the matching 1Password CLI build. > > > > | If `uname -m` returns | Replace `` with | > > | - | - | > > | `x86_64` | `amd64` | > > | `aarch64` or `arm64` | `arm64` | > > | `armv7l` or `armv6l` | `arm` | > > | `i386` or `i686` | `386` | > > > > ```shell highlight={2} theme={null} > > # Replace with amd64, arm64, arm, or 386 > > ARCH="" && \ > > OP_VERSION="v$(wget -qO- https://app-updates.agilebits.com/check/1/0/CLI2/en/2.0.0/N | grep -Eo '[0-9]+\.[0-9]+\.[0-9]+' | head -n1)" && \ > > [ "$OP_VERSION" != "v" ] || { echo "Couldn't determine the latest 1Password CLI version" >&2; exit 1; } && \ > > wget "https://cache.agilebits.com/dist/1P/op2/pkg/${OP_VERSION}/op_linux_${ARCH}_${OP_VERSION}.zip" -O op.zip && \ > > unzip -d op op.zip && \ > > sudo mv op/op /usr/local/bin/ && \ > > rm -r op.zip op && \ > > sudo groupadd -f onepassword-cli && \ > > sudo chgrp onepassword-cli /usr/local/bin/op && \ > > sudo chmod g+s /usr/local/bin/op > > ``` > > > > > [accordion] Or follow the extended guide > > > > > > 1. Download the [latest release of 1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) and extract it. To verify its authenticity: > > > ```shell theme={null} > > > gpg --keyserver keyserver.ubuntu.com --receive-keys 3FEF9748469ADBE15DA7CA80AC2D62742012EA22 > > > gpg --verify op.sig op > > > ``` > > > 2. Move `op` to `/usr/local/bin`, or another directory in your `$PATH`. > > > 3. Check that 1Password CLI installed successfully: > > > ```shell theme={null} > > > op --version > > > ``` > > > 4. Create the `onepassword-cli` group if it doesn't yet exist: > > > ```shell theme={null} > > > sudo groupadd onepassword-cli > > > ``` > > > 5. Set the correct permissions on the `op` binary: > > > ```shell theme={null} > > > sudo chgrp onepassword-cli /usr/local/bin/op && \ > > > sudo chmod g+s /usr/local/bin/op > > > ``` > [!TIP] > > **Installing inside WSL?** The desktop app integration authenticates over a local connection to the 1Password app on your Windows host, so it isn't available to a CLI binary installed inside the Linux side of WSL. Install 1Password CLI on Windows, then call the Windows `op.exe` from your WSL shell (or add it to your WSL `PATH`) — the same approach used by the [1Password SSH agent WSL integration](/ssh/integrations/wsl/). ## Step 2: Turn on the 1Password desktop app integration > [tab] Mac > > 1. Open and unlock the [1Password app](https://1password.com/downloads/). > 2. Select your account or collection at the top of the sidebar. > 3. Navigate to **Settings** > **Developer**. [Open Developer settings](onepassword://settings/developers) if 1Password is installed on this device. > 4. Select **Integrate with 1Password CLI**. > 5. If you want to authenticate 1Password CLI with your fingerprint, turn on **[Touch ID](https://support.1password.com/touch-id-mac/)** in the app. > > ![The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.](/static/img/developer-integrations-cli-light.png) > ![The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.](/static/img/developer-integrations-cli-dark.png) > [tab] Windows > > 1. Open and unlock the [1Password app](https://1password.com/downloads/). > 2. Select your account or collection at the top of the sidebar. > 3. Turn on **[Windows Hello](https://support.1password.com/windows-hello/)** in the app. > 4. Navigate to **Settings** > **Developer**. [Open Developer settings](onepassword://settings/developers) if 1Password is installed on this device. > 5. Select **Integrate with 1Password CLI**. > > ![The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.](/static/img/developer-integrations-cli-light.png) > ![The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.](/static/img/developer-integrations-cli-dark.png) > [tab] Linux > > 1. Open and unlock the [1Password app](https://1password.com/downloads/). > 2. Select your account or collection at the top of the sidebar. > 3. Navigate to **Settings** > **Security**. [Open Security settings](onepassword://settings/security) if 1Password is installed on this device. > 4. Turn on **[Unlock using system authentication](https://support.1password.com/system-authentication-linux/)**. > 5. Navigate to **Settings** > **Developer**. [Open Developer settings](onepassword://settings/developers) if 1Password is installed on this device. > 6. Select **Integrate with 1Password CLI**. > > ![The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.](/static/img/developer-integrations-cli-light.png) > ![The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.](/static/img/developer-integrations-cli-dark.png) [Learn more about the 1Password desktop app integration.](/cli/app-integration/) > [!TIP] > > You can also authenticate 1Password CLI using a [service account token](/service-accounts/get-started) scoped to specific vaults or Environments. We recommend using service accounts for shared building, automated access, and headless server authentication. ## Step 3: Enter any command to sign in After you've turned on the app integration, enter any command and you'll be prompted to authenticate. For example, run this command to see all the vaults in your account: ```shell theme={null} op vault list ``` #### If you have multiple accounts If you've added multiple 1Password accounts to your desktop app, you can use [`op signin`](/cli/reference/commands/signin/) to select an account to sign in to with 1Password CLI. Use the arrow keys to choose from the list of all accounts added to your 1Password app. ```shell highlight={2} theme={null} op signin #code-result Select account [Use arrows to move, type to filter] > ACME Corp (acme.1password.com) AgileBits (agilebits.1password.com) Add another account ``` [Learn more about using multiple accounts with 1Password CLI.](/cli/use-multiple-accounts/) #### If the app integration doesn't turn on A few things can block the **Integrate with 1Password CLI** toggle or the fingerprint prompt: * **Managed device policies**: If your 1Password account is managed by your organization, an administrator may need to turn on the CLI integration for your team before the toggle is available to you. Check with your 1Password administrator, or see [Set up your team to use 1Password developer tools](/get-started/administrator-quickstart#step-4-configure-team-policies). * **You're prompted for your Secret Key instead of a fingerprint**: This means the CLI is trying to sign in directly (`op signin`) instead of using the desktop app integration. Confirm the app integration toggle is turned on in **Settings > Developer**, then run a command again — you should see a fingerprint or system authentication prompt instead of a Secret Key field. * **No prompt appears at all**: Make sure the 1Password app is open and unlocked, and that you're running the command from the same user account the app is signed in to. ## Next steps 1. [Get started with basic 1Password CLI commands.](/cli/reference/) 2. [Set up 1Password Shell Plugins to handle authentication for your other command-line tools.](/cli/shell-plugins/) 3. [Learn how to securely load secrets from your 1Password account without putting any plaintext secrets in code.](/cli/secret-references/) ## Learn more * [1Password app integration troubleshooting](/cli/app-integration/#troubleshooting) * [1Password app integration security](/cli/app-integration-security/) * [How 1Password CLI detects configuration directories](/cli/config-directories) # Grant and revoke vault permissions Source: https://www.1password.dev/cli/grant-revoke-vault-permissions With 1Password CLI, you can manage the permissions each [user](/cli/reference/management-commands/vault/#vault-user) or [group](/cli/reference/management-commands/vault/#vault-group) has in each vault, so that everyone has access to the items they need. Some permissions require [dependent permissions](/cli/vault-permissions/). On interactive shells, you can specify any permission, and 1Password CLI will ask you whether you want to add or revoke dependent permissions. If you're using scripts, or your shell isn't interactive, you must [include dependent permissions](#scripting) in the command. [Learn what permissions are available for your account type.](/cli/vault-permissions/) ## Requirements Before you can use 1Password CLI to manage vault permissions, you'll need to: * [Sign up for 1Password](https://1password.com/pricing/password-manager) * [Install 1Password CLI](/cli/get-started/#step-1-install-1password-cli) You can manage vault permissions if you're an owner, administrator, or if you have the `manage_vault` permission in a vault. ## Grant permissions in vaults ### Users Use [`op vault user grant`](/cli/reference/management-commands/vault/#vault-user-grant) to grant a user permissions in a vault. For example, to grant the user Wendy Appleseed permission to edit items and manage vault permissions in the Prod vault: ```shell theme={null} op vault user grant --user wendy.appleseed@agilebits.com --vault Prod --permissions allow_editing,allow_managing ``` If the permissions you want to grant require dependent permissions to be granted alongside them, 1Password CLI will prompt you to grant those permissions: ``` In order to grant [allow_editing,allow_managing], the permission(s) [allow_viewing] are also required. Would you like to grant them as well? [Y/n] ``` To confirm which users have access to a vault and their current permissions: ```shell theme={null} op vault user list ``` ### Groups Use [`op vault group grant`](/cli/reference/management-commands/vault/#vault-group-grant) to grant a group permissions in a vault. For example, to grant the group IT permission to edit items and manage vault permissions in the Prod vault: ```shell theme={null} op vault group grant --group "IT" --vault Prod --permissions allow_editing,allow_managing ``` If the permissions you want to grant require dependent permissions to be granted alongside them, 1Password CLI will prompt you to grant those permissions: ``` In order to grant [allow_editing,allow_managing], the permission(s) [allow_viewing] are also required. Would you like to grant them as well? [Y/n] ``` To confirm which groups have access to a vault and their current permissions: ```shell theme={null} op vault group list ``` ## Revoke permissions in vaults ### Users Use [`op vault user revoke`](/cli/reference/management-commands/vault/#vault-user-revoke) to revoke a user's permissions in a vault. For example, to revoke the user Wendy Appleseed's permission to view items in the Prod vault: ```shell theme={null} op vault user revoke --user wendy.appleseed@agilebits.com --vault Prod --permissions allow_viewing ``` If the permission you want to revoke requires dependent permissions to be revoked alongside it, 1Password CLI will prompt you to revoke those permissions: ``` In order to revoke [allow_viewing], the permission(s) [allow_editing,allow_managing] are also required. Would you like to revoke them as well? [Y/n] ``` To confirm that the user's permissions have been revoked: ```shell theme={null} op vault user list ``` ### Groups Use [`op vault group revoke`](/cli/reference/management-commands/vault/#vault-group-grant) to revoke a group's permissions in a vault. For example, to revoke the group IT's permission to view items in the Prod vault: ```shell theme={null} op vault group revoke --group "IT" --vault Prod --permissions allow_viewing ``` If the permission you want to revoke requires dependent permissions to be revoked alongside it, 1Password CLI will prompt you to revoke those permissions: ``` In order to revoke [allow_viewing], the permission(s) [allow_editing,allow_managing] are also required. Would you like to revoke them as well? [Y/n] ``` To confirm the group's permissions have been revoked: ```shell theme={null} op vault group list ``` ## Scripting If you're using scripts to grant and revoke vault permissions, or if your shell isn't interactive, you'll need to include the `--no-input` flag and specify all [dependent permissions](/cli/vault-permissions/) in a comma-separated list after the `--permissions` flag. For example, the `allow_managing` permission requires the `allow_editing` and `allow_viewing` permission. To grant the user Wendy Appleseed permission to manage vault permissions in the Prod vault: ```shell theme={null} op vault user grant --no-input --user wendy.appleseed@agilebits.com --vault Prod --permissions allow_managing,allow_editing,allow_viewing ``` To revoke `allow_editing` from a group that currently also has `allow_managing` granted in a vault: ```shell theme={null} op vault group revoke --no-input --group "IT" --vault Prod --permissions allow_managing,allow_editing ``` ## Learn more * [Vault permission dependencies](/cli/vault-permissions/) * [Workflow: Programmatically manage your organization](/get-started/manage-organization) # Install 1Password CLI on a server Source: https://www.1password.dev/cli/install-server There are several different ways to install 1Password CLI on a server. To install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) on a Linux `amd64` host, you can use this one-line command: ```shell theme={null} ARCH="amd64"; \ OP_VERSION="v$(curl https://app-updates.agilebits.com/check/1/0/CLI2/en/2.0.0/N -s | grep -Eo '[0-9]+\.[0-9]+\.[0-9]+')"; \ curl -sSfo op.zip \ https://cache.agilebits.com/dist/1P/op2/pkg/"$OP_VERSION"/op_linux_"$ARCH"_"$OP_VERSION".zip \ && unzip -od /usr/local/bin/ op.zip \ && rm op.zip ``` To install with Docker, you can use the [1Password CLI 2 image](https://hub.docker.com/r/1password/op/tags) on Docker Hub: ```shell theme={null} docker pull 1password/op:2 ``` If you want to add the CLI installation to your Dockerfile, then add this line: ```docker Dockerfile theme={null} COPY --from=1password/op:2 /usr/local/bin/op /usr/local/bin/op ``` ## Learn more * [Install 1Password CLI on your machine](/cli/get-started/#step-1-install-1password-cli) # Create items Source: https://www.1password.dev/cli/item-create To create a new item in your 1Password account and assign information to it, use the [`op item create`](/cli/reference/management-commands/item/#item-create) command. You can [specify basic information about the item](#create-an-item) with flags and use assignment statements to [assign built-in and custom fields](#create-a-customized-item). To assign sensitive values, [use a JSON template](#with-an-item-json-template). ## Requirements Before you can use 1Password CLI to create items, you'll need to: * [Sign up for 1Password](https://1password.com/pricing/password-manager) * [Install 1Password CLI](/cli/get-started/#step-1-install-1password-cli) > [!NOTE] > > **Follow along** > > If you want to follow along with the examples in this guide, [sign in to your account](/cli/get-started/#step-3-enter-any-command-to-sign-in) then create a new vault named `Tutorial` where the example items will be saved: > > ```shell theme={null} > op vault create Tutorial > ``` ## Create an item To create a new item, use [`op item create`](/cli/reference/management-commands/item/#item-create) and specify basic information about the item with flags. For example, to create a Login item named `Netflix` in the `Tutorial` vault: > [tab] Bash, Zsh, sh, fish > > ```shell theme={null} > op item create \ > --category login \ > --title "Netflix" \ > --vault Tutorial \ > --url 'https://www.netflix.com/login' \ > --generate-password='letters,digits,symbols,32' \ > --tags tutorial,entertainment > ``` > [tab] PowerShell > > ```powershell theme={null} > op item create ` > --category login ` > --title "Netflix" ` > --vault Tutorial ` > --url 'https://www.netflix.com/login' ` > --generate-password='letters,digits,symbols,32' ` > --tags tutorial,entertainment > ``` Here's what each of the above flags does: `--category` Sets the [item category](https://support.1password.com/item-categories/), in this case a Login item. Use `op item template list` to get a list of available categories. The category value is case-insensitive and ignores whitespace characters. For example, the `Social Security Number` category can also be specified as `socialsecuritynumber`. `--title` Gives the item a name so that you can easily identify it. If unspecified, 1Password CLI selects a default name. For example, `Untitled Login item`. `--vault` Specifies which [vault](https://support.1password.com/create-share-vaults/) the item should be created in. If unspecified, the item will be created in 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. The name of this vault varies depending on your account type. `--url` Sets the website where 1Password suggests and fills a Login, Password, or API Credential item. `--generate-password` Generates a strong password for Login and Password category items. You can specify a password recipe, as shown in the example. If left unspecified, a default recipe will be used to generate a 32-character password consisting of letters, digits, and symbols. `--tags` Adds [tags](https://support.1password.com/favorites-tags/) to the item using a comma-separated list. ## Create a customized item Each item category has its own set of built-in fields that you can use to save more information to the item. You can also create custom fields to save additional details about the item. Learn more about [built-in and custom fields](/cli/item-fields/). You can assign built-in and custom fields to your item in two ways: * [With assignment statements](#with-assignment-statements) * [With an item JSON template](#with-an-item-json-template) ### With assignment statements > [!CAUTION] > > Command arguments can be visible to other processes on your machine. If you're assigning sensitive values, use [an item JSON template](#with-an-item-json-template) instead. The [`op item create`](/cli/reference/management-commands/item/#item-create) command can take a list of assignment statements as arguments to create fields on an item. Assignment statements are formatted like this: ```shell theme={null} [
.][[]]= ``` * `section` (Optional) The name of the section where you want to create the field. * `field` The name of the field you want to create. * `fieldType` The type of field you want to create. If unspecified, `fieldType` will default to `password`. * `value` The information you want to save in the field. For built-in fields, the `field` name should match the [built-in field `id`](/cli/item-fields/#built-in-fields) in the item category template. Don't include a `fieldType` for built-in fields. For custom fields, the `fieldType` should match the [custom field `type`](/cli/item-fields/#custom-fields) you want to create. The `field` name can be anything you want. If you need to use periods, equal signs, or backslashes in the name of a section or field, use a backslash character to escape them. Don't use backslashes to escape the `value`. Here's an example of an assignment statement for the built-in field `username` on a Login item, set to `john.doe@acme.org`: ```shell theme={null} 'username=john.doe@acme.org' ``` And here's an example of an assignment statement for a custom field type titled `date`, which is set to `2022-12-31`, in a field named `Renewal Date` within a section titled `Subscription Info`: ```shell theme={null} 'Subscription Info.Renewal Date[date]=2022-12-31' ``` To add both of the above assignment statements to a new item, `HBO Max`, in the `Tutorial` vault: > [tab] Bash, Zsh, sh, fish > > ```shell theme={null} > op item create \ > --category login \ > --title "HBO Max" \ > --vault Tutorial \ > --url 'https://www.hbomax.com' \ > --generate-password='letters,digits,symbols,32' \ > --tags tutorial,entertainment \ > 'username=john.doe@acme.org' \ > 'Subscription Info.Renewal Date[date]=2022-12-31' > ``` > [tab] PowerShell > > ```powershell theme={null} > op item create ` > --category login ` > --title "HBO Max" ` > --vault Tutorial ` > --url 'https://www.hbomax.com' ` > --generate-password='letters,digits,symbols,32' ` > --tags tutorial,entertainment ` > 'username=john.doe@acme.org' ` > 'Subscription Info.Renewal Date[date]=2022-12-31' > ``` ### With an item JSON template To assign sensitive values, fill out an item JSON template for the category of item you want to create. If you combine field assignment statements with a template, the assignment statements overwrite the template's values. To see a list of available templates, run [`op item template list`](/cli/reference/management-commands/item#item-template-list). To get a template for a category, run [`op item template get `](/cli/reference/management-commands/item#item-template-get). For example, to create a new Login item using a template: 1. Get the template for a Login item and save it in your current directory: ```shell theme={null} op item template get --out-file=login.json "Login" ``` 2. Edit [the template file](/cli/item-template-json/) to add your information. 3. Create the item using the `--template` flag to specify the path to the template file: ```shell theme={null} op item create --template=login.json ``` This example template file creates a Login item named `Hulu` in a vault [specified by its ID](/cli/reference/#unique-identifiers-ids). It specifies values for built-in `username`, `password`, and `notesPlain` fields. It also adds a custom `date` field. > [accordion] Example Login template > > ```json login.json theme={null} > { > "title": "Hulu", > "vault": { > "id": "sor33rgjjcg2xykftymcmqm5am" > }, > "category": "LOGIN", > "fields": [ > { > "id": "username", > "type": "STRING", > "purpose": "USERNAME", > "label": "username", > "value": "wendy.appleseed@gmail.com" > }, > { > "id": "password", > "type": "CONCEALED", > "purpose": "PASSWORD", > "label": "password", > "password_details": { > "strength": "" > }, > "value": "Dp2WxXfwN7VFJojENfEHLEBJmAGAxup@" > }, > { > "id": "notesPlain", > "type": "STRING", > "purpose": "NOTES", > "label": "notesPlain", > "value": "This is Wendy's Hulu account." > }, > { > "id": "date", > "type": "date", > "label": "Subscription renewal date", > "value": "2023-04-05" > } > ] > } > ``` 4. Delete the edited template file from your computer. You can also create an item from standard input using a template: ```shell theme={null} op item template get Login | op item create --vault Tutorial - ``` ## Create an item from an existing item You can create a new item from an existing item by piping the item JSON from standard input. For example, to create a new item based on the `HBO Max` item you created in the assignment statement section, with a new title, username, and password: ```shell theme={null} op item get "HBO Max" --format json | op item create --vault Tutorial --title "Wendy's HBO Max" - 'username=wendy.appleseed@acme.org' 'password=Dp2WxXfwN7VFJojENfEHLEBJmAGAxup@' ``` ## Add a one-time password to an item You can attach a [one-time password](https://support.1password.com/one-time-passwords/) to an item using a custom field [assignment statement](#with-assignment-statements). The `fieldType` should be `otp` and the `value` should be the [otpauth:// URI](https://github.com/google/google-authenticator/wiki/Key-Uri-Format) for the one-time password. > [tab] Bash, Zsh, sh, fish > > ```shell theme={null} > op item create \ > --category login \ > --title='My OTP Example' \ > --vault Tutorial \ > --url 'https://www.acme.com/login' \ > --generate-password='letters,digits,symbols,32' \ > --tags tutorial,entertainment \ > 'Test Section 1.Test Field3[otp]=otpauth://totp/:?secret=&issuer=' > ``` > [tab] PowerShell > > ```powershell theme={null} > op item create ` > --category login ` > --title='My OTP Example' ` > --vault Tutorial ` > --url 'https://www.acme.com/login' ` > --generate-password='letters,digits,symbols,32' ` > --tags tutorial,entertainment ` > 'Test Section 1.Test Field3[otp]=otpauth://totp/:?secret=&issuer=' > ``` ## Attach a file to an item You can attach a file to an item using a custom field [assignment statement](#with-assignment-statements). The `field` should be the name the file will have in 1Password, the `fieldType` should be `file`, and the `value` should be the path to the file. Include the file extension in the field name by [escaping the period with a backslash](#with-assignment-statements). This keeps the extension visible in 1Password instead of stripping it from the name. ```shell theme={null} JanuaryReceipt\.png[file]=/path/to/your/receipt.png ``` The file in the above example will be named `JanuaryReceipt.png`. To preserve the original file name from the path, you can omit the `field`: ```shell theme={null} [file]=/path/to/your/file ``` Here's what an example `PlayStation Store` login would look like with the file `/wendyappleseed/documents/receipt.png` attached, named `JanuaryReceipt.png`. > [tab] Bash, Zsh, sh, fish > > ```shell theme={null} > op item create \ > --category login \ > --title "PlayStation Store" \ > --vault Tutorial \ > --url 'https://store.playstation.com/' \ > --generate-password='letters,digits,symbols,32' \ > --tags tutorial,entertainment \ > 'JanuaryReceipt\.png[file]=/wendyappleseed/documents/receipt.png' > ``` > [tab] PowerShell > > ```powershell theme={null} > op item create ` > --category login ` > --title "PlayStation Store" ` > --vault Tutorial ` > --url 'https://store.playstation.com/' ` > --generate-password='letters,digits,symbols,32' ` > --tags tutorial,entertainment ` > 'JanuaryReceipt\.png[file]=/wendyappleseed/documents/receipt.png' > ``` ## Next steps If you want to continue learning about item management, keep the example items you created and move on to the [edit items](/cli/item-edit) tutorial. If you created a Tutorial vault and don't want to continue on, you can delete the vault and the examples items you created by running: ```shell theme={null} op vault delete "Tutorial" ``` ## Learn more * [`op item create` reference documentation](/cli/reference/management-commands/item#item-create) * [Built-in and custom item fields](/cli/item-fields) * [Item JSON template](/cli/item-template-json) * [Workflow: Build integrations with 1Password](/get-started/build-integrations) # Edit items Source: https://www.1password.dev/cli/item-edit To edit an existing item in your 1Password account, use the [`op item edit`](/cli/reference/management-commands/item#item-edit) command. You can [edit basic information about the item](#edit-an-item’s-basic-information) with flags and use assignment statements to [edit an item's built-in and custom fields](#edit-built-in-and-custom-fields). To edit sensitive values, [use a JSON template](#edit-an-item-using-a-json-template). You can't use `op item edit` to edit SSH keys. Learn more about [managing SSH keys](/cli/ssh-keys) with 1Password CLI. ## Requirements Before you can use 1Password CLI to edit items, you'll need to: * [Sign up for 1Password](https://1password.com/pricing/password-manager) * [Install 1Password CLI](/cli/get-started#step-1-install-1password-cli) > [!NOTE] > > **Follow along** > > If you want to follow along with the examples in this guide, [create the example items in the guide to creating items](/cli/item-create) first. ## Edit an item's basic information To edit an item, use [`op item edit`](/cli/reference/management-commands/item#item-edit) and specify the item by name, [unique identifier (ID)](/cli/reference#unique-identifiers-ids), or sharing link. You can use flags to generate a new password and edit an item's title, vault, or tags. You can also change the website where 1Password suggests and fills a Login, Password, or API Credential item. For example, to change the name of the example item `Netflix`, move it from the `Tutorial` vault to the `Private` vault, update its tags, edit its website, and generate a new random password: > [tab] Bash, Zsh, sh, fish > > ```shell theme={null} > op item edit "Netflix" \ > --title "Edited Netflix" \ > --vault Private \ > --tags tutorial \ > --url https://www.netflix.com \ > --generate-password='letters,digits,symbols,32' > > ``` > [tab] PowerShell > > ```powershell theme={null} > op item edit "Netflix" ` > --title "Edited Netflix" ` > --vault Private ` > --tags tutorial ` > --url https://www.netflix.com ` > --generate-password='letters,digits,symbols,32' > ``` To change the example item name back to `Netflix` and move it back to the `Tutorial` vault: > [tab] Bash, Zsh, sh, fish > > ```shell theme={null} > op item edit "Edited Netflix" \ > --title "Netflix" \ > --vault Tutorial > ``` > [tab] PowerShell > > ```powershell theme={null} > op item edit "Edited Netflix" ` > --title "Netflix" ` > --vault Tutorial > ``` ## Edit built-in and custom fields > [!CAUTION] > > Command arguments can be visible to other processes on your machine. To edit sensitive values, use [an item JSON template](#edit-an-item-using-a-json-template) instead. The `op item edit` command can take a list of assignment statements as arguments to edit an item's [built-in and custom fields](/cli/item-fields). ```shell theme={null} [
.][[]]= ``` * `section` (Optional) The name of the section where the field is saved. * `field` The name of the field. * `fieldType` The type of field. If unspecified, the fieldType stays the same. * `value` The information you want to save in the field. If unspecified, the value stays the same. For example, to change the subscription renewal date on the `HBO Max` item: > [tab] Bash, Zsh, sh, fish > > ```shell theme={null} > op item edit "HBO Max" \ > 'Renewal Date=2023-5-15' > ``` > [tab] PowerShell > > ```powershell theme={null} > op item edit "HBO Max" ` > 'Renewal Date=2023-5-15' > ``` ### Delete a custom field To delete a custom field, specify `[delete]` in place of the fieldType. If you remove all the fields in a section, the section is also removed. You can't delete empty fields, but you can set them to empty strings. To use an assignment statement to delete the subscription renewal date on the example `HBO Max` item: > [tab] Bash, Zsh, sh, fish > > ```shell theme={null} > op item edit "HBO Max" \ > 'Renewal Date[delete]=2023-5-15' > ``` > [tab] PowerShell > > ```powershell theme={null} > op item edit "HBO Max" ` > 'Renewal Date[delete]=2023-5-15' > ``` ## Edit an item using a JSON template > [!CAUTION] > > JSON item templates do not support passkeys. If you use a JSON template to update an item that contains a passkey, the passkey will be overwritten. To fix this, you can [restore a previous version of the item](https://support.1password.com/item-history/). To edit sensitive values on an item, use an [item JSON template](/cli/item-template-json). 1. Get the JSON output for the item you want to edit and save it to a file. ```shell theme={null} op item get --format json > newItem.json ``` If you prefer to start over, you can get a blank template for the item's category with [`op item template get`](/cli/reference/management-commands/item#item-template-get). 2. Edit the file. 3. Use the `--template` flag to specify the path to the edited file and apply the changes to the item: ```shell theme={null} op item edit --template=newItem.json ``` 4. Delete the file. You can also edit an item using piped input: ```shell theme={null} cat newItem.json | op item edit ``` To avoid collisions, you can't combine piped input and the `--template` flag in the same command. ## Next steps If you created a Tutorial vault, you can delete the vault and the examples items you created: ```shell theme={null} op vault delete "Tutorial" ``` ## Learn more * [`op item` reference documentation](/cli/reference/management-commands/item) * [Built-in and custom item fields](/cli/item-fields) * [Item JSON template](/cli/item-template-json) * [Workflow: Build integrations with 1Password](/get-started/build-integrations) # Item fields Source: https://www.1password.dev/cli/item-fields When you [use 1Password CLI to create items](/cli/item-create/), you can customize your items with [built-in](#built-in-fields) and [custom](#custom-fields) fields. Learn how to [add built-in and custom fields to your items](/cli/item-create/#create-a-customized-item) with either assignment statements or a JSON template. ## Built-in fields Each item category includes a set of default fields, some of which may be specific to the category. You can identify available built-in fields by looking at the [JSON template](/cli/item-template-json/) for the item category: ``` op item template get ``` > [accordion] View all categories > > * API Credential > * Bank Account > * Credit Card > * Crypto Wallet > * Database > * Document > * Driver License > * Email Account > * Identity > * Login > * Medical Record > * Membership > * Outdoor License > * Passport > * Password > * Reward Program > * Secure Note > * Server > * Social Security Number > * Software License > * SSH Key > * Wireless Router For example, the built-in fields available on a Login item are `username`, `password`, and `notesPlain`. > [accordion] View a Login item JSON template > > ```shell highlight={6,13,23} theme={null} > { > "title": "", > "category": "LOGIN", > "fields": [ > { > "id": "username", > "type": "STRING", > "purpose": "USERNAME", > "label": "username", > "value": "" > }, > { > "id": "password", > "type": "CONCEALED", > "purpose": "PASSWORD", > "label": "password", > "password_details": { > "strength": "TERRIBLE" > }, > "value": "" > }, > { > "id": "notesPlain", > "type": "STRING", > "purpose": "NOTES", > "label": "notesPlain", > "value": "" > } > ] > } > ``` When you use [assignment statements](/cli/item-create/#with-assignment-statements) to assign built-in fields, use the `id` from the JSON template as the `field` in the assignment statement. Don't include a fieldType for built-in fields. For example, to add a note to a Login item using an assignment statement: ```shell theme={null} 'notesPlain=This is a note.' ``` ## Custom fields Custom fields can be added to any item, regardless of the item's category. Use the `fieldType` with [assignment statements](/cli/item-create/#with-assignment-statements) and the `type` with an [item JSON template](/cli/item-create/#with-an-item-json-template). Available custom field types are: | `fieldType` | `type` | description | | - | - | - | | `password` | `CONCEALED` | A concealed password. | | `text` | `STRING` | A text string. | | `email` | `EMAIL` | An email address. | | `url` | `URL` | A web address to copy or open in your default web browser, not used for autofill behavior. Use the `--url` flag to set the website where 1Password suggests and fills a Login, Password, or API Credential item. | | `date` | `DATE` | A date with the format `YYYY-MM-DD`. | | `monthYear` | `MONTH_YEAR` | A date with the format `YYYYMM` or `YYYY/MM`. | | `phone` | `PHONE` | A phone number. | | `otp` | `OTP` | A one-time password. Accepts an [`otpauth://` URI](https://github.com/google/google-authenticator/wiki/Key-Uri-Format) as the value. | | `file` | N/A | A file attachment. Accepts the path to the file as the value. Can only be added with [assignment statements](/cli/item-create/#with-assignment-statements). | ## Learn more * [`op item` reference documentation](/cli/reference/management-commands/item/) * [Create an item](/cli/item-create/) * [Item JSON template](/cli/item-template-json/) * [Workflow: Build integrations with 1Password](/get-started/build-integrations) # Item JSON template Source: https://www.1password.dev/cli/item-template-json 1Password CLI supports item JSON templates that you can use to take control of how you create items in 1Password. Item JSON templates allow you to [create an item with all of its details specified](/cli/item-create/#with-an-item-json-template), including custom sections and fields. Item templates are formatted similarly to the JSON output for [`op item get`](/cli/reference/management-commands/item/#item-get), so you can easily create new items based on existing items. Each item category has its own template. You can get a list of all item categories with [`op item template list`](/cli/reference/management-commands/item/#item-template-list). And you can retrieve the template for an item category with [`op item template get `](/cli/reference/management-commands/item/#item-template-get). ## Item template keys Item JSON templates have common language keys that allow you to identify how the fields in the template correspond to the item in 1Password. ```json theme={null} { "title": " ", "category": " ", "sections": [ { "id": " ", "label": " " }, ], "fields": [ { "id": " ", "section": { "id": " " }, "type": " ", "label": " ", "value": " " } ] } ``` **Item** | Name | Description | | - | - | | `title` | The name of the item displayed in 1Password. | | `category` | The item's category. | **Section** | Name | Description | | - | - | | `id` | The identifier for the section. If the item has multiple sections, each ID must be unique. | | `label` | The name of the section displayed in 1Password. | To add a custom section, insert a section JSON object into the `sections` array. > [accordion] View a section JSON object > > ```json theme={null} > { > "id": " ", > "label": " " > } > ``` **Field** | Name | Description | | - | - | | `id` | The field's ID. Each ID should be unique. If left empty, 1Password will generate a random ID. | | `section id` | The ID of the section where the field is located. Only required if located in a custom section. | | `type` | The field's type. [Learn more about custom field types.](/cli/item-fields/#custom-fields) | | `label` | The name of the field displayed in 1Password. | | `value` | The information saved in the field. Depending on its type, it can be a string, a secret, a number, or a date. | To add a custom field to the template, insert a new field JSON object into the `fields` array. > [accordion] View a field JSON object > > ```json theme={null} > { > "id": " ", > "section": { > "id": " " > }, > "type": " ", > "label": " ", > "value": " " > } > ``` ## Example JSON representation This is an item `mysql` in the 1Password app, and the same item represented in an item JSON template. > [tab] In the app > > ![MySQL item in 1Password](https://mintcdn.com/ab-634991b8/pfc4yDcmGyZA8XDs/static/img/cli/mysql-item.png?fit=max\&auto=format\&n=pfc4yDcmGyZA8XDs\&q=85\&s=9b26f9b25150e46eda39454eb355ba38) > [tab] In the JSON template > > ```json theme={null} > { > "id": "4l3udxihvvuhszh2kxyjbblxl4", > "title": "mysql", > "version": 3, > "vault": { > "id": "uteieiwkhgv6hau7xkorejyvru" > }, > "category": "DATABASE", > "last_edited_by": "IU2OKUBKAFGQPFPFZEG7X3NQ4U", > "created_at": "2021-11-25T14:50:14Z", > "updated_at": "2022-02-25T18:12:12Z", > "sections": [ > { > "id": "g52gfotnw7nhnkgq477si2hmmi", > "label": "Database Owner" > } > ], > "fields": [ > { > "id": "notesPlain", > "type": "STRING", > "purpose": "NOTES", > "label": "notesPlain" > }, > { > "id": "database_type", > "type": "MENU", > "label": "type", > "value": "mysql" > }, > { > "id": "hostname", > "type": "STRING", > "label": "server", > "value": "http://localhost" > }, > { > "id": "port", > "type": "STRING", > "label": "port", > "value": "5432" > }, > { > "id": "database", > "type": "STRING", > "label": "database", > "value": "app-database" > }, > { > "id": "username", > "type": "STRING", > "label": "username", > "value": "mysql-user" > }, > { > "id": "password", > "type": "CONCEALED", > "label": "password", > "value": "T4Kn7np2bLJXAFoYPoVC" > }, > { > "id": "sid", > "type": "STRING", > "label": "SID" > }, > { > "id": "alias", > "type": "STRING", > "label": "alias" > }, > { > "id": "options", > "type": "STRING", > "label": "connection options" > }, > { > "id": "tpcs7jrjikehw5o4tzbe5pklca", > "section": { > "id": "g52gfotnw7nhnkgq477si2hmmi", > "label": "Database Owner" > }, > "type": "STRING", > "label": "admin", > "value": "Wendy Appleseed" > }, > { > "id": "sdqueijyulxryvu5ceuwktjkiq", > "section": { > "id": "g52gfotnw7nhnkgq477si2hmmi", > "label": "Database Owner" > }, > "type": "EMAIL", > "label": "email", > "value": "appleseed.wendy@gmail.com" > } > ] > } > ``` ## Learn more * [Create an item](/cli/item-create/) * [Work with items](/cli/reference/management-commands/item/) * [Work with vaults](/cli/reference/management-commands/vault/) * [Workflow: Build integrations with 1Password](/get-started/build-integrations) # Add and remove team members Source: https://www.1password.dev/cli/provision-users ## Requirements Before you can use 1Password CLI to add and remove team members, you'll need to: 1. [Sign up for 1Password Business](https://1password.com/pricing/password-manager). 2. [Install 1Password CLI](/cli/get-started/#step-1-install-1password-cli). If you use [automated provisioning hosted by 1Password](https://support.1password.com/provisioning/), you'll also need to [complete a one-time setup](#with-automated-provisioning) before managing users with the CLI. ## Set up provisioning ### With automated provisioning > [!NOTE] > > Support for automated provisioning hosted by 1Password is available in [the latest beta build of 1Password CLI](https://app-updates.agilebits.com/product_history/CLI2#beta), version `2.36.0-beta-02` or later. If your account uses [automated provisioning hosted by 1Password](https://support.1password.com/provisioning/), you'll need to run a one-time setup command before you can manage users with the CLI. Skip this section if your account doesn't use automated provisioning. Run `op provisioning configure` with your provisioning token and SCIM URL. The `--token` value must be a [secret reference](/cli/secret-references) that points to the vault, item, and field where your token is stored in your 1Password account (for example, `op://vault-name/item-name/field-name`). The `--url` flag accepts the SCIM URL as plaintext or as a secret reference. For example: ```shell theme={null} op provisioning configure --token --url ``` > [!WARNING] > > After you create users with the CLI with automated provisioning enabled, automated provisioning must remain enabled on the account. Users created this way are placed in provisioning-specific states. If automated provisioning is removed from the account, the CLI will return an error when attempting to suspend or reactivate those users. ### With 1Password CLI If you don't use automated provisioning, an owner or administrator must visit the [Provisioning settings page on 1Password.com](https://start.1password.com/settings/provisioning/cli) and select **Turn On CLI Provisioning**. This will create a [Provision Managers](https://support.1password.com/groups/#provision-managers) group with the permissions needed to provision and confirm team members, as well as recover accounts. The person who created the group will be added to it. ## Manage who can provision team members By default, the owner or administrator who created the [Provision Managers](https://support.1password.com/groups/#provision-managers) group is the only person added to it. If other team members need to be able to provision users, use [`op group user grant`](/cli/reference/management-commands/group/#group-user-grant) to add them to the group. For example, to add Wendy Appleseed to the Provision Managers group: ```shell theme={null} op group user grant --group "Provision Managers" --user "wendy.appleseed@agilebits.com" ``` To see a list of everyone in the Provision Managers group: ```shell theme={null} op group user list "Provision Managers" ``` ## Add team members To invite people to your team, use [`op user provision`](/cli/reference/management-commands/user/#user-provision) with the team member's name and email address. For example, to invite Wendy Appleseed to join your 1Password account: ```shell theme={null} op user provision --name "Wendy Appleseed" --email "wendy.appleseed@agilebits.com" ``` The person will receive an email invitation to join the team. After they've accepted the invitation, a member of the Provision Managers group can confirm them. ## Confirm team members > [!NOTE] > > If your account uses automated provisioning, users are confirmed automatically. You can skip this section. Anyone who belongs to the [Provision Managers](https://support.1password.com/groups/#provision-managers) group can confirm new team members with [`op user confirm`](#with-op-user-confirm) or [on 1Password.com](#on-1password-com). ### With `op user confirm` To confirm a team member on the command line, use [`op user confirm`](/cli/reference/management-commands/user/#user-confirm) with their name or email address. To confirm all unconfirmed team members, include the `--all` flag. For example, to confirm Wendy Appleseed: ```shell theme={null} op user confirm "wendy.appleseed@agilebits.com" ``` To confirm all pending users: ```shell theme={null} op user confirm --all ``` ### On 1Password.com To confirm a team member on 1Password.com: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select **[People](https://start.1password.com/people)** in the sidebar. 3. Select the name of any team member with the Pending Provision status. 4. Select **Confirm** or **Reject**. If you don't see the option to confirm or reject a team member, ask your administrator to [add you to the Provision Managers group](#manage-who-can-provision-team-members). ## Remove team members To remove someone's access to vaults and items, you can suspend or delete their account. ### Suspend an account temporarily Use [`op user suspend`](/cli/reference/management-commands/user/#user-suspend) to suspend a team member temporarily. Include the `--deauthorize-devices-after` flag, followed by the number of seconds, minutes, or hours (for example, `600s`, `10m`, or `1h`) to set the time after suspension to deauthorize the suspended team member's devices. The maximum time permitted is 24 hours. If unspecified, their devices will be deauthorized immediately. > [!NOTE] > > If your account uses automated provisioning, the `--deauthorize-devices-after` flag is ignored. The provisioning service always deauthorizes devices after 10 minutes. For example, to suspend Wendy Appleseed temporarily and deauthorize her devices after 10 minutes: ```shell theme={null} op user suspend "wendy.appleseed@agilebits.com --deauthorize-devices-after 10m" ``` You can reactivate a suspended user with [`op user reactivate`](/cli/reference/management-commands/user/#user-reactivate). ### Remove an account permanently Use [`op user delete`](/cli/reference/management-commands/user/#user-delete) to permanently remove a team member's access to vaults and items and delete all of their data from the account. For example, to remove Wendy Appleseed: ```shell theme={null} op user delete "wendy.appleseed@agilebits.com" ``` ## Learn more * [Add and remove team members on 1Password.com](https://support.1password.com/add-remove-team-members/) * [Set up automated provisioning](https://support.1password.com/provisioning/) * [Workflow: Programmatically manage your organization](/get-started/manage-organization) # Recover accounts using 1Password CLI Source: https://www.1password.dev/cli/recover-users You can use 1Password CLI to begin the account recovery process for a family or team member if they can't sign in to or unlock 1Password. When you recover an account for someone: * They'll receive a new Secret Key and create a new 1Password account password.\ If your team uses Unlock with SSO, they'll be able to [link a new app or browser to their account](https://support.1password.com/sso-linked-apps-browsers/) again. * They'll be able to access all the data they had before. * They'll need to sign in again on all their devices once recovery is complete. * Their two-factor authentication will be reset. ## Requirements * [Sign up for 1Password](https://1password.com/pricing/password-manager). * [Install 1Password CLI](/cli/get-started#step-1-install-1password-cli) version `2.32.0` or later. You can recover accounts for other people if: * You're a team [administrator](https://support.1password.com/groups/#administrators) or [owner](https://support.1password.com/groups/#owners). * You belong to a [custom group](https://support.1password.com/custom-groups/) that has the "Recover Accounts" permission. * You're a [family organizer](https://support.1password.com/family-organizer/). ## Begin recovery Use the command `op user recovery begin` with a person's name, email address, or [unique identifier (ID)](/cli/reference/#unique-identifiers-ids) to begin the account recovery process. You can recover up to ten accounts with each command. ```shell theme={null} op user recovery begin { | | } ``` For example, to begin recovery for multiple accounts using each person's ID: ```shell theme={null} op user recovery begin ZMAE4RTRONHN7LGELNYYO373KM WHPOFIMMYFFITBVTOTZUR3R324 FGH76DFS89FYCU6342CSDWIFJU ``` The person whose account you're recovering will get an email from 1Password. When they select **Recover my account** in the email, a page will open in their browser and they'll be asked to confirm their email address. Then they'll get a new Secret Key and create a new account password. ## Complete recovery After the person whose account you recovered creates a new account password, you'll need to complete the recovery process before they can access their account. Learn how to [complete account recovery for one or more people](https://support.1password.com/recovery/#complete-recovery). ## Learn more * [Add and remove team members](/cli/provision-users) * [Grant and revoke vault permissions](/cli/grant-revoke-vault-permissions) * [Sign back in to 1Password after your account has been recovered](https://support.1password.com/after-recovery/) * [Workflow: Programmatically manage your organization](/get-started/manage-organization) # 1Password CLI reference Source: https://www.1password.dev/cli/reference > [!NOTE] > > **Get started** > > If you're new to 1Password CLI, [learn how to set it up and sign in to your account](/cli/get-started/). ## Command structure ``` op [command] ``` 1Password CLI uses a noun-verb command structure that groups commands by topic rather than by operation. The basic structure of a command starts with the 1Password program `op`, then the `command name (noun)`, often followed by a `subcommand (verb)`, then `flags` (which include additional information that gets passed to the command). For example, to retrieve a list of all the items in your Private vault: ```shell theme={null} op item list --vault Private ``` To get a list of all global commands and flags, run the following: ​ ```shell theme={null} op --help ``` ## Command reference * [account](/cli/reference/management-commands/account): Manage your locally configured 1Password accounts * [completion](/cli/reference/commands/completion): Generate shell completion information * [connect](/cli/reference/management-commands/connect): Manage Connect server instances and tokens in your 1Password account * [document](/cli/reference/management-commands/document): Perform CRUD operations on Document items in your vaults * [environment](/cli/reference/management-commands/environment): Manage your 1Password Environments and their secrets * [events-api](/cli/reference/management-commands/events-api): Manage Events API integrations in your 1Password account * [group](/cli/reference/management-commands/group): Manage the groups in your 1Password account * [inject](/cli/reference/commands/inject): Inject secrets into a config file * [item](/cli/reference/management-commands/item): Perform CRUD operations on the 1Password items in your vaults * [plugin](/cli/reference/management-commands/plugin): Manage the shell plugins you use to authenticate third-party CLIs * [provisioning](/cli/reference/management-commands/provisioning): Manage provisioning integration settings * [read](/cli/reference/commands/read): Read a secret reference * [run](/cli/reference/commands/run): Pass secrets as environment variables to a process * [service-account](/cli/reference/management-commands/service-account): Manage service accounts * [signin](/cli/reference/commands/signin): Sign in to a 1Password account * [signout](/cli/reference/commands/signout): Sign out of a 1Password account * [update](/cli/reference/commands/update): Check for and download updates * [user](/cli/reference/management-commands/user): Manage users within this 1Password account * [vault](/cli/reference/management-commands/vault): Manage permissions and perform CRUD operations on your 1Password vaults * [whoami](/cli/reference/commands/whoami): Get information about a signed-in account ## Global flags ``` --account string Select the account to execute the command by account shorthand, sign-in address, account ID, or user ID. For a list of available accounts, run 'op account list'. Can be set as the OP_ACCOUNT environment variable. --cache Store and use cached information. Caching is enabled by default on UNIX-like systems. Caching is not available on Windows. Options: true, false. Can also be set with the OP_CACHE environment variable. (default true) --config directory Use this configuration directory. --debug Enable debug mode. Can also be enabled by setting the OP_DEBUG environment variable to true. --encoding type Use this character encoding type. Default: UTF-8. Supported: SHIFT_JIS, gbk. --format string Use this output format. Can be 'human-readable' or 'json'. Can be set as the OP_FORMAT environment variable. (default "human-readable") -h, --help Get help for op. --iso-timestamps Format timestamps according to ISO 8601 / RFC 3339. Can be set as the OP_ISO_TIMESTAMPS environment variable. --no-color Print output without color. --session token Authenticate with this session token. 1Password CLI outputs session tokens for successful `op signin` commands when 1Password app integration is not enabled. ``` ## Unique identifiers (IDs) When you retrieve information about an object using the `get` and `list` subcommands, you'll see a string of 26 numbers and letters that make up the object's unique identifier (ID). You can use names or IDs in commands that take any [account](/cli/reference/management-commands/account/#account-get), [user](/cli/reference/management-commands/user/#user-get), [vault](/cli/reference/management-commands/vault/#vault-get), or [item](/cli/reference/management-commands/item/#item-get) as an argument. IDs are the most stable way to reference an item. An item's ID only changes when you move the item to a different vault. Commands provided with an ID are also faster and more efficient. You can get information about an item, including the item's ID and the ID for the vault where it's stored, with [`op item get`](/cli/reference/management-commands/item#item-get). ```shell theme={null} op item get Netflix #code-result ID: t2Vz6kMDjByzEAcq6peKnHL4k3 Title: Netflix Vault: Private (sdfsdf7werjgdf8gdfgjdfgkj) Created: 6 months ago Updated: 1 month ago by Wendy Appleseed Favorite: false Version: 1 Category: LOGIN ``` To only fetch the item ID, use the same command with the format set to JSON, then use [jq](https://jqlang.github.io/jq/) to parse the output. ```shell theme={null} op item get Netflix --format json | jq .id #code-result "t2Vz6kMDjByzEAcq6peKnHL4k3" ``` To get the IDs for all vaults in an account: ```shell theme={null} op vault list #code-result ID NAME cfqtakqiutfhiewomztljx4woy Development rr3ggvrlr6opoete23q7c22ahi Personal 2gq6v6vzorl7jfxdurns4hl66e Work ``` ## Shell completion You can add shell completion so that 1Password CLI automatically completes your commands. With shell completion enabled, start typing an `op` command, then press Tab to see the available commands and options. > [tab] Bash > > To enable shell completion with Bash: > > 1. Install the bash-completion package > 2. Add this line to your `.bashrc` file: > > ``` > source <(op completion bash) > ``` > [tab] Zsh > > To enable shell completion with Zsh, add this line to your `.zshrc` file: > > ``` > eval "$(op completion zsh)"; compdef _op op > ``` > [tab] fish > > To enable shell completion with fish, add this to your `.fish` file: > > ``` > op completion fish | source > ``` > [tab] PowerShell > > To enable shell completion with PowerShell, add this to your `.ps1` file: > > ```powershell theme={null} > op completion powershell | Out-String | Invoke-Expression > ``` > > You'll need to enable script execution in PowerShell to start using shell completion. To do that, start a PowerShell window as an administrator and enter: > > ```powershell theme={null} > Set-ExecutionPolicy -ExecutionPolicy RemoteSigned > ``` ## Cache item and vault information 1Password CLI can use its daemon process to cache items, vault information, and the keys to access information in an account. The daemon stores encrypted information in memory using the same encryption methods as on 1Password.com. It can read the information to pass to 1Password CLI, but can’t decrypt it. On UNIX-like systems, caching between commands is enabled by default. This helps maximize performance and reduce the number of API calls. If you use 1Password CLI in an environment where caching is not possible, you can turn it off by appending the `--cache=false` flag to your commands, or by setting the `OP_CACHE` environment variable to false. Caching is not currently available on Windows. ## Alternative character encoding By default, 1Password CLI processes input and output with UTF-8 encoding. You can use an alternative character encoding with the `--encoding` option. Supported alternative character encoding types: * `gbk` * `shift-jis` ## Parse JSON output with jq You can use the `--format` flag or the `OP_FORMAT` environment variable to set your 1Password CLI command output to `json`. To parse JSON output, we recommend using the command-line tool [jq.](https://jqlang.github.io/jq/) For example, to use jq to retrieve a secret reference for the password saved on an item named `GitHub`: ```shell theme={null} op item get GitHub --format json --fields password | jq .reference #code-result "op://development/GitHub/password" ``` ## Beta builds To download 1Password CLI beta builds, navigate to the [1Password CLI downloads page](https://app-updates.agilebits.com/product_history/CLI2#beta) with the **Show betas** option selected. On Linux, you can switch the channel from "stable" to "beta" when adding the 1Password repository in your package manager. ## Example commands ### Items To get information about an item: ```shell theme={null} op item get ``` You'll see the item's [ID](#unique-identifiers-ids), title, vault, when it was created, when it was last modified, the item's version, if it's marked as a favorite, the type of item it is, and the item's fields. If an item name includes spaces or special characters, enclose it in quotes. For example: ```shell theme={null} op item get "work email" #code-result ID: a5w3is43ohs25qonzajrqaqx4q Title: work email Vault: Work (2gq6v6vzorl7jfxdurns4hl66e) Created: 6 years ago Updated: 9 months ago by Wendy Appleseed Favorite: true Version: 1 Category: LOGIN Fields: username: wendy.c.appleseed@agilebits.com password: NLuXcEtg27JMjGmiBHXZMGCgce URLs: website: https://www.gmail.com (primary) ``` To use `op item get` to retrieve specific fields, include the `--fields` flag followed by a comma-separated list, with the prefix `label=` before each field name. For example, to only retrieve the username and password for the item `work email`: ```shell theme={null} op item get "work email" --fields label=username,label=password #code-result wendy.c.appleseed@agilebits.com,NLuXcEtg27JMjGmiBHXZMGCgce ``` Learn more about working with [items](/cli/reference/management-commands/item/). ### Users and groups To get details about a user: ```shell theme={null} op user get "Wendy Appleseed" #code-result ID: SPRXJFTDHTA2DDTPE5F7DA64RQ Name: Wendy Appleseed Email: wendy.c.appleseed@agilebits.com State: ACTIVE Type: MEMBER Created: 6 years ago Updated: 4 months ago Last Authentication: 1 month ago ``` To list the users who belong to a group: ``` op group user list "Provision Managers" #code-result ID NAME EMAIL STATE TYPE ROLE 7YEOODASGJE6VAEIOHYWGP33II Wendy Appleseed wendy.c.appleseed@agilebits.com ACTIVE MEMBER UKCYFVOJSFEXLKKZREG7M2MZWM Johnny Appleseed johnny.appleseed@agilebits.com RECOVERY_STARTED MEMBER ``` Learn more about working with [users](/cli/reference/management-commands/user/) and [groups](/cli/reference/management-commands/group/). ### Vaults To create a new vault named `Test`: ```shell theme={null} op vault create Test ``` To get details about an existing vault: ```shell theme={null} op vault get Work #code-result ID: jAeq2tfunmifZfG4WkuWvsaGGj Name: Work Type: USER_CREATED Attribute version: 3 Content version: 241 Items: 25 Created: 1 year ago Updated: 1 month ago ``` To list the vaults in an account: ```shell theme={null} op vault list #code-result ID NAME vw8qjYEvsdCcZoULJRCqopy7Rv Development 2RNjh43dpHB9sDqZXEHiiw7zTe Personal cGxbZbV2pxKBmVJe9oWja4K8km Work ``` Learn more about working with [vaults](/cli/reference/management-commands/vault/). ### Secrets To insert a secret into an environment variable, config file, or script without putting the plaintext secret in code, use a [secret reference](/cli/secret-reference-syntax/) that specifies where the secret is stored in your 1Password account: ``` op://vault-name/item-name/[section-name/]field-name ``` Then, you can use [`op read`](/cli/reference/commands/read/), [`op run`](/cli/reference/commands/run/), or [`op inject`](/cli/reference/commands/inject/) to replace the secret reference with the actual secret at runtime. To resolve a secret reference and confirm it outputs correctly: ```shell theme={null} op read "op://Work/work email/username" #code-result wendy.c.appleseed@agilebits.com ``` Learn more about [loading secrets](/cli/secret-references/). ## Get help For help with any command, use the `--help` option: ``` op [subcommand] --help ``` # completion Source: https://www.1password.dev/cli/reference/commands/completion Generate shell completion information for 1Password CLI. ```shell theme={null} op completion [flags] ``` If you use Bash, Zsh, fish, or PowerShell, you can add shell completion for 1Password CLI. With completions loaded, after you start typing a command, press Tab to see available commands and options. #### Load shell completion information for Bash To always load the completion information for Bash, add this to your `.bashrc` file: ```shell theme={null} source <(op completion bash) ``` To use shell completion in Bash, you’ll need the `bash-completion` package. #### Load shell completion information for Zsh To always load the completion information for Zsh, add this to your `.zshrc` file: ```shell theme={null} eval "$(op completion zsh)"; compdef _op op ``` #### Load shell completion information for fish To always load the completion information for fish, add this to your `.fish` file: ```shell theme={null} op completion fish | source ``` #### Load shell completion information for PowerShell To always load the completion information for PowerShell, add this to your `.ps1` file: ```powershell theme={null} op completion powershell | Out-String | Invoke-Expression ``` > [!NOTE] > > To use shell completion in PowerShell, you need to enable > execution of scripts. To do that, start a PowerShell window as > administrator and run the following command: ```powershell theme={null} Set-ExecutionPolicy -ExecutionPolicy RemoteSigned ``` # inject Source: https://www.1password.dev/cli/reference/commands/inject Inject secrets into a file templated with secret references. ``` op inject [flags] ``` ### Flags ``` --file-mode filemode Set filemode for the output file. It is ignored without the --out-file flag. (default 0600) -f, --force Do not prompt for confirmation. -i, --in-file string The filename of a template file to inject. -o, --out-file string Write the injected template to a file instead of stdout. ``` [Learn more about secret references.](/cli/secret-references) You can pass in a config file templated with secret references and receive a config file with the actual secrets substituted. Make sure to delete the resolved file when you no longer need it. [Learn more about loading secrets into config files.](/cli/secrets-config-files) ### Examples Inject secrets into a config template from stdin: ``` echo "db_password: {{ op://app-prod/db/password }}" | op inject db_password: fX6nWkhANeyGE27SQGhYQ ``` Inject secrets into a config template file: ``` cat config.yml.tpl db_password: {{ op://app-prod/db/password }} ``` ``` op inject -i config.yml.tpl -o config.yml && cat config.yml db_password: fX6nWkhANeyGE27SQGhYQ ``` Multiple secrets can be concatenated: ``` echo "db_url: postgres://{{ op://lcl/db/user }}:{{ op://lcl/db/pw }}@{{ op://lcl/db/host }}:{{ op://lcl/db/port }}/{{ op://my-app-prd/db/db }}" | op inject db_url: postgres://admin:admin@127.0.0.1:5432/my-app" ``` Use variables in secret references to switch between different sets of secrets for different environments: ``` echo "db_password: op://$env/db/password" | env=prod op inject db_password: fX6nWkhANeyGE27SQGhYQ ``` # read Source: https://www.1password.dev/cli/reference/commands/read Read the value of the field in 1Password specified by a secret reference. [Learn more about secret references and query parameters.](/cli/secret-reference-syntax/) ``` op read [flags] ``` ### Flags ``` --file-mode filemode Set filemode for the output file. It is ignored without the --out-file flag. (default 0600) -f, --force Do not prompt for confirmation. -n, --no-newline Do not print a new line after the secret. -o, --out-file string Write the secret to a file instead of stdout. ``` ### Examples Print the secret saved in the field `password`, on the item `db`, in the vault `app-prod`: ```shell theme={null} op read op://app-prod/db/password ``` Use a secret reference with a query parameter to retrieve a one-time password: ```shell theme={null} op read "op://app-prod/db/one-time password?attribute=otp" ``` Use a secret reference with a query parameter to get an SSH key's private key in the OpenSSH format: ```shell theme={null} op read "op://app-prod/ssh key/private key?ssh-format=openssh" ``` Save the SSH key `key.pem` found in the section `ssh` on the item `server` in the vault `app-prod` as a new file on your computer: ```shell theme={null} op read --out-file ./key.pem op://app-prod/server/ssh/key.pem ``` Save the file attachment `config.yml` on the item `server` in the vault `app-prod` as a new file on your computer: ``` op read --out-file ./config.yml op://app-prod/server/config.yml ``` Use `op read` in a command with secret references in place of plaintext secrets: ```shell theme={null} docker login -u $(op read op://prod/docker/username) -p $(op read op://prod/docker/password) ``` # run Source: https://www.1password.dev/cli/reference/commands/run Pass secrets as environment variables to an application or script. ``` op run -- ... [flags] ``` ### Flags ``` --env-file stringArray Enable Dotenv integration with specific Dotenv files to parse. For example: --env-file=.env. --environment strings Load environment variables from one or more 1Password Environments by ID. If the same secret exists in multiple Environments, the last one takes precedence. -h, --help Help for run --no-masking Disable masking of secrets on stdout and stderr. ``` Use `op run` to securely load project secrets from 1Password, then run a provided command in a subprocess with the secrets made available as environment variables only for the duration of the subprocess. To limit which 1Password items processes in your authorized terminal session can access, make sure to authenticate 1Password CLI with a service account that only has access to the required secrets. You can scope service accounts to specific vaults and 1Password Environments. [Learn more about service accounts.](/service-accounts/) [Learn more about loading secrets with `op run`.](/cli/secrets-environment-variables) #### Load secrets using secret references `op run` can scan environment variables and files for secret references, then load the provided command with the referenced secrets made available as environment variables. Secret references are URIs that point to the ID or name of the vault, item, section, and field where a secret is stored in 1Password. You can export environment variables to secret references on the command line or using an .env file. Secrets printed to stdout or stderr are concealed by default. Include the `--no-masking` flag to turn off masking. When referencing an environment variable assigned to a secret reference within a command, `op run` must replace the reference with the actual secret value before the variable expands. To make sure this order of operations is followed, run the command that expands the variable in a subshell. #### Load variables from Environments Use `op run` with the `--environment` flag and an Environment's ID to load variables from a 1Password Environment. To find an Environment's ID, open the 1Password app, navigate to Developer > View Environments > then select View environment > Manage environment > Copy environment ID. Load variables from a 1Password Environment: ```shell theme={null} op run --environment -- printenv ``` #### Environment variable precedence If secrets of the same name exist in multiple 1Password Environments, the source with higher precedence takes effect. Precedence from highest to lowest: 1. 1Password Environments (--environment) 2. Environment files (--env-file) 3. Shell environment variables If the same environment variable name exists in multiple environment files, the last environment file takes precedence. If the same environment variable name exists in multiple 1Password Environments, the last Environment specified takes precedence. ### Examples Print secret value: ``` export DB_PASSWORD="op://app-prod/db/password" ``` ``` op run -- printenv DB_PASSWORD ``` ``` op run --no-masking -- printenv DB_PASSWORD fX6nWkhANeyGE27SQGhYQ ``` Specify an environment file and use it: ``` echo "DB_PASSWORD=op://app-dev/db/password" > .env ``` ``` op run --env-file="./.env" -- printenv DB_PASSWORD password ``` Use variables in secret references to switch between different sets of secrets for different environments: ``` cat .env DB_USERNAME = op://$APP_ENV/db/username DB_PASSWORD = op://$APP_ENV/db/password ``` ``` export APP_ENV="dev" op run --env-file="./.env" -- printenv DB_PASSWORD dev ``` ``` export APP_ENV="prod" op run --env-file="./.env" -- printenv DB_PASSWORD prod ``` # signin Source: https://www.1password.dev/cli/reference/commands/signin Sign in to 1Password CLI using the 1Password desktop app. ```shell theme={null} op signin [flags] ``` ### Flags ``` -f, --force Ignore warnings and print raw output from this command. --raw Only return the session token. ``` To turn on the 1Password app integration: 1. Open the 1Password app. 2. Navigate to **Settings** > **Security** and turn on Touch ID, Windows Hello, or a Linux system authentication option. 3. Navigate to **Developer** > **Settings** and select **Integrate with 1Password CLI**. [Learn more about the app integration.](/cli/app-integration/) If you add multiple 1Password accounts to the 1Password app, 1Password CLI determines which to use in this order: 1. The account specified with the `--account` flag. 2. The account specified by the `OP_ACCOUNT` environment variable. 3. The account you most recently signed in to with `op signin` in any terminal window. `op signin` is idempotent. It only prompts for authentication if you aren't already authenticated. ### Examples Sign in and set the environment variable in one step: ```shell theme={null} eval $(op signin --account acme.1password.com) ``` # signout Source: https://www.1password.dev/cli/reference/commands/signout Sign out of a 1Password account. ``` op signout [flags] ``` ### Flags ``` --all Sign out of all signed-in accounts. --forget Remove the details for a 1Password account from this device. ``` Signs out of the most recently used account by default. # update Source: https://www.1password.dev/cli/reference/commands/update Check for updates to `op` and download an updated version, if available. ``` op update [flags] ``` ### Flags ``` --directory path Download the update to this path. --channel string Look for updates from a specific channel. allowed: stable, beta ``` # whoami Source: https://www.1password.dev/cli/reference/commands/whoami Get information about a signed-in account. ``` op whoami [flags] ``` Returns the currently active account or service account. The command returns an error if no accounts are currently authenticated. Get information about a specific account with the `--account ` flag. # account Source: https://www.1password.dev/cli/reference/management-commands/account Manage your locally configured 1Password accounts. ### Subcommands * [account add](#account-add): Add an account to sign in to for the first time * [account forget](#account-forget): Remove a 1Password account from this device * [account get](#account-get): Get details about your account * [account list](#account-list): List users and accounts set up on this device ## account add Add a new 1Password account to 1Password CLI manually with your account password and Secret Key, instead of [signing in using your 1Password app](/cli/app-integration/). ```shell theme={null} op account add [flags] ``` ### Flags ``` --address string The sign-in address for your account. --email string The email address associated with your account. --raw Only return the session token. --shorthand string Set a custom account shorthand for your account. --signin Immediately sign in to the added account. ``` To sign in to manually-added accounts: > [tab] Bash, Zsh, sh, fish > > ```shell theme={null} > eval $(op signin) > ``` > [tab] PowerShell > > ```powershell theme={null} > Invoke-Expression $(op signin) > ``` [Learn more about signing in manually.](/cli/sign-in-manually/) When you sign in manually, 1Password CLI creates a session token and sets the `OP_SESSION` environment variable to it. Session tokens expire after 30 minutes of inactivity, after which you’ll need to sign in again. If you add multiple 1Password accounts, 1Password CLI determines which to use in this order: 1. An account specified with the `--account` flag. 2. An account specified with the `OP_ACCOUNT` environment variable. 3. The account most recently signed in to with `op signin` in the current terminal window. ### Examples Add an account using flags to specify account details: ```shell theme={null} op account add --address my.1password.com --email user@example.org ``` Add an account and immediately sign in to it: > [tab] Bash, Zsh, sh, fish > > ```shell theme={null} > eval $(op account add --signin) > ``` > [tab] PowerShell > > ```powershell theme={null} > Invoke-Expression $(op account add --signin) > ``` Sign in to a specific account: > [tab] Bash, Zsh, sh, fish > > ```shell theme={null} > eval $(op signin --account my) > ``` > [tab] PowerShell > > ```powershell theme={null} > Invoke-Expression $(op signin --account my) > ``` ## account forget Remove a 1Password account from this device. ``` op account forget [ ] [flags] ``` ### Flags ``` --all Forget all authenticated accounts. ``` ## account get Get details about your account. ``` op account get [flags] ``` ## account list List users and accounts set up on this device. ``` op account list [flags] ``` # connect Source: https://www.1password.dev/cli/reference/management-commands/connect Manage Connect server instances and tokens in your 1Password account. > [!TIP] > > Looking up a Connect server by its [ID](/cli/reference#unique-identifiers-ids) is more efficient than using the Connect server's name. ### Subcommands * [connect group](#connect-group): Manage group access to Secrets Automation * [connect server](#connect-server): Manage Connect servers * [connect token](#connect-token): Manage Connect server tokens * [connect vault](#connect-vault): Manage Connect server vault access ## connect group ### Subcommands * [connect group grant](#connect-group-grant): Grant a group access to manage Secrets Automation * [connect group revoke](#connect-group-revoke): Revoke a group's access to manage Secrets Automation ## connect group grant Grant a group access to manage Secrets Automation. ``` op connect group grant [flags] ``` ### Flags ``` --all-servers Grant access to all current and future servers in the authenticated account. --group group The group to receive access. --server server The server to grant access to. ``` If you don't specify a server, it adds the group to the list of Secrets Automation managers. ## connect group revoke Revoke a group's access to manage Secrets Automation. ``` op connect group revoke [flags] ``` ### Flags ``` --all-servers Revoke access to all current and future servers in the authenticated account. --group group The group to revoke access from. --server server The server to revoke access to. ``` ## connect server ### Subcommands * [connect server create](#connect-server-create): Set up a Connect server * [connect server delete](#connect-server-delete): Remove a Connect server * [connect server edit](#connect-server-edit): Rename a Connect server * [connect server get](#connect-server-get): Get a Connect server * [connect server list](#connect-server-list): List Connect servers ## connect server create Add a 1Password Connect server to your account and generate a credentials file for it. 1Password CLI saves the `1password-credentials.json` file in the current directory. Note: You can't grant a Connect server access to 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. ``` op connect server create [flags] ``` ### Flags ``` -f, --force Do not prompt for confirmation when overwriting credential files. --vaults strings Grant the Connect server access to these vaults. ``` 1Password CLI saves the `1password-credentials.json` file in the current directory. ## connect server delete Remove a Connect server. Specify the server by name or ID. ``` op connect server delete [{ | | - }] [flags] ``` The credentials file and all the tokens for the server will no longer be valid. ## connect server edit Rename a Connect server. Specify the server by name or ID. ``` op connect server edit { | } [flags] ``` ### Flags ``` --name name Change the server's name. ``` ## connect server get Get details about a Connect server. Specify the server by name or ID. ``` op connect server get [{ | | - }] [flags] ``` ## connect server list Get a list of Connect servers. ``` op connect server list [flags] ``` ## connect token ### Subcommands * [connect token create](#connect-token-create): Issue a token for a 1Password Connect server * [connect token delete](#connect-token-delete): Revoke a token for a Connect server * [connect token edit](#connect-token-edit): Rename a Connect server token * [connect token list](#connect-token-list): Get a list of tokens ## connect token create Issue a new token for a Connect server. ``` op connect token create [flags] ``` ### Flags ``` --expires-in duration Set how long the Connect token is valid for in (s)econds, (m)inutes, (h)ours, (d)ays, and/or (w)eeks. --server string Issue a token for this server. --vault stringArray Issue a token on these vaults. ``` Returns a token. You can only provision Connect server tokens to vaults that the Connect server has access to. Use `op connect vault grant` to grant access to vaults. Note: You can't grant a Connect server access to 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. By default, the `--vaults` option grants the same permissions as the server. To further limit the permissions a token has to read-only or write-only, add a comma and `r` or `w` after the vault specification. For example: ``` op connect token create "Dev k8s token" --server Dev --vaults Kubernetes,r \ --expires-in=30d ``` ``` op connect token create "Prod: Customer details" --server Prod --vault "Customers,w" \ --vault "Vendors,r" ``` ## connect token delete Revoke a token for a Connect server. ``` op connect token delete [ ] [flags] ``` ### Flags ``` --server string Only look for tokens for this 1Password Connect server. ``` ## connect token edit Rename a Connect server token. ``` op connect token edit [flags] ``` ### Flags ``` --name string Change the token's name. --server string Only look for tokens for this 1Password Connect server. ``` ## connect token list List tokens for Connect servers. ``` op connect token list [flags] ``` ### Flags ``` --server server Only list tokens for this Connect server. ``` Returns both active and revoked tokens. The `integrationId` is the ID for the Connect server the token belongs to. ## connect vault ### Subcommands * [connect vault grant](#connect-vault-grant): Grant a Connect server access to a vault * [connect vault revoke](#connect-vault-revoke): Revoke a Connect server's access to a vault ## connect vault grant Grant a Connect server access to a vault. ``` op connect vault grant [flags] ``` Note: You can't grant a Connect server access to 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. ### Flags ``` --server string The server to be granted access. --vault string The vault to grant access to. ``` ## connect vault revoke Revoke a Connect server's access to a vault. ``` op connect vault revoke [flags] ``` ### Flags ``` --server server The server to revoke access from. --vault vault The vault to revoke a server's access to. ``` # document Source: https://www.1password.dev/cli/reference/management-commands/document Perform CRUD operations on Document items in your vaults. ### Subcommands * [document create](#document-create): Create a document item * [document delete](#document-delete): Delete or archive a document item * [document edit](#document-edit): Edit a document item * [document get](#document-get): Download a document * [document list](#document-list): Get a list of documents ## document create Create a document item and receive a JSON object that contains the item's ID. ``` op document create [{ | - }] [flags] ``` ### Flags ``` --file-name name Set the file's name. --tags tags Set the tags to the specified (comma-separated) values. --title title Set the document item's title. --vault vault Save the document in this vault. Default: Private. ``` By default, the document is saved in 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. Specify a different vault with the `--vault` option. #### Create a file from standard input To create the file contents from standard input (stdin), enter a hyphen (`-`) instead of a path. You can use the `--file-name` option to change the name of the file. ### Examples Create a document by specifying the file path: ``` op document create "../demos/videos/demo.mkv" --title "2020-06-21 Demo Video" ``` Create a document from standard input: ``` cat auth.log.* | op document create - --title "Authlogs 2020-06" --file-name "auth.log.2020.06" ``` ## document delete Permanently delete a document. Specify the document to delete by its name or ID. Use the `--archive` option to move it to the Archive instead. ``` op document delete [{ | | - }] [flags] ``` ### Flags ``` --archive Move the document to the Archive. --vault vault Delete the document in this vault. ``` #### Specify items on standard input The command treats each line of information on standard input (stdin) as an object specifier. Run `op help` to learn more about how to specify objects. You can also input a list or array of JSON objects. The command will get an item for any object that has an ID. This is useful for passing information from one `op` command to another. ### Examples Permanently delete a document: ``` op document delete "2019 Contracts" ``` Move a document to the Archive: ``` op document delete "2019 Contracts" --archive ``` ## document edit Edit a document item. Specify the document item to edit by its name or ID. ``` op document edit { | } [{ | - }] [flags] ``` ### Flags ``` --file-name name Set the file's name. --tags tags Set the tags to the specified (comma-separated) values. An empty value removes all tags. --title title Set the document item's title. --vault vault Look up document in this vault. ``` Replaces the file contents of a Document item with the provided file or with the information on standard input (stdin). #### Update a file from standard input To update the file contents from standard input (stdin), enter a hyphen (`-`) instead of a path. You can use the `--file-name` option to change the name of the file. ## document get Download a document and print the contents. Specify the document by its name or ID. ``` op document get { | } [flags] ``` ### Flags ``` --file-mode filemode Set filemode for the output file. It is ignored without the --out-file flag. (default 0600) --force Forcibly print an unintelligible document to an interactive terminal. If --out-file is specified, save the document to a file without prompting for confirmation. --include-archive Include document items in the Archive. Can also be set using OP_INCLUDE_ARCHIVE environment variable. -o, --out-file path Save the document to the file path instead of stdout. --vault vault Look for the document in this vault. ``` Prints to standard output (stdout) by default. To print to a file, use the `--out-file path/to/file.ext` flag. #### Save to a file Use the `--out-file` option to have `op` save the document. This may be useful in some shells as a way to preserve the file's original encoding. The `--out-file` option won't overwrite an existing file. The destination path must be an empty file or not exist. ### Examples Save a document to a file called `secret-plans.text`: ``` op document get "Top Secret Plan B" --out-file=../documents/secret-plans.text ``` ## document list List documents. ``` op document list [flags] ``` ### Flags ``` --include-archive Include document items in the Archive. Can also be set using OP_INCLUDE_ARCHIVE environment variable. --vault vault Only list documents in this vault. ``` Returns a list of all documents the account has read access to by default. Excludes items in the Archive by default. # environment Source: https://www.1password.dev/cli/reference/management-commands/environment 1Password Environments allow you to organize and manage your project's environment secrets, separately from the rest of the items in your 1Password vaults. You can create an Environment for each project or development stage, then securely access your secrets directly from 1Password when you need them. [Learn more about 1Password Environments.](https://www.1password.dev/environments) ### Subcommands * [environment secret](#environment-secret): Manage the secrets in a 1Password Environment ## environment secret Secrets are addressed by name. Concealed secrets' values are withheld unless you pass the `--reveal` flag. ### Subcommands * [environment secret list](#environment-secret-list): List the secrets in a 1Password Environment ## environment secret list List the secrets in a 1Password Environment. ``` op environment secret list { | | - } [flags] ``` ### Flags ``` --format string Use this output format. Can be `human-readable`, `json`, `csv`, or `dotenv`. Can be set as the OP_FORMAT environment variable. (default "human-readable") --reveal Don't conceal the secrets' values. ``` Specify the Environment by name or ID. Returns each secret's name, value and whether it's concealed. Secrets are addressed by name, so no secret identifier is returned. Concealed secrets' values are withheld unless you pass the `--reveal` flag. ### Examples List the secrets in an Environment by ID: ``` op environment secret list 6ijsqfxvdxlwjcpsx7yrzs3tka ``` List the secrets in an Environment by name: ``` op environment secret list Staging ``` Reveal the concealed secrets' values: ``` op environment secret list Staging --reveal ``` Get the secrets as dotenv: ``` op environment secret list Staging --reveal --format=dotenv ``` # events-api Source: https://www.1password.dev/cli/reference/management-commands/events-api Manage Events API integrations in your 1Password account. Requires a business account. ### Subcommands * [events-api create](#events-api-create): Set up an integration with the Events API ## events-api create Create an Events API integration token. ``` op events-api create [flags] ``` ### Flags ``` --expires-in duration Set how the long the events-api token is valid for in (s)econds, (m)inutes, (h)ours, (d)ays, and/or (w)eeks. --features features Set the comma-separated list of features the integration token can be used for. Options: `signinattempts`, `itemusages`, `auditevents`. ``` 1Password CLI prints the token when successful. Requires a business account. ### Examples Create an Events API integration to report sign-in attempts that expires in one hour: ``` op events-api create SigninEvents --features signinattempts --expires-in 1h ``` Create an Events API integration that reports all supported events that does not expire: ``` op events-api create AllEvents ``` # group Source: https://www.1password.dev/cli/reference/management-commands/group Manage the groups in your 1Password account. Groups can be used to organize your team and delegate administrative responsibilities. You can give groups access to vaults and assign them permissions, so you don't have to keep track of everyone separately. ### Subcommands * [group create](#group-create): Create a group * [group delete](#group-delete): Remove a group * [group edit](#group-edit): Edit a group's name or description * [group get](#group-get): Get details about a group * [group list](#group-list): List groups * [group user](#group-user): Manage group membership ## group create Create a group and receive a JSON object with the group's ID. ``` op group create [flags] ``` ### Flags ``` --description string Set the group's description. ``` ## group delete Remove a group. Specify the group to delete by its name or ID. ``` op group delete [{ | | - }] [flags] ``` ## group edit Edit a group's name or description. Specify the group to edit by its name or ID. ``` op group edit [{ | | - }] [flags] ``` ### Flags ``` --description description Change the group's description. --name name Change the group's name. ``` ## group get Get details about a group. Specify the group by its name or ID. ``` op group get [{ | | - }] [flags] ``` #### Use standard input to specify objects If you enter a hyphen (`-`) instead of a single object for this command, the tool will read object specifiers from standard input (stdin). Separate each specifier with a new line. For more information about how to specify objects, run `op help`. You can also pass the command a list or array of JSON objects. The tool will get an item for any object that has an ID, ignoring line breaks. This is useful for passing information from one `op` command to another. ### Examples Get details for all groups: ``` op group list --format=json | op group get - ``` Get details for the groups who have access to a vault: ``` op group list --vault "Production keys" --format=json | op group get - ``` ## group list List groups. ``` op group list [flags] ``` ### Flags ``` --user user List groups that a user belongs to. --vault vault List groups that have direct access to a vault. ``` Returns all groups in an account by default. ### Examples Get details for all groups: ``` op group list | op group get - ``` Get details for the groups that have access to a vault: ``` op group list --vault Staging --format=json | op group get - ``` Get details for the groups that a user belongs to: ``` op group list --user wendy_appleseed@1password.com --format=json | op group get - ``` ## group user ### Subcommands * [group user grant](#group-user-grant): Add a user to a group * [group user list](#group-user-list): Retrieve users that belong to a group * [group user revoke](#group-user-revoke): Remove a user from a group ## group user grant Grant a user access to a group. ``` op group user grant [flags] ``` ### Flags ``` --group string Specify the group to grant the user access to. --role string Specify the user's role as a member or manager. Default: member. --user string Specify the user to grant group access to. ``` ## group user list Retrieve users that belong to a group. ``` op group user list [flags] ``` ## group user revoke Revoke a user's access to a group. ``` op group user revoke [flags] ``` ### Flags ``` --group string Specify the group to remove the user from. --help Get help with group user revoke. --user string Specify the user to remove from the group. ``` # item Source: https://www.1password.dev/cli/reference/management-commands/item Perform CRUD operations on the 1Password items in your vaults. ### Subcommands * [item create](#item-create): Create an item * [item delete](#item-delete): Delete or archive an item * [item edit](#item-edit): Edit an item's details * [item get](#item-get): Get an item's details * [item list](#item-list): List items * [item move](#item-move): Move an item between vaults * [item share](#item-share): Share an item * [item template](#item-template): Manage templates ## item create Create a new item. ``` op item create [ - ] [ ... ] [flags] ``` ### Flags ``` --category category Set the item's category. --dry-run Test the command and output a preview of the resulting item. --favorite Add item to favorites. --generate-password[=recipe] Add a randomly-generated password to a Login or Password item. --reveal Don't conceal sensitive fields. --ssh-generate-key The type of SSH key to create: Ed25519 or RSA. For RSA, specify 2048, 3072, or 4096 (default) bits. Possible values: ed25519, rsa, rsa2048, rsa3072, rsa4096. (default Ed25519) --tags tags Set the tags to the specified (comma-separated) values. --template string Specify the filepath to read an item template from. --title title Set the item's title. --url URL Set the website where 1Password suggests and fills a Login, Password, or API Credential item. --vault vault Save the item in this vault. Default: Private. ``` Get a list of all item categories: ```shell theme={null} op item template list ``` Use assignment statements or an item category JSON template to save details in built-in or custom fields. [Learn more about creating items.](/cli/item-create/) [Learn more about item fields and fieldTypes.](/cli/item-fields/) #### Generate a password Use the `--generate-password` option to set a random password for a Login or Password item. The default is 32-characters, and includes upper and lowercase letters, numbers, and symbols (`!@.-_*`). You can specify the password length (between 1 and 64 characters) and the character types to use: ```shell theme={null} --generate-password='letters,digits,symbols,32' ``` #### Set additional fields with assignment statements You can use assignment statements as command arguments to set built-in and custom fields. ``` [
.][[]]= ``` Command arguments get logged in your command history, and can be visible to other processes on your machine. If you’re assigning sensitive values, use a JSON template instead. For example, to create a text field named "host" within a section named "Database Credentials", with the value set to 33.166.240.221: ```shell theme={null} DatabaseCredentials.host[text]=33.166.240.221 ``` The section name is optional unless multiple sections contain fields with the same name. Use a backslash to escape periods, equal signs, or backslashes in section or field names. Don’t use backslashes to escape the value. You can omit spaces in the section or field name, or refer to the field by its JSON short name (`name` or `n`). #### Create an item using a json template Use an item JSON template to assign sensitive values to an item. If you combine a template with assignment statements, assignment statements take precedence. 1. Save the appropriate item category template to a file: ```shell theme={null} op item template get --out-file login.json "Login" ``` 2. Edit the template. 3. Create a new item using the `-—template` flag to specify the path to the edited template: ```shell theme={null} op item create --template=login.json ``` 4. After 1Password CLI creates the item, delete the edited template. You can also create an item from standard input using an item JSON template. Pass the `-` character as the first argument, followed by any assignment statements. ```shell theme={null} op item template get Login | op item create --vault personal - ``` You can’t use both piping and the `--template` flag in the same command, to avoid collisions. ### Examples Create a Login item with a random password and website set using flags and custom and built-in fields set with assignment statements, including a one-time password field and a file attachment: ```shell theme={null} op item create --category=login --title='My Example Item' --vault='Test' \ --url https://www.acme.com/login \ --generate-password=20,letters,digits \ username=jane@acme.com \ 'Test Section 1.Test Field3[otp]=otpauth://totp/:?secret=&issuer=' \ 'FileName[file]=/path/to/your/file' ``` Create an item by duplicating an existing item from another vault and modifying it with assignment statements: ```shell theme={null} op item get "My Item" --format json | op item create --vault prod - \ username="My Username" password="My Password" ``` Duplicate all items in a vault in one account to a vault in another account: ```shell theme={null} op item list --vault test-vault --format json --account agilebits | \ op item get --format json --account agilebits - | \ op item create --account work - ``` ## item delete Delete or archive items you no longer need. ``` op item delete [{ | | | - }] [flags] ``` ### Flags ``` --archive Move the item to the Archive. --vault string Look for the item in this vault. ``` Deleted items remain available for 30 days in Recently Deleted. You can restore or permanently delete items from Recently Deleted in the 1Password apps. Use the `--archive` option to move an item to the Archive instead. Specify an item to delete or archive by its name, ID, or sharing link. #### Specify items on standard input The command treats each line of information on standard input (stdin) as an object specifier. Run `op help` to learn more about how to specify objects. The input can also be a list or array of JSON objects. The command will get an item for any object that has an ID. This is useful for passing information from one `op` command to another. ### Examples Delete an item: ``` op item delete "Defunct Login" ``` Move an item to the Archive: ``` op item delete "Defunct Login" --archive ``` ## item edit Edit an item's details. ``` op item edit { | | } [ ... ] [flags] ``` ### Flags ``` --dry-run Perform a dry run of the command and output a preview of the resulting item. --favorite Whether this item is a favorite item. Options: true, false. --generate-password[=recipe] Give the item a randomly generated password. --reveal Don't conceal sensitive fields. --tags tags Set the tags to the specified (comma-separated) values. An empty value will remove all tags. --template string Specify the filepath to read an item template from. --title title Set the item's title. --url URL Set the website where 1Password suggests and fills a Login, Password, or API Credential item. --vault vault Edit the item in this vault. ``` Specify the item by its name, ID, or sharing link. Use flags to update the title, tags, or generate a new random password. You can use assignment statements as command arguments to update built-in or custom fields. For sensitive values, use a template instead. #### Edit an item using assignment statements Caution: Command arguments can be visible to other processes on your machine. ```shell theme={null} [
.][[]]= ``` To create a new field or section, specify a field or section name that doesn’t already exist on the item. To edit an existing field, specify the current section and field name, then make changes to the fieldType or value. If you don’t specify a fieldType or value, it will stay the same. To delete a custom field, specify `[delete]` in place of the fieldType. If a section no longer has any fields, the section will also be deleted. You can't delete built-in fields, but you can set them to empty strings. Learn more about assignment statements: `op item create –-help`. [Learn more about available fields and fieldTypes.](/cli/item-fields) #### Edit an item using a template > [!CAUTION] > > JSON item templates do not support passkeys. If you use a JSON template to update an item that contains a passkey, the passkey will be overwritten. To fix this, you can [restore a previous version of the item](https://support.1password.com/item-history/). You can use a JSON template to edit an item, alone or in combination with command arguments. Field assignment statements overwrite values in the template. 1. Get the item you want to edit in JSON format and save it to a file: ``` op item get oldLogin --format=json > updatedLogin.json ``` 2. Edit the file. 3. Use the `--template` flag to specify the path to the edited file and edit the item: op item edit oldLogin --template=updatedLogin.json 4. Delete the file. You can also edit an item using piped input: ```shell theme={null} cat updatedLogin.json | op item edit oldLogin ``` To avoid collisions, you can't combine piped input and the `--template` flag in the same command. ### Examples Add a 32-character random password that includes upper- and lower-case letters, numbers, and symbols to an item: ```shell theme={null} op item edit 'My Example Item' --generate-password='letters,digits,symbols,32' ``` Edit a custom field's value without changing the fieldType: ``` op item edit 'My Example Item' 'field1=new value' ``` Edit a custom field's fieldType without changing the value: ``` op item edit 'My Example Item' 'field1[password]' ``` Edit a custom field's type and value: ``` op item edit 'My Example Item' 'field1[monthyear]=2021/09' ``` Add a new custom field to an item: ``` op item edit 'My Example Item' 'section2.field5[phone]=1-234-567-8910' ``` Remove an existing custom field: ``` op item edit 'My Example Item' 'section2.field5[delete]' ``` Set the built-in username field to an empty value: ``` op item edit 'My Example Item' 'username=' ``` Edit an item using a template alongside command arguments and assignment statements: ```shell theme={null} op item edit oldLogin --vault Private 'username=Lucky' --template=updatedLogin.json ``` ## item get Get details about an item. Specify the item by its name, ID, or sharing link. ``` op item get [{ | | | - }] [flags] ``` ### Flags ``` --fields strings Return data from specific fields. Use `label=` to get the field by name or `type=` to filter fields by type. Specify multiple in a comma-separated list. --include-archive Include items in the Archive. Can also be set using OP_INCLUDE_ARCHIVE environment variable. --otp Output the primary one-time password for this item. --reveal Don't conceal sensitive fields. --share-link Get a shareable link for the item. --vault vault Look for the item in this vault. ``` If you have multiple items with the same name, or if you’re concerned about API rate limits, specify the item by its ID or limit the scope of the search with the `--vault` flag. [Learn more about IDs and caching.](/cli/reference) To retrieve the contents of a specific field, use `op read` instead. When using service accounts, you must specify a vault with the `--vault` flag or through piped input. #### Specify items on standard input `op item get` treats each line of information on standard input (stdin) as an object specifier. You can also input a list or array of JSON objects, and the command will get an item for any object that has an ID key. This is useful for passing information from one command to another. #### Items in the archive Items in the Archive are ignored by default. To get details for an item in the Archive, specify the item by ID or use the `--include-archive` option. ### Examples Get details for all items with a specified tag: ``` op item list --tags documentation --format json | op item get - ``` Get a CSV list of the username, and password for all logins in a vault: ``` op item list --categories Login --vault Staging --format json | op item get - --fields label=username,label=password ``` Get a JSON object of an item's username and password fields: ``` op item get Netflix --fields label=username,label=password --format json ``` Get a list of fields by type: ``` op item get Netflix --fields type=concealed ``` Get an item's one-time password: ``` op item get Google --otp ``` Retrieve a shareable link for the item referenced by ID: ``` op item get kiramv6tpjijkuci7fig4lndta --vault "Ops Secrets" --share-link ``` ## item list List items. ``` op item list [flags] ``` ### Flags ``` --categories categories Only list items in these categories (comma-separated). --favorite Only list favorite items. --include-archive Include items in the Archive. Can also be set using OP_INCLUDE_ARCHIVE environment variable. --long Output a more detailed item list. --tags tags Only list items with these tags (comma-separated). --vault vault Only list items in this vault. ``` Returns a list of all items the account has read access to by default. Use flags to filter results. Excludes items in the Archive by default. Categories are: * API Credential * Bank Account * Credit Card * Database * Document * Driver License * Email Account * Identity * Login * Membership * Outdoor License * Passport * Password * Reward Program * Secure Note * Server * Social Security Number * Software License * Wireless Router ### Examples Get details for all items with a specified tag: ``` op item list --tags documentation --format=json | op item get - ``` Get a CSV list of the username, and password for all logins in a vault: ``` op item list --categories Login --vault Staging --format=json | op item get - --fields username,password ``` Selecting a tag `` will also return items with tags sub-nested to ``. For example: ``. ## item move Move an item between vaults. Moving an item creates a copy of the item in the destination vault and deletes the item from the current vault. As a result, the item gets a new ID. ``` op item move [{ | | | - }] [flags] ``` ### Flags ``` --current-vault string Vault where the item is currently saved. --destination-vault string The vault you want to move the item to. --reveal Don't conceal sensitive fields. ``` To restore or permanently delete the original item, find the item in Recently Deleted in your 1Password app or on 1Password.com. Moving an item between vaults may change who has access to the item. ### Examples Move an item from the Private vault to the Shared vault: ``` op item move "My Example Item" --current-vault Private --destination-vault Shared ``` ## item share Share an item. ``` op item share { | } [flags] ``` ### Flags ``` --emails strings Email addresses to share with. --expires-in duration Expire link after the duration specified in (s)econds, (m)inutes, (h)ours, (d)ays, and/or (w)eeks. (default 7d) --vault string Look for the item in this vault. --view-once Expire link after a single view. ``` You can securely share copies of passwords and other items you've saved in 1Password with anyone, even if they don't use 1Password. When you share an item, you'll get a unique link that you can send to others. Copy the URL, then send the link to the person or people you want to share the item copy with, like in an email or text message. Anyone with the link can view the item copy unless you specify addresses with the emails flag. If you edit an item, your changes won't be shared until you share the item again. Note that file attachments and Document items cannot be shared. ## item template ### Subcommands * [item template get](#item-template-get): Get an item template * [item template list](#item-template-list): Get a list of templates ## item template get Return a template for an item type. ``` op item template get [{ | - }] [flags] ``` ### Flags ``` --file-mode filemode Set filemode for the output file. It is ignored without the --out-file flag. (default 0600) -f, --force Do not prompt for confirmation. -o, --out-file string Write the template to a file instead of stdout. ``` You can create a new item with a template. Run `op item create --help` for more information. Categories are: * API Credential * Bank Account * Credit Card * Database * Document * Driver License * Email Account * Identity * Login * Membership * Outdoor License * Passport * Password * Reward Program * Secure Note * Server * Social Security Number * Software License * Wireless Router ## item template list Lists available item type templates. ``` op item template list [flags] ``` Use `op item template get ` to get a template. # plugin Source: https://www.1password.dev/cli/reference/management-commands/plugin Manage your shell plugin configurations. You can use shell plugins to securely authenticate third-party CLIs with 1Password, rather than storing your CLI credentials in plaintext. After you configure a plugin, 1Password CLI will prompt you to authenticate the third-party CLI with your fingerprint or other system authentication option. [Learn more about shell plugins.](/cli/shell-plugins) ### Subcommands * [plugin clear](#plugin-clear): Clear shell plugin configuration * [plugin init](#plugin-init): Configure a shell plugin * [plugin inspect](#plugin-inspect): Inspect your existing shell plugin configurations * [plugin list](#plugin-list): List all available shell plugins * [plugin run](#plugin-run): Provision credentials from 1Password and run this command ## plugin clear Clear an existing shell plugin configuration. ```shell theme={null} op plugin clear [flags] ``` ### Flags ``` --all Clear all configurations for this plugin that apply to this directory and/or terminal session, including the global default. -f, --force Apply immediately without asking for confirmation. ``` You can clear one configuration at a time, in this order of precedence: * Terminal session default * Directory default, from the current directory to `$HOME` * Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear aws` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear aws --all`. ## plugin init Choose a shell plugin to install and configure your default credentials. Bash, Zsh, and fish shells are supported. ```shell theme={null} op plugin init [ ] [flags] ``` Shell plugins require the [1Password desktop app integration](/cli/shell-plugins/). To see all available plugins, run `op plugin list`. #### Configure your default credentials 1Password CLI prompts you to select or import the credentials you want to use with the third-party CLI, then returns a command to source your `plugins.sh` file and make the plugin alias usable. To use the plugin beyond the current terminal session, make sure to add the source command to your RC file or shell profile (e.g. `~/.bashrc`, `~/.zshrc`, `~/.config/fish/config.fish`). For example: ```shell theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` #### Configuration options You can choose whether 1Password CLI remembers your configuration. With any option, your credentials never leave your 1Password account. * "Prompt me for each new terminal session" only configures the credentials for the current terminal session. Once you exit the terminal, your default is removed. * "Use automatically when in this directory or subdirectories" makes your credentials the default in the current directory and all its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. * "Use as global default on my system" sets the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## plugin inspect Inspect your existing shell plugin configurations. ```shell theme={null} op plugin inspect [ ] [flags] ``` You can run `op plugin inspect` to select a plugin from the list of all available plugins, or `op plugin inspect ` to inspect a specific plugin. 1Password CLI returns a list of the credentials you've configured to use with the plugin and their default scopes, as well as configured alias details. ## plugin list Lists all available shell plugins, their usage, name, and required fields. ```shell theme={null} op plugin list [flags] ``` To get started with a shell plugin, run `op plugin init `. ## plugin run Provision credentials from 1Password and run this command. ```shell theme={null} op plugin run ... [flags] ``` `op plugin run` passes your credentials saved in 1Password to the underlying CLI and runs the provided command. If you haven't configured your default credentials, 1Password CLI will prompt you to select an item that contains your credentials. After this, you will be automagically authenticated with this CLI, and your selection will be recorded for future calls to this plugin in the current terminal session. To configure a default credential, see `op plugin init --help`. # provisioning Source: https://www.1password.dev/cli/reference/management-commands/provisioning ### Subcommands * [provisioning google](#provisioning-google): Manage Google Workspace provisioning for your 1Password account ## provisioning google ### Subcommands * [provisioning google sync](#provisioning-google-sync): Sync selected Google Workspace groups with 1Password ## provisioning google sync Start a sync between Google Workspace and your 1Password account. ``` op provisioning google sync [flags] ``` ### Flags ``` --integration UUID UUID of the Google Workspace integration to sync. Required. Shown during Google Workspace setup. ``` The sync updates 1Password with your selected Google Workspace groups and their members. Once started, the sync continues in the background. Sign in with the 1Password service account created during Google Workspace setup by setting the `OP_SERVICE_ACCOUNT_TOKEN` environment variable. This command is designed to run on a schedule, such as from the Google Cloud job created during setup, but you can also run it manually. The command exits with a non-zero code if the sync couldn't start. For troubleshooting details, run with `--debug`. ### Examples Run one sync for a Google Workspace integration: ``` op provisioning google sync --integration 6b7fghqewnfluffyuv5oj3anlq ``` # service-account Source: https://www.1password.dev/cli/reference/management-commands/service-account Manage service accounts. ### Subcommands * [service-account create](#service-account-create): Create a service account * [service-account ratelimit](#service-account-ratelimit): Retrieve rate limit usage for a service account ## service-account create Create a service account to gain programmatic access to your secrets using 1Password CLI. ```shell theme={null} op service-account create [flags] ``` ### Flags ``` --can-create-vaults Allow the service account to create new vaults. --expires-in duration Set how long the service account is valid for in (s)econds, (m)inutes, (h)ours, (d)ays, or (w)eeks. --raw Only return the service account token. --vault stringArray Give access to this vault with a set of permissions. Has syntax :[,] ``` You can specify the vaults the service account can access, as well as the permissions it will have for each vault using the `--vault` flag. The syntax looks like this: ```shell theme={null} --vault :, ``` The permissions can be one of the following: * `read_items` * `write_items` (requires `read_items`) * `share_items` (requires `read_items`) If no permissions are specified, it will default to `read_items`. You can set an expiry to a service account using the `--expires-in` flag. 1Password CLI only returns the service account token once. Save the token in 1Password immediately to avoid losing it. Treat this token like a password, and don't store it in plaintext. > [!NOTE] > > You can't grant a service account access to 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. ### Examples Create a new service account: ```shell theme={null} op service-account create my-service-account --vault Dev:read_items --vault Test:read_items,write_items ``` Create a service account with an expiry: ```shell theme={null} op service-account create my-service-account --expires-in=24h ``` Create a service account that can create new vaults: ```shell theme={null} op service-account create my-service-account --can-create-vaults ``` ## service-account ratelimit Retrieve hourly and daily rate limit usage for a service account. ```shell theme={null} op service-account ratelimit [{ | }] [flags] ``` # user Source: https://www.1password.dev/cli/reference/management-commands/user ### Subcommands * [user confirm](#user-confirm): Confirm a user * [user delete](#user-delete): Remove a user and all their data from the account * [user edit](#user-edit): Edit a user's name or Travel Mode status * [user get](#user-get): Get details about a user * [user list](#user-list): List users * [user provision](#user-provision): Provision a user in the authenticated account * [user reactivate](#user-reactivate): Reactivate a suspended user * [user recovery](#user-recovery): Manage user recovery in your 1Password account * [user suspend](#user-suspend): Suspend a user ## user confirm Specify the user by their e-mail address, name, or ID. ```shell theme={null} op user confirm [{ | | | - }] [flags] ``` ### Flags ``` --all Confirm all unconfirmed users. ``` Specify the user by their e-mail address, name, or ID. ### Examples Confirm a user by specifying their name: ```shell theme={null} op user confirm "Wendy Appleseed" ``` Confirm a user by specifying their email: ```shell theme={null} op user confirm "wendy.appleseed@example.com" ``` ## user delete Remove a user and all their data from the account. ```shell theme={null} op user delete [{ | | | - }] [flags] ``` Specify the user by their e-mail address, name, or ID. ## user edit Change a user's name or Travel Mode status. ```shell theme={null} op user edit [{ | | | - }] [flags] ``` ### Flags ``` --name string Set the user's name. --travel-mode on|off Turn Travel Mode on or off for the user. (default off) ``` Specify the user by their e-mail address, name, or ID. ## user get Get details about a user. ```shell theme={null} op user get [{ | | | --me | - }] [flags] ``` ### Flags ``` --fingerprint Get the user's public key fingerprint. --me Get the authenticated user's details. --public-key Get the user's public key. ``` Specify the user by their e-mail address, name, or ID. #### Use standard input to specify objects If you enter a hyphen (`-`) instead of a single object for this command, the tool will read object specifiers from standard input (stdin). Separate each specifier with a new line. For more information about how to specify objects, run `op help`. You can also pass the command a list or array of JSON objects. The tool will get an item for any object that has an ID, ignoring line breaks. This is useful for passing information from one `op` command to another. ### Examples Look up a user by name: ```shell theme={null} op user get "Wendy Appleseed" ``` Look up a user by e-mail: ```shell theme={null} op user get wendy.appleseed@example.com ``` Get details for all users: ```shell theme={null} op user list --format=json | op user get - ``` Get the public key for all users in a group: ```shell theme={null} op user list --group "Frontend Developers" --format=json | op user get - --publickey ``` Get details for all users who have access to a vault: ```shell theme={null} op user list --vault Staging --format=json | op user get - ``` ## user list List users. ```shell theme={null} op user list [flags] ``` ### Flags ``` --group group List users who belong to a group. --vault vault List users who have direct access to vault. ``` Returns all users in an account by default. Use flags to filter results. When you use the `--group` option, the output includes the user's role in the group. ### Examples Get details for all users: ```shell theme={null} op user list --format=json | op user get - ``` Get the public key for all users in a group: ```shell theme={null} op user list --group "Frontend Developers" --format=json | op user get - --publickey ``` Get details for all users who have access to a vault: ```shell theme={null} op user list --vault Staging --format=json | op user get - ``` ## user provision Provision a user in the authenticated account. > [!NOTE] > > Before you can use `op user provision`, you'll need to set up provisioning. If your account uses automated provisioning, [complete the one-time setup](/cli/provision-users#with-automated-provisioning). If your account doesn't use automated provisioning, an owner or administrator needs to [turn on CLI provisioning](/cli/provision-users#with-1password-cli). ```shell theme={null} op user provision [flags] ``` ### Flags ``` --email string Provide the user's email address. --language string Provide the user's account language. (default "en") --name string Provide the user's name. ``` Provisioned users will receive an invitation email to join the 1Password account. Once a user accepts an invitation, an admin must confirm them on 1Password.com or using the `op user confirm` command. Invited users will not be considered for billing until they accept their invitation. ### Examples Invite a user by specifying their e-mail address and name: ```shell theme={null} op user provision --name "Wendy Appleseed" --email "wendy.appleseed@example.com" ``` ## user reactivate Reactivate a suspended user. ```shell theme={null} op user reactivate [{ | | | - }] [flags] ``` A user may be specified by their e-mail address, name, or ID. ## user recovery ### Subcommands * [user recovery begin](#user-recovery-begin): Begin recovery for users in your 1Password account ## user recovery begin Begin recovery for users in your 1Password account: ```shell theme={null} op user recovery begin [ { | | } ] [flags] ``` ### Examples Begin recovery for multiple users by UUID: ```shell theme={null} op user recovery begin ZMAE4RTRONHN7LGELNYYO373KM WHPOFIMMYFFITBVTOTZUR3R324 ``` ## user suspend Suspend a user. ```shell theme={null} op user suspend [{ | | | - }] [flags] ``` ### Flags ``` --deauthorize-devices-after duration Deauthorize the user's devices after a time (rounded down to seconds). ``` Specify the user by their e-mail address, name, or ID. A suspended user will immediately be logged out of all devices and will not be able to log in or access any data. Users in a suspended state are not considered in billing. You can reactivate a suspended user with the `op user reactivate` command. # vault Source: https://www.1password.dev/cli/reference/management-commands/vault Manage permissions and perform CRUD operations on your 1Password vaults. ### Subcommands * [vault create](#vault-create): Create a new vault * [vault delete](#vault-delete): Remove a vault * [vault edit](#vault-edit): Edit a vault's name, description, icon, or Travel Mode status * [vault get](#vault-get): Get details about a vault * [vault group](#vault-group): Manage group vault access * [vault list](#vault-list): List all vaults in the account * [vault user](#vault-user): Manage user vault access ## vault create Create a new vault ``` op vault create [flags] ``` ### Flags ``` --allow-admins-to-manage true|false Set whether administrators can manage the vault. If not provided, the default policy for the account applies. --description description Set the vault's description. --icon string Set the vault icon. ``` Valid icon keywords are: airplane, application, art-supplies, bankers-box, brown-briefcase, brown-gate, buildings, cabin, castle, circle-of-dots, coffee, color-wheel, curtained-window, document, doughnut, fence, galaxy, gears, globe, green-backpack, green-gem, handshake, heart-with-monitor, house, id-card, jet, large-ship, luggage, plant, porthole, puzzle, rainbow, record, round-door, sandals, scales, screwdriver, shop, tall-window, treasure-chest, vault-door, vehicle, wallet, wrench ## vault delete Remove a vault. Specify the vault to delete by name or ID. ``` op vault delete [{ | | - }] [flags] ``` A vault may be specified by name or ID. ## vault edit Edit a vault's name, description, icon, or Travel Mode status. Specify the vault by name or ID. ``` op vault edit [{ | | - }] [flags] ``` ### Flags ``` --description description Change the vault's description. --icon icon Change the vault's icon. --name name Change the vault's name. --travel-mode on|off Turn Travel Mode on or off for the vault. (default off) ``` A vault may be specified by name or ID. Set Travel Mode to on to mark a vault as safe for travel. Vaults with Travel Mode set to off are hidden in the 1Password apps and browser extension when Travel Mode is enabled for a user. Valid icon keywords are: airplane, application, art-supplies, bankers-box, brown-briefcase, brown-gate, buildings, cabin, castle, circle-of-dots, coffee, color-wheel, curtained-window, document, doughnut, fence, galaxy, gears, globe, green-backpack, green-gem, handshake, heart-with-monitor, house, id-card, jet, large-ship, luggage, plant, porthole, puzzle, rainbow, record, round-door, sandals, scales, screwdriver, shop, tall-window, treasure-chest, vault-door, vehicle, wallet, wrench ## vault get Get details about a vault. Specify the vault by name or ID. ``` op vault get [{ | | - }] [flags] ``` A vault may be specified by name or ID. #### Use standard input to specify objects If you enter a hyphen (`-`) instead of a single object for this command, the tool will read object specifiers from standard input (stdin). Separate each specifier with a new line. For more information about how to specify objects, run `op help`. You can also pass the command a list or array of JSON objects. The tool will get an item for any object that has an ID, ignoring line breaks. This is useful for passing information from one `op` command to another. ### Examples Get details for all vaults: ``` op vault list --format=json | op vault get - ``` Get details for the vaults that a group has access to: ``` op vault list --group security --format=json | op vault get - ``` ## vault group ### Subcommands * [vault group grant](#vault-group-grant): Grant a group permissions to a vault * [vault group list](#vault-group-list): List all the groups that have access to the given vault * [vault group revoke](#vault-group-revoke): Revoke a portion or the entire access of a group to a vault ## vault group grant Grant a group permissions in a vault. ``` op vault group grant [flags] ``` ### Flags ``` --group group The group to receive access. --no-input input Do not prompt for input on interactive terminal. --permissions permissions The permissions to grant to the group. --vault vault The vault to grant group permissions to. ``` Permissions are specified in a comma separated list such as: ``` view_items,view_and_copy_passwords,edit_items ``` 1Password Teams includes three permissions: ``` allow_viewing, allow_editing, allow_managing ``` 1Password Business includes the permissions above as well as more granular options: allow\_viewing ``` view_items, view_and_copy_passwords, view_item_history ``` allow\_editing ``` create_items, edit_items, archive_items, delete_items, import_items, export_items, copy_and_share_items, print_items ``` allow\_managing ``` manage_vault ``` When granting or revoking permissions, some permissions require dependent permissions to be granted or revoked alongside them. [Learn more about managing vault permissions.](/cli/vault-permissions/) ### Examples Grant a group certain permissions in a vault with a business account: ``` op vault group grant --vault VAULT --group GROUP \ --permissions view_items,create_items,allow_viewing ``` ``` op vault group grant --vault VAULT --group GROUP \ --permissions allow_viewing,export_items ``` Grant a group certain permissions in a vault with a team account: ``` op vault group grant --vault VAULT --group GROUP \ --permissions allow_viewing,allow_editing ``` ## vault group list List all the groups that have access to the given vault. ``` op vault group list [{ | - }] [flags] ``` ## vault group revoke Revoke a group's permissions in a vault, in part or in full. ``` op vault group revoke [flags] ``` ### Flags ``` --group group The group to revoke access from. --no-input input Do not prompt for input on interactive terminal. --permissions permissions The permissions to revoke from the group. --vault vault The vault to revoke access to. ``` Not specifying any permissions revokes the group's access to the vault. Removing all existing permissions also revokes the group’s access to the vault. Permissions are specified in a comma separated list such as: ``` view_items,view_and_copy_passwords,edit_items ``` 1Password Teams includes three permissions: ``` allow_viewing, allow_editing, allow_managing ``` 1Password Business includes the permissions above as well as more granular options: allow\_viewing ``` view_items, view_and_copy_passwords, view_item_history ``` allow\_editing ``` create_items, edit_items, archive_items, delete_items, import_items, export_items, copy_and_share_items, print_items ``` allow\_managing ``` manage_vault ``` When granting or revoking permissions, some permissions require dependent permissions to be granted or revoked alongside them. [Learn more about managing vault permissions.](/cli/vault-permissions/) ### Examples Remove a group from a vault: ``` op vault group revoke --vault VAULT --group GROUP ``` Revoke certain permissions from a group in a vault with a business account: ``` op vault group revoke --vault VAULT --group GROUP \ --permissions view_items,create_items,allow_editing ``` Revoke certain permissions from a group in a vault with a team account: ``` op vault group revoke --vault VAULT --group GROUP \ --permissions allow_viewing,allow_editing ``` ## vault list List vaults. ``` op vault list [flags] ``` ### Flags ``` --group string List vaults a group has access to. --permission permissions List only vaults that the specified user/group has this permission for. --user string List vaults that a given user has access to. ``` By default, returns all vaults the current user has read access to. ### Examples Get details for all vaults: ``` op vault list --format=json | op vault get - ``` Get details for vaults that a group has access to: ``` op vault list --group Security --format=json | op vault get - ``` Get details for vaults that a user has access to: ``` op vault list --user wendy_appleseed@1password.com --format=json | op vault get - ``` Only list vaults for which the user/group has a specific set of permissions: ``` op vault list --user wendy_appleseed@1password.com --permission manage_vault ``` ## vault user ### Subcommands * [vault user grant](#vault-user-grant): Grant a user access to a vault * [vault user list](#vault-user-list): List all users with access to the vault and their permissions * [vault user revoke](#vault-user-revoke): Revoke a portion or the entire access of a user to a vault ## vault user grant Grant a user permissions in a vault. ``` op vault user grant [flags] ``` ### Flags ``` --no-input input Do not prompt for input on interactive terminal. --permissions permissions The permissions to grant to the user. --user user The user to receive access. --vault vault The vault to grant access to. ``` Permissions are specified in a comma separated list such as: ``` view_items,view_and_copy_passwords,edit_items ``` 1Password Teams and 1Password Families include three permissions: ``` allow_viewing, allow_editing, allow_managing ``` 1Password Business includes the permissions above as well as more granular options: allow\_viewing ``` view_items, view_and_copy_passwords, view_item_history ``` allow\_editing ``` create_items, edit_items, archive_items, delete_items, import_items, export_items, copy_and_share_items, print_items ``` allow\_managing ``` manage_vault ``` When granting or revoking permissions, some permissions require dependent permissions to be granted or revoked alongside them. [Learn more about managing vault permissions.](/cli/vault-permissions/) ### Examples Grant a user certain permissions in a vault with a business account: ``` op vault user grant --vault VAULT --user USER \ --permissions view_items,create_items,allow_viewing ``` ``` op vault user grant --vault VAULT --user USER \ --permissions allow_viewing,export_items ``` Grant a user certain permissions in a vault with a team account: ``` op vault user grant --vault VAULT --user USER \ --permissions allow_viewing,allow_editing ``` ## vault user list List all users with access to the vault and their permissions. ``` op vault user list [flags] ``` ## vault user revoke Revoke a user's permissions in a vault, in part or in full. ``` op vault user revoke [flags] ``` ### Flags ``` --no-input input Do not prompt for input on interactive terminal. --permissions permissions The permissions to revoke from the user. --user user The user to revoke access from. --vault vault The vault to revoke access to. ``` Not specifying any permissions revokes the user's access to the vault. Removing all existing permissions also revokes the user’s access to the vault. Permissions are specified in a comma separated list such as: ``` view_items,view_and_copy_passwords,edit_items ``` 1Password Teams and 1Password Families include three permissions: ``` allow_viewing, allow_editing, allow_managing ``` 1Password Business includes the permissions above as well as more granular options: allow\_viewing ``` view_items, view_and_copy_passwords, view_item_history ``` allow\_editing ``` create_items, edit_items, archive_items, delete_items, import_items, export_items, copy_and_share_items, print_items ``` allow\_managing ``` manage_vault ``` When granting or revoking permissions, some permissions require dependent permissions to be granted or revoked alongside them. [Learn more about managing vault permissions.](/cli/vault-permissions/) ### Examples Remove a user from a vault: ``` op vault user revoke --vault VAULT --user USER ``` Revoke certain permissions from a user in a vault with a business account: ``` op vault user revoke --vault VAULT --user USER \ --permissions view_items,create_items,allow_editing ``` Revoke certain permissions from a user in a vault with a team account: ``` op vault user revoke --vault VAULT --user USER \ --permissions allow_viewing,allow_editing ``` # Update to the latest version of 1Password CLI Source: https://www.1password.dev/cli/reference/update To make sure you're up to date with the latest features and security improvements, always use the latest version of 1Password CLI. To check what version you currently have installed, use `op --version`. ## Download the latest version There are two ways you can download the latest version for your platform and architecture: * Visit our [release page](https://app-updates.agilebits.com/product_history/CLI2) and download the latest version of 1Password CLI. * Use `op update` to download the latest version from the command line. Set the `--directory` flag to choose where to download the installer (defaults to `~/Downloads`) and confirm the download. You can use `op update` without signing in. After downloading the appropriate installer, follow the [installation instructions](/cli/get-started/#step-1-install-1password-cli) to finish the update. ## Update with a package manager If you installed 1Password CLI with a package manager, use the following commands to update your installation. > [tab] Mac > > ```shell title="Brew" theme={null} > brew upgrade --cask 1password-cli > ``` > [tab] Linux > > sudo apt update && sudo apt install 1password-cli > > sudo dnf check-update -y 1password-cli && sudo dnf install 1password-cli > > apk add --update-cache 1password-cli # Release notes Source: https://www.1password.dev/cli/release-notes # Example scripts Source: https://www.1password.dev/cli/scripts The 1Password Solutions team manages [a repository of example 1Password CLI scripts](https://github.com/1Password/solutions) that you can use as inspiration for your own projects. You'll need to install [jq](https://stedolan.github.io/jq/), a command-line JSON processor, for the example scripts to work correctly. You can find demo scripts to help you: * [Migrate from another password solution](https://github.com/1Password/solutions/tree/main/1password/migration) * [Provision new users from a CSV](https://github.com/1Password/solutions/tree/main/1password/scripted-provisioning) * [Audit or manage existing users](https://github.com/1Password/solutions/tree/main/1password/user-management) * [Manage your vaults and groups](https://github.com/1Password/solutions/tree/main/1password/account-management) * [Create, update, and share items](https://github.com/1Password/solutions/tree/main/1password/item-management) > [card] [Building an integration or automated workflow?](/get-started/build-integrations) > > Follow the build integrations workflow guide to choose the right authentication method and configuration for your use case. ## Learn more * [Get started with secret references](/cli/secret-references/) * [Load secrets into scripts](/cli/secrets-scripts/) * [Load secrets into the environment](/cli/secrets-environment-variables/) * [Load secrets into config files](/cli/secrets-config-files/) * [Workflow: Secure local development](/get-started/secure-developer-secrets) # Secret reference syntax Source: https://www.1password.dev/cli/secret-reference-syntax ![An environment file using a plaintext secret and the same file using a secret reference.](https://mintcdn.com/ab-634991b8/pfc4yDcmGyZA8XDs/static/img/cli/use-case-secret-reference.png?fit=max\&auto=format\&n=pfc4yDcmGyZA8XDs\&q=85\&s=9ad2bc030d00e90b6ca9dd46c607cb44) Secret reference URIs point to where a secret is saved in your 1Password account using the names (or [unique identifiers](/cli/reference/#unique-identifiers-ids)) of the vault, item, section, and field where the information is stored. ```shell theme={null} op:////[section-name/] ``` Secret references remove the risk of exposing plaintext secrets in your code and reflect changes you make in your 1Password account, so when you run a script you get the latest value. You can use secret references with: ### 1Password CLI Load secrets into environment variables, configuration files, and scripts. [Learn more](/cli/secret-references/) ### 1Password SDKs Programmatically access your secrets with Go, JavaScript, and Python. [Learn more](/sdks/) ### Secrets Automation Use secret references to secure your secrets management workflows. [Learn more](/secrets-automation/) ### VS Code Create, preview, and read secret references in your code. [Learn more](/vscode/) ### 1Password integrations Securely access your secrets in Kubernetes, CircleCI, GitHub Actions, Jenkins, Terraform, Pulumi, Postman, and more. [Learn more](/ci-cd/) ## Get secret references ### With the 1Password desktop app To see the option to copy secret references in the 1Password desktop app, first turn on the [integration with 1Password CLI](/cli/app-integration). Then: 1. Open the item where the secret you want to reference is stored. 2. Select next to the field that contains the secret you want to reference, then select **Copy Secret Reference**. ![An item in 1Password with the Copy Secret Reference option selected.](https://mintcdn.com/ab-634991b8/pfc4yDcmGyZA8XDs/static/img/cli/copy-secret-reference.png?fit=max\&auto=format\&n=pfc4yDcmGyZA8XDs\&q=85\&s=88384960f087feec95adb596a0a0c33c) ### With 1Password for VS Code You can use 1Password for VS Code to [insert secret references](/vscode/#get-values) from 1Password as you edit your code. First, [install the extension](/vscode/). Then: 1. Open the [**Command Palette**.](https://code.visualstudio.com/api/ux-guidelines/command-palette) 2. Enter `1Password: Get from 1Password`. 3. Enter the item name or ID. 4. Select the field to use. ### With 1Password CLI To get a secret reference with 1Password CLI, run [`op item get`](/cli/reference/management-commands/item/#item-get) with the `--format json` flag and include the `--fields` flag to specify a field label. Then use [jq](https://jqlang.github.io/jq/) to retrieve the secret reference from the JSON output. For example: ```shell theme={null} op item get GitHub --format json --fields username | jq .reference #code-result "op://development/GitHub/username" ``` To get secret references for every field on an item, use [`op item get`](/cli/reference/management-commands/item/#item-get) with the `--format json` flag without specifying a field. > [accordion] Example JSON output > > ```shell theme={null} > op item get GitHub --format json > ``` > > Each field object will include a `reference` key that contains its secret reference. For the example `GitHub` item, the output looks like this: > > ```json highlight={8,17,29,40} theme={null} > "fields": [ > { > "id": "username", > "type": "STRING", > "purpose": "USERNAME", > "label": "username", > "value": "wendy_appleseed@agilebits.com", > "reference": "op://development/GitHub/username" > }, > { > "id": "password", > "type": "CONCEALED", > "purpose": "PASSWORD", > "label": "password", > "value": "GADbhK6MjNZrRftGMqto", > "entropy": 115.5291519165039, > "reference": "op://development/GitHub/password", > "password_details": { > "entropy": 115, > "generated": true, > "strength": "FANTASTIC" > } > }, > { > "id": "notesPlain", > "type": "STRING", > "purpose": "NOTES", > "label": "notesPlain", > "reference": "op://development/GitHub/notesPlain" > }, > { > "id": "5ni6bw735myujqe4elwbzuf2ee", > "section": { > "id": "hv46kvrohfj75q6g45km2uultq", > "label": "credentials" > }, > "type": "CONCEALED", > "label": "personal_token", > "value": "ghp_WzgPAEutsFRZH9uxWYtw", > "reference": "op://development/GitHub/credentials/personal_token" > } > ] > } > ``` ## Syntax rules ### Supported characters Secret references are case-insensitive and support the following characters: * alphanumeric characters (`a-z`, `A-Z`, `0-9`) * `-`, `_`, `.` and the whitespace character If a secret reference includes a whitespace, enclose the secret reference in quotation marks. For example: ```shell theme={null} op read "op://development/aws/Access Keys/access_key_id" ``` Any part of a secret reference that includes an unsupported character must be referred to by its [unique identifier (ID)](/cli/reference/#unique-identifiers-ids) instead of its name. To get an ID, run [`op item get`](/cli/reference/management-commands/item#item-get) with the output set to JSON. For example, to get the ID for a custom text field named `test/`: ``` op item get PagerDuty --fields label=test/ --format json #code-result { "id": "hu4vwo3bjkawq2uw2fkn5pkjzu", "section": { "id": "add more" }, "type": "STRING", "label": "text/", "value": "t", "reference": "op://Management/PagerDuty/add more/hu4vwo3bjkawq2uw2fkn5pkjzu" } ``` ### File attachments To reference a file attachment, use the file name in place of a field name: ```shell theme={null} op://vault-name/item-name/[section-name/]file-name ``` ### Externally-set variables If you use different sets of secrets in different environments, you can include variables within secret references and then set the variable to switch between secrets. For example, the `APP_ENV` variable in the example below can be set to `dev` to load development credentials or `prod` to load production credentials, assuming the credentials are stored in 1Password vaults named `dev` and `prod`. ```shell app.env theme={null} MYSQL_DATABASE = "op://$APP_ENV/mysql/database" MYSQL_USERNAME = "op://$APP_ENV/mysql/username" MYSQL_PASSWORD = "op://$APP_ENV/mysql/password" ``` Learn how to use variables to switch between sets of secrets in [environment files](/cli/secrets-environment-variables#optional-differentiate-between-environments) and [config files](/cli/secrets-config-files#step-3-differentiate-between-environments). ### Field and file metadata attributes You can use secret references with query parameters to get more information about an item. #### Attribute parameter To get information about item fields and file attachments, use the `attribute` (or `attr`) query parameter. ```html Fields theme={null} op:///[/
]/?attribute= ``` ```html File attachments theme={null} op:///[/
]/?attribute= ``` Field attributes: | Attribute | Definition | | - | - | | `type` | The field's type | | `value` | The field's content | | `id` | The field's unique identifier | | `purpose` | The designation of a built-in field (can be "username", "password", or "notes") | | `otp` | Use with one-time password fields to generate a one-time password code | File attachment attributes: | Attribute | Definition | | - | - | | `type` | The field's type | | `content` | The file attachment's content | | `size` | The size of the file attachment | | `id` | The file attachment's unique identifier | | `name` | The name of the file attachment | For example, to retrieve an item's one-time password code: ```shell theme={null} op read "op://development/GitHub/Security/one-time password?attribute=otp" #code-result 359836 ``` To retrieve a field's type: ```shell theme={null} op read "op://Personal/aws/access credentials/username?attribute=type" #code-result string ``` To retrieve the name of a file attachment: ```shell theme={null} op read "op://app-infra/ssh/key.pem?attribute=name" #code-result key.pem ``` #### SSH format parameter To get an SSH private key in the OpenSSH format, include the `ssh-format` query parameter with the value `openssh` on a secret reference for the SSH key's `private key` field. ```shell theme={null} op read "op://Private/ssh keys/ssh key/private key?ssh-format=openssh" #code-result -----BEGIN OPENSSH PRIVATE KEY----- b3BlbnNzaC1rZXktdjEAAAAACmFlczI1Ni1jdHIAAAAGYmNyeXB0AAAAGAAAABD3rRrf8J ruD0CxZTYfpbTYAAAAEAAAAAEAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIJ5B/GnxX6t9jMwQ G7QE7r5daJLkMKTZhNZhWfvzK2y+AAAAkLgQAivYu/+12/YrZhK5keIAZf4ZgsZsZ2JI2q qbx23PqgO93oGy1iCxXe3kngQL4cM6lwOZPsZPKCinkN6KxEr6RnXqFRHJbMpOiGeZhTuD rjeo77HqFdxDqDeckB77XCKL0Ew28H5JlM/WO31XR3Z4VBAgTe+BQLjrFV8WU5UX38hpBJ PMJyRsK72ZUDDaGQ== -----END OPENSSH PRIVATE KEY----- ``` ## Secret reference examples ### A field inside a section To create a secret reference that refers to the PagerDuty email field, which is within the Admin section, use: ```shell theme={null} op://Management/PagerDuty/Admin/email ``` * `Management` refers to the vault where the item is saved * `PagerDuty` refers to the item * `Admin` refers to the section where the field is a part of * `email` refers to the field where the secret you want to reference is located ![PagerDuty 1Password item](https://mintcdn.com/ab-634991b8/pfc4yDcmGyZA8XDs/static/img/cli/pagerduty-light.png?fit=max\&auto=format\&n=pfc4yDcmGyZA8XDs\&q=85\&s=349008a4a1887c011958f5c582955742) ### A field without a section To create a secret reference for the Stripe publishable-key field, which is not part of a section, use: ```shell theme={null} op://dev/Stripe/publishable-key ``` * `dev` refers to the vault where the item is saved * `Stripe` refers to the item * `publishable-key` refers to the field where the secret you want to reference is located ![Stripe 1Password item](https://mintcdn.com/ab-634991b8/pfc4yDcmGyZA8XDs/static/img/cli/stripe-light.png?fit=max\&auto=format\&n=pfc4yDcmGyZA8XDs\&q=85\&s=71cdeba8ecfb5b84f6a4a006fb6349db) ## Learn more * [Use secret references with 1Password CLI](/cli/secret-references/) * [Get started with 1Password SDKs](/sdks/) * [Load secrets into config files](/cli/secrets-config-files/) * [Load secrets into the environment](/cli/secrets-environment-variables/) * [Template syntax](/cli/secrets-template-syntax/) * [Workflow: Secure local development](/get-started/secure-developer-secrets) # Use secret references with 1Password CLI Source: https://www.1password.dev/cli/secret-references Use secret references to point to secrets stored in 1Password instead of putting plaintext values in your code, config files, and scripts. > [!TIP] > > **New beta feature** > > You can now [pass secrets as environment variables](/cli/secrets-environment-variables) to applications or scripts from [1Password Environments](/environments). This allows you to more easily access project secrets from 1Password without the need to create secret references. With 1Password CLI, you can use [secret references](/cli/secret-reference-syntax) to securely load information saved in 1Password into environment variables, configuration files, and scripts without exposing any secrets in plaintext. A secret reference URI includes the names (or [unique identifiers](/cli/reference/#unique-identifiers-ids)) of the vault, item, section, and field where a secret is stored in your 1Password account: ```shell theme={null} op:////[section-name/] ``` To replace secret references with the secrets they refer to at runtime, use [`op read`](#with-op-read), [`op run`](#with-op-run), or [`op inject`](#with-op-inject). > [!TIP] > > We recommend using [1Password Service Accounts](/service-accounts/) to follow the [principle of least privilege](/cli/best-practices/). Service accounts support restricting 1Password CLI to specific vaults, so that processes in your authorized terminal session can only access items required for a given purpose. ## Requirements Before you can use secret references to securely load your secrets with 1Password CLI, you'll need to: 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. [Install 1Password CLI.](/cli/get-started/#step-1-install-1password-cli) 3. Save the secrets you want to reference in your 1Password account. ## Step 1: Get secret references You can get secret references in several ways: * [With the 1Password desktop app](/cli/secret-reference-syntax/#with-the-1password-desktop-app): Copy secret references from the app. * [With 1Password for VS Code](/vscode/#get-values): Insert secret references from 1Password as you edit code. * [With 1Password CLI](/cli/secret-reference-syntax/#with-1password-cli): Get secret references for one or multiple fields with `op item get`. * [With the secret reference syntax](/cli/secret-reference-syntax/#syntax-rules): Write secret references manually. ## Step 2: Replace plaintext secrets with secret references After you create secret references, use them in place of plaintext secrets in your code. The example below shows a GitHub environment file with a secret reference pointing to where the GitHub Personal Access Token is stored in 1Password rather than a plaintext token. ![An environment file using a plaintext secret and the same file using a secret reference.](https://mintcdn.com/ab-634991b8/pfc4yDcmGyZA8XDs/static/img/cli/use-case-secret-reference.png?fit=max\&auto=format\&n=pfc4yDcmGyZA8XDs\&q=85\&s=9ad2bc030d00e90b6ca9dd46c607cb44) ## Step 3: Resolve secret references There are three ways you can replace secret references with the actual secrets they reference at runtime: * [Use `op read` to write secrets to `stdout` or to a file.](#with-op-read) * [Use `op run` to pass secrets as environment variables to a process.](#with-op-run) * [Use `op inject` to inject secrets into configuration files or scripts.](#with-op-inject) ### With `op read` You can use [`op read`](/cli/reference/commands/read/) with a secret reference to print the secret to `stdout`. ```shell theme={null} op read op://development/GitHub/credentials/personal_token #code-result ghp_WzgPAEutsFRZH9uxWYtw ``` To write the secret to a file instead of `stdout`, include the `--out-file` flag (or `-o`) with the path to the new file. For example, to create a file `token.txt` that contains the GitHub personal access token: ```shell theme={null} op read --out-file token.txt op://development/GitHub/credentials/personal_token ``` ```shell token.txt theme={null} ghp_WzgPAEutsFRZH9uxWYtw ``` You can also use `op read` with secret references to [load secrets into scripts](/cli/secrets-scripts/). For example, to use secret references in place of your Docker username and password with the `docker login` command: ```shell myscript.sh theme={null} #!/bin/bash docker login -u "$(op read op://prod/docker/username)" -p "$(op read op://prod/docker/password)" ``` #### Query parameters You can use secret references with [query parameters](/cli/secret-reference-syntax/#field-and-file-metadata-attributes) to get more information about an item. To get information about item fields or file attachments, include the `attribute` (or `attr`) query parameter with the attribute you want to get. ```shell theme={null} op:///[/
]/?attribute= ``` You can query the following attributes for fields: `type`, `value`, `title`, `id`, `purpose`, `otp` And the following attributes for file attachments: `content`, `size`, `id`, `name`, `type`. For example, to retrieve a one-time password from the one-time password field on a GitHub item: ```shell theme={null} op read "op://development/GitHub/Security/one-time password?attribute=otp" #code-result 359836 ``` To get an SSH key's private key in the OpenSSH format, include the `ssh-format` query parameter with the value `openssh` on a secret reference for the SSH key's `private key` field. ```shell theme={null} op read "op://Private/ssh keys/ssh key/private key?ssh-format=openssh" #code-result -----BEGIN OPENSSH PRIVATE KEY----- b3BlbnNzaC1rZXktdjEAAAAACmFlczI1Ni1jdHIAAAAGYmNyeXB0AAAAGAAAABD3rRrf8J ruD0CxZTYfpbTYAAAAEAAAAAEAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIJ5B/GnxX6t9jMwQ G7QE7r5daJLkMKTZhNZhWfvzK2y+AAAAkLgQAivYu/+12/YrZhK5keIAZf4ZgsZsZ2JI2q qbx23PqgO93oGy1iCxXe3kngQL4cM6lwOZPsZPKCinkN6KxEr6RnXqFRHJbMpOiGeZhTuD rjeo77HqFdxDqDeckB77XCKL0Ew28H5JlM/WO31XR3Z4VBAgTe+BQLjrFV8WU5UX38hpBJ PMJyRsK72ZUDDaGQ== -----END OPENSSH PRIVATE KEY----- ``` > [!NOTE] > > **Next step** > > Learn more about [securely loading secrets into scripts](/cli/secrets-scripts/). ### With `op run` You can set environment variables to secret references, then use [`op run`](/cli/reference/commands/run/) to pass secrets to an application or script at runtime. `op run` scans environment variables for secret references, loads the corresponding values from 1Password, then runs the provided command in a subprocess with the secrets made available as environment variables for the duration of the subprocess. > [!NOTE] > > When you reference a variable like `$MY_VAR` in the **same command** where you call `op run`, your shell expands `$MY_VAR` before `op run` can substitute the secret reference. To make sure `op run` substitutes the secret before the variable expands, you can either: > > * **Export the variable** as a secret reference before calling `op run`, or > * Set the variable in the same command as `op run`, then **run the command to expand the variable in a subshell**. For example: > > ```shell theme={null} > MY_VAR=op://vault/item/field op run --no-masking -- sh -c 'echo "$MY_VAR"' > ``` #### Pass the secrets to an application or script To pass secrets to your script or application at runtime, wrap the command with `op run`. For example, here's a Node.js app that needs credentials to connect to a database: ```shell theme={null} $ node app.js [INFO] Launching Node.js app... [ERROR] Missing credentials DB_USER and DB_PASSWORD [INFO] Exiting with code 1 ``` You can set the `DB_USER` and `DB_PASSWORD` environment variables to secret references: > [tab] Bash, Zsh, sh > > ```shell theme={null} > export DB_USER="op://app-dev/db/user" > export DB_PASSWORD="op://app-dev/db/password" > ``` > [tab] fish > > ```shell theme={null} > set -x DB_USER="op://app-dev/db/user" > set -x DB_PASSWORD="op://app-dev/db/password" > ``` > [tab] PowerShell > > ```powershell theme={null} > $Env:DB_USER = "DB_USER=op://app-dev/db/user" > $Env:DB_PASSWORD = "DB_PASSWORD=op://app-dev/db/password" > ``` Then use `op run` to pass the secrets to the `node app.js` command: ```shell theme={null} op run -- node app.js [INFO] Launching Node.js app... [DEBUG] ✔ Connected to db as user 'mydbuser' with password '' ``` #### Use with environment files You can also use `op run` with environment files. To do this, use secret references instead of plaintext secrets in your environment file: ```html node.env theme={null} DB_USER="op://app-dev/db/user" DB_PASSWORD="op://app-dev/db/password" ``` Then use `op run` with the `--env-file` flag: ```shell theme={null} op run --env-file="./node.env" -- node app.js ``` #### Print a secret with or without masking If a subprocess used with `op run` prints a secret to `stdout`, the secret will be concealed by default. You can include the `--no-masking` flag to print the value. > [tab] Bash, Zsh, sh > > To export an example environment variable `DB_PASSWORD` to a secret reference: > > ```shell theme={null} > export DB_PASSWORD=op://app-prod/db/password > ``` > > Use `op run` with the `printenv` command to print the concealed secret: > > ```shell theme={null} > op run -- printenv DB_PASSWORD > #code-result > > ``` > > Include the `--no-masking` flag to print the actual secret: > > ```shell theme={null} > op run --no-masking -- printenv DB_PASSWORD > #code-result > fX6nWkhANeyGE27SQGhYQ > ``` > [tab] fish > > To export an example environment variable `DB_PASSWORD` to a secret reference: > > ```shell theme={null} > set -x DB_PASSWORD=op://app-prod/db/password > ``` > > Use `op run` with the `printenv` command to print the concealed secret: > > ```shell theme={null} > op run -- printenv DB_PASSWORD > #code-result > > ``` > > Include the `--no-masking` flag to print the actual secret: > > ```shell theme={null} > op run --no-masking -- printenv DB_PASSWORD > #code-result > fX6nWkhANeyGE27SQGhYQ > ``` > [tab] PowerShell > > To export an example environment variable `DB_PASSWORD` to a secret reference: > > ```powershell theme={null} > $Env:DB_PASSWORD = "DB_PASSWORD=op://app-prod/db/password" > ``` > > To print the concealed secret: > > ```powershell theme={null} > op run -- powershell -c '$env:DB_PASSWORD' > #code-result > > ``` > > Include the `--no-masking` flag to print the actual secret: > > ```powershell theme={null} > op run --no-masking -- powershell -c '$env:DB_PASSWORD' > #code-result > fX6nWkhANeyGE27SQGhYQ > ``` > [!NOTE] > > **Next step** > > Learn more about [loading secrets into the environment](/cli/secrets-environment-variables/) with `op run`, including how to use template variables to switch between different sets of secrets for different environments. ### With `op inject` You can use [`op inject`](/cli/reference/commands/inject/) to replace secret references in a script or file with the secrets they reference. By default, `op inject` accepts input on `stdin` and outputs on `stdout`. You can use the `--in-file` flag (or `-i`) to read the input from a file instead, and the `--out-file` flag (or `-o`) to specify where the ouput should be written. To use `op inject` to resolve a secret in a simple command: ```shell theme={null} echo "here is my GitHub token: op://development/GitHub/credentials/personal_token" | op inject #code-result here is my GitHub token: ghp_WzgPAEutsFRZH9uxWYtw ``` To write the output to a file `token.txt` in the current directory: ```shell theme={null} echo "here is my GitHub token: op://development/GitHub/credentials/personal_token" >> token.txt | op inject --out-file token.txt ``` ```shell token.txt theme={null} here is my GitHub token: ghp_WzgPAEutsFRZH9uxWYtw ``` #### Use with configuration files You can use `op inject` to pass in a configuration file templated with secret references and output a configuration file that contains resolved secrets. Configuration files that use secret references instead of plaintext secrets can be safely checked into Git. ```yaml config.yml.tpl theme={null} database: host: http://localhost port: 5432 username: op://prod/mysql/username password: op://prod/mysql/password ``` ```shell theme={null} op inject --in-file config.yml.tpl --out-file config.yml ``` > [!NOTE] > > **Next step** > > Learn more about [loading secrets into configuration files](/cli/secrets-config-files/) with `op inject`, including how to use template variables to switch between different sets of secrets for different environments. ## Learn more * [Secret reference syntax](/cli/secret-reference-syntax/) * [Load secrets into the environment](/cli/secrets-environment-variables/) * [Load secrets into config files](/cli/secrets-config-files/) * [Load secrets into scripts](/cli/secrets-scripts/) * [Use service accounts with 1Password CLI](/service-accounts/use-with-1password-cli) * [Workflow: Secure local development](/get-started/secure-developer-secrets) # Load secrets into config files Source: https://www.1password.dev/cli/secrets-config-files With 1Password CLI, you can use [secret references](/cli/secret-reference-syntax/) to automatically load secrets into configuration files from your 1Password account without putting any plaintext secrets in code. This allows you to check config files into source control and keep them in sync throughout developer workstations, CI, and production servers, which is otherwise manual and error-prone work. > [!TIP] > > We recommend using [1Password Service Accounts](/service-accounts/) to follow the [principle of least privilege](/cli/best-practices/). Service accounts support restricting 1Password CLI to specific vaults, so that processes in your authorized terminal session can only access items required for a given purpose. ## Requirements Before you can use 1Password to secure your config files, you'll need to: 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. [Install 1Password CLI.](/cli/get-started/#step-1-install-1password-cli) 3. Store the secrets you want to provision in your 1Password account. ## Step 1: Get secret references You can get secret references in several ways: * [With the 1Password desktop app](/cli/secret-reference-syntax/#with-the-1password-desktop-app): Copy secret references from the app. * [With 1Password for VSCode](/vscode/#get-values): Insert secret references from 1Password as you edit code. * [With 1Password CLI](/cli/secret-reference-syntax/#with-1password-cli): Get secret references for one or multiple fields with `op item get`. * Use the [secret reference syntax rules](/cli/secret-reference-syntax/#syntax-rules) to write secret references manually. ## Step 2: Use secret references in your config file Replace the plaintext secrets in your config file with the appropriate secret references, following the [template syntax](/cli/secrets-template-syntax/). For example, if you start with a config file that looks like this: ```yaml config.yml theme={null} database: host: http://localhost port: 5432 username: mysql-user password: piG1rX5P1QMF6J5k7u7sNb ``` And you saved the `username` and `password` secrets on the `mysql` item in the `prod` vault, you would end up with this templated config file: ```yaml config.yml.tpl theme={null} database: host: http://localhost port: 5432 username: op://prod/mysql/username password: op://prod/mysql/password ``` ## Step 2: Inject the secrets To load secrets from the config file and provision them at runtime, use `op inject` to inject the secrets directly into your production environment. For example: ```zsh theme={null} op inject -i config.yml.tpl -o config.yml ``` In the output file, `config.yml`, you'll see the secret references replaced with the plaintext secrets they reference. The config file template is stored together with the code in source control, so that every developer can see the structure of the file. > [!CAUTION] > > Make sure to delete the resolved config file when you no longer need it. ## Step 3: Differentiate between environments We highly recommend you organize your 1Password items in the same way across all of your environments. For example: `app/dev/db/password` and `app/prod/db/password`. If you do this, you can use variables in your template file to switch to a different set of secrets. You can have variables for your environment, stage, region, or anything else. For example: ```yaml config.yml.tpl theme={null} database: host: http://localhost port: 5432 username: op://$APP_ENV/mysql/username password: op://$APP_ENV/mysql/password ``` You can then set the `APP_ENV` variable when you inject into the template, using the [Template Syntax](/cli/secrets-template-syntax/): > [tab] Bash, Zsh, sh, fish > > ```shell theme={null} > APP_ENV=prod op inject -i config.yml.tpl -o config.yml > ``` > [tab] PowerShell > > 1. Set `APP_ENV` to `prod`: > > ```powershell theme={null} > $Env:APP_ENV = "prod" > ``` > > 2. Inject the secrets: > > ```powershell theme={null} > op inject -i config.yml.tpl -o config.yml > ``` This allows you to use the same template file, stored in source control next to your application, for all your deployments. ## Optional: Use `op inject` in production Now that the application works with the right configuration locally, you can use 1Password CLI to provision secrets in production environments. To do this, you'll first need to: 1. [Install 1Password CLI 2 in your production environment.](/cli/install-server/) 2. [Set up a Secrets Automation workflow](/connect/). 3. [Deploy 1Password Connect Server](/connect/get-started/#step-2-deploy-1password-connect-server) and make it accessible to your production environment. To use 1Password CLI with a Connect server, set the `OP_CONNECT_HOST` and `OP_CONNECT_TOKEN` environment variables to your Connect instance's credentials in your production environment. You can now move your secrets to config files and have them readily accessible with `op inject`. The following commands can be used with a Connect server: * `op run` * `op inject` * `op read` * `op item get` ## Learn more * [Load secrets into the environment](/cli/secrets-environment-variables/) * [Secret reference syntax](/cli/secret-reference-syntax/) * [Template syntax](/cli/secrets-template-syntax/) * [Workflow: Secure local development](/get-started/secure-developer-secrets) # Load secrets into the environment Source: https://www.1password.dev/cli/secrets-environment-variables Load secrets from 1Password into environment variables with op run, so your apps and scripts get the values they need without plaintext .env files. With [`op run`](/cli/reference/commands/run/), you can provide your project secrets directly from 1Password to an application or script as environment variables at runtime. You can use `op run` with [1Password Environments](/environments), environment variables set to [secret references](/cli/secret-references), or a combination of both. [Video walkthrough of loading secrets into the environment with 1Password CLI.](https://www.youtube.com/embed/yrqkJsas7ng) 1Password CLI loads the specified secrets, then runs the provided command in a subprocess with the secrets made available as environment variables only for the duration of the process. This allows you to avoid hardcoding any plaintext secrets and quickly switch between different sets of secrets for different development contexts. ## Choose your configuration 1Password CLI provides multiple methods to load your project secrets: * **[1Password Environments](/environments)** allow you to create Environments in 1Password that contain all your secrets for a specific workflow. You can share Environments with your team and create separate Environments for each project, application, or development context (like staging or production). * **[Secret references](/cli/secret-references)** are URIs that point to where a secret is stored in your 1Password account. A secret reference uses the names or unique identifiers of the vault, item, section, and field where the secret is stored in 1Password. You can set environment variables to secret references on the command line or use secret references in your `.env` files. Secret references require more manual setup than 1Password Environments to switch between different sets of variables for different contexts, or create shared team workflows. * **Hybrid approach**: You can use `op run` to load secrets from a 1Password Environment alongside secret references from `.env` files or exported environment variables. > [!TIP] > > Authenticate with a [1Password Service Account](/service-accounts/) to follow the [principle of least privilege](/cli/best-practices/). You can scope service account access to specific vaults and 1Password Environments so that processes in your authorized terminal session can only access secrets required for a given purpose. > [!WARNING] > > You should assume that processes on your computer can access the environment of other processes run by the same user. Be aware of this when supplying secrets through environment variables. ## Requirements > [tab] 1Password Environment > > 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) > 2. [Install 1Password CLI.](/cli/get-started#step-1-install-1password-cli) > [tab] Secret references > > Before you can load secrets into the environment, you'll need to: > > 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) > 2. [Install 1Password CLI.](/cli/get-started#step-1-install-1password-cli) ## Step 1: Store your project secrets in 1Password > [tab] 1Password Environment > > To store your project secrets in a 1Password Environment, [follow the steps to create an Environment](/environments), then import a `.env` file or manually add your secrets. > [tab] Secret references > > To use secret references, save your project secrets as items in a vault in your 1Password account. > > Then follow the instructions to create secret references for each item using your preferred method: > > * [With the 1Password desktop app](/cli/secret-reference-syntax#with-the-1password-desktop-app): Copy secret references from the app. > * [With 1Password for VSCode](/vscode#get-values): Insert secret references from 1Password as you edit code. > * [With 1Password CLI](/cli/secret-reference-syntax#with-1password-cli): Get secret references for one or multiple fields with `op item get`. > * Use the [secret reference syntax rules](/cli/secret-reference-syntax#syntax-rules) to write secret references manually. ## Step 2: Pass the secrets to the application > [tab] 1Password Environment > > To pass the secrets in your Environment to an application or script: > > 1. Open the 1Password app and navigate to **Developer** > **Environments**. > 2. Select the Environment where your project secrets are stored, then select **Manage environment** > **Copy environment ID**. > 3. Use `op run --` with the command for starting the application or script. 1Password will run the provided command in a subprocess with the secrets made available as environment variables for the duration of the process. > > ```shell theme={null} > op run --environment -- > ``` > > For example: > > ```shell theme={null} > op run --environment blgexucrwfr2dtsxe2q4uu7dp4 -- ./my-script.sh > ``` > [tab] Secret references > > ### Step 1: Map secret references to environment variables > > To pass secrets to an application or script using `op run` and [secret references](/cli/secret-references), you must first map the secret references to the appropriate environment variables. To do this, you can set environment variables to secret references using an environment file or export them on the command line. > > > [tab] Environment file > > > > Environment (`.env`) files allow you to define multiple environment variables as secret references with `KEY=VALUE` statements separated by a newline. > > > > To use an environment file with `op run`, add key-value pairs for each of your project secrets with the value set to a [secret reference](/cli/secret-references). For example: > > > > ```shell title="prod.env" theme={null} > > AWS_ACCESS_KEY_ID="op://development/aws/Access Keys/access_key_id" > > AWS_SECRET_ACCESS_KEY="op://development/aws/Access Keys/secret_access_key" > > ``` > > > > > [accordion] Environment file syntax rules > > > > > > The `.env` file parsing engine follows the following rules: > > > > > > * Environment variables are defined as `KEY=VALUE` statements separated by a newline. > > > > > > * Variables can span multiple lines if they are enclosed in either `'` or `"`: > > > > > > ``` > > > MY_VAR = "this is on the first line > > > and this is on the second line" > > > ``` > > > > > > * Empty lines are skipped. > > > > > > * Lines beginning with `#` are treated as comments. Comments can also be placed inline after `KEY=VALUE` statements. > > > > > > * Empty values become empty strings. For example, `EMPTY=` will set the environment variable `EMPTY` to the empty string. > > > > > > * If a value is surrounded by single or double quotes, these quotes do not end up in the evaluated value. So `KEY="VALUE"` and `KEY='VALUE'` both evaluate to `KEY` and `VALUE`. > > > > > > * Occurrences of `$VAR_NAME` or `${VAR_NAME}` are replaced with their respective value from the environment. > > > > > > * A variable defined in a .env file can be referred to later in the same file: > > > > > > ``` > > > SOME_VAR = value > > > OTHER_VAR = ${SOME_VAR} > > > ``` > > > > > > * Special characters can be escaped with `\`. For example, `MY_VAR = "\$SOME_VAR that is not actually replaced."` results in the following value for MY\_VAR: `$SOME_VAR that is not actually replaced.`. > > > > > > * Inner quotes are maintained, so `JSON={"foo":"bar"}` evaluates to `JSON` and `{"foo":"bar"}`. > > > > > > * Variables do not get replaced in values that are enclosed in single quotes. So `KEY='$SOME_VAR'` evaluates to `KEY` and `$SOME_VAR`. > > > > > > * Template syntax can be used in the `VALUE` to inject secrets. The `KEY` can only contain template variables. > > > > > > * Template parsing is performed after `.env` file parsing, so you cannot use the former to construct the latter. > > > > > > * Leading and trailing whitespace of both `KEY` and `VALUE` segments are ignored, so `KEY = VALUE` is parsed the same as `KEY=VALUE`. > > > > > > * Single and double quoted values maintain both leading and trailing whitespace, so `KEY=" some value "` evaluates to `KEY` and ` some value `. > > > > > > * These files should use UTF-8 character encoding. > > > > ### Optional: Differentiate between environments > > > > > [!TIP] > > > > > > If you need to pass secrets for multiple environments, we recommend using 1Password Environments instead of secret references. 1Password Environments allow you to more easily organize, share, and pass secrets for multiple contexts. > > > > If you have different sets of secrets for different environments, like staging and production, you can check a single environment file into source control and include a variable within the secret references to represent the context. You can then set the variable to the appropriate context when you pass the file to `op run`. > > > > To use this approach, you must organize your project secrets in 1Password into different vaults for each environment, with each item's fields structured in the same way. For example: `dev/mysql/password` and `prod/mysql/password`. > > > > Then, include an externally set variable (`$VARIABLE_NAME`) in place of the vault name for each secret reference in your environment file. > > > > For example, in the following environment file, `$APP_ENV` is the externally set environment variable. It can be set to `dev` or `prod` to load secrets from either the `dev` vault or the `prod` vault in 1Password. > > > > ```shell title="app.env" theme={null} > > MYSQL_DATABASE = "op://$APP_ENV/mysql/database" > > MYSQL_USERNAME = "op://$APP_ENV/mysql/username" > > MYSQL_PASSWORD = "op://$APP_ENV/mysql/password" > > ``` > > > [tab] Command line > > > > You can individually export environment variables as [secret references](/cli/secret-reference-syntax/) from the command line. > > > > For example, to set the variable `GITHUB_TOKEN` to a secret reference URI that points to the `personal_token` field within a `credentials` section in a `GitHub` item: > > > > > [tab] Bash, Zsh, sh > > > > > > ```shell theme={null} > > > export GITHUB_TOKEN=op://development/GitHub/credentials/personal_token > > > ``` > > > > > [tab] fish > > > > > > ```shell theme={null} > > > set -x GITHUB_TOKEN op://development/GitHub/credentials/personal_token > > > ``` > > > > > [tab] PowerShell > > > > > > ```powershell theme={null} > > > $Env:GITHUB_TOKEN = "op://development/GitHub/credentials/personal_token" > > > ``` > > ### Step 2: Pass the resolved secret references to the application > > > [tab] Environment file > > > > To use an environment file with `op run`, specify the path to the environment file using the `--env-file` flag: > > > > ```shell theme={null} > > op run --env-file="./prod.env" -- aws > > ``` > > > > If you structured your environment file to load secrets for multiple environments, make sure to also set the variable for the vault (in the example below, `APP_ENV`). > > > > For example, to pass secrets from the `dev` vault to an application running in the development environment: > > > > > [tab] Bash, Zsh, sh, fish > > > > > > ```shell theme={null} > > > APP_ENV=dev op run --env-file="./app.env" -- myapp deploy > > > ``` > > > > > [tab] PowerShell > > > > > > 1. Set the `$APP_ENV` variable: > > > > > > ```powershell theme={null} > > > $ENV:APP_ENV = "dev" > > > ``` > > > > > > 2. Run `op run` with the environment file: > > > > > > ```powershell theme={null} > > > op run --env-file="./app.env" -- myapp deploy > > > ``` > > > [tab] Command line > > > > If you exported environment variables as secret references on the command line, use `op run --` with the command to start the application or script. 1Password will run the provided command in a subprocess with the secrets made available as environment variables for the duration of the process. > > > > ```shell theme={null} > > op run -- > > ``` > > > > For example: > > > > ```shell theme={null} > > op run -- gh > > ``` > > > > > [!TIP] > > > > > > **Expand variables in a subshell** > > > > > > When you reference a variable like `$MY_VAR` in the same command where you call `op run`, your shell expands `$MY_VAR` before `op run` can substitute the secret reference. For example, a command like the following will pass the secret reference URI instead of the secret value from 1Password: > > > > > > ```shell theme={null} > > > MY_VAR=op://vault/item/field op run --no-masking -- echo "$MY_VAR" > > > ``` > > > > > > To make sure `op run` substitutes the secret before the variable expands, run the command to expand the variable in a subshell: > > > > > > ```shell theme={null} > > > MY_VAR=op://vault/item/field op run --no-masking -- sh -c 'echo "$MY_VAR"' > > > #code-result open > > > skdjfs7dyrwhk4jhref > > > ``` > [!TIP] > > **Use both methods together** > > You can load secrets from an Environment in combination with secret references from a `.env` file or flag. For example: > > ```shell theme={null} > op run --environment --env-file="./extra-secrets.env" -- > ``` ## Next step: Run in production Now that the application works locally, choose how to load your secrets in production or CI/CD: * **[1Password Service Account](/service-accounts/use-with-1password-cli)**: Automate access with a service account token. Service accounts support both secret references and 1Password Environments. * **[1Password Connect Server](/connect/cli/)**: Best for self-hosting within your own infrastructure. Connect only supports secret references and does not currently support 1Password Environments. ## Learn more * [Use 1Password Service Accounts with 1Password CLI](/service-accounts/use-with-1password-cli) * [Use 1Password Connect Server with 1Password CLI](/connect/cli#continuous-integration-ci-environments) * [Load secrets into config files](/cli/secrets-config-files/) * [Secret reference syntax](/cli/secret-reference-syntax/) * [Template syntax](/cli/secrets-template-syntax/) * [Workflow: Secure your deployments](/get-started/secure-deployment) # Load secrets into scripts Source: https://www.1password.dev/cli/secrets-scripts You can use 1Password CLI to load secrets into your scripts, so that the credentials in your scripts are always in sync with the information in your 1Password account and your secrets are never exposed in plaintext. > [!TIP] > > We recommend using [1Password Service Accounts](/service-accounts/) to follow the [principle of least privilege](/cli/best-practices/). Service accounts support restricting 1Password CLI to specific vaults, so that processes in your authorized terminal session can only access items required for a given purpose. > > Service accounts are also useful if your personal account has SSO or MFA requirements. You can use the following methods to load secrets into scripts, separately or in combination: 1. [Use `op run` to pass secrets from a 1Password Environment](#use-op-run-to-pass-secrets-from-a-1password-environment) 2. [Use `op run` to load secrets into the environment.](#use-op-run-to-pass-secrets-using-secret-references) 3. [Use `op read` to read secrets.](#use-op-read-to-read-secrets) 4. [Use `op inject` to load secrets into a config file.](#use-op-inject-to-load-secrets-into-a-config-file) 5. [Use `op plugin run` to load secrets using a shell plugin.](#use-op-plugin-run-to-load-secrets-using-a-shell-plugin) > [card] [Building an integration or automated workflow?](/get-started/build-integrations) > > Follow the build integrations workflow guide to choose the right authentication method and configuration for your use case. ## Requirements Before you can use 1Password CLI to load secrets into your scripts, you'll need to: 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. [Install 1Password CLI.](/cli/get-started#step-1-install-1password-cli) 3. Store the secrets you need for your script in your 1Password account. ## Use `op run` to pass secrets from a 1Password Environment You can use [`op run`](/cli/reference/commands/run/) to [pass the secrets](/cli/secrets-environment-variables) stored in a [1Password Environment](/environments) to an application or script at runtime. 1Password CLI runs the application or script in a subprocess with the secrets stored in your 1Password Environment provisioned as environment variables for the duration of the process. ## Use `op run` to pass secrets using secret references You can replace the plaintext secrets in your environment files with [secret reference URIs](/cli/secret-reference-syntax/) that reference where your project secrets are stored in your 1Password account, then use [`op run`](/cli/reference/commands/run/) to load the corresponding secrets from 1Password and pass them to your script as environment variables at runtime. Learn more about [loading secrets into the environment](/cli/secrets-environment-variables/). ## Use `op read` to read secrets You can use `op read` with secret references [directly in your script](#directly-in-your-script) or [with environment variables](#with-environment-variables). ### Directly in your script With this method, secrets are only passed to the single command that includes the secret reference. For example, to replace your Docker username and password with [secret references](/cli/secret-reference-syntax/) in a command to log in to Docker: ```shell title="yourscript.sh" theme={null} #!/bin/bash docker login -u "$(op read op://prod/docker/username)" -p "$(op read op://prod/docker/password)" ``` ### With environment variables You can also include a command to set environment variables to `op read` and [secret references](/cli/secret-reference-syntax/) in your script. For example, if you supply an AWS command in your script with secrets using the `AWS_SECRET_ACCESS_KEY` and `AWS_ACCESS_KEY_ID` environment variables, your script might look like this: ```shell title="yourscript.sh" theme={null} #!/bin/bash export AWS_SECRET_ACCESS_KEY="$(op read op://prod/aws/secret-key)" export AWS_ACCESS_KEY_ID="$(op read op://prod/aws/access-key-id)" aws sts get-caller-identity ``` ## Use `op inject` to load secrets into a config file If your script uses a configuration file, you can template the config file with [secret references](/cli/secret-reference-syntax/), then use [`op inject`](/cli/reference/commands/inject/) to pass the config file with the resolved secrets to your script at runtime. This allows you to check config files into source control and keep them in sync throughout developer workstations, CI, and production servers. And you can include template variables within the secret references to [load different sets of secrets for different environments](/cli/secrets-config-files#step-3-differentiate-between-environments). [Learn how to load secrets into config files](/cli/secrets-config-files/). ## Use `op plugin run` to load secrets using a shell plugin If your script runs interactively and each person using the script authenticates with their own personal token, you can minimize the configuration required in advance of using the script with a [1Password Shell Plugin](/cli/shell-plugins/). Shell plugins prompt each user to select their credentials when the script is executed. Each person using the script will be prompted to configure when their credentials should be used to authenticate. To make sure the credentials they selected will also be used for future invocations of the script, they can configure their credentials as a global or directory default. To use a shell plugin to authenticate an individual command, wrap the command in [`op plugin run`](/cli/reference/management-commands/plugin#plugin-run). For example, to use the AWS shell plugin to provide an AWS Access Key and Secret Key ID to the `sts get-caller-identity` command: ```shell title="yourscript.sh" theme={null} #!/bin/bash op plugin run -- aws sts get-caller-identity ``` To use a shell plugin throughout a script, you can include an alias for the tool's executable command at the beginning of the script. For example, in this script, the AWS shell plugin would be used to supply secrets for every `aws` command in the script. ```shell title="yourscript.sh" theme={null} #!/bin/bash alias aws="op plugin run -- aws" aws sts get-caller-identity ``` If a shell plugin doesn't exist for the tool you're using, you can [build a new plugin](/cli/shell-plugins/contribute/). ## Learn more * [Example CLI scripts](/cli/scripts/) * [Get started with secret references](/cli/secret-references/) * [Load secrets into the environment](/cli/secrets-environment-variables/) * [Load secrets into config files](/cli/secrets-config-files/) * [Use 1Password Shell Plugins to securely authenticate third-party CLIs](/cli/shell-plugins/) * [Workflow: Secure local development](/get-started/secure-developer-secrets) # Template syntax Source: https://www.1password.dev/cli/secrets-template-syntax You can create a templated config file that contains [secret references](/cli/secret-reference-syntax/), then [use op inject](/cli/secrets-config-files/) to receive a resolved config file that contains the actual secrets. Here's an example of a template file with enclosed secret references in place of the plaintext secrets: ```yml config.yml.tpl theme={null} database: host: localhost port: 5432 username: {{ op://prod/database/username }} password: {{ op://prod/database/password }} ``` ## Secret references Secret references included in template files can be formatted as either [unenclosed secret references](#unenclosed-secret-references) or [enclosed secret references](#enclosed-secret-references). ### Unenclosed secret references ```shell theme={null} op://test-app/database/password ``` An unenclosed secret reference is a string that: * Begins with `op://` and is not preceded by any of the characters from: `alphanumeric`, `-`, `+` , `\`, `.`. * Ends with either the end of the template, or the first encountered character outside the following set: `alphanumeric`, `-`, `?`, `_`, `.`. Examples of good and bad unenclosed secret references: ```yml theme={null} op://prod/docker-credentials/username ``` ```yml theme={null} op://d3v/stripe.keys/s3ct10n/public_key ``` ```yml theme={null} op://h?ack/1Password!/for"real ``` (contains special characters that are not supported by the syntax) ```yml theme={null} op://{vault}/[item]/(section)/field ``` (contains special characters that are not supported by the syntax) ### Enclosed secret references ```shell theme={null} {{ op://test-app/database/password }} ``` An enclosed secret reference is defined as any string that satisifies all of the following: * Begins with two closed braces `{{` * Ends with the two closed braces `}}` * Contains a valid unenclosed secret reference between the two pairs of braces, possibly padded with spaces Examples of good and bad enclosed secret references: ```yml theme={null} {{op://prod/docker-credentials/username}} ``` ```yml theme={null} {{ op://d3v/stripe.keys/s3ct10n/public_key }} ``` ```yml theme={null} {{op://h?ack/1Password!/for"real}} ``` (the secret reference contains unsupported characters) ### Special characters If you need to escape special characters in your template, you can use curly braces and double quotes: ```yml theme={null} {{ "{{ test op://prod/docker-credentials/username }}" }} will be resolved to {{ test op://prod/docker-credentials/username }} ``` If the content contains double quotes, they must be escaped with `\`: ```yml theme={null} {{ "{{ test \"test\" test }}" }} will be resolved to {{ test "test" test }} ``` ## Variables The template syntax also supports variable tags: * `$var` (unenclosed variables) * `${var}` (enclosed variables) When resolving an unenclosed variable of the form `$FOO`, it is replaced with the value of the environment variable named `FOO`. When resolving an enclosed variable of the form `${FOO}`, any whitespace at the beginning or end of `FOO` is discarded and the reference is replaced with the value of the environment variable named `FOO`. Variable names are case-insensitive, cannot start with a number, and can only contain letters, numbers, and underscores. Examples of good and bad unenclosed variables: ```yml theme={null} $my_var ``` ```yml theme={null} $mY_2nd_vAr ``` ```yml theme={null} $2nd_var ``` (starts with a number) ```yml theme={null} $var-?notvar! ``` (contains unsupported special characters) Examples of good and bad enclosed variables: ```yml theme={null} ${my_var} ``` ```yml theme={null} ${ mY_2nd_vAr } ``` ```yml theme={null} ${my_var\} ``` (the closing brace is escaped) ### Default values To set a default value for a template variable, use this syntax: `${VAR_NAME:-}` The default value will be used when the variable can't be found in the environment. For example, `op://${VAULT:-dev}/docker/password` evaluates to `op://dev/docker/password` when the `VAULT` environment variable isn't set. If `VAULT` is set to `prod` instead, it will evaluate to `op://prod/docker/password`. ## Learn more * [Load secrets into config files](/cli/secrets-config-files/) * [Load secrets into the environment](/cli/secrets-environment-variables/) * [Secret reference syntax](/cli/secret-reference-syntax/) * [Workflow: Secure local development](/get-started/secure-developer-secrets) # Use 1Password Shell Plugins to securely authenticate any CLI Source: https://www.1password.dev/cli/shell-plugins Use 1Password Shell Plugins to sign in to third-party CLIs with your fingerprint instead of keeping API keys and tokens in plaintext config files. With 1Password Shell Plugins, you can configure 1Password to securely authenticate third-party CLIs with your fingerprint, Apple Watch, or system authentication. Your CLI credentials are stored in your 1Password account, so you never have to manually enter your credentials or store them in plaintext. ![Mac terminal window showing 1Password saving a GitLab access token and setting up authentication for the GitLab CLI.](https://images.ctfassets.net/3091ajzcmzlr/2cfte9fVfkmwNRqJN2jsEf/d6b1d29024086e1bc86480c922f005ab/_Users_andrewhill_Projects_blog.1password.com_content_posts_2022_shell-plugins_gitlab_access_token.png) Setting up the GitLab CLI shell plugin with op plugin init. You can [test shell plugins](/cli/shell-plugins/test/) or choose a shell plugin from the [list below](#get-started) to get started. Shell plugins are compatible with the following shells: * Bash * Zsh * fish [Unlock Any CLI Using Your Fingerprint With 1Password Shell Plugins](https://www.youtube.com/embed/7aT4K1AMfGI) ## Get started [Akamai](/cli/shell-plugins/akamai/) [Argo CD](/cli/shell-plugins/argo-cd/) [Axiom](/cli/shell-plugins/axiom) [AWS](/cli/shell-plugins/aws/) [AWS CDK Toolkit](/cli/shell-plugins/aws-cdk-toolkit/) [AWS Eksctl](/cli/shell-plugins/eksctl/) [AWS SAM CLI](/cli/shell-plugins/aws-sam-cli/) [awslogs](/cli/shell-plugins/awslogs/) [Binance](/cli/shell-plugins/binance) [Cachix](/cli/shell-plugins/cachix/) [Cargo](/cli/shell-plugins/cargo/) [CircleCI](/cli/shell-plugins/circleci/) [Claude Code](/cli/shell-plugins/claude-code/) [Civo](/cli/shell-plugins/civo) [Cline](/cli/shell-plugins/cline) [Cloudflare Workers](/cli/shell-plugins/cloudflare-workers/) [CockroachDB](/cli/shell-plugins/cockroachdb) [CrateDB](/cli/shell-plugins/cratedb) [Crowdin](/cli/shell-plugins/crowdin) [Cursor](/cli/shell-plugins/cursor) [Databricks](/cli/shell-plugins/databricks/) [Descope](/cli/shell-plugins/descope) [DigitalOcean](/cli/shell-plugins/digitalocean/) [Dogshell](/cli/shell-plugins/datadog/) [Doppler](/cli/shell-plugins/doppler) [EAS](/cli/shell-plugins/eas) [Exercism](/cli/shell-plugins/exercism) [Expo](/cli/shell-plugins/expo) [Fastly](/cli/shell-plugins/fastly/) [Flyctl](/cli/shell-plugins/flyctl) [FOSSA](/cli/shell-plugins/fossa/) [Gitea](/cli/shell-plugins/gitea/) [GitHub](/cli/shell-plugins/github/) [GitHub Copilot](/cli/shell-plugins/github-copilot) [GitLab](/cli/shell-plugins/gitlab/) [Gemini CLI](/cli/shell-plugins/gemini) [Grok Build](/cli/shell-plugins/xai-grok) [HashiCorp Vault](/cli/shell-plugins/hashicorp-vault/) [Heroku](/cli/shell-plugins/heroku/) [Hetzner Cloud](/cli/shell-plugins/hetzner-cloud/) [Homebrew](/cli/shell-plugins/homebrew/) [HuggingFace](/cli/shell-plugins/huggingface) [InfluxDB](/cli/shell-plugins/influxdb) [JetBrains Junie](/cli/shell-plugins/jetbrains-junie) [Kaggle](/cli/shell-plugins/kaggle) [Kiro](/cli/shell-plugins/kiro) [Lacework](/cli/shell-plugins/lacework/) [Laravel Forge](/cli/shell-plugins/laravel-forge/) [Laravel Vapor](/cli/shell-plugins/laravel-vapor/) [Linode](/cli/shell-plugins/linode/) [LocalStack](/cli/shell-plugins/localstack/) [LocalXpose](/cli/shell-plugins/localxpose) [MongoDB Atlas](/cli/shell-plugins/mongodb-atlas) [MotherDuck](/cli/shell-plugins/motherduck) [MySQL](/cli/shell-plugins/mysql/) [Netlify](/cli/shell-plugins/netlify) [ngrok](/cli/shell-plugins/ngrok/) [npm and pnpm](/cli/shell-plugins/npm) [Octopus Deploy](/cli/shell-plugins/octopus-deploy) [Oh Dear](/cli/shell-plugins/oh-dear/) [Okta](/cli/shell-plugins/okta/) [OpenAI](/cli/shell-plugins/openai/) [OpenAI Codex CLI](/cli/shell-plugins/openai-codex/) [OpenAI Evals](/cli/shell-plugins/openai-evals/) [OpenBao](/cli/shell-plugins/openbao) [OpenCode](/cli/shell-plugins/opencode) [OpenTofu](/cli/shell-plugins/opentofu) [Pipedream](/cli/shell-plugins/pipedream) [PostgreSQL](/cli/shell-plugins/postgresql/) [Postman](/cli/shell-plugins/postman) [Pulumi](/cli/shell-plugins/pulumi/) [PyPI](/cli/shell-plugins/pypi) [ReadMe](/cli/shell-plugins/readme/) [Redis](/cli/shell-plugins/redis) [Scaleway](/cli/shell-plugins/scaleway/) [Sentry](/cli/shell-plugins/sentry/) [Snowflake](/cli/shell-plugins/snowflake/) [Snyk](/cli/shell-plugins/snyk/) [Sourcegraph](/cli/shell-plugins/sourcegraph/) [Spacelift](/cli/shell-plugins/spacelift) [Stackhero](/cli/shell-plugins/stackhero) [Stripe](/cli/shell-plugins/stripe/) [Terraform](/cli/shell-plugins/terraform/) [Todoist](/cli/shell-plugins/todoist) [Treasure Data](/cli/shell-plugins/treasure-data/) [Tugboat](/cli/shell-plugins/tugboat/) [Twilio](/cli/shell-plugins/twilio/) [UpCloud](/cli/shell-plugins/upcloud) [Upstash](/cli/shell-plugins/upstash) [Vercel](/cli/shell-plugins/vercel/) [Vertica](/cli/shell-plugins/vertica) [Vultr](/cli/shell-plugins/vultr/) [YugabyteDB](/cli/shell-plugins/yugabytedb/) [Zapier](/cli/shell-plugins/zapier) [Zendesk](/cli/shell-plugins/zendesk/) ## Your favorite tool not listed? Find out how to [build your own plugin](/cli/shell-plugins/contribute/). # Use 1Password to securely authenticate the Akamai CLI Source: https://www.1password.dev/cli/shell-plugins/akamai The Akamai CLI shell plugin allows you to use 1Password to securely authenticate [the Akamai CLI](https://techdocs.akamai.com/developer/docs/about-clis) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Akamai CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.13.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Akamai CLI.](https://techdocs.akamai.com/developer/docs/about-clis) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Akamai CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the Akamai CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init akamai
You'll be prompted to import your Akamai CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/akamai-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Akamai CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/akamai-2.png) #### Select an existing item If you've already saved your Akamai CLI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/akamai-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Akamai CLI. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/akamai-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Akamai CLI, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/Ul-COtb5ywadNlrP/static/img/shell-plugins/akamai-5.png?fit=max\&auto=format\&n=Ul-COtb5ywadNlrP\&q=85\&s=7ff58a20c55b9ff24e5c31fd925e62ad) ## Step 4: Remove imported credentials from disk After saving your Akamai CLI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Akamai CLI configuration: op plugin inspect akamai 1Password CLI will return a list of the credentials you've configured to use with Akamai CLI and their default scopes, as well as a list of aliases configured for Akamai CLI. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/Ul-COtb5ywadNlrP/static/img/shell-plugins/akamai-6.png?fit=max\&auto=format\&n=Ul-COtb5ywadNlrP\&q=85\&s=3e5e02667249e1d625c727850620ee1f) ### Clear your credentials To reset the credentials used with Akamai CLI: op plugin clear akamai You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear akamai` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear akamai --all`. ## Reference 1Password authenticates with Akamai by injecting a temporary config file with the credentials required by the plugin commands directly from your 1Password account. If you saved your Akamai CLI credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | `.edgerc` field | | - | - | | Client Secret | `client_secret` | | Host | `host` | | Access Token | `access_token` | | Client Token | `Client_token` | *Thanks to [@wongle](https://github.com/wongle) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/234) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate Argo CD CLI Source: https://www.1password.dev/cli/shell-plugins/argo-cd The Argo CD shell plugin allows you to use 1Password to securely authenticate [Argo CD CLI](https://argo-cd.readthedocs.io/en/stable/user-guide/commands/argocd/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Argo CD CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.13.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [Argo CD CLI.](https://argo-cd.readthedocs.io/en/stable/cli_installation/) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Argo CD CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the Argo CD CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init argocd
You'll be prompted to import your Argo CD CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/argocd-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Argo CD CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/argocd-2.png) #### Select an existing item If you've already saved your Argo CD CLI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/argocd-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Argo CD CLI. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/argocd-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Argo CD CLI, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/Ul-COtb5ywadNlrP/static/img/shell-plugins/argocd-5.png?fit=max\&auto=format\&n=Ul-COtb5ywadNlrP\&q=85\&s=9c6da6cff30591957887dce277be826d) ## Step 4: Remove imported credentials from disk After saving your Argo CD CLI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Argo CD CLI configuration: op plugin inspect argocd 1Password CLI will return a list of the credentials you've configured to use with Argo CD CLI and their default scopes, as well as a list of aliases configured for Argo CD CLI. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/Ul-COtb5ywadNlrP/static/img/shell-plugins/argocd-6.png?fit=max\&auto=format\&n=Ul-COtb5ywadNlrP\&q=85\&s=c3871d769584727a68de9b55c67e5d53) ### Clear your credentials To reset the credentials used with Argo CD CLI: op plugin clear argocd You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear argocd` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear argocd --all`. ## Reference 1Password authenticates with Argo CD CLI by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Argo CD CLI credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | AuthToken | `ARGOCD_AUTH_TOKEN` | | Address (optional) | `ARGOCD_SERVER` | If your item includes an Address, 1Password only provides credentials when Argo CD CLI targets that server, whether the server is set with `--server`, `ARGOCD_SERVER`, `--argocd-context`, or your current context. If Argo CD CLI isn't targeting a specific server, 1Password provides the credentials from your item. For other servers, Argo CD CLI uses the credentials saved in its config file when you signed in with `argocd login`. The `argocd login` and `argocd relogin` commands don't use your 1Password item. *Thanks to [@ssttehrani](https://github.com/ssttehrani) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/145) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate the AWS CLI Source: https://www.1password.dev/cli/shell-plugins/aws The AWS shell plugin allows you to use 1Password to securely authenticate [the AWS CLI](https://aws.amazon.com/cli/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the AWS CLI with biometrics. If you use `cdk`, you can also set up the [AWS CDK Toolkit shell plugin](/cli/shell-plugins/aws-cdk-toolkit/). If you use `eksctl`, you can set up the [eksctl shell plugin](/cli/shell-plugins/eksctl/). ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the AWS CLI.](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) After you install the AWS CLI, make sure you have an AWS config file at `~/.aws/config` on Mac or Linux, or `C:\Users\USERNAME\.aws\config` on Windows. If you don't have a config file: 1. Use [`aws configure`](https://docs.aws.amazon.com/cli/latest/reference/configure/) to create one. 2. When prompted, skip entering your AWS access key pair to avoid writing your credentials on disk in the `.aws/credentials` file. The following shells are supported: * Bash * Zsh * fish ## Before you begin: Create and save an AWS access key If you've already created an AWS access key, [skip to Step 1](#step-1-configure-your-default-credentials). If you haven't created an access key yet, you can create one and use the [1Password browser extension](https://support.1password.com/getting-started-browser/) to quickly save it in 1Password: 1. Open and unlock [1Password in your browser](https://support.1password.com/getting-started-browser/). 2. [Follow the steps](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html?icmpid=docs_iam_console#Using_CreateAccessKey) to create an access key for the AWS CLI. 3. On the "Retrieve access keys" page, select **Show** to reveal the secret access key. 4. Select **Save item** when 1Password asks if you want to save an item for the AWS access key. 5. Choose the vault where you want to save the item, edit the item's name and details, then select **Save item**. ![The pop-up screen to save your AWS access key in 1Password.](https://mintcdn.com/ab-634991b8/Ul-COtb5ywadNlrP/static/img/shell-plugins/aws-save.png?fit=max\&auto=format\&n=Ul-COtb5ywadNlrP\&q=85\&s=1dbff1f579b57b088ad124ff7355a53c) ## Step 1: Configure your default credentials > [!TIP] > > **If you use AWS in multiple environments** > > If you want to use the AWS shell plugin in multiple environments, like production and development, [learn how to set up your plugin for seamless context switching](/cli/shell-plugins/environments/). To get started with the AWS shell plugin:
  1. Sign in to the 1Password account you want to use with the AWS plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init aws
You'll be prompted to import your AWS credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/aws-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your AWS credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/aws-2.png) #### Select an existing item If you've already saved your AWS credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/aws-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate AWS. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/aws-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with AWS, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/Ul-COtb5ywadNlrP/static/img/shell-plugins/aws-5.png?fit=max\&auto=format\&n=Ul-COtb5ywadNlrP\&q=85\&s=29e1785425ad21c02080c96aaad2ee55) ## Step 4: Remove imported credentials from disk After you save your AWS credentials in 1Password, you can remove all local copies you currently have stored on disk. Plaintext access keys are commonly stored in your AWS [shared credentials file](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/creds-file.html) (default location: `~/.aws/credentials`). If you remove your credentials from this file, make sure to configure shell plugins for any other tools that use the file to authenticate to AWS, like [Terraform](/cli/shell-plugins/terraform/). ## Optional: Assume multiple roles You can use the AWS shell plugin to assume multiple roles in the same way you'd assume roles with the AWS CLI, by defining role profiles [in your AWS config file.](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html#cli-role-prepare) For example: ```html ~/.aws/config theme={null} [profile prod] role_arn = arn:aws:iam::123456789012:role/prod source_profile = wendyappleseed ``` Then include the `--profile` flag to call an AWS command using a role. For example: ```shell theme={null} aws sts get-caller-identity --profile prod ``` If you want to always use the same profile, you can set the `AWS_PROFILE` environment variable. In that case, the `--profile` flag would only be needed to override the default set in the environment. For example: ```shell theme={null} export AWS_PROFILE=prod ``` ## Optional: Set up multi-factor authentication If you use [multi-factor authentication](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa.html) with AWS, you can configure the AWS shell plugin to provide your one-time password. You can do this in two ways: * [Add the ARN for your multi-factor authentication device to a profile in your AWS config file.](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html#cli-configure-role-mfa) * Add the one-time password code and ARN to the item in 1Password where your AWS credentials are stored. If you choose this option, your multi-factor authentication information will be treated as your `default` profile and used globally with every other profile. ### Save your one-time password and ARN in 1Password #### Step 1: Save your QR code 2. Open and unlock the 1Password app. 3. Select the item where your AWS credentials are saved, then select **Edit**. 4. Select **Add More** > **One-Time Password**. 5. [Follow the steps to enable a virtual multi-factor authentication device](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa_enable_virtual.html) for your AWS account. 6. Select **Show secret key** in the AWS wizard, then copy the string of characters into the One-Time Password field on your item. 7. Select **Save**. Your item will now show a one-time password that you can use to finish the AWS multi-factor authentication device set-up flow. Your edited item must include the `one-time password` and `mfa serial` fields: ![The AWS item in 1Password with MFA credentials added.](https://mintcdn.com/ab-634991b8/Ul-COtb5ywadNlrP/static/img/shell-plugins/aws-mfa.png?fit=max\&auto=format\&n=Ul-COtb5ywadNlrP\&q=85\&s=bd93eb598d2546197eb749c500776ac2) #### Step 2: Save the ARN for your multi-factor authentication device 1. Find the [ARN for your multi-factor authentication device](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa_checking-status.html) and copy it. 2. Open and unlock the 1Password app. 3. Select the item where you saved your AWS credentials then select **Edit**. 4. Select **Add More** > **Text**. 5. Paste the ARN as the value of the field. 6. Title the field `mfa serial`. 7. Select **Save**. 1Password CLI will detect your multi-factor authentication credentials if they're saved in fields titled `one-time password` and `mfa serial`. If your one-time password isn't detected, make sure your fields are titled correctly. 1Password CLI will then set the `AWS_SECRET_ACCESS_KEY`, `AWS_ACCESS_KEY_ID` and `AWS_SESSION_TOKEN` provisional environment variables to specify the temporary multi-factor authentication session values. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current AWS configuration: op plugin inspect aws 1Password CLI will return a list of the credentials you've configured to use with AWS and their default scopes, as well as a list of aliases configured for AWS. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/Ul-COtb5ywadNlrP/static/img/shell-plugins/aws-6.png?fit=max\&auto=format\&n=Ul-COtb5ywadNlrP\&q=85\&s=17ae1e62d7c9c38ceefa454b549dda7d) ### Clear your credentials To reset the credentials used with AWS: op plugin clear aws You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear aws` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear aws --all`. ## Reference 1Password authenticates with AWS by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your AWS credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variables | | - | - | | Access Key ID | `AWS_ACCESS_KEY_ID` | | Secret Access Key | `AWS_SECRET_ACCESS_KEY` | | Default region (optional) | `AWS_DEFAULT_REGION` | ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate the AWS CDK Toolkit Source: https://www.1password.dev/cli/shell-plugins/aws-cdk-toolkit The AWS CDK Toolkit shell plugin allows you to use 1Password to securely authenticate the [AWS CDK Toolkit](https://docs.aws.amazon.com/cdk/v2/guide/cli.html) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the AWS CDK Toolkit with biometrics. You can also set up the [AWS CLI shell plugin](/cli/shell-plugins/aws/) or the [eksctl shell plugin](/cli/shell-plugins/eksctl/). ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.17.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. [Install the AWS CDK Toolkit.](https://docs.aws.amazon.com/cdk/v2/guide/cli.html) 6. Make sure you have an AWS config file at `~/.aws/config` on Mac or Linux, or `C:\Users\USERNAME\.aws\config` on Windows. If you don't have a config file, use [`aws configure`](https://docs.aws.amazon.com/cli/latest/reference/configure/) to create one. When prompted, skip entering your AWS access key pair to avoid writing your credentials on disk in the `.aws/credentials` file. The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the the AWS CDK Toolkit shell plugin:
  1. Sign in to the 1Password account you want to use with the the AWS CDK Toolkit plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init cdk
You'll be prompted to import your the AWS CDK Toolkit credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/cdk-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your the AWS CDK Toolkit credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/cdk-2.png) #### Select an existing item If you've already saved your the AWS CDK Toolkit credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/cdk-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate the AWS CDK Toolkit. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/cdk-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with the AWS CDK Toolkit, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/Ul-COtb5ywadNlrP/static/img/shell-plugins/cdk-5.png?fit=max\&auto=format\&n=Ul-COtb5ywadNlrP\&q=85\&s=793714b75fd6f181891f6f8bb20eadf9) ## Step 4: Remove imported credentials from disk After saving your the AWS CDK Toolkit credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current the AWS CDK Toolkit configuration: op plugin inspect cdk 1Password CLI will return a list of the credentials you've configured to use with the AWS CDK Toolkit and their default scopes, as well as a list of aliases configured for the AWS CDK Toolkit. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/Ul-COtb5ywadNlrP/static/img/shell-plugins/cdk-6.png?fit=max\&auto=format\&n=Ul-COtb5ywadNlrP\&q=85\&s=946c668c160a57ee4df4139b24480075) ### Clear your credentials To reset the credentials used with the AWS CDK Toolkit: op plugin clear cdk You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear cdk` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear cdk --all`. ## Reference 1Password authenticates with the AWS CDK Toolkit by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your the AWS CDK Toolkit credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variables | | - | - | | Access Key ID | `AWS_ACCESS_KEY_ID` | | Secret Access Key | `AWS_SECRET_ACCESS_KEY` | | Default region (optional) | `AWS_DEFAULT_REGION` | ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate the AWS SAM CLI Source: https://www.1password.dev/cli/shell-plugins/aws-sam-cli The AWS SAM CLI shell plugin allows you to use 1Password to securely authenticate [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/reference-sam-cli.html) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate AWS SAM CLI with biometrics. You can also set up the [AWS CLI shell plugin](/cli/shell-plugins/aws/). ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.34.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. [Install AWS SAM CLI.](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/reference-sam-cli.html) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the AWS SAM CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the AWS SAM CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init sam
You'll be prompted to import your AWS SAM CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your AWS SAM CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. #### Select an existing item If you've already saved your AWS SAM CLI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate AWS SAM CLI.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with AWS SAM CLI, you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your AWS SAM CLI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current AWS SAM CLI configuration: op plugin inspect sam 1Password CLI will return a list of the credentials you've configured to use with AWS SAM CLI and their default scopes, as well as a list of aliases configured for AWS SAM CLI. ### Clear your credentials To reset the credentials used with AWS SAM CLI: op plugin clear sam You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear sam` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear sam --all`. ## Reference 1Password authenticates with AWS SAM CLI by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your AWS SAM CLI credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variables | | - | - | | Access Key ID | `AWS_ACCESS_KEY_ID` | | Secret Access Key | `AWS_SECRET_ACCESS_KEY` | *Thanks to [@simonmcc](https://github.com/simonmcc) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/473) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* # Use 1Password to securely authenticate awslogs Source: https://www.1password.dev/cli/shell-plugins/awslogs The `awslogs` shell plugin allows you to use 1Password to securely authenticate [`awslogs`](https://github.com/jorgebastida/awslogs) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate `awslogs` with biometrics. You can also set up the [AWS CLI shell plugin](/cli/shell-plugins/aws/). ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.34.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. [Install `awslogs`.](https://github.com/jorgebastida/awslogs) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the `awslogs` shell plugin:
  1. Sign in to the 1Password account you want to use with the `awslogs` plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init awslogs
You'll be prompted to import your `awslogs` credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your `awslogs` credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. #### Select an existing item If you've already saved your `awslogs` credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate `awslogs`.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with `awslogs`, you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current `awslogs` configuration: op plugin inspect awslogs 1Password CLI will return a list of the credentials you've configured to use with `awslogs` and their default scopes, as well as a list of aliases configured for `awslogs`. ### Clear your credentials To reset the credentials used with `awslogs`: op plugin clear awslogs You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear awslogs` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear awslogs --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variables | | - | - | | Access Key ID | `AWS_ACCESS_KEY_ID` | | Secret Access Key | `AWS_SECRET_ACCESS_KEY` | *Thanks to [@jonasws](https://github.com/jonasws) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/504) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* # Use 1Password to securely authenticate Axiom CLI Source: https://www.1password.dev/cli/shell-plugins/axiom The Axiom CLI shell plugin allows you to use 1Password to securely authenticate [Axiom CLI](https://axiom.co/docs/reference/cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Axiom CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.x.x or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/). 5. [Install Axiom CLI.](https://axiom.co/docs/reference/cli) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Axiom CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the Axiom CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init axiom
You'll be prompted to import your Axiom CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Axiom CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. #### Select an existing item If you've already saved your Axiom CLI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Axiom CLI.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Axiom CLI, you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your Axiom CLI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Axiom CLI configuration: op plugin inspect axiom 1Password CLI will return a list of the credentials you've configured to use with Axiom CLI and their default scopes, as well as a list of aliases configured for Axiom CLI. ### Clear your credentials To reset the credentials used with Axiom CLI: op plugin clear axiom You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear axiom` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear axiom --all`. ## Reference 1Password authenticates with Axiom CLI by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Axiom CLI credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | Token | `AXIOM_TOKEN` | | Organization | `AXIOM_ORG_ID` | | Deployment | `AXIOM_DEPLOYMENT` | *Thanks to [@rajapri28613](https://github.com/rajapri28613) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/342) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate Binance CLI Source: https://www.1password.dev/cli/shell-plugins/binance Store your API key in 1Password then authenticate Binance CLI with your fingerprint. The Binance shell plugin allows you to use 1Password to securely authenticate [Binance CLI](https://github.com/binance/binance-cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext.Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Binance CLI with biometrics.## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.22.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install Binance CLI.](https://github.com/binance/binance-cli)
The following shells are supported:
  • Bash
  • Zsh
  • fish
## Step 1: Configure your default credentialsTo get started with the Binance shell plugin:
  1. Sign in to the 1Password account you want to use with the Binance plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init binance-cli
You'll be prompted to import your Binance credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used.### Step 1.1: Import or select an item#### Import a new itemIf you haven't saved your Binance credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it.If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them.#### Select an existing itemIf you've already saved your Binance credentials in 1Password, select **Search in 1Password**.You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account.### Step 1.2: Set default credential scopeAfter you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Binance.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh fileTo make the plugin available, source your `plugins.sh` file. For example:```shell theme={null} source ~/.config/op/plugins.sh ```The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path.If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example:```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``````shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``````shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ```## Step 3: Use the CLIThe next time you enter a command with Binance, you'll be prompted to authenticate with biometrics or system authentication.## Step 4: Remove imported credentials from diskAfter saving your Binance credentials in 1Password, you can remove all local copies you previously had stored on disk.## Next steps1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs:```shell theme={null} op plugin list ```To choose another plugin to get started with:```shell theme={null} op plugin init ```To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/)## Get help### Inspect your configurationTo inspect your current Binance configuration:op plugin inspect binance-cli1Password CLI will return a list of the credentials you've configured to use with Binance and their default scopes, as well as a list of aliases configured for Binance.### Clear your credentialsTo reset the credentials used with Binance:op plugin clear binance-cliYou can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear binance-cli` four times to clear all of your defaults.To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear binance-cli --all`.## Reference 1Password authenticates with Binance by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Binance credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. \ \ \
1Password field nameEnvironment variable
*Thanks to [@bala-ceg](https://github.com/bala-ceg) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/391) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate the Cachix CLI Source: https://www.1password.dev/cli/shell-plugins/cachix The Cachix shell plugin allows you to use 1Password to securely authenticate [the Cachix CLI](https://docs.cachix.org) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Cachix CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.11.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Cachix CLI.](https://github.com/cachix/cachix#installation) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Cachix shell plugin:
  1. Sign in to the 1Password account you want to use with the Cachix plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init cachix
You'll be prompted to import your Cachix credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/cachix-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Cachix credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/cachix-2.png) #### Select an existing item If you've already saved your Cachix credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/cachix-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Cachix. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/cachix-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Cachix, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/Ul-COtb5ywadNlrP/static/img/shell-plugins/cachix-5.png?fit=max\&auto=format\&n=Ul-COtb5ywadNlrP\&q=85\&s=2b871b590bf7d6334c4a8c98ec00d092) ## Step 4: Remove imported credentials from disk After saving your Cachix credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Cachix configuration: op plugin inspect cachix 1Password CLI will return a list of the credentials you've configured to use with Cachix and their default scopes, as well as a list of aliases configured for Cachix. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/Ul-COtb5ywadNlrP/static/img/shell-plugins/cachix-6.png?fit=max\&auto=format\&n=Ul-COtb5ywadNlrP\&q=85\&s=328f005d895bd966ed63c03b35d38940) ### Clear your credentials To reset the credentials used with Cachix: op plugin clear cachix You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear cachix` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear cachix --all`. ## Reference 1Password authenticates with Cachix by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Cachix credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | Token | `CACHIX_AUTH_TOKEN` | *Thanks to [@micnncim](https://github.com/micnncim) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/97) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate Cargo CLI Source: https://www.1password.dev/cli/shell-plugins/cargo The Cargo CLI shell plugin allows you to use 1Password to securely authenticate [Cargo CLI](https://crates.io/crates/cargo-cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Cargo CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.13.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [Cargo CLI.](https://crates.io/crates/cargo-cli) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Cargo CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the Cargo CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init cargo
You'll be prompted to import your Cargo CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/cargo-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Cargo CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/cargo-2.png) #### Select an existing item If you've already saved your Cargo CLI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/cargo-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Cargo CLI. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/cargo-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Cargo CLI, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/Ul-COtb5ywadNlrP/static/img/shell-plugins/cargo-5.png?fit=max\&auto=format\&n=Ul-COtb5ywadNlrP\&q=85\&s=2ad6bb3356bd0940a02473f07308b123) ## Step 4: Remove imported credentials from disk After saving your Cargo CLI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Cargo CLI configuration: op plugin inspect cargo 1Password CLI will return a list of the credentials you've configured to use with Cargo CLI and their default scopes, as well as a list of aliases configured for Cargo CLI. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/Ul-COtb5ywadNlrP/static/img/shell-plugins/cargo-6.png?fit=max\&auto=format\&n=Ul-COtb5ywadNlrP\&q=85\&s=d6ceae90e10b7fd873cfda16d2e77fd2) ### Clear your credentials To reset the credentials used with Cargo CLI: op plugin clear cargo You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear cargo` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear cargo --all`. ## Reference 1Password authenticates with Cargo CLI by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Cargo CLI credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | Token | `CARGO_REGISTRY_TOKEN` | *Thanks to [@accraw](https://github.com/accraw) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/139) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate the CircleCI CLI Source: https://www.1password.dev/cli/shell-plugins/circleci The CircleCI shell plugin allows you to use 1Password to securely authenticate [the CircleCI CLI](https://circleci-public.github.io/circleci-cli/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the CircleCI CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the CircleCI CLI.](https://circleci.com/docs/local-cli/#installation) The following shells are supported: * Bash * Zsh * fish ## Before you begin: Create and save a CircleCI personal API token If you've already created a CircleCI personal API token, [skip to Step 1](#step-1-configure-your-default-credentials). If you haven't created a personal API token yet, you can create one and use the [1Password browser extension](https://support.1password.com/getting-started-browser/) to quickly save it in 1Password: 1. Open and unlock [1Password in your browser](https://support.1password.com/getting-started-browser/). 2. [Follow the steps](https://circleci.com/docs/managing-api-tokens/#creating-a-personal-api-token) to create a CircleCI personal API token. 3. Select **Save item** when 1Password asks if you want to save an item for the CircleCI personal API token. 4. Choose the vault where you want to save the item, edit the item's name and details, then select **Save item**. ![The prompt to save your CircleCI personal API token in 1Password.](https://mintcdn.com/ab-634991b8/GCQVFnB1yNS2i2Vr/static/img/shell-plugins/circleci-save.png?fit=max\&auto=format\&n=GCQVFnB1yNS2i2Vr\&q=85\&s=362300cff54192d96b506b12c3a1b884) ## Step 1: Configure your default credentials To get started with the CircleCI shell plugin:
  1. Sign in to the 1Password account you want to use with the CircleCI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init circleci
You'll be prompted to import your CircleCI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/circleci-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your CircleCI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/circleci-2.png) #### Select an existing item If you've already saved your CircleCI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/circleci-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate CircleCI. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/circleci-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with CircleCI, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/Ul-COtb5ywadNlrP/static/img/shell-plugins/circleci-5.png?fit=max\&auto=format\&n=Ul-COtb5ywadNlrP\&q=85\&s=6b1f72f77b428875111ab9c1595f4ba9) ## Step 4: Remove imported credentials from disk After saving your CircleCI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current CircleCI configuration: op plugin inspect circleci 1Password CLI will return a list of the credentials you've configured to use with CircleCI and their default scopes, as well as a list of aliases configured for CircleCI. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/Ul-COtb5ywadNlrP/static/img/shell-plugins/circleci-6.png?fit=max\&auto=format\&n=Ul-COtb5ywadNlrP\&q=85\&s=dfe9bbee2396870d54db9502786125ee) ### Clear your credentials To reset the credentials used with CircleCI: op plugin clear circleci You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear circleci` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear circleci --all`. ## Reference 1Password authenticates with CircleCI by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your CircleCI credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | Token | `CIRCLECI_CLI_TOKEN` | ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate Civo CLI Source: https://www.1password.dev/cli/shell-plugins/civo The Civo CLI shell plugin allows you to use 1Password to securely authenticate [Civo CLI](https://www.civo.com/docs/overview/civo-cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Civo CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.22.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/). 5. [Install Civo CLI.](https://www.civo.com/docs/overview/civo-cli) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Civo CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the Civo CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init civo
You'll be prompted to import your Civo CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Civo CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. #### Select an existing item If you've already saved your Civo CLI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Civo CLI.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Civo CLI, you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your Civo CLI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Civo CLI configuration: op plugin inspect civo 1Password CLI will return a list of the credentials you've configured to use with Civo CLI and their default scopes, as well as a list of aliases configured for Civo CLI. ### Clear your credentials To reset the credentials used with Civo CLI: op plugin clear civo You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear civo` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear civo --all`. ## Reference 1Password authenticates with Civo CLI by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Civo CLI credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | API Key | `CIVO_API_KEY` | | API Key ID | `CIVO_API_KEY_NAME` | *Thanks to [@siddhikhapare](https://github.com/siddhikhapare) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/325) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to authenticate Claude Code with biometrics Source: https://www.1password.dev/cli/shell-plugins/claude-code The Claude Code shell plugin allows you to use your Anthropic API key through 1Password to securely authenticate the [`claude` CLI](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to store your API key in 1Password and source the `plugins.sh` file, then you'll be prompted to authenticate the `claude` CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.34.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [Claude Code](https://code.claude.com/docs/en/overview) in your terminal and [create an Anthropic API key.](https://console.anthropic.com/settings/keys) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Claude Code shell plugin:
  1. Sign in to the 1Password account you want to use with the Claude Code plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init claude
You'll be prompted to import your Claude Code credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Claude Code credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. #### Select an existing item If you've already saved your Claude Code credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Claude Code.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Claude Code, you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your Claude Code credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Claude Code configuration: op plugin inspect claude 1Password CLI will return a list of the credentials you've configured to use with Claude Code and their default scopes, as well as a list of aliases configured for Claude Code. ### Clear your credentials To reset the credentials used with Claude Code: op plugin clear claude You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear claude` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear claude --all`. ## Reference 1Password authenticates with Claude Code by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Claude Code credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | API Key | `ANTHROPIC_API_KEY` | *Thanks to [@malob](https://github.com/malob) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/519) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate Cline CLI Source: https://www.1password.dev/cli/shell-plugins/cline Store your credentials in 1Password then authenticate Cline CLI with your fingerprint. The Cline shell plugin allows you to use 1Password to securely authenticate [Cline CLI](https://docs.cline.bot/usage/cli-overview) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext.Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Cline CLI with biometrics.## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.35.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install Cline CLI.](https://docs.cline.bot/usage/cli-overview)
The following shells are supported:
  • Bash
  • Zsh
  • fish
## Step 1: Configure your default credentialsTo get started with the Cline shell plugin:
  1. Sign in to the 1Password account you want to use with the Cline plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init cline
You'll be prompted to import your Cline credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used.### Step 1.1: Import or select an item#### Import a new itemIf you haven't saved your Cline credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it.If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them.#### Select an existing itemIf you've already saved your Cline credentials in 1Password, select **Search in 1Password**.You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account.### Step 1.2: Set default credential scopeAfter you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Cline.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh fileTo make the plugin available, source your `plugins.sh` file. For example:```shell theme={null} source ~/.config/op/plugins.sh ```The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path.If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example:```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``````shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``````shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ```## Step 3: Use the CLIThe next time you enter a command with Cline, you'll be prompted to authenticate with biometrics or system authentication.## Step 4: Remove imported credentials from diskAfter saving your Cline credentials in 1Password, you can remove all local copies you previously had stored on disk.## Next steps1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs:```shell theme={null} op plugin list ```To choose another plugin to get started with:```shell theme={null} op plugin init ```To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/)## Get help### Inspect your configurationTo inspect your current Cline configuration:op plugin inspect cline1Password CLI will return a list of the credentials you've configured to use with Cline and their default scopes, as well as a list of aliases configured for Cline.### Clear your credentialsTo reset the credentials used with Cline:op plugin clear clineYou can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear cline` four times to clear all of your defaults.To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear cline --all`.## Reference 1Password authenticates with Cline by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Cline credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. \ \ \
1Password field nameEnvironment variable
*Thanks to [@eddumelendez](https://github.com/eddumelendez) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/611) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate the Cloudflare Workers CLI Source: https://www.1password.dev/cli/shell-plugins/cloudflare-workers The Cloudflare Workers shell plugin allows you to use 1Password to securely authenticate [Wrangler](https://developers.cloudflare.com/workers/wrangler/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Wrangler with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.12.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [Wrangler.](https://developers.cloudflare.com/workers/wrangler/install-and-update/) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Cloudflare Workers shell plugin:
  1. Sign in to the 1Password account you want to use with the Cloudflare Workers plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init wrangler
You'll be prompted to import your Cloudflare Workers credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/wrangler-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Cloudflare Workers credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/wrangler-2.png) #### Select an existing item If you've already saved your Cloudflare Workers credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/wrangler-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Cloudflare Workers. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/wrangler-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Cloudflare Workers, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/MKy6sgNGqMk-yGDS/static/img/shell-plugins/wrangler-5.png?fit=max\&auto=format\&n=MKy6sgNGqMk-yGDS\&q=85\&s=59489581c4116739921d6c0fc210c725) ## Step 4: Remove imported credentials from disk After saving your Cloudflare Workers credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Cloudflare Workers configuration: op plugin inspect wrangler 1Password CLI will return a list of the credentials you've configured to use with Cloudflare Workers and their default scopes, as well as a list of aliases configured for Cloudflare Workers. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/MKy6sgNGqMk-yGDS/static/img/shell-plugins/wrangler-6.png?fit=max\&auto=format\&n=MKy6sgNGqMk-yGDS\&q=85\&s=90a897d500ff3099079f683043b7a695) ### Clear your credentials To reset the credentials used with Cloudflare Workers: op plugin clear wrangler You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear wrangler` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear wrangler --all`. ## Reference 1Password authenticates with Cloudflare Workers by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Cloudflare Workers credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | Account ID (Optional) | `CLOUDFLARE_ACCOUNT_ID` | | Token | `CLOUDFLARE_API_TOKEN` | *Thanks to [@shyim](https://github.com/shyim) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/94) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate cockroach sql Source: https://www.1password.dev/cli/shell-plugins/cockroachdb Store your credentials in 1Password then authenticate cockroach sql with your fingerprint. The CockroachDB shell plugin allows you to use 1Password to securely authenticate [cockroach sql](https://www.cockroachlabs.com/docs/stable/cockroach-sql.html) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext.Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate cockroach sql with biometrics.## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.42.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install cockroach sql.](https://www.cockroachlabs.com/docs/stable/cockroach-sql.html)
The following shells are supported:
  • Bash
  • Zsh
  • fish
## Step 1: Configure your default credentialsTo get started with the CockroachDB shell plugin:
  1. Sign in to the 1Password account you want to use with the CockroachDB plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init cockroach
You'll be prompted to import your CockroachDB credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used.### Step 1.1: Import or select an item#### Import a new itemIf you haven't saved your CockroachDB credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it.If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them.#### Select an existing itemIf you've already saved your CockroachDB credentials in 1Password, select **Search in 1Password**.You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account.### Step 1.2: Set default credential scopeAfter you select or import your credentials, you'll be prompted to configure when to use the item to authenticate CockroachDB.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh fileTo make the plugin available, source your `plugins.sh` file. For example:```shell theme={null} source ~/.config/op/plugins.sh ```The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path.If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example:```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``````shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``````shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ```## Step 3: Use the CLIThe next time you enter a command with CockroachDB, you'll be prompted to authenticate with biometrics or system authentication.1Password only provides credentials to `cockroach sql` commands. Other `cockroach` commands run without prompting you to authenticate.## Step 4: Remove imported credentials from diskAfter saving your CockroachDB credentials in 1Password, you can remove all local copies you previously had stored on disk.## Next steps1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs:```shell theme={null} op plugin list ```To choose another plugin to get started with:```shell theme={null} op plugin init ```To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/)## Get help### Inspect your configurationTo inspect your current CockroachDB configuration:op plugin inspect cockroach1Password CLI will return a list of the credentials you've configured to use with CockroachDB and their default scopes, as well as a list of aliases configured for CockroachDB.### Clear your credentialsTo reset the credentials used with CockroachDB:op plugin clear cockroachYou can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear cockroach` four times to clear all of your defaults.To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear cockroach --all`.## Reference 1Password authenticates with CockroachDB by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your CockroachDB credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. \ \ \
1Password field nameEnvironment variable
*Thanks to [@syndbg](https://github.com/syndbg) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/536) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Build your own shell plugins (beta) Source: https://www.1password.dev/cli/shell-plugins/contribute If you don't see your favorite command-line tool [listed in the 1Password Shell Plugin registry](/cli/shell-plugins/), you can write your own plugin. 1Password CLI allows you to build and test shell plugins locally, so you can add support for authenticating your favorite CLI using a credential you saved in 1Password. If you want to make your plugin available to others, you can [create a pull request in the shell plugins GitHub repository.](https://github.com/1Password/shell-plugins) ## Requirements * [Sign up for 1Password](https://1password.com/pricing/password-manager). * Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). * Install [1Password CLI](/cli/get-started/) and turn on the [desktop app integration](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). * Install [Go 1.18 or later.](https://go.dev/doc/install) * Install [Git.](https://git-scm.com/) * Install [GNU Make.](https://www.gnu.org/software/make/) ## Concepts A 1Password Shell Plugin should describe the following: * The **credential** offered by a platform * The CLI or **executable** offered by a platform * How the credential should be **provisioned** for the respective CLI to authenticate * Which commands for the respective CLI **need authentication** * How credentials stored on the local filesystem can be **imported** into 1Password Shell plugins are written in Go and consist of a set of Go structs in a package that together make up the plugin for a certain platform, service, or product. Don't worry if you're not a Go expert – there are [lots of examples](https://github.com/1Password/shell-plugins/tree/main/plugins) you can learn from to build your plugin! ## Step 1: Use the plugin template First, clone or fork the [1Password Shell Plugins repository](https://github.com/1Password/shell-plugins) on GitHub. It contains the current plugin registry, as well as the SDK needed to contribute. To get started with those, use the following Makefile command: ```shell theme={null} make new-plugin ``` You'll be prompted to enter the following information: * **Plugin name:** Lowercase identifier for the platform, e.g. `aws`, `github`, `digitalocean`, `azure`. This will also be used as the name of the Go package. * **Plaform display name:** The display name of the platform, e.g `AWS`, `GitHub`, `DigitalOcean`, `Azure`. * **Credential name:** The credentials the platform offers, e.g. `Personal Access Token`, `API Key`, `Auth Token`. * **Executable name:** The command to invoke, e.g. `aws`, `gh`, `doctl`, `az`. After filling in the form, you'll see a Go package created in the `plugins` directory, with separate files for the plugin, credential, and executable. For example: ``` plugins/ ├── aws/ │ ├── plugin.go │ ├── access_key.go │ └── aws.go ├── digitalocean/ │ ├── plugin.go │ ├── personal_access_token.go │ └── doctl.go ├── github/ │ ├── plugin.go │ ├── personal_access_token.go │ └── gh.go └── heroku/ ├── plugin.go ├── api_key.go └── heroku.go ``` To save you some time, the generated files will be stubbed out with information that's derived from the Makefile prompts on a best-effort basis. It contains *TODO* comments in the code to steer you in the direction of what to change or validate for correctness. ## Step 2: Edit the plugin definition The `plugin.go` file contains basic information about the plugin and the platform it represents, including which credential types and executables make up the plugin. ### Plugin Examples * [AWS](https://github.com/1Password/shell-plugins/blob/main/plugins/aws/plugin.go) * [GitHub](https://github.com/1Password/shell-plugins/blob/main/plugins/github/plugin.go) * [Heroku](https://github.com/1Password/shell-plugins/blob/main/plugins/heroku/plugin.go) ## Step 3: Edit the credential definition The credential definition file describes the schema of the credential, how the credential should get provisioned to executables, and how the credential can be imported into 1Password. ### Credential Examples * [AWS Access Key](https://github.com/1Password/shell-plugins/blob/main/plugins/aws/access_key.go) * [GitHub Personal Access Token](https://github.com/1Password/shell-plugins/blob/main/plugins/github/personal_access_token.go) * [Heroku API Key](https://github.com/1Password/shell-plugins/blob/main/plugins/heroku/api_key.go) ### Credential information and schema The first section of the credential definition is where you can add information about the credential: * The **name** of the credential, as the platform calls it. * The **documentation URL** provided by the platform that describes the credential. *(optional)* * The **management URL** on the platform where the credential can be created and revoked. This is usually a URL to the dashboard, console, or authentication settings of the platform. *(optional)* The next section is where you define the schema of the credential. This is segmented into fields. Many credentials consist of just a single secret field, but you can add more fields to add more details to the 1Password item that are related to authentication, even if the fields are not secret. Examples of additional fields are: the host, username, account ID, and all other things that are needed to authenticate and make sense to include in the 1Password item for the credential type. All fields you declare here will also show up in the end user's 1Password item. Here's what you can specify per **field**: * The **field name**, titlecased. *(required)* * A short **description** of the field. This supports markdown. *(required)* * Whether the field is **optional**. Defaults to false. * Whether the field is **secret**, and should be concealed in the 1Password GUI. Defaults to not secret.\ Note: The credential schema is expected to contain at least 1 secret field. * What the actual credential **value is composed of**. The length, character set, and whether it contains a fixed prefix. ### Provisioner The credential definition also specifies how the credential is usually provisioned to exectuables, in order for them to use the credential for authentication. Provisioners are in essence hooks that get executed before the executable is run by 1Password CLI, and after the executable exits in case any cleanup is needed. In those hooks, provisioners can do all the setup required for the executable to authenticate, including setting environment variables, creating files, adding command-line arguments, or even generating temporary credentials. After the executable exits, there should be no trace of the credentials on the user's filesystem. The SDK provides a few common provisioners out of the box, so in most cases you don't have to care about the provisioning internals. > [tab] Environment variables > > We currently recommend using environment variables as your provisioning method. > > Environment variables are the most ubiquitous way to provision secrets. They only live in memory, and almost every CLI allows you to authenticate with them. > > Here's how you can use the environment variable provisioner provided by the SDK: > > ```go theme={null} > provision.EnvVars(map[string]sdk.FieldName{ > "AWS_ACCESS_KEY_ID": fieldname.AccessKeyID, > "AWS_SECRET_ACCESS_KEY": fieldname.SecretAccessKey, > }) > ``` > > Specify the 1Password field name and the environment variable name it should be placed in. > > To figure out what environment variable the underlying CLI reads, here are a few tips: > > * Search the platform's CLI documentation website for a getting started guide, authentication guide, or CLI reference docs. > * Look at the CLI's help text or manpage. > * If the CLI or the underlying SDK it uses is open source, scan the source code to see if it accepts environment variables for authentication. > [tab] Files > > Some CLIs only support reading credentials from files on disk. In that case, you can use the file provisioner provided by the SDK. The file provisioner takes care of creating the file in a temporary directory and deleting it afterwards. > > For security purposes, the file created by the file provisioner can only be read **once** by the executable. If that limitation does not work for your use case, you can file an [issue on GitHub.](https://github.com/1Password/shell-plugins/issues) > > Here are a few examples on how you can use the file provisioner to provision a temporary JSON file and pass the generated path to the executable: > > ```go Create a file provisioner and pass output path as --config-file theme={null} > provision.TempFile(configFile, > provision.Filename("config.json"), > provision.AddArgs("--config-file", "{{ .Path }}"), > ) > ``` > > ```go Create a file provisioner and set output path as CONFIG_FILE_PATH theme={null} > provision.TempFile(configFile, > provision.Filename("config.json"), > provision.SetPathAsEnvVar("CONFIG_FILE_PATH"), > ) > ``` > > ```go Create a file provisioner and pass output path as Java property theme={null} > provision.TempFile(configFile, > provision.Filename("config.json"), > provision.AddArgs(`-Dconfig.path="{{ .Path }}"`), > ) > ``` > > ```go Code to generate JSON file contents theme={null} > func configFile(in sdk.ProvisionInput) ([]byte, error) { > config := Config{ > Token: in.ItemFields[fieldname.Token] > } > > contents, err := json.Marshal(config) > if err != nil { > return nil, err > } > > return []byte(contents), nil > } > > type Config struct { > Token string `json:"token"` > } > ``` > [tab] Other > > If the standard provisioners included in the SDK are not enough to authenticate the executable, you can also write your own provisioner. You can do so by implementing the [`sdk.Provisioner` interface.](https://github.com/1Password/shell-plugins/blob/main/sdk/provisioner.go) > > A good example of a custom provisioner is the [AWS STS provisioner](https://github.com/1Password/shell-plugins/blob/main/plugins/aws/sts_provisioner.go) that generates temporary credentials based on a one-time password code loaded from 1Password. ### Importer The credential definition also lets you specify importers. Importers are responsible for scanning the user's environment and file system for any occurrences of the needed credentials. 1Password CLI will run the importer and prompt the user to import their credentials one by one into 1Password. It's very common for CLIs to write authentication data to disk, most commonly in a hidden config file in your home directory. This is not always documented by the CLI, so here are some tips to figure out if such a config file exists: * Check the platform's documentation for mentions of config files. * See if the CLI offers a `login`, `auth`, `configure`, or `setup` command that covers authentication. If it does, it's pretty likely there's a credential being stored in your home directory after completing such a flow. * If the CLI is open source, check the source code to see if such a file exists. * Look at your own home directory or `~/.config` directory to see if there are files related to the platform. Here's an example command to find local `aws` configuration files: ```shell theme={null} find ~/.* -maxdepth 3 -path "*aws*" ``` The SDK provides helper functions to load files, parse files, and scan environment variables to make writing an importer for your credential type easier. ### Importer Examples * [AWS Access Key](https://github.com/1Password/shell-plugins/blob/main/plugins/aws/access_key.go) (`~/.aws/credentials`) * [CircleCI Personal API Token](https://github.com/1Password/shell-plugins/blob/main/plugins/circleci/personal_api_token.go) (`~/.circleci/cli.yml`) * [Heroku API Key](https://github.com/1Password/shell-plugins/blob/main/plugins/heroku/api_key.go) (`~/.netrc`) If you already have a shell plugin configured for a tool, and you want to generate an example configuration tile to test an importer, reference the tool by its full path rather than by its name. This makes sure you invoke the the tool without the plugin. ## Step 4: Edit the executable definition The last thing the plugin is responsible for is to define the CLI or executable that you'd like 1Password to handle authentication for. This is the final piece that glues everything together. The executable definition describes the following: * The **command** that should get executed by the 1Password CLI. * The display **name** of the CLI, as the platform calls it. * The **documentation URL** provided by the platform that describes the executable. *(optional)* * When the executable **needs authentication**. For example, many CLIs don't require authentication when the `--help` or `--version` flags are present. * The **credentials** that the executable uses. ### Executable Examples * [AWS CLI](https://github.com/1Password/shell-plugins/blob/main/plugins/aws/aws.go) (`aws`) * [GitHub CLI](https://github.com/1Password/shell-plugins/blob/main/plugins/github/gh.go) (`gh`) * [Heroku CLI](https://github.com/1Password/shell-plugins/blob/main/plugins/heroku/heroku.go) (`heroku`) ## Step 5: Build and test your plugin locally To see if you've properly filled out the plugin, credential, and executable defintions, you can run the following Makefile command to validate the definitions: ``` make /validate ``` If that succeeds, it's now time to locally build and test your plugin! You can do so using the following command: ``` make /build ``` The build artifact will be placed in `~/.op/plugins/local`. It should show up in `op` if you run the following command: ```shell theme={null} op plugin list ``` To see it in action, you can use the `op plugin init` command: ```shell theme={null} op plugin init ``` ## Submit a PR While you're free to keep on using the plugin locally, we'd encourage you to submit a PR on the [main registry on GitHub](https://github.com/1Password/shell-plugins) so others can use it too! Before doing so, be sure to read the [CONTRIBUTING.md](https://github.com/1Password/shell-plugins/blob/main/CONTRIBUTING.md) file on GitHub. If you feel that the SDK does not serve your use case well, reach out to us by creating an [issue on GitHub](https://github.com/1Password/shell-plugins/issues) or by joining our [Developer Slack workspace](/joinslack) to tell us about your plugin proposal. We can advise you on the most suitable approach for your use case. ## Learn more * [Shell plugins troubleshooting](/cli/shell-plugins/troubleshooting/) * [Join our Developer Slack workspace](/joinslack) # Use 1Password to securely authenticate CrateDB Shell Source: https://www.1password.dev/cli/shell-plugins/cratedb Store your credentials in 1Password then authenticate CrateDB Shell with your fingerprint. The CrateDB shell plugin allows you to use 1Password to securely authenticate [CrateDB Shell](https://crate.io/docs/crate/crash/en/latest/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext.Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate CrateDB Shell with biometrics.## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.35.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install CrateDB Shell.](https://crate.io/docs/crate/crash/en/latest/)
The following shells are supported:
  • Bash
  • Zsh
  • fish
## Step 1: Configure your default credentialsTo get started with the CrateDB shell plugin:
  1. Sign in to the 1Password account you want to use with the CrateDB plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init crash
You'll be prompted to import your CrateDB credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used.### Step 1.1: Import or select an item#### Import a new itemIf you haven't saved your CrateDB credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it.If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them.#### Select an existing itemIf you've already saved your CrateDB credentials in 1Password, select **Search in 1Password**.You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account.### Step 1.2: Set default credential scopeAfter you select or import your credentials, you'll be prompted to configure when to use the item to authenticate CrateDB.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh fileTo make the plugin available, source your `plugins.sh` file. For example:```shell theme={null} source ~/.config/op/plugins.sh ```The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path.If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example:```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``````shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``````shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ```## Step 3: Use the CLIThe next time you enter a command with CrateDB, you'll be prompted to authenticate with biometrics or system authentication.## Step 4: Remove imported credentials from diskAfter saving your CrateDB credentials in 1Password, you can remove all local copies you previously had stored on disk.## Next steps1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs:```shell theme={null} op plugin list ```To choose another plugin to get started with:```shell theme={null} op plugin init ```To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/)## Get help### Inspect your configurationTo inspect your current CrateDB configuration:op plugin inspect crash1Password CLI will return a list of the credentials you've configured to use with CrateDB and their default scopes, as well as a list of aliases configured for CrateDB.### Clear your credentialsTo reset the credentials used with CrateDB:op plugin clear crashYou can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear crash` four times to clear all of your defaults.To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear crash --all`.## Reference 1Password authenticates with CrateDB by injecting the credentials required by the plugin commands directly from your 1Password account as environment variables or command-line flags. If you saved your CrateDB credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. \ \ \
1Password field nameProvisioned as
*Thanks to [@accraw](https://github.com/accraw) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/394) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate Crowdin CLI Source: https://www.1password.dev/cli/shell-plugins/crowdin The Crowdin CLI shell plugin allows you to use 1Password to securely authenticate [Crowdin CLI](https://crowdin.github.io/crowdin-cli/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Crowdin CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.22.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/). 5. [Install Crowdin CLI.](https://crowdin.github.io/crowdin-cli/) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Crowdin CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the Crowdin CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init crowdin
You'll be prompted to import your Crowdin CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Crowdin CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. #### Select an existing item If you've already saved your Crowdin CLI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Crowdin CLI.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Crowdin CLI, you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your Crowdin CLI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Crowdin CLI configuration: op plugin inspect crowdin 1Password CLI will return a list of the credentials you've configured to use with Crowdin CLI and their default scopes, as well as a list of aliases configured for Crowdin CLI. ### Clear your credentials To reset the credentials used with Crowdin CLI: op plugin clear crowdin You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear crowdin` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear crowdin --all`. ## Reference 1Password authenticates with Crowdin CLI by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Crowdin CLI credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | Token | `CROWDIN_PERSONAL_TOKEN` | | Project ID | `CROWDIN_PROJECT_ID` | | Host Address | `CROWDIN_BASE_URL` | *Thanks to [@JoeKarow](https://github.com/JoeKarow) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/359) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate Cursor CLI Source: https://www.1password.dev/cli/shell-plugins/cursor Store your credentials in 1Password then authenticate Cursor CLI with your fingerprint. The Cursor shell plugin allows you to use 1Password to securely authenticate [Cursor CLI](https://cursor.com/docs/cli/overview) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext.Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Cursor CLI with biometrics.## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.35.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install Cursor CLI.](https://cursor.com/docs/cli/overview)
The following shells are supported:
  • Bash
  • Zsh
  • fish
## Step 1: Configure your default credentialsTo get started with the Cursor shell plugin:
  1. Sign in to the 1Password account you want to use with the Cursor plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init agent
You'll be prompted to import your Cursor credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used.### Step 1.1: Import or select an item#### Import a new itemIf you haven't saved your Cursor credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it.If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them.#### Select an existing itemIf you've already saved your Cursor credentials in 1Password, select **Search in 1Password**.You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account.### Step 1.2: Set default credential scopeAfter you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Cursor.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh fileTo make the plugin available, source your `plugins.sh` file. For example:```shell theme={null} source ~/.config/op/plugins.sh ```The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path.If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example:```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``````shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``````shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ```## Step 3: Use the CLIThe next time you enter a command with Cursor, you'll be prompted to authenticate with biometrics or system authentication.## Step 4: Remove imported credentials from diskAfter saving your Cursor credentials in 1Password, you can remove all local copies you previously had stored on disk.## Next steps1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs:```shell theme={null} op plugin list ```To choose another plugin to get started with:```shell theme={null} op plugin init ```To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/)## Get help### Inspect your configurationTo inspect your current Cursor configuration:op plugin inspect agent1Password CLI will return a list of the credentials you've configured to use with Cursor and their default scopes, as well as a list of aliases configured for Cursor.### Clear your credentialsTo reset the credentials used with Cursor:op plugin clear agentYou can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear agent` four times to clear all of your defaults.To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear agent --all`.## Reference 1Password authenticates with Cursor by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Cursor credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. \ \ \
1Password field nameEnvironment variable
*Thanks to [@eddumelendez](https://github.com/eddumelendez) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/612) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate Databricks CLI Source: https://www.1password.dev/cli/shell-plugins/databricks The Databricks shell plugin allows you to use 1Password to securely authenticate [Databricks CLI](https://docs.databricks.com/dev-tools/cli/index.html) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Databricks CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.13.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [Databricks CLI.](https://docs.databricks.com/dev-tools/cli/index.html) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Databricks CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the Databricks CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init databricks
You'll be prompted to import your Databricks CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/databricks-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Databricks CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/databricks-2.png) #### Select an existing item If you've already saved your Databricks CLI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/databricks-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Databricks CLI. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/databricks-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Databricks CLI, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/GCQVFnB1yNS2i2Vr/static/img/shell-plugins/databricks-5.png?fit=max\&auto=format\&n=GCQVFnB1yNS2i2Vr\&q=85\&s=42714fcddfde772bf7e79f80728d4faf) ## Step 4: Remove imported credentials from disk After saving your Databricks CLI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Databricks CLI configuration: op plugin inspect databricks 1Password CLI will return a list of the credentials you've configured to use with Databricks CLI and their default scopes, as well as a list of aliases configured for Databricks CLI. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/GCQVFnB1yNS2i2Vr/static/img/shell-plugins/databricks-6.png?fit=max\&auto=format\&n=GCQVFnB1yNS2i2Vr\&q=85\&s=0e4ed6a7e024158cd42d24208d77ede8) ### Clear your credentials To reset the credentials used with Databricks CLI: op plugin clear databricks You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear databricks` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear databricks --all`. ## Reference 1Password authenticates with Databricks CLI by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Databricks CLI credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | Host | `DATABRICKS_HOST` | | Token | `DATABRICKS_TOKEN` | *Thanks to [@bsamseth](https://github.com/bsamseth) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/143) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate Dogshell Source: https://www.1password.dev/cli/shell-plugins/datadog The Dogshell shell plugin allows you to use 1Password to securely authenticate [Dogshell](https://docs.datadoghq.com/developers/guide/dogshell-quickly-use-datadog-s-api-from-terminal-shell/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Dogshell with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [Dogshell.](https://docs.datadoghq.com/developers/guide/dogshell-quickly-use-datadog-s-api-from-terminal-shell/) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Dogshell shell plugin:
  1. Sign in to the 1Password account you want to use with the Dogshell plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init dog
You'll be prompted to import your Dogshell credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/dog-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Dogshell credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/dog-2.png) #### Select an existing item If you've already saved your Dogshell credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/dog-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Dogshell. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/dog-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Dogshell, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/GCQVFnB1yNS2i2Vr/static/img/shell-plugins/dog-5.png?fit=max\&auto=format\&n=GCQVFnB1yNS2i2Vr\&q=85\&s=2abffee6370399b4662bb78708ae669a) ## Step 4: Remove imported credentials from disk After saving your Dogshell credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Dogshell configuration: op plugin inspect dog 1Password CLI will return a list of the credentials you've configured to use with Dogshell and their default scopes, as well as a list of aliases configured for Dogshell. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/GCQVFnB1yNS2i2Vr/static/img/shell-plugins/dog-6.png?fit=max\&auto=format\&n=GCQVFnB1yNS2i2Vr\&q=85\&s=6dd0542b9b2ff2013ef2986f7fd88cde) ### Clear your credentials To reset the credentials used with Dogshell: op plugin clear dog You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear dog` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear dog --all`. ## Reference 1Password authenticates with Dogshell by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Dogshell credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variable | | - | - | | API Key | `DATADOG_API_KEY` | | App Key | `DATADOG_APP_KEY` | ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate Descope CLI Source: https://www.1password.dev/cli/shell-plugins/descope Store your credentials in 1Password then authenticate Descope CLI with your fingerprint. The Descope shell plugin allows you to use 1Password to securely authenticate [Descope CLI](https://docs.descope.com/cli/descope) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext.Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Descope CLI with biometrics.## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.35.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install Descope CLI.](https://docs.descope.com/cli/descope)
The following shells are supported:
  • Bash
  • Zsh
  • fish
## Step 1: Configure your default credentialsTo get started with the Descope shell plugin:
  1. Sign in to the 1Password account you want to use with the Descope plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init descope
You'll be prompted to import your Descope credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used.### Step 1.1: Import or select an item#### Import a new itemIf you haven't saved your Descope credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it.If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them.#### Select an existing itemIf you've already saved your Descope credentials in 1Password, select **Search in 1Password**.You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account.### Step 1.2: Set default credential scopeAfter you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Descope.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh fileTo make the plugin available, source your `plugins.sh` file. For example:```shell theme={null} source ~/.config/op/plugins.sh ```The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path.If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example:```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``````shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``````shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ```## Step 3: Use the CLIThe next time you enter a command with Descope, you'll be prompted to authenticate with biometrics or system authentication.## Step 4: Remove imported credentials from diskAfter saving your Descope credentials in 1Password, you can remove all local copies you previously had stored on disk.## Next steps1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs:```shell theme={null} op plugin list ```To choose another plugin to get started with:```shell theme={null} op plugin init ```To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/)## Get help### Inspect your configurationTo inspect your current Descope configuration:op plugin inspect descope1Password CLI will return a list of the credentials you've configured to use with Descope and their default scopes, as well as a list of aliases configured for Descope.### Clear your credentialsTo reset the credentials used with Descope:op plugin clear descopeYou can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear descope` four times to clear all of your defaults.To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear descope --all`.## Reference 1Password authenticates with Descope by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Descope credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. \ \ \
1Password field nameEnvironment variable
*Thanks to [@scottisloud](https://github.com/scottisloud) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/570) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate the DigitalOcean CLI Source: https://www.1password.dev/cli/shell-plugins/digitalocean The DigitalOcean shell plugin allows you to use 1Password to securely authenticate [doctl](https://docs.digitalocean.com/reference/doctl/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate doctl with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [doctl.](https://docs.digitalocean.com/reference/doctl/how-to/install/) The following shells are supported: * Bash * Zsh * fish ## Before you begin: Create and save a DigitalOcean personal access token If you've already created a DigitalOcean personal access token, [skip to Step 1](#step-1-configure-your-default-credentials). If you haven't created a personal access token yet, you can create one and use the [1Password browser extension](https://support.1password.com/getting-started-browser/) to quickly save it in 1Password: 1. Open and unlock [1Password in your browser](https://support.1password.com/getting-started-browser/). 2. [Follow the steps](https://docs.digitalocean.com/reference/api/create-personal-access-token/) to create a DigitalOcean personal access token. 3. Select **Save item** when 1Password asks if you want to save an item for the DigitalOcean personal access token. 4. Choose the vault where you want to save the item, edit the item's name and details, then select **Save item**. ![The prompt to save your DigitalOcean personal access token in 1Password.](https://mintcdn.com/ab-634991b8/GCQVFnB1yNS2i2Vr/static/img/shell-plugins/doctl-save.png?fit=max\&auto=format\&n=GCQVFnB1yNS2i2Vr\&q=85\&s=1420fdb4ac1ab427080ae18d2ce3e633) ## Step 1: Configure your default credentials To get started with the the DigitalOcean CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the the DigitalOcean CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init doctl
You'll be prompted to import your the DigitalOcean CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/doctl-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your the DigitalOcean CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/doctl-2.png) #### Select an existing item If you've already saved your the DigitalOcean CLI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/doctl-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate the DigitalOcean CLI. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/doctl-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with DigitalOcean, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/GCQVFnB1yNS2i2Vr/static/img/shell-plugins/doctl-5.png?fit=max\&auto=format\&n=GCQVFnB1yNS2i2Vr\&q=85\&s=2a9e02aa42e6e1c1ec01e4f75eb91ece) ## Step 4: Remove imported credentials from disk After saving your DigitalOcean credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current DigitalOcean configuration: op plugin inspect doctl 1Password CLI will return a list of the credentials you've configured to use with DigitalOcean and their default scopes, as well as a list of aliases configured for DigitalOcean. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/GCQVFnB1yNS2i2Vr/static/img/shell-plugins/doctl-6.png?fit=max\&auto=format\&n=GCQVFnB1yNS2i2Vr\&q=85\&s=4f48e06d7a0cb387e7ab300b5104cb7d) ### Clear your credentials To reset the credentials used with DigitalOcean: op plugin clear doctl You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear doctl` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear doctl --all`. ## Reference 1Password authenticates with DigitalOcean by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your DigitalOcean credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | Token | `DIGITALOCEAN_ACCESS_TOKEN` | ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate Doppler CLI Source: https://www.1password.dev/cli/shell-plugins/doppler Store your credentials in 1Password then authenticate Doppler CLI with your fingerprint. The Doppler shell plugin allows you to use 1Password to securely authenticate [Doppler CLI](https://docs.doppler.com/docs/cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext.Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Doppler CLI with biometrics.## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.42.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install Doppler CLI.](https://docs.doppler.com/docs/cli)
The following shells are supported:
  • Bash
  • Zsh
  • fish
## Step 1: Configure your default credentialsTo get started with the Doppler shell plugin:
  1. Sign in to the 1Password account you want to use with the Doppler plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init doppler
You'll be prompted to import your Doppler credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used.### Step 1.1: Import or select an item#### Import a new itemIf you haven't saved your Doppler credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it.If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them.#### Select an existing itemIf you've already saved your Doppler credentials in 1Password, select **Search in 1Password**.You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account.### Step 1.2: Set default credential scopeAfter you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Doppler.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh fileTo make the plugin available, source your `plugins.sh` file. For example:```shell theme={null} source ~/.config/op/plugins.sh ```The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path.If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example:```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``````shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``````shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ```## Step 3: Use the CLIThe next time you enter a command with Doppler, you'll be prompted to authenticate with biometrics or system authentication.## Step 4: Remove imported credentials from diskAfter saving your Doppler credentials in 1Password, you can remove all local copies you previously had stored on disk.## Next steps1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs:```shell theme={null} op plugin list ```To choose another plugin to get started with:```shell theme={null} op plugin init ```To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/)## Get help### Inspect your configurationTo inspect your current Doppler configuration:op plugin inspect doppler1Password CLI will return a list of the credentials you've configured to use with Doppler and their default scopes, as well as a list of aliases configured for Doppler.### Clear your credentialsTo reset the credentials used with Doppler:op plugin clear dopplerYou can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear doppler` four times to clear all of your defaults.To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear doppler --all`.## Reference 1Password authenticates with Doppler by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Doppler credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. \ \ \
1Password field nameEnvironment variable
*Thanks to [@CodeByZach](https://github.com/CodeByZach) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/562) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate EAS CLI Source: https://www.1password.dev/cli/shell-plugins/eas Store your credentials in 1Password then authenticate EAS CLI with your fingerprint. The EAS shell plugin allows you to use 1Password to securely authenticate [EAS CLI](https://docs.expo.dev/eas/cli/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext.Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate EAS CLI with biometrics.## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.35.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install EAS CLI.](https://docs.expo.dev/eas/cli/)
The following shells are supported:
  • Bash
  • Zsh
  • fish
## Step 1: Configure your default credentialsTo get started with the EAS shell plugin:
  1. Sign in to the 1Password account you want to use with the EAS plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init eas
You'll be prompted to import your EAS credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used.### Step 1.1: Import or select an item#### Import a new itemIf you haven't saved your EAS credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it.If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them.#### Select an existing itemIf you've already saved your EAS credentials in 1Password, select **Search in 1Password**.You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account.### Step 1.2: Set default credential scopeAfter you select or import your credentials, you'll be prompted to configure when to use the item to authenticate EAS.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh fileTo make the plugin available, source your `plugins.sh` file. For example:```shell theme={null} source ~/.config/op/plugins.sh ```The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path.If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example:```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``````shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``````shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ```## Step 3: Use the CLIThe next time you enter a command with EAS, you'll be prompted to authenticate with biometrics or system authentication.## Step 4: Remove imported credentials from diskAfter saving your EAS credentials in 1Password, you can remove all local copies you previously had stored on disk.## Next steps1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs:```shell theme={null} op plugin list ```To choose another plugin to get started with:```shell theme={null} op plugin init ```To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/)## Get help### Inspect your configurationTo inspect your current EAS configuration:op plugin inspect eas1Password CLI will return a list of the credentials you've configured to use with EAS and their default scopes, as well as a list of aliases configured for EAS.### Clear your credentialsTo reset the credentials used with EAS:op plugin clear easYou can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear eas` four times to clear all of your defaults.To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear eas --all`.## Reference 1Password authenticates with EAS by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your EAS credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. \ \ \
1Password field nameEnvironment variable
*Thanks to [@CodeByZach](https://github.com/CodeByZach) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/563) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate AWS Eksctl Source: https://www.1password.dev/cli/shell-plugins/eksctl The `eksctl` shell plugin allows you to use 1Password to securely authenticate [`eksctl`](https://eksctl.io/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate `eksctl` with biometrics. You can also set up the [AWS CLI shell plugin](/cli/shell-plugins/aws/) or the [AWS CDK Toolkit shell plugin](/cli/shell-plugins/aws-cdk-toolkit/). ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.17.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. [Install `eksctl`.](https://docs.aws.amazon.com/eks/latest/eksctl/installation.html) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the `eksctl` shell plugin:
  1. Sign in to the 1Password account you want to use with the `eksctl` plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init eksctl
You'll be prompted to import your `eksctl` credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your `eksctl` credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. #### Select an existing item If you've already saved your `eksctl` credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate `eksctl`.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with `eksctl`, you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current `eksctl` configuration: op plugin inspect eksctl 1Password CLI will return a list of the credentials you've configured to use with `eksctl` and their default scopes, as well as a list of aliases configured for `eksctl`. ### Clear your credentials To reset the credentials used with `eksctl`: op plugin clear eksctl You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear eksctl` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear eksctl --all`. ## Reference 1Password authenticates with by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variables | | - | - | | Access Key ID | `AWS_ACCESS_KEY_ID` | | Secret Access Key | `AWS_SECRET_ACCESS_KEY` | ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
*Thanks to [@skpaz](https://github.com/skpaz) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/500) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use shell plugins to switch between multiple environments Source: https://www.1password.dev/cli/shell-plugins/environments You can use [1Password Shell Plugins](/cli/shell-plugins/) to seamlessly switch between different sets of credentials for different environments, so you don't have to spend time signing in or out between environments. For example, you can set the Terraform shell plugin to use your development credentials in the working directory for your development environment and your production credentials in the working directory for your production environment. Then when you run a Terraform command in either directory, the Terraform plugin will automatically authenticate with the appropriate credentials. ## Step 1: Organize your directories by environment Before you configure a shell plugin for context switching between environments, group the directories you want to use with the plugin by environment. For example, if you wanted to use the Terraform shell plugin in both development and production environments, you would organize your directories like this: ``` projects/ ├─ development/ │ ├─ dev-project-1 │ ├─ dev-project-2 ├─ production/ │ ├─ prod-project-1 │ ├─ prod-project-2 ``` ## Step 2: Configure default credentials for each environment After you organize your directories by environment, you can set default credentials for your shell plugin to use in each directory and all its subfolders. 1. Change directories to one of the environment-level folders you created. For example: ```shell theme={null} cd projects/production ``` 2. Sign in to the 1Password account where the credentials you want to use are stored: ```shell theme={null} op signin ``` 3. Choose a plugin to initialize, or run `op plugin init` to choose from a list of all available plugins. For example, to initialize the Terraform shell plugin: ```shell theme={null} op plugin init terraform ``` 4. Import or select the appropriate credentials for the environment. 5. Select **Use automatically when in this directory or subdirectories** as the default credential scope. 6. Repeat the process in other environment-level folders with their respective credentials. This will make the credentials you configure in each environment-level folder the default for all subfolders within it, as long as no other directory-specific defaults are set in them. ## Step 3: Use the plugin in multiple environments After you set default credentials in all your environment-level folders, you can use the shell plugin in the working directories for each environment without needing to sign in or out. 1. Enter the working directory for an environment. For example, to change directories into the development environment from the example above: ```shell theme={null} cd ~/projects/development ``` 2. Run a job in that environment. For example: ```shell theme={null} terraform apply ``` 3. Switch to a different environment. For example, to change to the production environment: ```shell theme={null} cd ~/projects/production ``` 4. Run a job in that environment: ```shell theme={null} terraform apply ``` 5. Exit the environment: ```shell theme={null} op signout ``` The shell plugin will automatically authenticate with the appropriate credentials for each environment, without requiring any action on your part. ## Learn more * [Get started with 1Password Shell Plugins](/cli/shell-plugins/) * [Build your own shell plugins](/cli/shell-plugins/contribute/) # Use 1Password to securely authenticate Exercism CLI Source: https://www.1password.dev/cli/shell-plugins/exercism Store your credentials in 1Password then authenticate Exercism CLI with your fingerprint. The Exercism shell plugin allows you to use 1Password to securely authenticate [Exercism CLI](https://exercism.org/docs/using/solving-exercises/working-locally) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext.Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Exercism CLI with biometrics.## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.35.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install Exercism CLI.](https://exercism.org/docs/using/solving-exercises/working-locally)
The following shells are supported:
  • Bash
  • Zsh
  • fish
## Step 1: Configure your default credentialsTo get started with the Exercism shell plugin:
  1. Sign in to the 1Password account you want to use with the Exercism plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init exercism
You'll be prompted to import your Exercism credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used.### Step 1.1: Import or select an item#### Import a new itemIf you haven't saved your Exercism credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it.If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them.#### Select an existing itemIf you've already saved your Exercism credentials in 1Password, select **Search in 1Password**.You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account.### Step 1.2: Set default credential scopeAfter you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Exercism.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh fileTo make the plugin available, source your `plugins.sh` file. For example:```shell theme={null} source ~/.config/op/plugins.sh ```The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path.If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example:```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``````shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``````shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ```## Step 3: Use the CLIThe next time you enter a command with Exercism, you'll be prompted to authenticate with biometrics or system authentication.## Step 4: Remove imported credentials from diskAfter saving your Exercism credentials in 1Password, you can remove all local copies you previously had stored on disk.## Next steps1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs:```shell theme={null} op plugin list ```To choose another plugin to get started with:```shell theme={null} op plugin init ```To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/)## Get help### Inspect your configurationTo inspect your current Exercism configuration:op plugin inspect exercism1Password CLI will return a list of the credentials you've configured to use with Exercism and their default scopes, as well as a list of aliases configured for Exercism.### Clear your credentialsTo reset the credentials used with Exercism:op plugin clear exercismYou can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear exercism` four times to clear all of your defaults.To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear exercism --all`.## Reference 1Password authenticates with Exercism by provisioning your credentials to a configuration file at \`~/.config/exercism/user.json`. If you saved your Exercism credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. \ \ \
1Password field nameDescription
*Thanks to [@dethancosta](https://github.com/dethancosta) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/404) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate Expo CLI Source: https://www.1password.dev/cli/shell-plugins/expo Store your credentials in 1Password then authenticate Expo CLI with your fingerprint. The Expo shell plugin allows you to use 1Password to securely authenticate [Expo CLI](https://docs.expo.dev/more/expo-cli/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext.Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Expo CLI with biometrics.## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.35.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install Expo CLI.](https://docs.expo.dev/more/expo-cli/)
The following shells are supported:
  • Bash
  • Zsh
  • fish
## Step 1: Configure your default credentialsTo get started with the Expo shell plugin:
  1. Sign in to the 1Password account you want to use with the Expo plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init expo
You'll be prompted to import your Expo credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used.### Step 1.1: Import or select an item#### Import a new itemIf you haven't saved your Expo credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it.If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them.#### Select an existing itemIf you've already saved your Expo credentials in 1Password, select **Search in 1Password**.You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account.### Step 1.2: Set default credential scopeAfter you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Expo.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh fileTo make the plugin available, source your `plugins.sh` file. For example:```shell theme={null} source ~/.config/op/plugins.sh ```The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path.If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example:```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``````shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``````shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ```## Step 3: Use the CLIThe next time you enter a command with Expo, you'll be prompted to authenticate with biometrics or system authentication.## Step 4: Remove imported credentials from diskAfter saving your Expo credentials in 1Password, you can remove all local copies you previously had stored on disk.## Next steps1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs:```shell theme={null} op plugin list ```To choose another plugin to get started with:```shell theme={null} op plugin init ```To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/)## Get help### Inspect your configurationTo inspect your current Expo configuration:op plugin inspect expo1Password CLI will return a list of the credentials you've configured to use with Expo and their default scopes, as well as a list of aliases configured for Expo.### Clear your credentialsTo reset the credentials used with Expo:op plugin clear expoYou can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear expo` four times to clear all of your defaults.To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear expo --all`.## Reference 1Password authenticates with Expo by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Expo credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. \ \ \
1Password field nameEnvironment variable
*Thanks to [@CodeByZach](https://github.com/CodeByZach) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/563) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate Fastly CLI Source: https://www.1password.dev/cli/shell-plugins/fastly The Fastly shell plugin allows you to use 1Password to securely authenticate [Fastly CLI](https://developer.fastly.com/reference/cli/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Fastly CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.14.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [Fastly CLI.](https://developer.fastly.com/learning/tools/cli) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Fastly shell plugin:
  1. Sign in to the 1Password account you want to use with the Fastly plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init fastly
You'll be prompted to import your Fastly credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/fastly-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Fastly credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/fastly-2.png) #### Select an existing item If you've already saved your Fastly credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/fastly-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Fastly. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/fastly-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Fastly, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/GCQVFnB1yNS2i2Vr/static/img/shell-plugins/fastly-5.png?fit=max\&auto=format\&n=GCQVFnB1yNS2i2Vr\&q=85\&s=4b5134a460ce88e72a17078180e75128) ## Step 4: Remove imported credentials from disk After saving your Fastly credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Fastly configuration: op plugin inspect fastly 1Password CLI will return a list of the credentials you've configured to use with Fastly and their default scopes, as well as a list of aliases configured for Fastly. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/GCQVFnB1yNS2i2Vr/static/img/shell-plugins/fastly-6.png?fit=max\&auto=format\&n=GCQVFnB1yNS2i2Vr\&q=85\&s=f6936275706f4e2f26c576c8cf753734) ### Clear your credentials To reset the credentials used with Fastly: op plugin clear fastly You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear fastly` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear fastly --all`. ## Reference 1Password authenticates with Fastly by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Fastly credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | Token | `FASTLY_API_TOKEN` | *Thanks to [@arunsathiya](https://github.com/arunsathiya) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/169) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate Flyctl Source: https://www.1password.dev/cli/shell-plugins/flyctl The Flyctl shell plugin allows you to use 1Password to securely authenticate [Flyctl](https://fly.io/docs/hands-on/install-flyctl/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Flyctl with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.22.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/). 5. [Install Flyctl.](https://fly.io/docs/hands-on/install-flyctl/) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Flyctl shell plugin:
  1. Sign in to the 1Password account you want to use with the Flyctl plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init fly
You'll be prompted to import your Flyctl credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Flyctl credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. #### Select an existing item If you've already saved your Flyctl credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Flyctl.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Flyctl, you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your Flyctl credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Flyctl configuration: op plugin inspect fly 1Password CLI will return a list of the credentials you've configured to use with Flyctl and their default scopes, as well as a list of aliases configured for Flyctl. ### Clear your credentials To reset the credentials used with Flyctl: op plugin clear fly You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear fly` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear fly --all`. ## Reference 1Password authenticates with Flyctl by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Flyctl credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | Token | `FLY_ACCESS_TOKEN` | *Thanks to [@arunsathiya](https://github.com/arunsathiya) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/141) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate FOSSA CLI Source: https://www.1password.dev/cli/shell-plugins/fossa The FOSSA shell plugin allows you to use 1Password to securely authenticate [FOSSA CLI](https://github.com/fossas/fossa-cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate FOSSA CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [FOSSA CLI.](https://github.com/fossas/fossa-cli) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the FOSSA shell plugin:
  1. Sign in to the 1Password account you want to use with the FOSSA plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init fossa
You'll be prompted to import your FOSSA credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/fossa-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your FOSSA credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/fossa-2.png) #### Select an existing item If you've already saved your FOSSA credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/fossa-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate FOSSA. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/fossa-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with FOSSA, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/GCQVFnB1yNS2i2Vr/static/img/shell-plugins/fossa-5.png?fit=max\&auto=format\&n=GCQVFnB1yNS2i2Vr\&q=85\&s=b6f140131c99dc0207f76715c129e1a1) ## Step 4: Remove imported credentials from disk After saving your FOSSA credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current FOSSA configuration: op plugin inspect fossa 1Password CLI will return a list of the credentials you've configured to use with FOSSA and their default scopes, as well as a list of aliases configured for FOSSA. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/GCQVFnB1yNS2i2Vr/static/img/shell-plugins/fossa-6.png?fit=max\&auto=format\&n=GCQVFnB1yNS2i2Vr\&q=85\&s=e4481e73f98d9ae0987960390357191c) ### Clear your credentials To reset the credentials used with FOSSA: op plugin clear fossa You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear fossa` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear fossa --all`. ## Reference 1Password authenticates with FOSSA by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your FOSSA credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | API Key | `FOSSA_API_KEY` | ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate Gemini CLI Source: https://www.1password.dev/cli/shell-plugins/gemini Store your credentials in 1Password then authenticate Gemini CLI with your fingerprint. The Gemini CLI shell plugin allows you to use 1Password to securely authenticate [Gemini CLI](https://geminicli.com/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext.Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Gemini CLI with biometrics.## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.35.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install Gemini CLI.](https://geminicli.com/)
The following shells are supported:
  • Bash
  • Zsh
  • fish
## Step 1: Configure your default credentialsTo get started with the Gemini CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the Gemini CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init gemini
You'll be prompted to import your Gemini CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used.### Step 1.1: Import or select an item#### Import a new itemIf you haven't saved your Gemini CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it.If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them.#### Select an existing itemIf you've already saved your Gemini CLI credentials in 1Password, select **Search in 1Password**.You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account.### Step 1.2: Set default credential scopeAfter you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Gemini CLI.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh fileTo make the plugin available, source your `plugins.sh` file. For example:```shell theme={null} source ~/.config/op/plugins.sh ```The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path.If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example:```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``````shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``````shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ```## Step 3: Use the CLIThe next time you enter a command with Gemini CLI, you'll be prompted to authenticate with biometrics or system authentication.## Step 4: Remove imported credentials from diskAfter saving your Gemini CLI credentials in 1Password, you can remove all local copies you previously had stored on disk.## Next steps1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs:```shell theme={null} op plugin list ```To choose another plugin to get started with:```shell theme={null} op plugin init ```To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/)## Get help### Inspect your configurationTo inspect your current Gemini CLI configuration:op plugin inspect gemini1Password CLI will return a list of the credentials you've configured to use with Gemini CLI and their default scopes, as well as a list of aliases configured for Gemini CLI.### Clear your credentialsTo reset the credentials used with Gemini CLI:op plugin clear geminiYou can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear gemini` four times to clear all of your defaults.To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear gemini --all`.## Reference 1Password authenticates with Gemini CLI by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Gemini CLI credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. \ \ \
1Password field nameEnvironment variable
*Thanks to [@fproulx-boostsecurity](https://github.com/fproulx-boostsecurity) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/560) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate the Gitea CLI Source: https://www.1password.dev/cli/shell-plugins/gitea The Gitea shell plugin allows you to use 1Password to securely authenticate [the Gitea CLI](https://gitea.com/gitea/tea) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Gitea with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.16.1 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. [Install the Gitea CLI.](https://gitea.com/gitea/tea) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Gitea shell plugin:
  1. Sign in to the 1Password account you want to use with the Gitea plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init tea
You'll be prompted to import your Gitea credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/gitea-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Gitea credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/gitea-2.png) #### Select an existing item If you've already saved your Gitea credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/gitea-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Gitea. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/gitea-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Gitea, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/NmanhI8sMYqqcc1i/static/img/shell-plugins/gitea-5.png?fit=max\&auto=format\&n=NmanhI8sMYqqcc1i\&q=85\&s=8b1e086da232b0d46733932a59261365) ## Step 4: Remove imported credentials from disk After saving your Gitea credentials in 1Password, you can remove all local copies you previously had stored on disk. ```shell theme={null} rm ~/.config/tea/config.yml ``` ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Gitea configuration: op plugin inspect tea 1Password CLI will return a list of the credentials you've configured to use with Gitea and their default scopes, as well as a list of aliases configured for Gitea. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/NmanhI8sMYqqcc1i/static/img/shell-plugins/gitea-6.png?fit=max\&auto=format\&n=NmanhI8sMYqqcc1i\&q=85\&s=53928241b65d7bc5eaa4c39d28e1c7a6) ### Clear your credentials To reset the credentials used with Gitea: op plugin clear tea You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear tea` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear tea --all`. ## Reference 1Password authenticates with Gitea by injecting a temporary file with the credentials required by the plugin commands directly from your 1Password account. If you saved your Gitea credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | YAML config field | | - | - | | Token | `token` | | HostAddress | `name`, `url` | | User | `user` | ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate the GitHub CLI Source: https://www.1password.dev/cli/shell-plugins/github The GitHub shell plugin allows you to use 1Password to securely authenticate [the GitHub CLI](https://cli.github.com/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. You can use the plugin with github.com, GitHub Enterprise Cloud, or GitHub Enterprise Server. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the GitHub CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the GitHub CLI.](https://github.com/cli/cli#installation) The following shells are supported: * Bash * Zsh * fish ## Before you begin: Create and save a GitHub personal access token Before you can use 1Password to authenticate the GitHub CLI, you'll need to [create a GitHub personal access token.](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) 1Password authenticates the GitHub CLI with your personal access token instead of a username and password. If you use GitHub Enterprise Server, create the token on your own GitHub host rather than on github.com. If you've already created a personal access token, [skip to Step 1](#step-1-configure-your-default-credentials). If you haven't created a personal access token yet, you can create one and use the [1Password browser extension](https://support.1password.com/getting-started-browser/) to quickly save it in 1Password: 1. Open and unlock [1Password in your browser](https://support.1password.com/getting-started-browser/). 2. [Follow the steps](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) to create a GitHub personal access token. 3. Select **Save item** when 1Password asks if you want to save an item for the GitHub personal access token. 4. Choose the vault where you want to save the item, edit the item's name and details, then select **Save item**. ![The pop-up screen to save your GitHub personal access token in 1Password.](https://mintcdn.com/ab-634991b8/NmanhI8sMYqqcc1i/static/img/shell-plugins/github-save.png?fit=max\&auto=format\&n=NmanhI8sMYqqcc1i\&q=85\&s=636267621524ce365ebd7d75f51bff91) ## Step 1: Configure your default credentials > [!TIP] > > **If you use multiple GitHub accounts** > > If you want to use the GitHub shell plugin with more than one GitHub account, like your personal and work accounts, [learn how to set up your plugin to use multiple accounts](/cli/shell-plugins/multiple-accounts/). To get started with the GitHub shell plugin:
  1. Sign in to the 1Password account you want to use with the GitHub plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init gh
You'll be prompted to import your GitHub credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/gh-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your GitHub credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/gh-2.png) #### Select an existing item If you've already saved your GitHub credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/gh-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate GitHub. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/gh-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
If you use a single GitHub account, select **Use as global default on my system**. This will set your personal access token as the default in all terminal sessions and directories. If you use multiple GitHub accounts, [learn how to use directory-specific defaults for context switching](/cli/shell-plugins/multiple-accounts/). ### Authenticate with GitHub Enterprise If your personal access token is for GitHub Enterprise rather than github.com, enter the hostname you use to reach GitHub in the optional **Host** field when you import or create the item, for example `github.example.com` or `company.ghe.com`. Leave the field empty if you use github.com. The plugin provisions your token to the environment variables the GitHub CLI expects for that host: * **github.com and GitHub Enterprise Cloud**: Your token is provisioned as `GH_TOKEN` and `GITHUB_TOKEN`. * **GitHub Enterprise Server**: Your token is provisioned as `GH_ENTERPRISE_TOKEN` and `GITHUB_ENTERPRISE_TOKEN`, along with `GH_HOST` so the GitHub CLI knows which host to authenticate to. If you work with accounts for both github.com and an Enterprise Server host, save a separate 1Password item for each token, one with your Enterprise Server hostname and one without a **Host** value. Then [configure a default credential for each](/cli/shell-plugins/multiple-accounts/) so each project authenticates with the right token. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with GitHub, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/GCQVFnB1yNS2i2Vr/static/img/shell-plugins/gh-5.png?fit=max\&auto=format\&n=GCQVFnB1yNS2i2Vr\&q=85\&s=1c13f93c0faccbc4a094349357c46664) ## Step 4: Remove imported credentials from disk After saving your GitHub credentials in 1Password, you can remove all local copies you previously had stored on disk. ```shell theme={null} rm ~/.config/gh/hosts.yml ``` ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current GitHub configuration: op plugin inspect gh 1Password CLI will return a list of the credentials you've configured to use with GitHub and their default scopes, as well as a list of aliases configured for GitHub. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/GCQVFnB1yNS2i2Vr/static/img/shell-plugins/gh-6.png?fit=max\&auto=format\&n=GCQVFnB1yNS2i2Vr\&q=85\&s=d6fd7938fc1ec5fa6bf08524c5f48fe6) ### Clear your credentials To reset the credentials used with GitHub: op plugin clear gh You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear gh` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear gh --all`. ## Reference 1Password authenticates with GitHub by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your GitHub credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. The environment variables your token is provisioned to depend on the value of the **Host** field. **github.com and GitHub Enterprise Cloud** (**Host** empty, `github.com`, or a `*.ghe.com` hostname): | 1Password field names | Environment variables | | - | - | | Token | `GH_TOKEN`, `GITHUB_TOKEN` | | Host (optional) | `GH_HOST` | **GitHub Enterprise Server** (**Host** set to your own GitHub hostname): | 1Password field names | Environment variables | | - | - | | Token | `GH_ENTERPRISE_TOKEN`, `GITHUB_ENTERPRISE_TOKEN` | | Host | `GH_HOST` | `GH_HOST` is only set if you entered a **Host** value other than `github.com`. ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate GitHub Copilot CLI Source: https://www.1password.dev/cli/shell-plugins/github-copilot Store your credentials in 1Password then authenticate GitHub Copilot CLI with your fingerprint. The GitHub Copilot shell plugin allows you to use 1Password to securely authenticate [GitHub Copilot CLI](https://github.com/features/copilot/cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext.Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate GitHub Copilot CLI with biometrics.## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.35.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install GitHub Copilot CLI.](https://github.com/features/copilot/cli)
The following shells are supported:
  • Bash
  • Zsh
  • fish
## Step 1: Configure your default credentialsTo get started with the GitHub Copilot shell plugin:
  1. Sign in to the 1Password account you want to use with the GitHub Copilot plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init copilot
You'll be prompted to import your GitHub Copilot credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used.### Step 1.1: Import or select an item#### Import a new itemIf you haven't saved your GitHub Copilot credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it.If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them.#### Select an existing itemIf you've already saved your GitHub Copilot credentials in 1Password, select **Search in 1Password**.You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account.### Step 1.2: Set default credential scopeAfter you select or import your credentials, you'll be prompted to configure when to use the item to authenticate GitHub Copilot.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh fileTo make the plugin available, source your `plugins.sh` file. For example:```shell theme={null} source ~/.config/op/plugins.sh ```The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path.If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example:```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``````shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``````shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ```## Step 3: Use the CLIThe next time you enter a command with GitHub Copilot, you'll be prompted to authenticate with biometrics or system authentication.## Step 4: Remove imported credentials from diskAfter saving your GitHub Copilot credentials in 1Password, you can remove all local copies you previously had stored on disk.## Next steps1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs:```shell theme={null} op plugin list ```To choose another plugin to get started with:```shell theme={null} op plugin init ```To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/)## Get help### Inspect your configurationTo inspect your current GitHub Copilot configuration:op plugin inspect copilot1Password CLI will return a list of the credentials you've configured to use with GitHub Copilot and their default scopes, as well as a list of aliases configured for GitHub Copilot.### Clear your credentialsTo reset the credentials used with GitHub Copilot:op plugin clear copilotYou can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear copilot` four times to clear all of your defaults.To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear copilot --all`.## Reference 1Password authenticates with GitHub Copilot by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your GitHub Copilot credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. \ \ \
1Password field nameEnvironment variable
*Thanks to [@eddumelendez](https://github.com/eddumelendez) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/603) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate the GitLab CLI Source: https://www.1password.dev/cli/shell-plugins/gitlab The GitLab shell plugin allows you to use 1Password to securely authenticate [the GitLab CLI](https://docs.gitlab.com/ee/integration/glab/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the GitLab CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the GitLab CLI.](https://gitlab.com/gitlab-org/cli/-/blob/main/README.md#installation) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the GitLab shell plugin:
  1. Sign in to the 1Password account you want to use with the GitLab plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init glab
You'll be prompted to import your GitLab credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/glab-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your GitLab credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/glab-2.png) #### Select an existing item If you've already saved your GitLab credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/glab-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate GitLab. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/glab-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Optional: If you use a self-hosted instance, set the host If you use a self-hosted GitLab instance, you'll need to add your host URL to the GitLab item you configured in the previous step. Save the URL in a custom text field titled `Host` to make it available to the shell plugin. > [tab] 1Password CLI > > To add the field using 1Password CLI: > > op item edit \ \\ > 'Host\[text]=[https://gitlab.yourdomain.com](https://gitlab.yourdomain.com)' > > op item edit \ \` > 'Host\[text]=[https://gitlab.yourdomain.com](https://gitlab.yourdomain.com)' > [tab] 1Password desktop app > > To add the field using the 1Password desktop app: > > 1. Open and unlock the [1Password app](https://1password.com/downloads/). > 2. Navigate to the item you configured in the previous step and select **Edit**. > 3. Select **Add More** > **Text** to add a custom text field. > 4. Select the default field name, "text", and rename it to `Host`. > 5. Enter your GitLab host as the field value. For example, `https://gitlab.yourdomain.com` > 6. Select **Save**. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with GitLab, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/NmanhI8sMYqqcc1i/static/img/shell-plugins/glab-5.png?fit=max\&auto=format\&n=NmanhI8sMYqqcc1i\&q=85\&s=eca4cab8aa6a155bae59590979cb3d16) ## Step 4: Remove imported credentials from disk After saving your GitLab credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current GitLab configuration: op plugin inspect glab 1Password CLI will return a list of the credentials you've configured to use with GitLab and their default scopes, as well as a list of aliases configured for GitLab. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/NmanhI8sMYqqcc1i/static/img/shell-plugins/glab-6.png?fit=max\&auto=format\&n=NmanhI8sMYqqcc1i\&q=85\&s=68e8d935f6e2cd525e3156901a3617f3) ### Clear your credentials To reset the credentials used with GitLab: op plugin clear glab You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear glab` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear glab --all`. ## Reference 1Password authenticates with GitLab by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your GitLab credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variables | | - | - | | Token | `GITLAB_TOKEN` | | Host (optional; required for self-hosted instances) | `GITLAB_HOST` | | API Host (optional) | `GITLAB_API_HOST` | ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate the HashiCorp Vault CLI Source: https://www.1password.dev/cli/shell-plugins/hashicorp-vault The HashiCorp Vault shell plugin allows you to use 1Password to securely authenticate [the Vault CLI](https://developer.hashicorp.com/vault/docs/commands) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Vault CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Vault CLI.](https://developer.hashicorp.com/vault/tutorials/getting-started/getting-started-install) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the HashiCorp Vault shell plugin:
  1. Sign in to the 1Password account you want to use with the HashiCorp Vault plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init vault
You'll be prompted to import your HashiCorp Vault credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/vault-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your HashiCorp Vault credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/vault-2.png) #### Select an existing item If you've already saved your HashiCorp Vault credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/vault-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate HashiCorp Vault. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/vault-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with HashiCorp Vault, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/MKy6sgNGqMk-yGDS/static/img/shell-plugins/vault-5.png?fit=max\&auto=format\&n=MKy6sgNGqMk-yGDS\&q=85\&s=4e252f84a89e2f9f414955f5b9fb2ef1) ## Step 4: Remove imported credentials from disk After saving your HashiCorp Vault credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current HashiCorp Vault configuration: op plugin inspect vault 1Password CLI will return a list of the credentials you've configured to use with HashiCorp Vault and their default scopes, as well as a list of aliases configured for HashiCorp Vault. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/MKy6sgNGqMk-yGDS/static/img/shell-plugins/vault-6.png?fit=max\&auto=format\&n=MKy6sgNGqMk-yGDS\&q=85\&s=d08ecfbdb7e88f52e578dfb713335078) ### Clear your credentials To reset the credentials used with HashiCorp Vault: op plugin clear vault You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear vault` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear vault --all`. ## Reference 1Password authenticates with HashiCorp Vault by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your HashiCorp Vault credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variables | | - | - | | Token | `VAULT_TOKEN` | | Address (optional) | `VAULT_ADDR` | | Namespace (optional) | `VAULT_NAMESPACE` | ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate the Heroku CLI Source: https://www.1password.dev/cli/shell-plugins/heroku The Heroku shell plugin allows you to use 1Password to securely authenticate [the Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Heroku CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Heroku CLI.](https://devcenter.heroku.com/articles/heroku-cli#install-the-heroku-cli) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Heroku shell plugin:
  1. Sign in to the 1Password account you want to use with the Heroku plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init heroku
You'll be prompted to import your Heroku credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/heroku-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Heroku credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/heroku-2.png) #### Select an existing item If you've already saved your Heroku credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/heroku-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Heroku. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/heroku-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Heroku, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/NmanhI8sMYqqcc1i/static/img/shell-plugins/heroku-5.png?fit=max\&auto=format\&n=NmanhI8sMYqqcc1i\&q=85\&s=ed8dcba75d9349f99a4236b73c2496e2) ## Step 4: Remove imported credentials from disk After saving your Heroku credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Heroku configuration: op plugin inspect heroku 1Password CLI will return a list of the credentials you've configured to use with Heroku and their default scopes, as well as a list of aliases configured for Heroku. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/NmanhI8sMYqqcc1i/static/img/shell-plugins/heroku-6.png?fit=max\&auto=format\&n=NmanhI8sMYqqcc1i\&q=85\&s=041ea95c8880b29be490b07381bb2dac) ### Clear your credentials To reset the credentials used with Heroku: op plugin clear heroku You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear heroku` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear heroku --all`. ## Reference 1Password authenticates with Heroku by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Heroku credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | API Key | `HEROKU_API_KEY` | ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate the Hetzner Cloud CLI Source: https://www.1password.dev/cli/shell-plugins/hetzner-cloud The Hetzner Cloud shell plugin allows you to use 1Password to securely authenticate [hcloud](https://github.com/hetznercloud/cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate hcloud with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.12.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [hcloud.](https://github.com/hetznercloud/cli#installation) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Hetzner Cloud CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the Hetzner Cloud CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init hcloud
You'll be prompted to import your Hetzner Cloud CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/hcloud-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Hetzner Cloud CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/hcloud-2.png) #### Select an existing item If you've already saved your Hetzner Cloud CLI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/hcloud-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Hetzner Cloud CLI. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/hcloud-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with hcloud, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/NmanhI8sMYqqcc1i/static/img/shell-plugins/hcloud-5.png?fit=max\&auto=format\&n=NmanhI8sMYqqcc1i\&q=85\&s=71491a0f3c4f2557a122d2c97858d19f) ## Step 4: Remove imported credentials from disk After saving your Hetzner Cloud CLI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Hetzner Cloud CLI configuration: op plugin inspect hcloud 1Password CLI will return a list of the credentials you've configured to use with Hetzner Cloud CLI and their default scopes, as well as a list of aliases configured for Hetzner Cloud CLI. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/NmanhI8sMYqqcc1i/static/img/shell-plugins/hcloud-6.png?fit=max\&auto=format\&n=NmanhI8sMYqqcc1i\&q=85\&s=f12eb8a89de43da94cf069f0bd73fbdf) ### Clear your credentials To reset the credentials used with Hetzner Cloud CLI: op plugin clear hcloud You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear hcloud` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear hcloud --all`. ## Reference 1Password authenticates with Hetzner Cloud by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Hetzner Cloud credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variable | | - | - | | Token | `HCLOUD_TOKEN` | *Thanks to [@shyim](https://github.com/shyim) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/87) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate brew Source: https://www.1password.dev/cli/shell-plugins/homebrew The Homebrew shell plugin allows you to use 1Password to securely authenticate [the Homebrew package manager](https://brew.sh/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate brew with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.11.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [brew.](https://brew.sh/) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Homebrew shell plugin:
  1. Sign in to the 1Password account you want to use with the Homebrew plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init brew
You'll be prompted to import your Homebrew credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/homebrew-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Homebrew credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/homebrew-2.png) #### Select an existing item If you've already saved your Homebrew credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/homebrew-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Homebrew. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/homebrew-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Homebrew, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/NmanhI8sMYqqcc1i/static/img/shell-plugins/homebrew-5.png?fit=max\&auto=format\&n=NmanhI8sMYqqcc1i\&q=85\&s=c59830e81d55454be66c225dd8c2c7b2) ## Step 4: Remove imported credentials from disk After saving your Homebrew credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Homebrew configuration: op plugin inspect brew 1Password CLI will return a list of the credentials you've configured to use with Homebrew and their default scopes, as well as a list of aliases configured for Homebrew. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/NmanhI8sMYqqcc1i/static/img/shell-plugins/homebrew-6.png?fit=max\&auto=format\&n=NmanhI8sMYqqcc1i\&q=85\&s=9ff732c19fb671d164bd36f64eb32393) ### Clear your credentials To reset the credentials used with Homebrew: op plugin clear brew You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear brew` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear brew --all`. ## Reference 1Password authenticates with Homebrew by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Homebrew credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | Token | `HOMEBREW_GITHUB_API_TOKEN` | *Thanks to [@markdorison](https://github.com/markdorison) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/110) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate HuggingFace CLI Source: https://www.1password.dev/cli/shell-plugins/huggingface The HuggingFace CLI shell plugin allows you to use 1Password to securely authenticate [HuggingFace CLI](https://huggingface.co/docs/huggingface_hub/quick-start) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate HuggingFace CLI with biometrics. > [!NOTE] > > The HuggingFace shell plugin now uses the `hf` command, which replaces `huggingface-cli`. If you set up the plugin with `huggingface-cli` before 1Password CLI 2.42.0, run `op plugin init hf`, then remove the `huggingface-cli` alias from your `plugins.sh` file. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.42.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/). 5. [Install HuggingFace CLI.](https://huggingface.co/docs/huggingface_hub/quick-start) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the HuggingFace CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the HuggingFace CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init hf
You'll be prompted to import your HuggingFace CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your HuggingFace CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. #### Select an existing item If you've already saved your HuggingFace CLI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate HuggingFace CLI.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with HuggingFace CLI, you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your HuggingFace CLI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current HuggingFace CLI configuration: op plugin inspect hf 1Password CLI will return a list of the credentials you've configured to use with HuggingFace CLI and their default scopes, as well as a list of aliases configured for HuggingFace CLI. ### Clear your credentials To reset the credentials used with HuggingFace CLI: op plugin clear hf You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear hf` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear hf --all`. ## Reference 1Password authenticates with HuggingFace CLI by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your HuggingFace CLI credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | User Access Token | `HUGGING_FACE_HUB_TOKEN` | | Endpoint (optional) | `HF_ENDPOINT` | | API URL (optional) | `HF_INFERENCE_ENDPOINT` | *Thanks to [@bala-ceg](https://github.com/bala-ceg) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/393) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate InfluxDB Source: https://www.1password.dev/cli/shell-plugins/influxdb The InfluxDB shell plugin allows you to use 1Password to securely authenticate [InfluxDB](https://docs.influxdata.com/influxdb/cloud/reference/cli/influx/config/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate InfluxDB with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.22.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/). 5. [Install InfluxDB.](https://docs.influxdata.com/influxdb/cloud/reference/cli/influx/config/) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the InfluxDB shell plugin:
  1. Sign in to the 1Password account you want to use with the InfluxDB plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init influx
You'll be prompted to import your InfluxDB credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your InfluxDB credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. #### Select an existing item If you've already saved your InfluxDB credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate InfluxDB.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with InfluxDB, you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your InfluxDB credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current InfluxDB configuration: op plugin inspect influx 1Password CLI will return a list of the credentials you've configured to use with InfluxDB and their default scopes, as well as a list of aliases configured for InfluxDB. ### Clear your credentials To reset the credentials used with InfluxDB: op plugin clear influx You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear influx` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear influx --all`. ## Reference 1Password authenticates with InfluxDB by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your InfluxDB credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | Host | `INFLUX_HOST` | | Organization | `INFLUX_ORG` | | Access Token | `INFLUX_TOKEN` | *Thanks to [@bala-ceg](https://github.com/bala-ceg) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/392) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate Junie CLI Source: https://www.1password.dev/cli/shell-plugins/jetbrains-junie Store your credentials in 1Password then authenticate Junie CLI with your fingerprint. The JetBrains Junie shell plugin allows you to use 1Password to securely authenticate [Junie CLI](https://junie.jetbrains.com/docs/junie-cli-usage.html) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext.Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Junie CLI with biometrics.> [!NOTE] > > This shell plugins supports authentication with `JUNIE_API_Key`. Bring Your Own Key (BYOK) authentication is not supported.## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.35.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install Junie CLI.](https://junie.jetbrains.com/docs/junie-cli-usage.html)
The following shells are supported:
  • Bash
  • Zsh
  • fish
## Step 1: Configure your default credentialsTo get started with the Junie CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the Junie CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init junie
You'll be prompted to import your Junie CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used.### Step 1.1: Import or select an item#### Import a new itemIf you haven't saved your Junie CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it.If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them.#### Select an existing itemIf you've already saved your Junie CLI credentials in 1Password, select **Search in 1Password**.You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account.### Step 1.2: Set default credential scopeAfter you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Junie CLI.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh fileTo make the plugin available, source your `plugins.sh` file. For example:```shell theme={null} source ~/.config/op/plugins.sh ```The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path.If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example:```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``````shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``````shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ```## Step 3: Use the CLIThe next time you enter a command with Junie CLI, you'll be prompted to authenticate with biometrics or system authentication.## Step 4: Remove imported credentials from diskAfter saving your Junie CLI credentials in 1Password, you can remove all local copies you previously had stored on disk.## Next steps1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs:```shell theme={null} op plugin list ```To choose another plugin to get started with:```shell theme={null} op plugin init ```To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/)## Get help### Inspect your configurationTo inspect your current Junie CLI configuration:op plugin inspect junie1Password CLI will return a list of the credentials you've configured to use with Junie CLI and their default scopes, as well as a list of aliases configured for Junie CLI.### Clear your credentialsTo reset the credentials used with Junie CLI:op plugin clear junieYou can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear junie` four times to clear all of your defaults.To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear junie --all`.## Reference 1Password authenticates with Junie CLI by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Junie CLI credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. \ \ \
1Password field nameEnvironment variable
*Thanks to [@eddumelendez](https://github.com/eddumelendez) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/604) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate Kaggle CLI Source: https://www.1password.dev/cli/shell-plugins/kaggle The Kaggle CLI shell plugin allows you to use 1Password to securely authenticate [Kaggle CLI](https://github.com/Kaggle/kaggle-api) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Kaggle CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.22.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/). 5. [Install Kaggle CLI.](https://github.com/Kaggle/kaggle-api) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Kaggle CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the Kaggle CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init kaggle
You'll be prompted to import your Kaggle CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Kaggle CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. #### Select an existing item If you've already saved your Kaggle CLI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Kaggle CLI.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Kaggle CLI, you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your Kaggle CLI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Kaggle CLI configuration: op plugin inspect kaggle 1Password CLI will return a list of the credentials you've configured to use with Kaggle CLI and their default scopes, as well as a list of aliases configured for Kaggle CLI. ### Clear your credentials To reset the credentials used with Kaggle CLI: op plugin clear kaggle You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear kaggle` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear kaggle --all`. ## Reference 1Password authenticates with Kaggle CLI by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Kaggle CLI credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | Token | `KAGGLE_KEY` | | Username | `KAGGLE_USERNAME` | *Thanks to [@rajapri28613](https://github.com/rajapri28613) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/341) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate Kiro CLI Source: https://www.1password.dev/cli/shell-plugins/kiro Store your credentials in 1Password then authenticate Kiro CLI with your fingerprint. The Kiro shell plugin allows you to use 1Password to securely authenticate [Kiro CLI](https://kiro.dev/docs/cli/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext.Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Kiro CLI with biometrics.## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.35.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install Kiro CLI.](https://kiro.dev/docs/cli/)
The following shells are supported:
  • Bash
  • Zsh
  • fish
## Step 1: Configure your default credentialsTo get started with the Kiro shell plugin:
  1. Sign in to the 1Password account you want to use with the Kiro plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init kiro-cli
You'll be prompted to import your Kiro credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used.### Step 1.1: Import or select an item#### Import a new itemIf you haven't saved your Kiro credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it.If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them.#### Select an existing itemIf you've already saved your Kiro credentials in 1Password, select **Search in 1Password**.You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account.### Step 1.2: Set default credential scopeAfter you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Kiro.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh fileTo make the plugin available, source your `plugins.sh` file. For example:```shell theme={null} source ~/.config/op/plugins.sh ```The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path.If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example:```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``````shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``````shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ```## Step 3: Use the CLIThe next time you enter a command with Kiro, you'll be prompted to authenticate with biometrics or system authentication.## Step 4: Remove imported credentials from diskAfter saving your Kiro credentials in 1Password, you can remove all local copies you previously had stored on disk.## Next steps1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs:```shell theme={null} op plugin list ```To choose another plugin to get started with:```shell theme={null} op plugin init ```To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/)## Get help### Inspect your configurationTo inspect your current Kiro configuration:op plugin inspect kiro-cli1Password CLI will return a list of the credentials you've configured to use with Kiro and their default scopes, as well as a list of aliases configured for Kiro.### Clear your credentialsTo reset the credentials used with Kiro:op plugin clear kiro-cliYou can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear kiro-cli` four times to clear all of your defaults.To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear kiro-cli --all`.## Reference 1Password authenticates with Kiro by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Kiro credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. \ \ \
1Password field nameEnvironment variable
*Thanks to [@eddumelendez](https://github.com/eddumelendez) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/605) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate the Lacework CLI Source: https://www.1password.dev/cli/shell-plugins/lacework The Lacework shell plugin allows you to use 1Password to securely authenticate [the Lacework CLI](https://docs.lacework.com/cli/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Lacework CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.10.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Lacework CLI.](https://docs.lacework.com/cli/) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Lacework shell plugin:
  1. Sign in to the 1Password account you want to use with the Lacework plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init lacework
You'll be prompted to import your Lacework credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/lacework-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Lacework credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/lacework-2.png) #### Select an existing item If you've already saved your Lacework credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/lacework-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Lacework. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/lacework-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Lacework, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/NmanhI8sMYqqcc1i/static/img/shell-plugins/lacework-5.png?fit=max\&auto=format\&n=NmanhI8sMYqqcc1i\&q=85\&s=bad2b651a7fd8884449e3882794935cb) ## Step 4: Remove imported credentials from disk After saving your Lacework credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Lacework configuration: op plugin inspect lacework 1Password CLI will return a list of the credentials you've configured to use with Lacework and their default scopes, as well as a list of aliases configured for Lacework. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/NmanhI8sMYqqcc1i/static/img/shell-plugins/lacework-6.png?fit=max\&auto=format\&n=NmanhI8sMYqqcc1i\&q=85\&s=7f2d9d7dd08cdcd829fb8d1634b47634) ### Clear your credentials To reset the credentials used with Lacework: op plugin clear lacework You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear lacework` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear lacework --all`. ## Reference 1Password authenticates with Lacework by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Lacework credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | Account | `LW_ACCOUNT` | | API Key ID | `LW_API_KEY` | | API Secret | `LW_API_SECRET` | *Thanks to [@colinbarr](https://github.com/colinbarr) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/95) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate the Laravel Forge CLI Source: https://www.1password.dev/cli/shell-plugins/laravel-forge The Laravel Forge shell plugin allows you to use 1Password to securely authenticate [the Laravel Forge CLI](https://forge.laravel.com/docs/1.0/cli.html) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Laravel Forge CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.17.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Laravel Forge CLI.](https://forge.laravel.com/docs/1.0/cli.html#installation) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the the Laravel Forge CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the the Laravel Forge CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init forge
You'll be prompted to import your the Laravel Forge CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/forge-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your the Laravel Forge CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/forge-2.png) #### Select an existing item If you've already saved your the Laravel Forge CLI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/forge-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate the Laravel Forge CLI. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/forge-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with the Laravel Forge CLI, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/GCQVFnB1yNS2i2Vr/static/img/shell-plugins/forge-5.png?fit=max\&auto=format\&n=GCQVFnB1yNS2i2Vr\&q=85\&s=0986613b92f93d40642e17bd9ea66643) ## Step 4: Remove imported credentials from disk After saving your the Laravel Forge CLI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current the Laravel Forge CLI configuration: op plugin inspect forge 1Password CLI will return a list of the credentials you've configured to use with the Laravel Forge CLI and their default scopes, as well as a list of aliases configured for the Laravel Forge CLI. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/GCQVFnB1yNS2i2Vr/static/img/shell-plugins/forge-6.png?fit=max\&auto=format\&n=GCQVFnB1yNS2i2Vr\&q=85\&s=4d24df77e83766f5b0f7aaefcffda2be) ### Clear your credentials To reset the credentials used with the Laravel Forge CLI: op plugin clear forge You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear forge` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear forge --all`. ## Reference 1Password authenticates with the Laravel Forge CLI by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your the Laravel Forge CLI credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | Token | `FORGE_API_TOKEN` | *Thanks to [@andresayej](https://github.com/andresayej) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/244) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate the Laravel Vapor CLI Source: https://www.1password.dev/cli/shell-plugins/laravel-vapor The Laravel Vapor shell plugin allows you to use 1Password to securely authenticate [the Laravel Vapor CLI](https://docs.vapor.build/1.0/introduction.html) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Laravel Vapor CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.17.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Laravel Vapor CLI.](https://docs.vapor.build/1.0/introduction.html#installing-the-vapor-cli) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the the Laravel Vapor CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the the Laravel Vapor CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init vapor
You'll be prompted to import your the Laravel Vapor CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/vapor-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your the Laravel Vapor CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/vapor-2.png) #### Select an existing item If you've already saved your the Laravel Vapor CLI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/vapor-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate the Laravel Vapor CLI. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/vapor-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with the Laravel Vapor CLI, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/MKy6sgNGqMk-yGDS/static/img/shell-plugins/vapor-5.png?fit=max\&auto=format\&n=MKy6sgNGqMk-yGDS\&q=85\&s=4bb2dc03f3a808eadb169cf14f7be825) ## Step 4: Remove imported credentials from disk After saving your the Laravel Vapor CLI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current the Laravel Vapor CLI configuration: op plugin inspect vapor 1Password CLI will return a list of the credentials you've configured to use with the Laravel Vapor CLI and their default scopes, as well as a list of aliases configured for the Laravel Vapor CLI. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/MKy6sgNGqMk-yGDS/static/img/shell-plugins/vapor-6.png?fit=max\&auto=format\&n=MKy6sgNGqMk-yGDS\&q=85\&s=e68bdde8480e281620a5c0ff7391203d) ### Clear your credentials To reset the credentials used with the Laravel Vapor CLI: op plugin clear vapor You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear vapor` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear vapor --all`. ## Reference 1Password authenticates with the Laravel Vapor CLI by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your the Laravel Vapor CLI credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | Token | `VAPOR_API_TOKEN` | *Thanks to [@andresayej](https://github.com/andresayej) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/245) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate the Linode CLI Source: https://www.1password.dev/cli/shell-plugins/linode The Linode shell plugin allows you to use 1Password to securely authenticate [the Linode CLI](https://www.linode.com/docs/products/tools/cli/get-started/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Linode CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.10.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Linode CLI.](https://www.linode.com/docs/products/tools/cli/get-started/) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Linode shell plugin:
  1. Sign in to the 1Password account you want to use with the Linode plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init linode-cli
You'll be prompted to import your Linode credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/linode-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Linode credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/linode-2.png) #### Select an existing item If you've already saved your Linode credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/linode-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Linode. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/linode-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Linode, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/NmanhI8sMYqqcc1i/static/img/shell-plugins/linode-5.png?fit=max\&auto=format\&n=NmanhI8sMYqqcc1i\&q=85\&s=422d447e4d3b5ec711abb484de266264) ## Step 4: Remove imported credentials from disk After saving your Linode credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Linode configuration: op plugin inspect linode-cli 1Password CLI will return a list of the credentials you've configured to use with Linode and their default scopes, as well as a list of aliases configured for Linode. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/NmanhI8sMYqqcc1i/static/img/shell-plugins/linode-6.png?fit=max\&auto=format\&n=NmanhI8sMYqqcc1i\&q=85\&s=6a8cb4d00bc5c18527c932790c8e730c) ### Clear your credentials To reset the credentials used with Linode: op plugin clear linode-cli You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear linode-cli` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear linode-cli --all`. ## Reference 1Password authenticates with Linode by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Linode credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | Token | `LINODE_CLI_TOKEN` | *Thanks to [@alexclst](https://github.com/alexclst) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/86) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate LocalStack Source: https://www.1password.dev/cli/shell-plugins/localstack The LocalStack shell plugin allows you to use 1Password to securely authenticate [LocalStack](https://docs.localstack.cloud/getting-started/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate LocalStack with biometrics. > [!NOTE] > > LocalStack has replaced API keys with auth tokens, and the LocalStack shell plugin now provisions `LOCALSTACK_AUTH_TOKEN` instead of `LOCALSTACK_API_KEY`. If you set up the plugin with an API key before 1Password CLI 2.42.0, run `op plugin init localstack` again and import or select an item that contains your [LocalStack auth token](https://docs.localstack.cloud/getting-started/auth-token/). ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.42.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/). 5. [Install LocalStack.](https://docs.localstack.cloud/getting-started/) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the LocalStack shell plugin:
  1. Sign in to the 1Password account you want to use with the LocalStack plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init localstack
You'll be prompted to import your LocalStack credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your LocalStack credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. #### Select an existing item If you've already saved your LocalStack credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate LocalStack.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with LocalStack, you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your LocalStack credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current LocalStack configuration: op plugin inspect localstack 1Password CLI will return a list of the credentials you've configured to use with LocalStack and their default scopes, as well as a list of aliases configured for LocalStack. ### Clear your credentials To reset the credentials used with LocalStack: op plugin clear localstack You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear localstack` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear localstack --all`. ## Reference 1Password authenticates with LocalStack by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your LocalStack credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | Auth Token | `LOCALSTACK_AUTH_TOKEN` | You can run `localstack auth` commands without a 1Password item. # Use 1Password to securely authenticate LocalXpose CLI Source: https://www.1password.dev/cli/shell-plugins/localxpose Store your credentials in 1Password then authenticate LocalXpose CLI with your fingerprint. The LocalXpose shell plugin allows you to use 1Password to securely authenticate [LocalXpose CLI](https://localxpose.io/docs/cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext.Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate LocalXpose CLI with biometrics.## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.42.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install LocalXpose CLI.](https://localxpose.io/docs/cli)
The following shells are supported:
  • Bash
  • Zsh
  • fish
## Step 1: Configure your default credentialsTo get started with the LocalXpose shell plugin:
  1. Sign in to the 1Password account you want to use with the LocalXpose plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init loclx
You'll be prompted to import your LocalXpose credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used.### Step 1.1: Import or select an item#### Import a new itemIf you haven't saved your LocalXpose credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it.If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them.#### Select an existing itemIf you've already saved your LocalXpose credentials in 1Password, select **Search in 1Password**.You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account.### Step 1.2: Set default credential scopeAfter you select or import your credentials, you'll be prompted to configure when to use the item to authenticate LocalXpose.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh fileTo make the plugin available, source your `plugins.sh` file. For example:```shell theme={null} source ~/.config/op/plugins.sh ```The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path.If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example:```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``````shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``````shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ```## Step 3: Use the CLIThe next time you enter a command with LocalXpose, you'll be prompted to authenticate with biometrics or system authentication.## Step 4: Remove imported credentials from diskAfter saving your LocalXpose credentials in 1Password, you can remove all local copies you previously had stored on disk.## Next steps1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs:```shell theme={null} op plugin list ```To choose another plugin to get started with:```shell theme={null} op plugin init ```To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/)## Get help### Inspect your configurationTo inspect your current LocalXpose configuration:op plugin inspect loclx1Password CLI will return a list of the credentials you've configured to use with LocalXpose and their default scopes, as well as a list of aliases configured for LocalXpose.### Clear your credentialsTo reset the credentials used with LocalXpose:op plugin clear loclxYou can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear loclx` four times to clear all of your defaults.To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear loclx --all`.## Reference 1Password authenticates with LocalXpose by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your LocalXpose credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. \ \ \
1Password field nameEnvironment variable
*Thanks to [@LocalXpose](https://github.com/LocalXpose) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/534) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate MongoDB Atlas Source: https://www.1password.dev/cli/shell-plugins/mongodb-atlas The MongoDB Atlas shell plugin allows you to use 1Password to securely authenticate [the Atlas CLI](https://www.mongodb.com/tools/atlas-cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Atlas CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.22.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/). 5. [Install the Atlas CLI.](https://www.mongodb.com/try/download/atlascli) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the MongoDB Atlas shell plugin:
  1. Sign in to the 1Password account you want to use with the MongoDB Atlas plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init atlas
You'll be prompted to import your MongoDB Atlas credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/mongodb-atlas-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your MongoDB Atlas credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/mongodb-atlas-2.png) #### Select an existing item If you've already saved your MongoDB Atlas credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/mongodb-atlas-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate MongoDB Atlas. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/mongodb-atlas-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with MongoDB Atlas, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/NmanhI8sMYqqcc1i/static/img/shell-plugins/mongodb-atlas-5.png?fit=max\&auto=format\&n=NmanhI8sMYqqcc1i\&q=85\&s=958d4a056034685da242fecc222e3461) ## Step 4: Remove imported credentials from disk After saving your MongoDB Atlas credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current MongoDB Atlas configuration: op plugin inspect atlas 1Password CLI will return a list of the credentials you've configured to use with MongoDB Atlas and their default scopes, as well as a list of aliases configured for MongoDB Atlas. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/NmanhI8sMYqqcc1i/static/img/shell-plugins/mongodb-atlas-6.png?fit=max\&auto=format\&n=NmanhI8sMYqqcc1i\&q=85\&s=21ea6415a3541d895df7ec26bace3733) ### Clear your credentials To reset the credentials used with MongoDB Atlas: op plugin clear atlas You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear atlas` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear atlas --all`. ## Reference 1Password authenticates with MongoDB Atlas by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your MongoDB Atlas credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | Public key | `MONGODB_ATLAS_PUBLIC_API_KEY` | | Private key | `MONGODB_ATLAS_PRIVATE_API_KEY` | *Thanks to [@joqim](https://github.com/joqim) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/198) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate DuckDB CLI Source: https://www.1password.dev/cli/shell-plugins/motherduck Store your credentials in 1Password then authenticate DuckDB CLI with your fingerprint. The MotherDuck shell plugin allows you to use 1Password to securely authenticate [DuckDB CLI](https://duckdb.org/docs/api/cli/overview) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext.Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate DuckDB CLI with biometrics.## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.42.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install DuckDB CLI.](https://duckdb.org/docs/api/cli/overview)
The following shells are supported:
  • Bash
  • Zsh
  • fish
## Step 1: Configure your default credentialsTo get started with the MotherDuck shell plugin:
  1. Sign in to the 1Password account you want to use with the MotherDuck plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init duckdb
You'll be prompted to import your MotherDuck credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used.### Step 1.1: Import or select an item#### Import a new itemIf you haven't saved your MotherDuck credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it.If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them.#### Select an existing itemIf you've already saved your MotherDuck credentials in 1Password, select **Search in 1Password**.You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account.### Step 1.2: Set default credential scopeAfter you select or import your credentials, you'll be prompted to configure when to use the item to authenticate MotherDuck.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh fileTo make the plugin available, source your `plugins.sh` file. For example:```shell theme={null} source ~/.config/op/plugins.sh ```The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path.If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example:```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``````shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``````shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ```## Step 3: Use the CLIThe next time you enter a command with MotherDuck, you'll be prompted to authenticate with biometrics or system authentication.1Password only provides your MotherDuck token when a `duckdb` command connects to MotherDuck, for example `duckdb md:` or `duckdb md:my_db`. Commands that only use local databases run without prompting you to authenticate. 1Password also doesn't provide the token if one is already set in the `motherduck_token` or `MOTHERDUCK_TOKEN` environment variable, or in the connection string.## Step 4: Remove imported credentials from diskAfter saving your MotherDuck credentials in 1Password, you can remove all local copies you previously had stored on disk.## Next steps1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs:```shell theme={null} op plugin list ```To choose another plugin to get started with:```shell theme={null} op plugin init ```To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/)## Get help### Inspect your configurationTo inspect your current MotherDuck configuration:op plugin inspect duckdb1Password CLI will return a list of the credentials you've configured to use with MotherDuck and their default scopes, as well as a list of aliases configured for MotherDuck.### Clear your credentialsTo reset the credentials used with MotherDuck:op plugin clear duckdbYou can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear duckdb` four times to clear all of your defaults.To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear duckdb --all`.## Reference 1Password authenticates with MotherDuck by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your MotherDuck credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. \ \ \
1Password field nameEnvironment variable
*Thanks to [@sterlinm](https://github.com/sterlinm) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/511) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use shell plugins to authenticate with multiple accounts Source: https://www.1password.dev/cli/shell-plugins/multiple-accounts You can configure [1Password Shell Plugins](/cli/shell-plugins/) to authenticate with different accounts in different directories, so you don't have to spend time signing in or out between projects. For example, you can set the GitHub shell plugin to authenticate with your work credentials in the directories for your work repositories and your personal credentials in the directories for your personal repositories. ## Step 1: Organize your directories by account Before you configure your shell plugins to use multiple accounts, group the project directories on your computer by the accounts they use. For example, if you have a personal and a work GitHub account, you might organize your personal and work GitHub repository folders like this: ``` github/ ├─ personal/ │ ├─ personal-repo-1 │ ├─ personal-repo-2 │ ├─ personal-repo-3 ├─ work/ │ ├─ work-repo-1 │ ├─ work-repo-2 ``` ## Step 2: Configure default credentials for each environment After you organize your projects under account-level directories, you can set default credentials for your shell plugin to use in each directory and all its subfolders. 1. Change directories to one of the account-level folders you created. For example: ```shell theme={null} cd projects/work ``` 2. Sign in to the 1Password account where the credentials you want to use are stored: ```shell theme={null} op signin ``` 3. Choose a plugin to initialize, or run `op plugin init` to choose from a list of all available plugins. For example, to initialize the GitHub plugin: ```shell theme={null} op plugin init gh ``` 4. Import or select the appropriate credentials to use with the account. 5. Select **Use automatically when in this directory or subdirectories** as the default credential scope. 6. Repeat the process in other account-level folders with their respective credentials. This will make the credentials you configure in each account-level folder the default for all subfolders within it, as long as no other directory-specific defaults are set in them. After you set defaults in all your account-level folders, use the shell plugin as you normally would across all your projects. When you use the plugin in a folder within the personal or work directories, the plugin will automatically authenticate with the appropriate credentials. ## Learn more * [Get started with 1Password Shell Plugins](/cli/shell-plugins/) * [Build your own shell plugins](/cli/shell-plugins/contribute/) # Use 1Password to securely authenticate the MySQL CLI Source: https://www.1password.dev/cli/shell-plugins/mysql The MySQL shell plugin allows you to use 1Password to securely authenticate [the MySQL CLI](https://dev.mysql.com/doc/refman/en/mysql.html) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the MySQL CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the MySQL CLI.](https://dev.mysql.com/doc/refman/en/installing.html) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the MySQL shell plugin:
  1. Sign in to the 1Password account you want to use with the MySQL plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init mysql
You'll be prompted to import your MySQL credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/mysql-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your MySQL credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/mysql-2.png) #### Select an existing item If you've already saved your MySQL credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/mysql-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate MySQL. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/mysql-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with MySQL, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/v5QMonLfC2BgFxf9/static/img/shell-plugins/mysql-5.png?fit=max\&auto=format\&n=v5QMonLfC2BgFxf9\&q=85\&s=b3b3c2a1b466b6bacca89b4c771a241d) ## Step 4: Remove imported credentials from disk After saving your MySQL credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current MySQL configuration: op plugin inspect mysql 1Password CLI will return a list of the credentials you've configured to use with MySQL and their default scopes, as well as a list of aliases configured for MySQL. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/v5QMonLfC2BgFxf9/static/img/shell-plugins/mysql-6.png?fit=max\&auto=format\&n=v5QMonLfC2BgFxf9\&q=85\&s=8b18004dde5b27a94739d33c4d5c037c) ### Clear your credentials To reset the credentials used with MySQL: op plugin clear mysql You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear mysql` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear mysql --all`. ## Reference If you saved your MySQL credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If your credentials are stored in a different field, you'll be prompted to select the field manually. Field names are case-insensitive. Field name tokens can be separated by whitespaces, underscores, dashes, or nothing. | 1Password field name | Parameter | | - | - | | Host (optional) | `host` | | Port (optional) | `port` | | User (optional) | `user` | | Password | `password` | | Database (optional) | `database` | ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate Netlify CLI Source: https://www.1password.dev/cli/shell-plugins/netlify Store your credentials in 1Password then authenticate Netlify CLI with your fingerprint. The Netlify shell plugin allows you to use 1Password to securely authenticate [Netlify CLI](https://cli.netlify.com) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext.Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Netlify CLI with biometrics.## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.42.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install Netlify CLI.](https://cli.netlify.com)
The following shells are supported:
  • Bash
  • Zsh
  • fish
## Step 1: Configure your default credentialsTo get started with the Netlify shell plugin:
  1. Sign in to the 1Password account you want to use with the Netlify plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init netlify
You'll be prompted to import your Netlify credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used.### Step 1.1: Import or select an item#### Import a new itemIf you haven't saved your Netlify credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it.If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them.#### Select an existing itemIf you've already saved your Netlify credentials in 1Password, select **Search in 1Password**.You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account.### Step 1.2: Set default credential scopeAfter you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Netlify.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh fileTo make the plugin available, source your `plugins.sh` file. For example:```shell theme={null} source ~/.config/op/plugins.sh ```The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path.If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example:```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``````shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``````shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ```## Step 3: Use the CLIThe next time you enter a command with Netlify, you'll be prompted to authenticate with biometrics or system authentication.## Step 4: Remove imported credentials from diskAfter saving your Netlify credentials in 1Password, you can remove all local copies you previously had stored on disk.## Next steps1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs:```shell theme={null} op plugin list ```To choose another plugin to get started with:```shell theme={null} op plugin init ```To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/)## Get help### Inspect your configurationTo inspect your current Netlify configuration:op plugin inspect netlify1Password CLI will return a list of the credentials you've configured to use with Netlify and their default scopes, as well as a list of aliases configured for Netlify.### Clear your credentialsTo reset the credentials used with Netlify:op plugin clear netlifyYou can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear netlify` four times to clear all of your defaults.To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear netlify --all`.## Reference 1Password authenticates with Netlify by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Netlify credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. \ \ \
1Password field nameEnvironment variable
*Thanks to [@eddumelendez](https://github.com/eddumelendez) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/627) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate ngrok Source: https://www.1password.dev/cli/shell-plugins/ngrok The ngrok shell plugin allows you to use 1Password to securely authenticate [the ngrok CLI](https://ngrok.com/docs/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate ngrok with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.14.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the ngrok CLI.](https://ngrok.com/docs/getting-started) The following shells are supported: * Bash * Zsh * Fish ## Step 1: Configure your default credentials To get started with the ngrok shell plugin:
  1. Sign in to the 1Password account you want to use with the ngrok plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init ngrok
You'll be prompted to import your ngrok credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/ngrok-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your ngrok credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/ngrok-2.png) #### Select an existing item If you've already saved your ngrok credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/ngrok-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate ngrok. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/ngrok-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
### Optional: Add an API key The ngrok shell plugin sets up authentication for the following ngrok commands by default: `http`, `service`, `start`, `tcp`, `tls`, and `tunnel`. To configure authentication for the `ngrok api` command, [add a custom field](https://support.1password.com/custom-fields/#add-a-custom-field) to your ngrok item titled `API Key` and save [your ngrok API key](https://dashboard.ngrok.com/api/keys) there. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: > [tab] Bash > > echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc > [tab] Zsh > > echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc > [tab] fish > > echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with ngrok, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/v5QMonLfC2BgFxf9/static/img/shell-plugins/ngrok-5.png?fit=max\&auto=format\&n=v5QMonLfC2BgFxf9\&q=85\&s=ec251cbda1b54e4d56c51c11a98b910a) ## Step 4: Remove imported credentials from disk After saving your ngrok credentials in 1Password, you can remove all local copies you previously had stored on disk. To find your ngrok configuration file location, run: ```shell theme={null} ngrok config check ``` To remove your credentials, run `rm` with the filepath for your configuration file. For example: > [tab] Mac > > rm "\~/Library/Application Support/ngrok/ngrok.yml" > [tab] Linux > > rm \~/.config/ngrok/ngrok.yml ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current ngrok configuration: op plugin inspect ngrok 1Password CLI will return a list of the credentials you've configured to use with ngrok and their default scopes, as well as a list of aliases configured for ngrok. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/v5QMonLfC2BgFxf9/static/img/shell-plugins/ngrok-6.png?fit=max\&auto=format\&n=v5QMonLfC2BgFxf9\&q=85\&s=11431674e8e0f964b8fbc45f980e38b2) ### Clear your credentials To reset the credentials used with ngrok: op plugin clear ngrok You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ngrok` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear ngrok --all`. ## Reference If you're using ngrok 3.2.1 or later, 1Password authenticates with ngrok by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you're using an earlier version of ngrok, 1Password authenticates by injecting a temporary file with the appropriate credentials. If you saved your ngrok credentials in 1Password manually rather than using `op plugin init` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | YAML config field | Environment variable | | - | - | - | | Auth Token | `authtoken` | `NGROK_AUTHTOKEN` | | API Key | `api_key` | `NGROK_API_KEY` | *Thanks to [@arunsathiya](https://github.com/arunsathiya) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/165) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Configure shell plugins using Nix Source: https://www.1password.dev/cli/shell-plugins/nix If you're using Nix to manage your shell configuration, you can configure 1Password Shell Plugins natively within your Nix configuration. 1. Add the 1Password Shell Plugins flake to your flake inputs: ```nix theme={null} { description = "My NixOS system flake"; inputs = { nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"; # import the 1Password Shell Plugins Flake _1password-shell-plugins.url = "github:1Password/shell-plugins"; # the rest of your flake inputs here }; outputs = inputs@{ nixpkgs, ... }: { # the rest of your flake here } } ``` 2. Somewhere in your flake output configuration, import and use the appropriate module: > [tab] NixOS without home-manager > > ```nix theme={null} > { > # import the NixOS module > imports = [ inputs._1password-shell-plugins.nixosModules.default ]; > programs._1password-shell-plugins = { > # enable 1Password shell plugins for bash, zsh, and fish shell > enable = true; > # the specified packages as well as 1Password CLI will be > # automatically installed and configured to use shell plugins > plugins = with pkgs; [ gh awscli2 cachix ]; > }; > # this can also be `programs.bash` or `programs.fish` > programs.zsh = { > enable = true; > # the rest of your shell configuration here > }; > } > ``` > [tab] Nix with home-manager > > ```nix theme={null} > { > # import the home-manager module > imports = [ inputs._1password-shell-plugins.hmModules.default ]; > programs._1password-shell-plugins = { > # enable 1Password shell plugins for bash, zsh, and fish shell > enable = true; > # the specified packages as well as 1Password CLI will be > # automatically installed and configured to use shell plugins > plugins = with pkgs; [ gh awscli2 cachix ]; > }; > # this can also be `programs.bash` or `programs.fish` > programs.zsh = { > enable = true; > # the rest of your shell configuration here > }; > } > ``` 3. Apply the updated configuration: > [tab] NixOS (including home-manager as a NixOS module) > > `~/path/to/flake/directory/` should be the path > to the directory containing your `flake.nix` file, and `my-computer` > should be the name of the flake output to use as the system configuration. > > ```shell theme={null} > sudo nixos-rebuild switch --flake "~/path/to/flake/directory/.#my-computer" > ``` > [tab] Nix with standalone home-manager > > `~/path/to/flake/directory/` should be the path > to the directory containing your `flake.nix` file, and `my-computer` > should be the name of the flake output to use as the system configuration. > > ```shell theme={null} > home-manager switch --flake "~/path/to/flake/directory/.#my-computer" > ``` # Use 1Password to securely authenticate npm and pnpm Source: https://www.1password.dev/cli/shell-plugins/npm Store your registry access token in 1Password then authenticate npm and pnpm with your fingerprint. The npm shell plugin allows you to use 1Password to securely authenticate [npm CLI](https://docs.npmjs.com/cli/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate npm CLI with biometrics. The npm shell plugin also works with [pnpm](https://pnpm.io/pnpm-cli). Both tools use the same access token item in 1Password. To set up the plugin for pnpm, follow the same steps with `pnpm` in place of `npm`, for example `op plugin init pnpm`. ## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.42.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install npm CLI.](https://docs.npmjs.com/cli/)
The following shells are supported:
  • Bash
  • Zsh
  • fish
To use the plugin with pnpm, also [install pnpm](https://pnpm.io/installation). ## Step 1: Configure your default credentials To get started with the npm shell plugin:
  1. Sign in to the 1Password account you want to use with the npm plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init npm
You'll be prompted to import your npm credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your npm credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. #### Select an existing item If you've already saved your npm credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate npm.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
To use pnpm, run `op plugin init pnpm` and select the same item. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: ```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` ```shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` ```shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with npm, you'll be prompted to authenticate with biometrics or system authentication. 1Password only provides your access token to commands that talk to a registry, such as `install`, `ci`, `publish`, and `view`. See the [full list of commands](#commands-that-use-your-access-token). ## Step 4: Remove imported credentials from disk After saving your npm credentials in 1Password, you can remove all local copies you previously had stored on disk. Access tokens are commonly stored in `~/.npmrc` as an `_authToken` line, or in pnpm's `auth.ini` file. If you remove them, make sure to configure shell plugins for any other tools that read those files. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: ```shell theme={null} op plugin list ``` To choose another plugin to get started with: ```shell theme={null} op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current npm configuration: op plugin inspect npm 1Password CLI will return a list of the credentials you've configured to use with npm and their default scopes, as well as a list of aliases configured for npm. ### Clear your credentials To reset the credentials used with npm: op plugin clear npm You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear npm` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear npm --all`. ## Reference 1Password authenticates npm and pnpm by injecting configuration environment variables with your access token directly from your 1Password account. Nothing is written to `.npmrc`. If you saved your access token in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Description | | - | - | | Token | The access token for your registry. | | Organization (optional) | A package scope, without the leading `@`. If set, the token and registry are only used for packages in that scope. | | Host (optional) | The host or URL of an npm-compatible registry. If you don't include a scheme, `https://` is used. Defaults to `https://registry.npmjs.org/`. | ### npm environment variables | Variable | Value | When it's set | | - | - | - | | `npm_config_///:_authToken` | Token | Always | | `npm_config_@:registry` | Registry URL | When Organization is set | | `npm_config_registry` | Registry URL | When Host is set and Organization isn't | ### pnpm environment variables | Variable | Value | | - | - | | `PNPM_CONFIG__AUTH` | The registry URL and token as JSON, scoped to `@` if Organization is set | ### Commands that use your access token 1Password provides your access token to these npm and pnpm commands: `access`, `add`, `audit`, `ci`, `cit`, `deprecate`, `dist-tag`, `exec`, `fetch`, `i`, `install`, `install-ci-test`, `install-test`, `it`, `owner`, `pack`, `profile`, `publish`, `search`, `stage`, `team`, `token`, `unpublish`, `update`, `view`, `whoami` *Thanks to [@dalldrit13](https://github.com/dalldrit13) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/658) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate Octopus CLI Source: https://www.1password.dev/cli/shell-plugins/octopus-deploy Store your credentials in 1Password then authenticate Octopus CLI with your fingerprint. The Octopus Deploy shell plugin allows you to use 1Password to securely authenticate [Octopus CLI](https://github.com/OctopusDeploy/cli/blob/main/README.md) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext.Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Octopus CLI with biometrics.## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.42.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install Octopus CLI.](https://github.com/OctopusDeploy/cli/blob/main/README.md)
The following shells are supported:
  • Bash
  • Zsh
  • fish
## Step 1: Configure your default credentialsTo get started with the Octopus Deploy shell plugin:
  1. Sign in to the 1Password account you want to use with the Octopus Deploy plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init octopus
You'll be prompted to import your Octopus Deploy credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used.### Step 1.1: Import or select an item#### Import a new itemIf you haven't saved your Octopus Deploy credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it.If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them.#### Select an existing itemIf you've already saved your Octopus Deploy credentials in 1Password, select **Search in 1Password**.You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account.### Step 1.2: Set default credential scopeAfter you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Octopus Deploy.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh fileTo make the plugin available, source your `plugins.sh` file. For example:```shell theme={null} source ~/.config/op/plugins.sh ```The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path.If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example:```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``````shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``````shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ```## Step 3: Use the CLIThe next time you enter a command with Octopus Deploy, you'll be prompted to authenticate with biometrics or system authentication.## Step 4: Remove imported credentials from diskAfter saving your Octopus Deploy credentials in 1Password, you can remove all local copies you previously had stored on disk.## Next steps1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs:```shell theme={null} op plugin list ```To choose another plugin to get started with:```shell theme={null} op plugin init ```To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/)## Get help### Inspect your configurationTo inspect your current Octopus Deploy configuration:op plugin inspect octopus1Password CLI will return a list of the credentials you've configured to use with Octopus Deploy and their default scopes, as well as a list of aliases configured for Octopus Deploy.### Clear your credentialsTo reset the credentials used with Octopus Deploy:op plugin clear octopusYou can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear octopus` four times to clear all of your defaults.To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear octopus --all`.## Reference 1Password authenticates with Octopus Deploy by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Octopus Deploy credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. \ \ \
1Password field nameEnvironment variable
*Thanks to [@xcezx](https://github.com/xcezx) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/623) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate Oh Dear CLI Source: https://www.1password.dev/cli/shell-plugins/oh-dear The Oh Dear CLI shell plugin allows you to use 1Password to securely authenticate [Oh Dear CLI](https://github.com/ohdearapp/ohdear-cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Oh Dear CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.19.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. [Install Oh Dear CLI.](https://github.com/ohdearapp/ohdear-cli) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Oh Dear CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the Oh Dear CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init ohdear
You'll be prompted to import your Oh Dear CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/ohdear-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Oh Dear CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/ohdear-2.png) #### Select an existing item If you've already saved your Oh Dear CLI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/ohdear-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Oh Dear CLI. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/ohdear-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Oh Dear CLI, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/v5QMonLfC2BgFxf9/static/img/shell-plugins/ohdear-5.png?fit=max\&auto=format\&n=v5QMonLfC2BgFxf9\&q=85\&s=97bec7b058d6919583ba185ceababb78) ## Step 4: Remove imported credentials from disk After saving your Oh Dear CLI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Oh Dear CLI configuration: op plugin inspect ohdear 1Password CLI will return a list of the credentials you've configured to use with Oh Dear CLI and their default scopes, as well as a list of aliases configured for Oh Dear CLI. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/v5QMonLfC2BgFxf9/static/img/shell-plugins/ohdear-6.png?fit=max\&auto=format\&n=v5QMonLfC2BgFxf9\&q=85\&s=9855c942312afcf4fef7b5020a480592) ### Clear your credentials To reset the credentials used with Oh Dear CLI: op plugin clear ohdear You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ohdear` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear ohdear --all`. ## Reference 1Password authenticates with Oh Dear CLI by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Oh Dear CLI credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | Token | `OHDEAR_API_TOKEN` | *Thanks to [@owenvoke](https://github.com/owenvoke) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/269) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate the Okta CLI Source: https://www.1password.dev/cli/shell-plugins/okta The Okta shell plugin allows you to use 1Password to securely authenticate [the Okta CLI](https://cli.okta.com/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Okta CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Okta CLI.](https://cli.okta.com/manual/#installation) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Okta shell plugin:
  1. Sign in to the 1Password account you want to use with the Okta plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init okta
You'll be prompted to import your Okta credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/okta-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Okta credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/okta-2.png) #### Select an existing item If you've already saved your Okta credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/okta-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Okta. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/okta-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Okta, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/v5QMonLfC2BgFxf9/static/img/shell-plugins/okta-5.png?fit=max\&auto=format\&n=v5QMonLfC2BgFxf9\&q=85\&s=5fa897d318d1f340fbbab769f3e9eb08) ## Step 4: Remove imported credentials from disk After saving your Okta credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Okta configuration: op plugin inspect okta 1Password CLI will return a list of the credentials you've configured to use with Okta and their default scopes, as well as a list of aliases configured for Okta. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/v5QMonLfC2BgFxf9/static/img/shell-plugins/okta-6.png?fit=max\&auto=format\&n=v5QMonLfC2BgFxf9\&q=85\&s=8f17eb077fdbc133abc2e9a1ca99ffbb) ### Clear your credentials To reset the credentials used with Okta: op plugin clear okta You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear okta` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear okta --all`. ## Reference 1Password authenticates with Okta by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Okta credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variables | | - | - | | Token | `OKTA_CLIENT_TOKEN` | | Org URL | `OKTA_CLIENT_ORGURL` | ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate the OpenAI CLI Source: https://www.1password.dev/cli/shell-plugins/openai The OpenAI shell plugin allows you to use 1Password to securely authenticate [the OpenAI CLI](https://pypi.org/project/openai/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the OpenAI CLI with biometrics. > [!TIP] > > You can also use 1Password Shell Plugins to authenticate [OpenAI Evals](/cli/shell-plugins/openai-evals). ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.13.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the OpenAI CLI.](https://pypi.org/project/openai/) The following shells are supported: * Bash * Zsh * fish ## Before you begin: Create and save an OpenAI API key If you've already created an OpenAI API key, [skip to Step 1](#step-1-configure-your-default-credentials). If you haven't created an API key yet, you can create one and use the [1Password browser extension](https://support.1password.com/getting-started-browser/) to quickly save it in 1Password: 1. Open and unlock [1Password in your browser](https://support.1password.com/getting-started-browser/). 2. [Follow the steps](https://platform.openai.com/account/api-keys) to create an OpenAI API key. 3. Select **Save item** when 1Password asks if you want to save an item for the OpenAI API key. 4. Choose the vault where you want to save the item, edit the item's name and details, then select **Save item**. ![The prompt to save your OpenAI API key in 1Password.](https://mintcdn.com/ab-634991b8/v5QMonLfC2BgFxf9/static/img/shell-plugins/openai-save.png?fit=max\&auto=format\&n=v5QMonLfC2BgFxf9\&q=85\&s=0b2fbe9f11cc4ef8365e984b0432fdba) ## Step 1: Configure your default credentials To get started with the OpenAI shell plugin:
  1. Sign in to the 1Password account you want to use with the OpenAI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init openai
You'll be prompted to import your OpenAI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/openai-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your OpenAI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/openai-2.png) #### Select an existing item If you've already saved your OpenAI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/openai-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate OpenAI. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/openai-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with OpenAI, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/v5QMonLfC2BgFxf9/static/img/shell-plugins/openai-5.png?fit=max\&auto=format\&n=v5QMonLfC2BgFxf9\&q=85\&s=851d38015b0d0156bf02f0cacd1baf0f) ## Step 4: Remove imported credentials from disk After saving your OpenAI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current OpenAI configuration: op plugin inspect openai 1Password CLI will return a list of the credentials you've configured to use with OpenAI and their default scopes, as well as a list of aliases configured for OpenAI. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/v5QMonLfC2BgFxf9/static/img/shell-plugins/openai-6.png?fit=max\&auto=format\&n=v5QMonLfC2BgFxf9\&q=85\&s=4d96037251a3c3089596e1e32db0bdcb) ### Clear your credentials To reset the credentials used with OpenAI: op plugin clear openai You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear openai` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear openai --all`. ## Reference 1Password authenticates with OpenAI by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your OpenAI credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | API Key | `OPENAI_API_KEY` | *Thanks to [@jodyheavener](https://github.com/jodyheavener) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/152) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate Codex CLI Source: https://www.1password.dev/cli/shell-plugins/openai-codex The OpenAI Codex CLI shell plugin allows you to use 1Password to securely authenticate [Codex CLI](https://help.openai.com/en/articles/11096431-openai-codex-cli-getting-started) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Codex CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.34.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/). 5. [Install Codex CLI.](https://help.openai.com/en/articles/11096431-openai-codex-cli-getting-started) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Codex CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the Codex CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init codex
You'll be prompted to import your Codex CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Codex CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. #### Select an existing item If you've already saved your Codex CLI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Codex CLI.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Codex CLI, you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your Codex CLI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Codex CLI configuration: op plugin inspect codex 1Password CLI will return a list of the credentials you've configured to use with Codex CLI and their default scopes, as well as a list of aliases configured for Codex CLI. ### Clear your credentials To reset the credentials used with Codex CLI: op plugin clear codex You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear codex` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear codex --all`. ## Reference 1Password authenticates with Codex CLI by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Codex CLI credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | API Key | `OPENAI_API_KEY` | *Thanks to [@shyim](https://github.com/shyim) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/517) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* # Use 1Password to securely authenticate OpenAI Evals Source: https://www.1password.dev/cli/shell-plugins/openai-evals The OpenAI Evals shell plugins allow you to use 1Password to securely authenticate [`oaieval` and `oaievalset`](https://github.com/openai/evals/blob/main/docs/run-evals.md) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials for each CLI and source the `plugins.sh` file, then you'll be prompted to authenticate OpenAI Evals with biometrics. > [!TIP] > > You can also use 1Password Shell Plugins to authenticate [OpenAI](/cli/shell-plugins/openai). ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.19.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/). 5. [Install OpenAI Evals.](https://github.com/openai/evals/blob/main/docs/run-evals.md) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your oaieval credentials To get started with the oaieval shell plugin:
  1. Sign in to the 1Password account you want to use with the oaieval plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init oaieval
You'll be prompted to import your oaieval credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your oaieval credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. #### Select an existing item If you've already saved your oaieval credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate oaieval.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Configure your oaievalset credentials To get started with the oaievalset shell plugin:
  1. Sign in to the 1Password account you want to use with the oaievalset plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init oaievalset
You'll be prompted to import your oaievalset credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your oaievalset credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. #### Select an existing item If you've already saved your oaievalset credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate oaievalset.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 3: Source the plugins.sh file echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 4: Use the CLI The next time you enter a command with oaieval or oaievalset, you'll be prompted to authenticate with biometrics or system authentication. ## Step 5: Remove imported credentials from disk After saving your OpenAI Evals credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current OpenAI Evals configuration: op plugin inspect \ 1Password CLI will return a list of the credentials you've configured to use with OpenAI Evals and their default scopes, as well as a list of aliases configured for OpenAI Evals. ### Clear your credentials To reset the credentials used with OpenAI Evals: op plugin clear \ You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference 1Password authenticates with OpenAI Evals by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your OpenAI Evals credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | API Key | `OPENAI_API_KEY` | *Thanks to [@arunsathiya](https://github.com/arunsathiya) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/208) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate OpenBao CLI Source: https://www.1password.dev/cli/shell-plugins/openbao Store your credentials in 1Password then authenticate OpenBao CLI with your fingerprint. The OpenBao shell plugin allows you to use 1Password to securely authenticate [OpenBao CLI](https://openbao.org/docs/commands/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext.Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate OpenBao CLI with biometrics.## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.42.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install OpenBao CLI.](https://openbao.org/docs/commands/)
The following shells are supported:
  • Bash
  • Zsh
  • fish
## Step 1: Configure your default credentialsTo get started with the OpenBao shell plugin:
  1. Sign in to the 1Password account you want to use with the OpenBao plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init bao
You'll be prompted to import your OpenBao credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used.### Step 1.1: Import or select an item#### Import a new itemIf you haven't saved your OpenBao credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it.If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them.#### Select an existing itemIf you've already saved your OpenBao credentials in 1Password, select **Search in 1Password**.You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account.### Step 1.2: Set default credential scopeAfter you select or import your credentials, you'll be prompted to configure when to use the item to authenticate OpenBao.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh fileTo make the plugin available, source your `plugins.sh` file. For example:```shell theme={null} source ~/.config/op/plugins.sh ```The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path.If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example:```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``````shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``````shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ```## Step 3: Use the CLIThe next time you enter a command with OpenBao, you'll be prompted to authenticate with biometrics or system authentication.## Step 4: Remove imported credentials from diskAfter saving your OpenBao credentials in 1Password, you can remove all local copies you previously had stored on disk.## Next steps1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs:```shell theme={null} op plugin list ```To choose another plugin to get started with:```shell theme={null} op plugin init ```To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/)## Get help### Inspect your configurationTo inspect your current OpenBao configuration:op plugin inspect bao1Password CLI will return a list of the credentials you've configured to use with OpenBao and their default scopes, as well as a list of aliases configured for OpenBao.### Clear your credentialsTo reset the credentials used with OpenBao:op plugin clear baoYou can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear bao` four times to clear all of your defaults.To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear bao --all`.## Reference 1Password authenticates with OpenBao by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your OpenBao credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. \ \ \
1Password field nameEnvironment variable
*Thanks to [@gaige](https://github.com/gaige) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/576) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate OpenCode CLI Source: https://www.1password.dev/cli/shell-plugins/opencode Store your credentials in 1Password then authenticate OpenCode CLI with your fingerprint. The OpenCode shell plugin allows you to use 1Password to securely authenticate [OpenCode CLI](https://opencode.ai/docs/cli/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext.Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate OpenCode CLI with biometrics.## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.35.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install OpenCode CLI.](https://opencode.ai/docs/cli/)
The following shells are supported:
  • Bash
  • Zsh
  • fish
## Step 1: Configure your default credentialsTo get started with the OpenCode shell plugin:
  1. Sign in to the 1Password account you want to use with the OpenCode plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init opencode
You'll be prompted to import your OpenCode credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used.### Step 1.1: Import or select an item#### Import a new itemIf you haven't saved your OpenCode credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it.If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them.#### Select an existing itemIf you've already saved your OpenCode credentials in 1Password, select **Search in 1Password**.You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account.### Step 1.2: Set default credential scopeAfter you select or import your credentials, you'll be prompted to configure when to use the item to authenticate OpenCode.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh fileTo make the plugin available, source your `plugins.sh` file. For example:```shell theme={null} source ~/.config/op/plugins.sh ```The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path.If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example:```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``````shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``````shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ```## Step 3: Use the CLIThe next time you enter a command with OpenCode, you'll be prompted to authenticate with biometrics or system authentication.## Step 4: Remove imported credentials from diskAfter saving your OpenCode credentials in 1Password, you can remove all local copies you previously had stored on disk.## Next steps1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs:```shell theme={null} op plugin list ```To choose another plugin to get started with:```shell theme={null} op plugin init ```To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/)## Get help### Inspect your configurationTo inspect your current OpenCode configuration:op plugin inspect opencode1Password CLI will return a list of the credentials you've configured to use with OpenCode and their default scopes, as well as a list of aliases configured for OpenCode.### Clear your credentialsTo reset the credentials used with OpenCode:op plugin clear opencodeYou can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear opencode` four times to clear all of your defaults.To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear opencode --all`.## Reference 1Password authenticates with OpenCode by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your OpenCode credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. \ \ \
1Password field nameEnvironment variable
*Thanks to [@eddumelendez](https://github.com/eddumelendez) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/613) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate OpenTofu CLI Source: https://www.1password.dev/cli/shell-plugins/opentofu Store your credentials in 1Password then authenticate OpenTofu CLI with your fingerprint. The OpenTofu shell plugin allows you to use 1Password to securely authenticate [OpenTofu CLI](https://opentofu.org/docs/cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. You can configure the OpenTofu plugin to provision credentials from the [1Password Shell Plugin ecosystem](/cli/shell-plugins#get-started) for use with providers such as AWS, MongoDB Atlas, or Databricks. ## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.35.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install OpenTofu CLI.](https://opentofu.org/docs/cli)
The following shells are supported:
  • Bash
  • Zsh
  • fish
## Step 1: Configure your default credentials To get started with the OpenTofu shell plugin:
  1. Sign in to the 1Password account you want to use with the OpenTofu plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init tofu
You'll be prompted to select the credential types you want to use with OpenTofu. Select the credential type for [a supported provider](/cli/shell-plugins#get-started), then you can either [import the credential](#import-a-new-item) into your 1Password account or [select an existing 1Password item](#select-an-existing-item) where the credential is saved. When you've configured all the credentials you want to use with OpenTofu, select **Stop choosing credentials**. ### Step 1.1: Import or select an item #### Import a new item If you haven't saved a credential in 1Password yet, select **Import into 1Password**. Enter a name for the new 1Password item and select the vault where you want to save it. If 1Password detects the credential in your local development environment, you'll be automatically prompted to import it. #### Select an existing item If you've already saved a credential in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see the credential, select **Expand search** to browse all items in your account. ### Step 1.2: Set default credential scope After you finish selecting your credentials, you'll be prompted to configure when to use them.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the defaults will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the defaults in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: ```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` ```shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` ```shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you use OpenTofu CLI with one of the providers you configured credentials for, you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your OpenTofu credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: ```shell theme={null} op plugin list ``` To choose another plugin to get started with: ```shell theme={null} op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current OpenTofu configuration: op plugin inspect tofu 1Password CLI will return a list of the credentials you've configured to use with OpenTofu and their default scopes, as well as a list of aliases configured for OpenTofu. ### Clear your credentials To reset the credentials used with OpenTofu: op plugin clear tofu You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear tofu` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear tofu --all`. ## Reference Unlike most shell plugins, OpenTofu doesn't define its own set of credentials. Instead, it can provision any of the credentials you've already configured in 1Password for your other shell plugins, so you can use them within your OpenTofu project. When you run `op plugin init tofu`, you choose which of your saved 1Password items to use, and 1Password provisions them automatically when you run OpenTofu commands that need them. 1Password provides credentials to the following OpenTofu commands: * `apply` * `destroy` * `import` * `init` * `plan` * `refresh` * `state` * `test` * `workspace` *Thanks to [@ianneub](https://github.com/ianneub) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/585) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate Pipedream CLI Source: https://www.1password.dev/cli/shell-plugins/pipedream The Pipedream CLI shell plugin allows you to use 1Password to securely authenticate [Pipedream CLI](https://pipedream.com/docs/cli/install/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Pipedream CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.22.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/). 5. [Install Pipedream CLI.](https://pipedream.com/docs/cli/install/) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Pipedream CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the Pipedream CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init pd
You'll be prompted to import your Pipedream CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Pipedream CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. #### Select an existing item If you've already saved your Pipedream CLI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Pipedream CLI.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Pipedream CLI, you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your Pipedream CLI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Pipedream CLI configuration: op plugin inspect pd 1Password CLI will return a list of the credentials you've configured to use with Pipedream CLI and their default scopes, as well as a list of aliases configured for Pipedream CLI. ### Clear your credentials To reset the credentials used with Pipedream CLI: op plugin clear pd You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear pd` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear pd --all`. ## Reference 1Password authenticates with Pipedream by injecting a temporary config file with the credentials required by the plugin commands directly from your 1Password account. If you saved your Pipedream credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Config file field | | - | - | | API Key | api\_key | | Org ID (optional) | org\_id | *Thanks to [@rajapri28613](https://github.com/rajapri28613) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/338) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate the PostgreSQL CLI Source: https://www.1password.dev/cli/shell-plugins/postgresql The PostgreSQL shell plugin allows you to use 1Password to securely authenticate [psql](https://www.postgresguide.com/utilities/psql/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate psql with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [psql.](https://www.postgresql.org/docs/current/app-psql.html) The following shells are supported: * Bash * Zsh * fish ## Additional executables You can also use the PostgreSQL shell plugin with: * [`pg_dump`](https://www.postgresql.org/docs/current/app-pgdump.html) * [`pg_restore`](https://www.postgresql.org/docs/current/app-pgrestore.html) * [`pgcli`](https://www.pgcli.com/) Run `op plugin init ` with the executable you want to configure, then follow the steps to select your credentials. ## Step 1: Configure your default credentials To get started with the PostgreSQL shell plugin:
  1. Sign in to the 1Password account you want to use with the PostgreSQL plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init psql
You'll be prompted to import your PostgreSQL credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/psql-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your PostgreSQL credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/psql-2.png) #### Select an existing item If you've already saved your PostgreSQL credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/psql-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate PostgreSQL. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/psql-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with PostgreSQL, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/v5QMonLfC2BgFxf9/static/img/shell-plugins/psql-5.png?fit=max\&auto=format\&n=v5QMonLfC2BgFxf9\&q=85\&s=77cad58dc9af8bc3643643dffe83a7f8) ## Step 4: Remove imported credentials from disk After saving your PostgreSQL credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current PostgreSQL configuration: op plugin inspect psql 1Password CLI will return a list of the credentials you've configured to use with PostgreSQL and their default scopes, as well as a list of aliases configured for PostgreSQL. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/v5QMonLfC2BgFxf9/static/img/shell-plugins/psql-6.png?fit=max\&auto=format\&n=v5QMonLfC2BgFxf9\&q=85\&s=03c3b66d8d3926c3e51e494c04dcf069) ### Clear your credentials To reset the credentials used with PostgreSQL: op plugin clear psql You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear psql` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear psql --all`. ## Reference 1Password authenticates with PostgreSQL by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your PostgreSQL credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variables | | - | - | | Server | `PGHOST` | | Port (optional) | `PGPORT` | | Username | `PGUSER` | | Password (optional) | `PGPASSWORD` | | Database (optional) | `PGDATABASE` | ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate the Postman CLI Source: https://www.1password.dev/cli/shell-plugins/postman Store your credentials in 1Password then authenticate the Postman CLI with your fingerprint. The Postman shell plugin allows you to use 1Password to securely authenticate [Postman CLI](https://learning.postman.com/docs/postman-cli/postman-cli-overview/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext.Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Postman CLI with biometrics.## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.42.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install Postman CLI.](https://learning.postman.com/docs/postman-cli/postman-cli-overview/)
The following shells are supported:
  • Bash
  • Zsh
  • fish
## Step 1: Configure your default credentialsTo get started with the Postman shell plugin:
  1. Sign in to the 1Password account you want to use with the Postman plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init postman
You'll be prompted to import your Postman credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used.### Step 1.1: Import or select an item#### Import a new itemIf you haven't saved your Postman credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it.If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them.#### Select an existing itemIf you've already saved your Postman credentials in 1Password, select **Search in 1Password**.You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account.### Step 1.2: Set default credential scopeAfter you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Postman.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh fileTo make the plugin available, source your `plugins.sh` file. For example:```shell theme={null} source ~/.config/op/plugins.sh ```The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path.If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example:```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``````shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``````shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ```## Step 3: Use the CLIThe next time you enter a command with Postman, you'll be prompted to authenticate with biometrics or system authentication.## Step 4: Remove imported credentials from diskAfter saving your Postman credentials in 1Password, you can remove all local copies you previously had stored on disk.## Next steps1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs:```shell theme={null} op plugin list ```To choose another plugin to get started with:```shell theme={null} op plugin init ```To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/)## Get help### Inspect your configurationTo inspect your current Postman configuration:op plugin inspect postman1Password CLI will return a list of the credentials you've configured to use with Postman and their default scopes, as well as a list of aliases configured for Postman.### Clear your credentialsTo reset the credentials used with Postman:op plugin clear postmanYou can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear postman` four times to clear all of your defaults.To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear postman --all`.## Reference 1Password authenticates with Postman by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Postman credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. \ \ \
1Password field nameEnvironment variable
*Thanks to [@ericflores108](https://github.com/ericflores108) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/448) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate the Pulumi CLI Source: https://www.1password.dev/cli/shell-plugins/pulumi The Pulumi CLI shell plugin allows you to use 1Password to securely authenticate [the Pulumi CLI](https://www.pulumi.com/docs/reference/cli/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Pulumi CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.17.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Pulumi CLI.](https://www.pulumi.com/docs/get-started/install/) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Pulumi CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the Pulumi CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init pulumi
You'll be prompted to import your Pulumi CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/pulumi-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Pulumi CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/pulumi-2.png) #### Select an existing item If you've already saved your Pulumi CLI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/pulumi-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Pulumi CLI. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/pulumi-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Pulumi CLI, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/v5QMonLfC2BgFxf9/static/img/shell-plugins/pulumi-5.png?fit=max\&auto=format\&n=v5QMonLfC2BgFxf9\&q=85\&s=076015fc4890cbafead1ca52bf0c52eb) ## Step 4: Remove imported credentials from disk After saving your Pulumi CLI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Pulumi CLI configuration: op plugin inspect pulumi 1Password CLI will return a list of the credentials you've configured to use with Pulumi CLI and their default scopes, as well as a list of aliases configured for Pulumi CLI. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/v5QMonLfC2BgFxf9/static/img/shell-plugins/pulumi-6.png?fit=max\&auto=format\&n=v5QMonLfC2BgFxf9\&q=85\&s=37d7e74c19518b0e697a0fff71a3c73c) ### Clear your credentials To reset the credentials used with Pulumi CLI: op plugin clear pulumi You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear pulumi` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear pulumi --all`. ## Reference 1Password authenticates with Pulumi CLI by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Pulumi CLI credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | Token | `PULUMI_ACCESS_TOKEN` | | Host (optional) | `PULUMI_BACKEND_URL` | *Thanks to [@ringods](https://github.com/ringods) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/199) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate PyPI publishing tools Source: https://www.1password.dev/cli/shell-plugins/pypi Store your PyPI API token in 1Password, then authenticate Twine, Flit, and Hatch with your fingerprint. The PyPI shell plugin allows you to use 1Password to securely authenticate [Twine, Flit, or Hatch](https://pypi.org) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Twine, Flit, or Hatch with biometrics. ## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.35.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install Twine, Flit, or Hatch.](https://pypi.org)
The following shells are supported:
  • Bash
  • Zsh
  • fish
## Supported tools The PyPI shell plugin works with the following tools. Configure each one separately by running `op plugin init` with the tool you want to use: * [Twine](https://twine.readthedocs.io) ```shell theme={null} op plugin init twine ``` * [Flit](https://flit.pypa.io) ```shell theme={null} op plugin init flit ``` * [Hatch](https://hatch.pypa.io) ```shell theme={null} op plugin init hatch ``` ## Step 1: Configure your default credentials To get started with the PyPI shell plugin:
  1. Sign in to the 1Password account you want to use with the PyPI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init \
You'll be prompted to import your PyPI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your PyPI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. #### Select an existing item If you've already saved your PyPI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate PyPI.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: ```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``` ```shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``` ```shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ``` ## Step 3: Use the CLI The next time you enter a command with the shell plugin you set up, you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your PyPI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: ```shell theme={null} op plugin list ``` To choose another plugin to get started with: ```shell theme={null} op plugin init ``` To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current PyPI configuration: op plugin inspect \ 1Password CLI will return a list of the credentials you've configured to use with PyPI and their default scopes, as well as a list of aliases configured for PyPI. ### Clear your credentials To reset the credentials used with PyPI: op plugin clear \ You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear --all`. ## Reference The PyPI shell plugin uses a single API token stored in 1Password to authenticate each of its tools, injecting it into that tool's environment variable. If you saved your API token in 1Password manually rather than using `op plugin` to import a new item, make sure your field name matches the tables below. *Thanks to [@cpierce](https://github.com/cpierce) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/589) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate the ReadMe CLI Source: https://www.1password.dev/cli/shell-plugins/readme The ReadMe shell plugin allows you to use 1Password to securely authenticate [the ReadMe CLI](https://docs.readme.com/main/docs/rdme) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the ReadMe CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.12.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the ReadMe CLI.](https://github.com/readmeio/rdme#setup) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the ReadMe shell plugin:
  1. Sign in to the 1Password account you want to use with the ReadMe plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init rdme
You'll be prompted to import your ReadMe credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/readme-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your ReadMe credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/readme-2.png) #### Select an existing item If you've already saved your ReadMe credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/readme-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate ReadMe. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/readme-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with ReadMe, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/v5QMonLfC2BgFxf9/static/img/shell-plugins/readme-5.png?fit=max\&auto=format\&n=v5QMonLfC2BgFxf9\&q=85\&s=3dd59eee8de90b7e5fb0d4b7646f1649) ## Step 4: Remove imported credentials from disk After saving your ReadMe credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current ReadMe configuration: op plugin inspect rdme 1Password CLI will return a list of the credentials you've configured to use with ReadMe and their default scopes, as well as a list of aliases configured for ReadMe. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/v5QMonLfC2BgFxf9/static/img/shell-plugins/readme-6.png?fit=max\&auto=format\&n=v5QMonLfC2BgFxf9\&q=85\&s=0b831e20db7b10f4d84ad1045976ef8e) ### Clear your credentials To reset the credentials used with ReadMe: op plugin clear rdme You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear rdme` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear rdme --all`. ## Reference 1Password authenticates with ReadMe by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your ReadMe credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variable | | - | - | | API Key | `RDME_API_KEY` | | Username (Optional) | `RDME_EMAIL` | | Website (Optional) | `RDME_PROJECT` | *Thanks to [@kanadgupta](https://github.com/kanadgupta) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/106) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate Redis CLI Source: https://www.1password.dev/cli/shell-plugins/redis Store your credentials in 1Password then authenticate Redis CLI with your fingerprint. The Redis shell plugin allows you to use 1Password to securely authenticate [Redis CLI](https://redis.io/docs/latest/develop/tools/cli/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext.Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Redis CLI with biometrics.## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.35.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install Redis CLI.](https://redis.io/docs/latest/develop/tools/cli/)
The following shells are supported:
  • Bash
  • Zsh
  • fish
## Step 1: Configure your default credentialsTo get started with the Redis shell plugin:
  1. Sign in to the 1Password account you want to use with the Redis plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init redis-cli
You'll be prompted to import your Redis credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used.### Step 1.1: Import or select an item#### Import a new itemIf you haven't saved your Redis credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it.If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them.#### Select an existing itemIf you've already saved your Redis credentials in 1Password, select **Search in 1Password**.You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account.### Step 1.2: Set default credential scopeAfter you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Redis.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh fileTo make the plugin available, source your `plugins.sh` file. For example:```shell theme={null} source ~/.config/op/plugins.sh ```The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path.If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example:```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``````shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``````shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ```## Step 3: Use the CLIThe next time you enter a command with Redis, you'll be prompted to authenticate with biometrics or system authentication.## Step 4: Remove imported credentials from diskAfter saving your Redis credentials in 1Password, you can remove all local copies you previously had stored on disk.## Next steps1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs:```shell theme={null} op plugin list ```To choose another plugin to get started with:```shell theme={null} op plugin init ```To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/)## Get help### Inspect your configurationTo inspect your current Redis configuration:op plugin inspect redis-cli1Password CLI will return a list of the credentials you've configured to use with Redis and their default scopes, as well as a list of aliases configured for Redis.### Clear your credentialsTo reset the credentials used with Redis:op plugin clear redis-cliYou can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear redis-cli` four times to clear all of your defaults.To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear redis-cli --all`.## Reference 1Password authenticates with Redis by injecting the credentials required by the plugin commands directly from your 1Password account as environment variables or command-line flags. If you saved your Redis credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. \ \ \
1Password field nameProvisioned as
*Thanks to [@arunsathiya](https://github.com/arunsathiya) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/276) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate the Scaleway CLI Source: https://www.1password.dev/cli/shell-plugins/scaleway The Scaleway shell plugin lets you use 1Password to authenticate the [Scaleway CLI (`scw`)](https://www.scaleway.com/en/cli/) with your fingerprint, Apple Watch, or system authentication, instead of storing API keys in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Scaleway CLI with biometrics. > [!TIP] > > The plugin applies to the Scaleway CLI’s **default** configuration. It does not support separate [CLI profiles.](https://github.com/scaleway/scaleway-cli/blob/master/docs/commands/config.md) ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.34.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install and configure the [Scaleway CLI.](https://www.scaleway.com/en/docs/developer-tools/scaleway-cli/quickstart/) The following shells are supported: * Bash * Zsh * fish ## Before you begin: Create a Scaleway API key If you already have a Scaleway API key, [skip to step 1](#step-1-configure-your-default-credentials). Otherwise, create an API key in the [Scaleway console](https://console.scaleway.com/iam/api-keys) and save the **access key** and **secret key** in 1Password. See Scaleway’s guide to [creating API keys.](https://www.scaleway.com/en/docs/iam/how-to/create-api-keys/) ## Step 1: Configure your default credentials To get started with the Scaleway CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the Scaleway CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init scw
You'll be prompted to import your Scaleway CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Scaleway CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. #### Select an existing item If you've already saved your Scaleway CLI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Scaleway CLI.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Scaleway CLI, you'll be prompted to authenticate with biometrics or system authentication. For example, after configuring the plugin, try: ```shell theme={null} scw account project list ``` ## Step 4: Remove imported credentials from disk After saving your Scaleway CLI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Scaleway CLI configuration: op plugin inspect scw 1Password CLI will return a list of the credentials you've configured to use with Scaleway CLI and their default scopes, as well as a list of aliases configured for Scaleway CLI. ### Clear your credentials To reset the credentials used with Scaleway CLI: op plugin clear scw You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear scw` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear scw --all`. ## Reference 1Password authenticates with Scaleway by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Scaleway credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variable | | - | - | | Access key | `SCW_ACCESS_KEY` | | Secret key | `SCW_SECRET_KEY` | | Default region (optional) | `SCW_DEFAULT_REGION` | | Default zone (optional) | `SCW_DEFAULT_ZONE` | | Project ID (optional) | `SCW_DEFAULT_PROJECT_ID` | | Organization ID (optional) | `SCW_DEFAULT_ORGANIZATION_ID` | *Thanks to [@jksolbakken](https://github.com/jksolbakken) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/515) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# About 1Password Shell Plugins security Source: https://www.1password.dev/cli/shell-plugins/security ## Authorization model To get your consent when a 1Password CLI command or 1Password Shell Plugin is invoked, 1Password will present you with an approval dialog: ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/Ul-COtb5ywadNlrP/static/img/shell-plugins/aws-5.png?fit=max\&auto=format\&n=Ul-COtb5ywadNlrP\&q=85\&s=29e1785425ad21c02080c96aaad2ee55) This dialog will show which application is requesting permission to use which 1Password account. After you approve the request, a *session* will be established between 1Password and the terminal window or tab the plugin was invoked from. Any consecutive invocations of 1Password CLI within that terminal window can use your 1Password account without additional authorization until 1Password locks. This includes invocations of the same plugin, a different plugin and any other 1Password CLI commands. As always when working with secrets, it's worth being mindful of the processes, scripts, and plugins you run that can access those secrets. A session is ended in any of the following scenarios: * When 1Password is locked * After 10 minutes of inactivity * After 12 hours * When `op signout` is run in the authorized terminal session * When `op signout --all` is run in any terminal session ## Extendability & community contributions 1Password Shell Plugins is [extendable](/cli/shell-plugins/contribute/). Contributed plugins are curated and reviewed by 1Password before they are included and shipped in 1Password CLI. 1Password has only reviewed contributed plugins if they are included in 1Password CLI. We recommend you only run plugins included in 1Password CLI and plugins you've written yourself. In practice, this means you should not download binaries and place them in `~/.op/plugins/local`. ## Learn more * [Biometric security](/cli/app-integration/) # Use 1Password to securely authenticate the Sentry CLI Source: https://www.1password.dev/cli/shell-plugins/sentry The Sentry shell plugin allows you to use 1Password to securely authenticate [the Sentry CLI](https://docs.sentry.io/product/cli/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Sentry CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Sentry CLI.](https://docs.sentry.io/product/cli/installation/) The following shells are supported: * Bash * Zsh * fish > [!TIP] > > Get \$240 in Sentry credits when you [create a new Sentry account](https://sentry.io/signup/) using the promo code **1Password**. ## Step 1: Configure your default credentials To get started with the Sentry shell plugin:
  1. Sign in to the 1Password account you want to use with the Sentry plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init sentry-cli
You'll be prompted to import your Sentry credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/sentry-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Sentry credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/sentry-2.png) #### Select an existing item If you've already saved your Sentry credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/sentry-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Sentry. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/sentry-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Sentry, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/DMnym2BeeklqeCzz/static/img/shell-plugins/sentry-5.png?fit=max\&auto=format\&n=DMnym2BeeklqeCzz\&q=85\&s=fd447647d7c89c1e9c49bb6a8f57231d) ## Step 4: Remove imported credentials from disk After saving your Sentry credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Sentry configuration: op plugin inspect sentry-cli 1Password CLI will return a list of the credentials you've configured to use with Sentry and their default scopes, as well as a list of aliases configured for Sentry. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/DMnym2BeeklqeCzz/static/img/shell-plugins/sentry-6.png?fit=max\&auto=format\&n=DMnym2BeeklqeCzz\&q=85\&s=09df3f36a54914d0a99c6f72c6ba2558) ### Clear your credentials To reset the credentials used with Sentry: op plugin clear sentry-cli You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear sentry-cli` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear sentry-cli --all`. ## Reference 1Password authenticates with Sentry by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Sentry credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variables | | - | - | | Token | `SENTRY_AUTH_TOKEN` | | Organization (optional) | `SENTRY_ORG` | | Project (optional) | `SENTRY_PROJECT` | | URL (optional) | `SENTRY_URL` | ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate the Snowflake CLI Source: https://www.1password.dev/cli/shell-plugins/snowflake The Snowflake shell plugin allows you to use 1Password to securely authenticate [SnowSQL](https://docs.snowflake.com/en/user-guide/snowsql.html) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the SnowSQL with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.14.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [SnowSQL.](https://docs.snowflake.com/en/user-guide/snowsql-install-config) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Snowflake shell plugin:
  1. Sign in to the 1Password account you want to use with the Snowflake plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init snowsql
You'll be prompted to import your Snowflake credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/snowsql-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Snowflake credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/snowsql-2.png) #### Select an existing item If you've already saved your Snowflake credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/snowsql-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Snowflake. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/snowsql-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Snowflake, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/DMnym2BeeklqeCzz/static/img/shell-plugins/snowsql-5.png?fit=max\&auto=format\&n=DMnym2BeeklqeCzz\&q=85\&s=0a7582cd82c335a4dbb575767ae870e3) ## Step 4: Remove imported credentials from disk After saving your Snowflake credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Snowflake configuration: op plugin inspect snowsql 1Password CLI will return a list of the credentials you've configured to use with Snowflake and their default scopes, as well as a list of aliases configured for Snowflake. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/DMnym2BeeklqeCzz/static/img/shell-plugins/snowsql-6.png?fit=max\&auto=format\&n=DMnym2BeeklqeCzz\&q=85\&s=8c125083965a9d5c1ec403ec7a93287e) ### Clear your credentials To reset the credentials used with Snowflake: op plugin clear snowsql You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear snowsql` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear snowsql --all`. ## Reference 1Password authenticates with Snowflake by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Snowflake credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variable | | - | - | | Account | `SNOWSQL_ACCOUNT` | | Username | `SNOWSQL_USER` | | Password | `SNOWSQL_PWD` | *Thanks to [@williamhpark](https://github.com/williamhpark) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/161) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate the Snyk CLI Source: https://www.1password.dev/cli/shell-plugins/snyk The Snyk shell plugin allows you to use 1Password to securely authenticate [the Snyk CLI](https://docs.snyk.io/snyk-cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Snyk CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Snyk CLI.](https://docs.snyk.io/snyk-cli/install-the-snyk-cli) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Snyk shell plugin:
  1. Sign in to the 1Password account you want to use with the Snyk plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init snyk
You'll be prompted to import your Snyk credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/snyk-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Snyk credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/snyk-2.png) #### Select an existing item If you've already saved your Snyk credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/snyk-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Snyk. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/snyk-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Snyk, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/DMnym2BeeklqeCzz/static/img/shell-plugins/snyk-5.png?fit=max\&auto=format\&n=DMnym2BeeklqeCzz\&q=85\&s=bf6e34131c5c6cf5707b712561e9cf70) ## Step 4: Remove imported credentials from disk After saving your Snyk credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Snyk configuration: op plugin inspect snyk 1Password CLI will return a list of the credentials you've configured to use with Snyk and their default scopes, as well as a list of aliases configured for Snyk. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/DMnym2BeeklqeCzz/static/img/shell-plugins/snyk-6.png?fit=max\&auto=format\&n=DMnym2BeeklqeCzz\&q=85\&s=28a263dbfbd870eec31a3fcaedda9277) ### Clear your credentials To reset the credentials used with Snyk: op plugin clear snyk You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear snyk` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear snyk --all`. ## Reference 1Password authenticates with Snyk by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Snyk credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | Token | `SNYK_TOKEN` | ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate the Sourcegraph CLI Source: https://www.1password.dev/cli/shell-plugins/sourcegraph The Sourcegraph shell plugin allows you to use 1Password to securely authenticate [the Sourcegraph CLI](https://sourcegraph.com/docs/cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Sourcegraph CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.14.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Sourcegraph CLI.](https://sourcegraph.com/docs/cli/quickstart) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the the Sourcegraph CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the the Sourcegraph CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init src
You'll be prompted to import your the Sourcegraph CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/src-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your the Sourcegraph CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/src-2.png) #### Select an existing item If you've already saved your the Sourcegraph CLI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/src-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate the Sourcegraph CLI. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/src-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with the Sourcegraph CLI, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/DMnym2BeeklqeCzz/static/img/shell-plugins/src-5.png?fit=max\&auto=format\&n=DMnym2BeeklqeCzz\&q=85\&s=ed8e96732a8bcec20035af7b95a8ddc4) ## Step 4: Remove imported credentials from disk After saving your the Sourcegraph CLI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current the Sourcegraph CLI configuration: op plugin inspect src 1Password CLI will return a list of the credentials you've configured to use with the Sourcegraph CLI and their default scopes, as well as a list of aliases configured for the Sourcegraph CLI. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/DMnym2BeeklqeCzz/static/img/shell-plugins/src-6.png?fit=max\&auto=format\&n=DMnym2BeeklqeCzz\&q=85\&s=a9ffd800d7a1d8d4d368700d0a9cb929) ### Clear your credentials To reset the credentials used with the Sourcegraph CLI: op plugin clear src You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear src` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear src --all`. ## Reference 1Password authenticates with Sourcegraph by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Sourcegraph credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variable | | - | - | | Endpoint | `SRC_ENDPOINT` | | Token | `SRC_ACCESS_TOKEN` | *Thanks to [@arunsathiya](https://github.com/arunsathiya) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/146) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate spacectl Source: https://www.1password.dev/cli/shell-plugins/spacelift Store your credentials in 1Password then authenticate spacectl with your fingerprint. The Spacelift shell plugin allows you to use 1Password to securely authenticate [spacectl](https://github.com/spacelift-io/spacectl) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext.Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate spacectl with biometrics.## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.42.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install spacectl.](https://github.com/spacelift-io/spacectl)
The following shells are supported:
  • Bash
  • Zsh
  • fish
## Step 1: Configure your default credentialsTo get started with the Spacelift shell plugin:
  1. Sign in to the 1Password account you want to use with the Spacelift plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init spacectl
You'll be prompted to import your Spacelift credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used.### Step 1.1: Import or select an item#### Import a new itemIf you haven't saved your Spacelift credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it.If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them.#### Select an existing itemIf you've already saved your Spacelift credentials in 1Password, select **Search in 1Password**.You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account.### Step 1.2: Set default credential scopeAfter you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Spacelift.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh fileTo make the plugin available, source your `plugins.sh` file. For example:```shell theme={null} source ~/.config/op/plugins.sh ```The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path.If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example:```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``````shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``````shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ```## Step 3: Use the CLIThe next time you enter a command with Spacelift, you'll be prompted to authenticate with biometrics or system authentication.## Step 4: Remove imported credentials from diskAfter saving your Spacelift credentials in 1Password, you can remove all local copies you previously had stored on disk.## Next steps1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs:```shell theme={null} op plugin list ```To choose another plugin to get started with:```shell theme={null} op plugin init ```To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/)## Get help### Inspect your configurationTo inspect your current Spacelift configuration:op plugin inspect spacectl1Password CLI will return a list of the credentials you've configured to use with Spacelift and their default scopes, as well as a list of aliases configured for Spacelift.### Clear your credentialsTo reset the credentials used with Spacelift:op plugin clear spacectlYou can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear spacectl` four times to clear all of your defaults.To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear spacectl --all`.## Reference 1Password authenticates with Spacelift by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Spacelift credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. \ \ \
1Password field nameEnvironment variable
*Thanks to [@damianstasik](https://github.com/damianstasik) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/285) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate Stackhero CLI Source: https://www.1password.dev/cli/shell-plugins/stackhero Store your credentials in 1Password then authenticate Stackhero CLI with your fingerprint. The Stackhero shell plugin allows you to use 1Password to securely authenticate [Stackhero CLI](https://www.stackhero.io/stackhero/documentations/Use-the-CLI) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext.Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Stackhero CLI with biometrics.## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.42.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install Stackhero CLI.](https://www.stackhero.io/stackhero/documentations/Use-the-CLI)
The following shells are supported:
  • Bash
  • Zsh
  • fish
## Step 1: Configure your default credentialsTo get started with the Stackhero shell plugin:
  1. Sign in to the 1Password account you want to use with the Stackhero plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init stackhero
You'll be prompted to import your Stackhero credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used.### Step 1.1: Import or select an item#### Import a new itemIf you haven't saved your Stackhero credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it.If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them.#### Select an existing itemIf you've already saved your Stackhero credentials in 1Password, select **Search in 1Password**.You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account.### Step 1.2: Set default credential scopeAfter you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Stackhero.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh fileTo make the plugin available, source your `plugins.sh` file. For example:```shell theme={null} source ~/.config/op/plugins.sh ```The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path.If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example:```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``````shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``````shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ```## Step 3: Use the CLIThe next time you enter a command with Stackhero, you'll be prompted to authenticate with biometrics or system authentication.## Step 4: Remove imported credentials from diskAfter saving your Stackhero credentials in 1Password, you can remove all local copies you previously had stored on disk.## Next steps1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs:```shell theme={null} op plugin list ```To choose another plugin to get started with:```shell theme={null} op plugin init ```To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/)## Get help### Inspect your configurationTo inspect your current Stackhero configuration:op plugin inspect stackhero1Password CLI will return a list of the credentials you've configured to use with Stackhero and their default scopes, as well as a list of aliases configured for Stackhero.### Clear your credentialsTo reset the credentials used with Stackhero:op plugin clear stackheroYou can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear stackhero` four times to clear all of your defaults.To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear stackhero --all`.## Reference 1Password authenticates with Stackhero by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Stackhero credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. \ \ \
1Password field nameEnvironment variable
*Thanks to [@martijngastkemper](https://github.com/martijngastkemper) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/671) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate the Stripe CLI Source: https://www.1password.dev/cli/shell-plugins/stripe The Stripe shell plugin allows you to use 1Password to securely authenticate [the Stripe CLI](https://stripe.com/docs/cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Stripe CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Stripe CLI.](https://stripe.com/docs/stripe-cli) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Stripe shell plugin:
  1. Sign in to the 1Password account you want to use with the Stripe plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init stripe
You'll be prompted to import your Stripe credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/stripe-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Stripe credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/stripe-2.png) #### Select an existing item If you've already saved your Stripe credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/stripe-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Stripe. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/stripe-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Stripe, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/DMnym2BeeklqeCzz/static/img/shell-plugins/stripe-5.png?fit=max\&auto=format\&n=DMnym2BeeklqeCzz\&q=85\&s=b820ced58faa3dc28888456ad80e7835) ## Step 4: Remove imported credentials from disk After saving your Stripe credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Stripe configuration: op plugin inspect stripe 1Password CLI will return a list of the credentials you've configured to use with Stripe and their default scopes, as well as a list of aliases configured for Stripe. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/DMnym2BeeklqeCzz/static/img/shell-plugins/stripe-6.png?fit=max\&auto=format\&n=DMnym2BeeklqeCzz\&q=85\&s=eda0d68807314ffd81beda28bcda2f1f) ### Clear your credentials To reset the credentials used with Stripe: op plugin clear stripe You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear stripe` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear stripe --all`. ## Reference 1Password authenticates with Stripe by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Stripe credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | API Key | `STRIPE_API_KEY` | ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate Terraform Source: https://www.1password.dev/cli/shell-plugins/terraform Beta The Terraform shell plugin allows you to use 1Password to securely authenticate [Terraform CLI](https://developer.hashicorp.com/terraform/cli) to supported providers with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. You can configure the Terraform plugin to authenticate with biometrics to any provider in the [1Password Shell Plugin ecosystem](/cli/shell-plugins#get-started), like AWS, ngrok, and Databricks. > [!TIP] > > The Terraform shell plugin is currently in beta. It can only be used with the latest [beta build](https://app-updates.agilebits.com/product_history/CLI2#beta) of 1Password CLI, version `2.19.0-beta.01` or later. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [the latest beta build of 1Password CLI](https://app-updates.agilebits.com/product_history/CLI2#beta) (`2.19.0-beta.01` or later). 4. [Integrate 1Password CLI with the 1Password app](/cli/app-integration#step-1-turn-on-the-app-integration). 5. Install [Terraform CLI.](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials > [!TIP] > > If you have multiple 1Password accounts, run `op signin` to select the account you want to use before configuring the plugin. When you use the plugin, 1Password CLI will automatically switch to that account. To get started with the Terraform shell plugin, run: ```shell theme={null} op plugin init terraform ``` You'll be prompted to select the credential types you want to use with Terraform — you can choose as many as you want. Select the credential type for [a supported provider](/cli/shell-plugins#get-started), then you can either [import the credential](#import-a-new-item) into your 1Password account or [select an existing 1Password item](#select-an-existing-item) where the credential is saved. When you've configured all the credentials you want to use with Terraform, select **Stop choosing credentials**. ### Step 1.1: Import or select an item #### Import a new item If you haven't saved a credential in 1Password yet, select **Import into 1Password**. Enter a name for the new 1Password item and select the vault where you want to save it. If 1Password detects the credential in your local development environment, you'll be automatically prompted to import it. #### Select an existing item If you've already saved a credential in 1Password, select **Search in 1Password**. Select the item from the list of suggested items. If you don't see the item you want, select **Expand search** to browse all items in your account. ### Step 1.2: Set default credential scope After you finish selecting your credentials, you'll be prompted to configure when to use them. * **Prompt me for each new terminal session** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the defaults will be removed. * **Use automatically when in this directory or subdirectories** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one. * **Use as global default on my system** will set the credentials as the defaults in all terminal sessions and directories. A directory-specific default takes precedence over a global one. ## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```shell theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you use Terraform CLI with one of the providers you configured credentials for, you'll be prompted to authenticate with biometrics or system authentication. ![The terraform plan command being authenticated to AWS with Touch ID.](https://mintcdn.com/ab-634991b8/DMnym2BeeklqeCzz/static/img/shell-plugins/terraform-5.png?fit=max\&auto=format\&n=DMnym2BeeklqeCzz\&q=85\&s=a7dfe6b3215d452c2dd7fd86192933e1) ## Step 4: Remove imported credentials from disk After saving your credentials in 1Password, you can remove all local copies you previously had stored on disk, like in your [provider configurations.](https://developer.hashicorp.com/terraform/language/providers/configuration) ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Terraform configuration: ```shell theme={null} op plugin inspect terraform ``` 1Password CLI will return a list of the credentials you've configured to use with Terraform and their default scope, as well as a list of aliases configured for Terraform CLI. ![1Password CLI inspecting a Terraform shell plugin with AWS and ngrok credentials configured as global defaults.](https://mintcdn.com/ab-634991b8/DMnym2BeeklqeCzz/static/img/shell-plugins/terraform-6.png?fit=max\&auto=format\&n=DMnym2BeeklqeCzz\&q=85\&s=49dd9014f8aa1f6af7ba73b6786a702c) ### Clear your credentials To reset the credentials used with Terraform CLI: ```shell theme={null} op plugin clear terraform ``` You can clear one configuration at a time, in this order of precedence: 1. Terminal session default 2. Directory default, from the current directory to `$HOME` 3. Global default For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear terraform` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear terraform --all`. ## Reference 1Password authenticates to Terraform providers by provisioning the credentials required by the plugin commands directly from your 1Password account. If you saved your provider credentials manually rather than using `op plugin` to import a new item, you might be prompted to rename your item's fields to match the item structure required by the credential schema. 1Password provides credentials to the following Terraform commands: * `apply` * `destroy` * `import` * `init` * `output` * `plan` * `refresh` * `state` * `taint` * `test` * `workspace` # Test shell plugins Source: https://www.1password.dev/cli/shell-plugins/test You can test [1Password Shell Plugins](/cli/shell-plugins/) without making any changes to your current workflows. To do this, you'll configure a shell plugin with default credentials that only last for the duration of your current terminal session, then source the shell plugin aliases script in your current terminal session instead of adding it to your shell profile. When you close your terminal window, your temporary shell plugin configuration will be cleared. ## Step 1: Temporarily configure a shell plugin 1. Sign in to the 1Password account where the credentials you want to use with the shell plugin are stored: ```shell theme={null} op signin ``` 2. Choose a plugin to test, or run `op plugin init` to choose from a list of all available plugins. For example, to test the AWS shell plugin: ```shell theme={null} op plugin init aws ``` 3. Import or select the credentials you want to test with the plugin. 4. When you're prompted to choose when the credentials will be used to authenticate, select **Prompt me for each new terminal session**. This will configure your credentials as a temporary default for the duration of your current terminal session. 5. Instead of adding the command to source the `plugins.sh` file to your shell profile, source the `plugins.sh` file in your current terminal session. This will create an alias for the CLI executable that lasts for the duration of your current terminal session. For example: ```shell theme={null} source ~/.config/op/plugins.sh ``` The location of the `plugins.sh` file will vary depending on your [configuration directory](/cli/config-directories/). ## Step 2: Test the shell plugin You can test the shell plugin for the duration of your current terminal session. 1. Sign out of 1Password CLI to make sure you'll be prompted to authenticate: ```shell theme={null} op signout ``` 2. Run a command with the CLI that requires authentication. For example, if you configured a shell plugin for AWS: ```shell theme={null} aws s3 ls ``` When you're done testing, close the terminal window to clear your default credentials and remove the alias for the CLI executable. To continue using a shell plugin, follow the installation guide for the [plugin of your choice](/cli/shell-plugins/). # Use 1Password to securely authenticate Todoist CLI Source: https://www.1password.dev/cli/shell-plugins/todoist The Todoist CLI shell plugin allows you to use 1Password to securely authenticate [Todoist CLI](https://github.com/sachaos/todoist) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Todoist CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.22.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/). 5. [Install Todoist CLI.](https://github.com/sachaos/todoist) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Todoist CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the Todoist CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init todoist
You'll be prompted to import your Todoist CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Todoist CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. #### Select an existing item If you've already saved your Todoist CLI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Todoist CLI.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Todoist CLI, you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your Todoist CLI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Todoist CLI configuration: op plugin inspect todoist 1Password CLI will return a list of the credentials you've configured to use with Todoist CLI and their default scopes, as well as a list of aliases configured for Todoist CLI. ### Clear your credentials To reset the credentials used with Todoist CLI: op plugin clear todoist You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear todoist` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear todoist --all`. ## Reference 1Password authenticates with Todoist by injecting a temporary config file with the credentials required by the plugin commands directly from your 1Password account. If you saved your Todoist credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Config file field | | - | - | | Token | token | *Thanks to [@rajapri28613](https://github.com/rajapri28613) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/340) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate the Treasure Data CLI Source: https://www.1password.dev/cli/shell-plugins/treasure-data The Treasure Data shell plugin allows you to use 1Password to securely authenticate the [Treasure Data Toolbelt](https://www.treasuredata.com/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Treasure Data with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.16.1 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Treasure Data Toolbelt.](https://toolbelt.treasuredata.com/) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Treasure Data shell plugin:
  1. Sign in to the 1Password account you want to use with the Treasure Data plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init td
You'll be prompted to import your Treasure Data credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/treasure-data-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Treasure Data credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/treasure-data-2.png) #### Select an existing item If you've already saved your Treasure Data credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/treasure-data-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Treasure Data. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/treasure-data-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Treasure Data, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/DMnym2BeeklqeCzz/static/img/shell-plugins/treasure-data-5.png?fit=max\&auto=format\&n=DMnym2BeeklqeCzz\&q=85\&s=ac7d738dff589dcc1a7371b2f8dda86c) ## Step 4: Remove imported credentials from disk After saving your Treasure Data credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Treasure Data configuration: op plugin inspect td 1Password CLI will return a list of the credentials you've configured to use with Treasure Data and their default scopes, as well as a list of aliases configured for Treasure Data. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/DMnym2BeeklqeCzz/static/img/shell-plugins/treasure-data-6.png?fit=max\&auto=format\&n=DMnym2BeeklqeCzz\&q=85\&s=3535180ea6bcb21e641271cedbcf8f4c) ### Clear your credentials To reset the credentials used with Treasure Data: op plugin clear td You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear td` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear td --all`. ## Reference 1Password authenticates with Treasure Data by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Treasure Data credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | API Key | `TD_API_KEY` | ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# 1Password Shell Plugins troubleshooting Source: https://www.1password.dev/cli/shell-plugins/troubleshooting ## Using shell plugins ### If you're using a non-interactive shell 1Password Shell Plugins are built to be used with interactive shells. An interactive shell is required for the shell plugin to prompt for authentication. ### If your script doesn't inherit shell plugin aliases Scripts might not inherit your shell plugin aliases if they're run in a subshell where the `plugins.sh` file isn't sourced. When this happens, the CLI command in the script will output an error instead of running correctly. For example, the following script runs a `doctl` command in a subshell, and as a result wouldn't inherit the `doctl` shell plugin alias: ```html yourscript.sh theme={null} #!/usr/bin/env bash doctl account get ``` To make the script run correctly, you can wrap the `doctl` command in [`op plugin run`](/cli/reference/management-commands/plugin/#plugin-run). For example: ```html yourscript.sh theme={null} #!/usr/bin/env bash op plugin run doctl account get ``` ### If autocompletion stops working If autocompletion stops working in Zsh after you configure a shell plugin, run the following command to configure completion for aliases: ```shell theme={null} setopt completealiases ``` ## Contributing shell plugins ### If your locally-built plugin stops working If your locally-built plugin stops working, you might need to update your 1Password CLI version or rebuild your plugin with the latest shell plugins SDK. #### Update your 1Password CLI installation If you're using an outdated version of the CLI, you'll see this error message: ```shell theme={null} 1Password CLI is outdated, please run: op update to update 1Password CLI to the latest version and to be able to use this Shell Plugin. ``` To update your 1Password CLI installation to the latest version: ```shell theme={null} op update ``` Or [update 1Password CLI with a package manager](/cli/reference/update/#update-with-a-package-manager). #### Rebuild your plugins with the latest shell plugins SDK If the shell plugins SDK is outdated, you'll see this error message: ```shell theme={null} 1Password Shell Plugin is out of date. Remove the plugin at '/Users//.op/plugins/local/aws' or rebuild it with the latest Shell Plugin SDK to use it. ``` To update to the latest shell plugins SDK, you'll need to merge the `main` branch of the [shell plugins repository](https://github.com/1Password/shell-plugins/tree/main/) into the branch for your plugin. To do this: 1. Navigate to the directory where you cloned the shell plugins repo: ```shell theme={null} cd ``` 2. If you've made any local changes to your plugin branch, commit or stash them: ```shell theme={null} git commit -am "" ``` 3. Check out the `main` branch: ```shell theme={null} git checkout main ``` 4. Pull the `main` branch: ```shell theme={null} git pull main ``` 5. Check out your plugin branch: ```shell theme={null} git checkout ``` 6. Merge `main` into your branch: ``` git merge main ``` Then fix any merge conflicts and make any needed changes to the plugin code to conform to the latest version of the SDK. When you're ready to rebuild your plugin: ```shell theme={null} make /build ``` > [!NOTE] > > **Join our Developer Slack** > > If you're still having trouble, join our [Developer Slack workspace](/joinslack) and we'll help you figure out a solution. ## Learn more * [Uninstall shell plugins](/cli/shell-plugins/uninstall/) * [Test shell plugins](/cli/shell-plugins/test/) * [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/) * [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/) # Use 1Password to securely authenticate the Tugboat CLI Source: https://www.1password.dev/cli/shell-plugins/tugboat The Tugboat shell plugin allows you to use 1Password to securely authenticate [the Tugboat CLI](https://docs.tugboatqa.com/tugboat-cli/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Tugboat CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.10.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Tugboat CLI.](https://docs.tugboatqa.com/tugboat-cli/install-the-cli/) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Tugboat shell plugin:
  1. Sign in to the 1Password account you want to use with the Tugboat plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init tugboat
You'll be prompted to import your Tugboat credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/tugboat-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Tugboat credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/tugboat-2.png) #### Select an existing item If you've already saved your Tugboat credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/tugboat-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Tugboat. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/tugboat-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Tugboat, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/DMnym2BeeklqeCzz/static/img/shell-plugins/tugboat-5.png?fit=max\&auto=format\&n=DMnym2BeeklqeCzz\&q=85\&s=bb2e7308a34b77fb8b535d2a9803bafa) ## Step 4: Remove imported credentials from disk After saving your Tugboat credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Tugboat configuration: op plugin inspect tugboat 1Password CLI will return a list of the credentials you've configured to use with Tugboat and their default scopes, as well as a list of aliases configured for Tugboat. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/DMnym2BeeklqeCzz/static/img/shell-plugins/tugboat-6.png?fit=max\&auto=format\&n=DMnym2BeeklqeCzz\&q=85\&s=8a817fecbea41c1602254cdb77e00d96) ### Clear your credentials To reset the credentials used with Tugboat: op plugin clear tugboat You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear tugboat` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear tugboat --all`. ## Reference 1Password authenticates with Tugboat by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Tugboat credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | Token | `TUGBOAT_API_TOKEN` | *Thanks to [@markdorison](https://github.com/markdorison) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/85) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate the Twilio CLI Source: https://www.1password.dev/cli/shell-plugins/twilio The Twilio shell plugin allows you to use 1Password to securely authenticate [the Twilio CLI](https://twilio.com/docs/cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Twilio CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.9.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [the Twilio CLI.](https://www.twilio.com/docs/twilio-cli/quickstart) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Twilio shell plugin:
  1. Sign in to the 1Password account you want to use with the Twilio plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init twilio
You'll be prompted to import your Twilio credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/twilio-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Twilio credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/twilio-2.png) #### Select an existing item If you've already saved your Twilio credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/twilio-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Twilio. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/twilio-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Twilio, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/DMnym2BeeklqeCzz/static/img/shell-plugins/twilio-5.png?fit=max\&auto=format\&n=DMnym2BeeklqeCzz\&q=85\&s=d83ce5df390dd418d331ceb34968c1a9) ## Step 4: Remove imported credentials from disk After saving your Twilio credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Twilio configuration: op plugin inspect twilio 1Password CLI will return a list of the credentials you've configured to use with Twilio and their default scopes, as well as a list of aliases configured for Twilio. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/DMnym2BeeklqeCzz/static/img/shell-plugins/twilio-6.png?fit=max\&auto=format\&n=DMnym2BeeklqeCzz\&q=85\&s=b6723552349b4cdfc7fd36d302f4e251) ### Clear your credentials To reset the credentials used with Twilio: op plugin clear twilio You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear twilio` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear twilio --all`. ## Reference 1Password authenticates with Twilio by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Twilio credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variables | | - | - | | Account SID | `TWILIO_ACCOUNT_SID` | | API Key | `TWILIO_API_KEY` | | API Secret | `TWILIO_API_SECRET` | | Region (optional) | `TWILIO_REGION` | ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Uninstall shell plugins Source: https://www.1password.dev/cli/shell-plugins/uninstall [1Password Shell Plugins](/cli/shell-plugins/) are built so you can stop using them at any time. * If you want to [reset a shell plugin configuration](#clear-your-default-credentials-for-a-plugin), you can clear your default credentials. * If you want to [temporarily stop using a shell plugin](#temporarily-stop-using-a-shell-plugin), you can run `unalias ` or remove the alias for its executable from your `plugins.sh` file. * If you want to [temporarily stop using all shell plugins](#temporarily-stop-using-all-shell-plugins), you can remove the command to source the `plugins.sh` file from your shell profile. * And if you want to [completely uninstall shell plugins](#completely-stop-using-shell-plugins), you can do that too. ## Clear your default credentials for a plugin If you want to remove your default credentials for a shell plugin: ```shell theme={null} op plugin clear ``` Credentials will be removed in this order: 1. Terminal session default 2. Directory default, from the current directory to `$HOME` 3. Global default To remove all the credentials you've configured for a shell plugin at the same time: ```shell theme={null} op plugin clear --all ``` ## Temporarily stop using a shell plugin If you want to stop using a shell plugin for the current terminal session, run: ``` unalias ``` If you want to temporarily stop using a plugin for a longer period of time, you can remove its alias from your `plugins.sh` file. Then 1Password CLI will no longer handle authentication when you use the third-party CLI. 1. Open your [`plugins.sh` file](#if-you-cant-find-your-pluginssh-file) file. 2. Remove the alias for the plugin you want to stop using. For example, `alias aws="op plugin run -- aws"`. 3. Save the file. 4. Open a new terminal window or source your shell profile for the change to go into effect. You can add the alias back to the file at any time to continue using the shell plugin with your current setup. ## Temporarily stop using all shell plugins If you want to temporarily stop using shell plugins without losing your configurations, you can remove the command to source the `plugins.sh` file from your shell profile. 1. Open your shell profile. 2. Remove the line that looks like this. Your [`plugins.sh` file path](#if-you-cant-find-your-pluginssh-file) may vary. ```shell theme={null} source ~/.config/op/plugins.sh ``` 3. Open a new terminal session or source your shell profile for the change to go into effect. 1Password will no longer prompt you to authenticate for any third-party CLI. ## Completely stop using shell plugins To completely stop using shell plugins and remove all information about your configurations: 1. [Clear the default credentials](#clear-your-default-credentials-for-a-plugin) for each of your plugins. 2. [Remove the command to source the `plugins.sh` file](#temporarily-stop-using-all-shell-plugins) from your shell profile. 3. Delete the [`plugins.sh` file](#if-you-cant-find-your-pluginssh-file) and the `plugins` folder within your `op` directory. 4. If you configured any directory-specific defaults, remove the `.op` folder from those directories. ## Get help ### If you can't find your plugins.sh file The file path for your `plugins.sh` file may vary depending on your [configuration directory](/cli/config-directories/). Common locations include: * `~/.op/plugins.sh` * `~/.config/op/plugins.sh` * `~/op/plugins.sh` # Use 1Password to securely authenticate UpCloud CLI Source: https://www.1password.dev/cli/shell-plugins/upcloud Store your credentials in 1Password then authenticate UpCloud CLI with your fingerprint. The UpCloud shell plugin allows you to use 1Password to securely authenticate [UpCloud CLI](https://upcloudltd.github.io/upcloud-cli/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext.Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate UpCloud CLI with biometrics.## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.35.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install UpCloud CLI.](https://upcloudltd.github.io/upcloud-cli/)
The following shells are supported:
  • Bash
  • Zsh
  • fish
## Step 1: Configure your default credentialsTo get started with the UpCloud shell plugin:
  1. Sign in to the 1Password account you want to use with the UpCloud plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init upctl
You'll be prompted to import your UpCloud credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used.### Step 1.1: Import or select an item#### Import a new itemIf you haven't saved your UpCloud credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it.If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them.#### Select an existing itemIf you've already saved your UpCloud credentials in 1Password, select **Search in 1Password**.You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account.### Step 1.2: Set default credential scopeAfter you select or import your credentials, you'll be prompted to configure when to use the item to authenticate UpCloud.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh fileTo make the plugin available, source your `plugins.sh` file. For example:```shell theme={null} source ~/.config/op/plugins.sh ```The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path.If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example:```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``````shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``````shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ```## Step 3: Use the CLIThe next time you enter a command with UpCloud, you'll be prompted to authenticate with biometrics or system authentication.## Step 4: Remove imported credentials from diskAfter saving your UpCloud credentials in 1Password, you can remove all local copies you previously had stored on disk.## Next steps1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs:```shell theme={null} op plugin list ```To choose another plugin to get started with:```shell theme={null} op plugin init ```To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/)## Get help### Inspect your configurationTo inspect your current UpCloud configuration:op plugin inspect upctl1Password CLI will return a list of the credentials you've configured to use with UpCloud and their default scopes, as well as a list of aliases configured for UpCloud.### Clear your credentialsTo reset the credentials used with UpCloud:op plugin clear upctlYou can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear upctl` four times to clear all of your defaults.To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear upctl --all`.## Reference 1Password authenticates with UpCloud by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your UpCloud credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. \ \ \
1Password field nameEnvironment variable
*Thanks to [@jksolbakken](https://github.com/jksolbakken) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/538) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate Upstash CLI Source: https://www.1password.dev/cli/shell-plugins/upstash The Upstash CLI shell plugin allows you to use 1Password to securely authenticate [Upstash CLI](https://github.com/upstash/cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Upstash CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.22.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/). 5. [Install Upstash CLI.](https://github.com/upstash/cli) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Upstash CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the Upstash CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init upstash
You'll be prompted to import your Upstash CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Upstash CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. #### Select an existing item If you've already saved your Upstash CLI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Upstash CLI.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Upstash CLI, you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your Upstash CLI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Upstash CLI configuration: op plugin inspect upstash 1Password CLI will return a list of the credentials you've configured to use with Upstash CLI and their default scopes, as well as a list of aliases configured for Upstash CLI. ### Clear your credentials To reset the credentials used with Upstash CLI: op plugin clear upstash You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear upstash` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear upstash --all`. ## Reference 1Password authenticates with Upstash CLI by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Upstash CLI credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | API Key | `UPSTASH_API_KEY` | | Email | `UPSTASH_EMAIL` | *Thanks to [@siddhikhapare](https://github.com/siddhikhapare) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/316) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate Vercel CLI Source: https://www.1password.dev/cli/shell-plugins/vercel The Vercel CLI shell plugin allows you to use 1Password to securely authenticate [Vercel CLI](https://vercel.com/docs/cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Vercel CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.19.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. [Install Vercel CLI.](https://vercel.com/docs/cli) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Vercel CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the Vercel CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init vercel
You'll be prompted to import your Vercel CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/vercel-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Vercel CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/vercel-2.png) #### Select an existing item If you've already saved your Vercel CLI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/vercel-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Vercel CLI. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/vercel-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Vercel CLI, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/MKy6sgNGqMk-yGDS/static/img/shell-plugins/vercel-5.png?fit=max\&auto=format\&n=MKy6sgNGqMk-yGDS\&q=85\&s=f84634b2bc82bc6052893c3730500c71) ## Step 4: Remove imported credentials from disk After saving your Vercel CLI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Vercel CLI configuration: op plugin inspect vercel 1Password CLI will return a list of the credentials you've configured to use with Vercel CLI and their default scopes, as well as a list of aliases configured for Vercel CLI. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/MKy6sgNGqMk-yGDS/static/img/shell-plugins/vercel-6.png?fit=max\&auto=format\&n=MKy6sgNGqMk-yGDS\&q=85\&s=df20e5690e45375db2c11d41fe004e8f) ### Clear your credentials To reset the credentials used with Vercel CLI: op plugin clear vercel You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear vercel` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear vercel --all`. ## Reference 1Password authenticates with Vercel by injecting injecting the token as a command line argument. If you saved your Vercel CLI credentials in 1Password manually rather than using `op plugin init` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Command line argument | | | - | - | - | | Token | `--token` | \` | *Thanks to [@j178](https://github.com/j178) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/273) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate Vertica CLI Source: https://www.1password.dev/cli/shell-plugins/vertica The Vertica CLI shell plugin allows you to use 1Password to securely authenticate [Vertica CLI](https://www.vertica.com/docs/9.2.x/HTML/Content/Authoring/ConnectingToVertica/vsql/Install/InstallingTheVsqlClient.htm) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Vertica CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.22.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/). 5. [Install Vertica CLI.](https://www.vertica.com/docs/9.2.x/HTML/Content/Authoring/ConnectingToVertica/vsql/Install/InstallingTheVsqlClient.htm) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Vertica CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the Vertica CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init vsql
You'll be prompted to import your Vertica CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Vertica CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. #### Select an existing item If you've already saved your Vertica CLI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Vertica CLI.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Vertica CLI, you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your Vertica CLI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Vertica CLI configuration: op plugin inspect vsql 1Password CLI will return a list of the credentials you've configured to use with Vertica CLI and their default scopes, as well as a list of aliases configured for Vertica CLI. ### Clear your credentials To reset the credentials used with Vertica CLI: op plugin clear vsql You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear vsql` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear vsql --all`. ## Reference 1Password authenticates with Vertica CLI by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Vertica CLI credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | Username | `VSQL_USER` | | Password | `VSQL_PASSWORD` | | Host (optional) | `VSQL_HOST` | | Port (optional) | `VSQL_PORT` | | Database | `VSQL_DATABASE` | *Thanks to [@parthiv11](https://github.com/parthiv11) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/327) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate Vultr CLI Source: https://www.1password.dev/cli/shell-plugins/vultr The Vultr CLI shell plugin allows you to use 1Password to securely authenticate [Vultr CLI](https://github.com/vultr/vultr-cli) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Vultr CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.14.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [Vultr CLI.](https://github.com/vultr/vultr-cli#installation) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Vultr CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the Vultr CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init vultr-cli
You'll be prompted to import your Vultr CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/vultr-cli-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Vultr CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/vultr-cli-2.png) #### Select an existing item If you've already saved your Vultr CLI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/vultr-cli-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Vultr CLI. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/vultr-cli-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Vultr CLI, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/MKy6sgNGqMk-yGDS/static/img/shell-plugins/vultr-cli-5.png?fit=max\&auto=format\&n=MKy6sgNGqMk-yGDS\&q=85\&s=eec4c054ba0cc16984ab27ff0afefe16) ## Step 4: Remove imported credentials from disk After saving your Vultr CLI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Vultr CLI configuration: op plugin inspect vultr-cli 1Password CLI will return a list of the credentials you've configured to use with Vultr CLI and their default scopes, as well as a list of aliases configured for Vultr CLI. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/MKy6sgNGqMk-yGDS/static/img/shell-plugins/vultr-cli-6.png?fit=max\&auto=format\&n=MKy6sgNGqMk-yGDS\&q=85\&s=0288132988b2c87a8f071cb884c86b8a) ### Clear your credentials To reset the credentials used with Vultr CLI: op plugin clear vultr-cli You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear vultr-cli` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear vultr-cli --all`. ## Reference 1Password authenticates with Vultr by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Vultr credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field names | Environment variable | | - | - | | API Key | `VULTR_API_KEY` | *Thanks to [@arunsathiya](https://github.com/arunsathiya) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/159) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Use 1Password to securely authenticate the Grok Build CLI Source: https://www.1password.dev/cli/shell-plugins/xai-grok Store your credentials in 1Password then authenticate the Grok Build CLI with your fingerprint. The Grok Build shell plugin allows you to use 1Password to securely authenticate [the Grok Build CLI](https://docs.x.ai/build/overview) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext.Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate the Grok Build CLI with biometrics.## Requirements
  1. [Sign up for 1Password.](https://1password.com/pricing/password-manager)
  2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux).
  3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.42.0 or later. If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/).
  4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/).
  5. [Install the Grok Build CLI.](https://docs.x.ai/build/overview)
The following shells are supported:
  • Bash
  • Zsh
  • fish
## Step 1: Configure your default credentialsTo get started with the Grok Build shell plugin:
  1. Sign in to the 1Password account you want to use with the Grok Build plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init grok
You'll be prompted to import your Grok Build credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used.### Step 1.1: Import or select an item#### Import a new itemIf you haven't saved your Grok Build credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it.If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them.#### Select an existing itemIf you've already saved your Grok Build credentials in 1Password, select **Search in 1Password**.You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account.### Step 1.2: Set default credential scopeAfter you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Grok Build.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh fileTo make the plugin available, source your `plugins.sh` file. For example:```shell theme={null} source ~/.config/op/plugins.sh ```The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path.If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example:```shell Bash theme={null} echo "source ~/.config/op/plugins.sh" >> ~/.bashrc && source ~/.bashrc ``````shell Zsh theme={null} echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc ``````shell Fish theme={null} echo "source ~/.op/plugins.sh" >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish ```## Step 3: Use the CLIThe next time you enter a command with Grok Build, you'll be prompted to authenticate with biometrics or system authentication.## Step 4: Remove imported credentials from diskAfter saving your Grok Build credentials in 1Password, you can remove all local copies you previously had stored on disk.## Next steps1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs:```shell theme={null} op plugin list ```To choose another plugin to get started with:```shell theme={null} op plugin init ```To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/)## Get help### Inspect your configurationTo inspect your current Grok Build configuration:op plugin inspect grok1Password CLI will return a list of the credentials you've configured to use with Grok Build and their default scopes, as well as a list of aliases configured for Grok Build.### Clear your credentialsTo reset the credentials used with Grok Build:op plugin clear grokYou can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear grok` four times to clear all of your defaults.To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear grok --all`.## Reference 1Password authenticates with Grok Build by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Grok Build credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. \ \ \
1Password field nameEnvironment variable
*Thanks to [@eddumelendez](https://github.com/eddumelendez) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/626) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate YugabyteDB SQL Shell Source: https://www.1password.dev/cli/shell-plugins/yugabytedb The YugabyteDB SQL Shell shell plugin allows you to use 1Password to securely authenticate [YugabyteDB SQL Shell](https://docs.yugabyte.com/preview/admin/ysqlsh/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate YugabyteDB SQL Shell with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.22.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/). 5. [Install YugabyteDB SQL Shell.](https://docs.yugabyte.com/preview/admin/ysqlsh/) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the YugabyteDB SQL Shell shell plugin:
  1. Sign in to the 1Password account you want to use with the YugabyteDB SQL Shell plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init ysqlsh
You'll be prompted to import your YugabyteDB SQL Shell credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your YugabyteDB SQL Shell credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. #### Select an existing item If you've already saved your YugabyteDB SQL Shell credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate YugabyteDB SQL Shell.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with YugabyteDB SQL Shell, you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your YugabyteDB SQL Shell credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current YugabyteDB SQL Shell configuration: op plugin inspect ysqlsh 1Password CLI will return a list of the credentials you've configured to use with YugabyteDB SQL Shell and their default scopes, as well as a list of aliases configured for YugabyteDB SQL Shell. ### Clear your credentials To reset the credentials used with YugabyteDB SQL Shell: op plugin clear ysqlsh You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear ysqlsh` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear ysqlsh --all`. ## Reference 1Password authenticates with YugabyteDB SQL Shell by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your YugabyteDB SQL Shell credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | Host | `PGHOST` | | Port | `PGPORT` | | Username | `PGUSER` | | Password | `PGPASSWORD` | *Thanks to [@parthiv11](https://github.com/parthiv11) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/322) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate Zapier CLI Source: https://www.1password.dev/cli/shell-plugins/zapier The Zapier CLI shell plugin allows you to use 1Password to securely authenticate [Zapier CLI](https://platform.zapier.com/cli_docs/docs) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate Zapier CLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.22.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Connect 1Password CLI with the 1Password app](/cli/app-integration/). 5. [Install Zapier CLI.](https://platform.zapier.com/cli_docs/docs) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Zapier CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the Zapier CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init zapier
You'll be prompted to import your Zapier CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Zapier CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. #### Select an existing item If you've already saved your Zapier CLI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Zapier CLI.
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Zapier CLI, you'll be prompted to authenticate with biometrics or system authentication. ## Step 4: Remove imported credentials from disk After saving your Zapier CLI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Zapier CLI configuration: op plugin inspect zapier 1Password CLI will return a list of the credentials you've configured to use with Zapier CLI and their default scopes, as well as a list of aliases configured for Zapier CLI. ### Clear your credentials To reset the credentials used with Zapier CLI: op plugin clear zapier You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear zapier` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear zapier --all`. ## Reference 1Password authenticates with Zapier CLI by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Zapier CLI credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | Key | `ZAPIER_DEPLOY_KEY` | *Thanks to [@rajapri28613](https://github.com/rajapri28613) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/337) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute).* # Use 1Password to securely authenticate the Zendesk CLI Source: https://www.1password.dev/cli/shell-plugins/zendesk The Zendesk CLI shell plugin allows you to use 1Password to securely authenticate [ZCLI](https://developer.zendesk.com/documentation/apps/getting-started/using-zcli/) with your fingerprint, Apple Watch, or system authentication, rather than storing your credentials in plaintext. Follow the instructions to configure your default credentials and source the `plugins.sh` file, then you'll be prompted to authenticate ZCLI with biometrics. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. Install [1Password CLI](https://app-updates.agilebits.com/product_history/CLI2) 2.17.0 or later.\ If you've already installed 1Password CLI, learn how to [update your installation](/cli/reference/update/). 4. [Integrate 1Password CLI with the 1Password app](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration). 5. Install [ZCLI.](https://developer.zendesk.com/documentation/apps/getting-started/using-zcli/#installing-and-updating-zcli) The following shells are supported: * Bash * Zsh * fish ## Step 1: Configure your default credentials To get started with the Zendesk CLI shell plugin:
  1. Sign in to the 1Password account you want to use with the Zendesk CLI plugin: op signin
  2. If you only want to configure the plugin in a specific directory, change to that directory.
  3. Run the command to set up the plugin: op plugin init zcli
You'll be prompted to import your Zendesk CLI credentials into 1Password or select an existing 1Password item where your credentials are saved, then configure when the credentials should be used. ![A terminal window displaying the op plugin init command and options to import or select an item.](/static/img/shell-plugins/zendesk-1.png) ### Step 1.1: Import or select an item #### Import a new item If you haven't saved your Zendesk CLI credentials in 1Password yet, select **Import into 1Password**. Enter your credentials, choose a name for the new 1Password item, and select the vault where you want to save it. If 1Password detects your credentials in your local development environment, you'll be automatically prompted to import them. ![A terminal window showing the fields available to import an item, including the token, item name, and vault.](/static/img/shell-plugins/zendesk-2.png) #### Select an existing item If you've already saved your Zendesk CLI credentials in 1Password, select **Search in 1Password**. You'll see a list of related items and the vaults where they're saved. If you don't see your credentials, select **Expand search** to browse all items in your account. ![A terminal window showing the option to search for an existing item in your 1Password account.](/static/img/shell-plugins/zendesk-3.png) ### Step 1.2: Set default credential scope After you select or import your credentials, you'll be prompted to configure when to use the item to authenticate Zendesk CLI. ![A terminal window showing the options for configuring when the credentials should be used.](/static/img/shell-plugins/zendesk-4.png)
  • **"Prompt me for each new terminal session"** will only configure the credentials for the duration of the current terminal session. Once you exit the terminal, the default will be removed.
  • **"Use automatically when in this directory or subdirectories"** will make the credentials the default in the current directory and all of its subdirectories, as long as no other directory-specific defaults are set in them. A terminal-session default takes precedence over a directory-specific one.
  • **"Use as global default on my system"** will set the credentials as the default in all terminal sessions and directories. A directory-specific default takes precedence over a global one.
## Step 2: Source the plugins.sh file To make the plugin available, source your `plugins.sh` file. For example: ```sh theme={null} source ~/.config/op/plugins.sh ``` The file path for your `op` folder may vary depending on your [configuration directory](/cli/config-directories/). `op plugin init` will output a source command with the correct file path. If this is your first time installing a shell plugin, you'll also need to add the source command to your RC file or shell profile to persist the plugin beyond the current terminal session. For example: echo "source \~/.config/op/plugins.sh" >> \~/.bashrc && source \~/.bashrc echo "source \~/.config/op/plugins.sh" >> \~/.zshrc && source \~/.zshrc echo "source \~/.config/op/plugins.sh" >> \~/.config/fish/config.fish && source \~/.config/fish/config.fish ## Step 3: Use the CLI The next time you enter a command with Zendesk CLI, you'll be prompted to authenticate with biometrics or system authentication. ![A CLI being authenticated using 1Password CLI biometric unlock.](https://mintcdn.com/ab-634991b8/MKy6sgNGqMk-yGDS/static/img/shell-plugins/zendesk-5.png?fit=max\&auto=format\&n=MKy6sgNGqMk-yGDS\&q=85\&s=20570515185c5d8530df285a0faf9f90) ## Step 4: Remove imported credentials from disk After saving your Zendesk CLI credentials in 1Password, you can remove all local copies you previously had stored on disk. ## Next steps 1Password Shell Plugins support [more than 60 third-party CLIs](/cli/shell-plugins/#get-started). To see a list of supported CLIs: op plugin list To choose another plugin to get started with: op plugin init To use shell plugins for seamless context switching, learn how to configure a plugin in [multiple environments](/cli/shell-plugins/environments/) or with [multiple accounts.](/cli/shell-plugins/multiple-accounts/) ## Get help ### Inspect your configuration To inspect your current Zendesk CLI configuration: op plugin inspect zcli 1Password CLI will return a list of the credentials you've configured to use with Zendesk CLI and their default scopes, as well as a list of aliases configured for Zendesk CLI. ![A terminal window showing the results of the command op plugin inspect.](https://mintcdn.com/ab-634991b8/MKy6sgNGqMk-yGDS/static/img/shell-plugins/zendesk-6.png?fit=max\&auto=format\&n=MKy6sgNGqMk-yGDS\&q=85\&s=f3cd3bd550f97a394f1102aef77b673f) ### Clear your credentials To reset the credentials used with Zendesk CLI: op plugin clear zcli You can clear one configuration at a time, in this order of precedence:
  1. Terminal session default
  2. Directory default, from the current directory to `$HOME`
  3. Global default
For example, if you're in the directory `$HOME/projects/awesomeProject` and you have a terminal session default, directory defaults for `$HOME` and `$HOME/projects/awesomeProject`, and a global default credential configured, you would need to run `op plugin clear zcli` four times to clear all of your defaults. To clear your global default credentials, terminal session default, and the defaults for your current directory at the same time, run `op plugin clear zcli --all`. ## Reference 1Password authenticates with Zendesk CLI by injecting environment variables with the credentials required by the plugin commands directly from your 1Password account. If you saved your Zendesk CLI credentials in 1Password manually rather than using `op plugin` to import a new item, make sure that your field names match the table below. If the item doesn't contain a field with the required name, you'll be prompted to rename one of the existing fields. | 1Password field name | Environment variable | | - | - | | Subdomain | `ZENDESK_SUBDOMAIN` | | Email | `ZENDESK_EMAIL` | | Token | `ZENDESK_API_TOKEN` | *Thanks to [@williamhpark](https://github.com/williamhpark) for [contributing this plugin!](https://github.com/1Password/shell-plugins/pull/207) Learn how to [build your own shell plugins](/cli/shell-plugins/contribute/).* ## Learn more
  • [Use shell plugins to switch between multiple environments](/cli/shell-plugins/environments/)
  • [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/)
  • [Build your own shell plugins](/cli/shell-plugins/contribute/)
  • [Workflow: Secure AI access](/get-started/secure-ai-access)
# Sign in to your 1Password account manually Source: https://www.1password.dev/cli/sign-in-manually If you don't want to [use the 1Password app to sign in to 1Password CLI](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration), you can manually add and sign in to your accounts in the terminal. > [!CAUTION] > > **Known security risks** > > If you sign in to 1Password CLI manually, any process running under the current user can, on some platforms, potentially access your 1Password account. > > We recommend you [use the 1Password app to sign in to 1Password CLI](/cli/app-integration/) because it offers more robust security guarantees. When you sign in manually in the terminal, 1Password CLI stores your session key encrypted on disk and the random wrapper key used in the environment of the current shell. Sessions expire after 30 minutes of inactivity, after which you’ll need to sign in again and save a new token. If you want to immediately terminate your authenticated session, you can run `op signout`. ## Sign in manually ### Step 1: Add an account To manually add a 1Password account to 1Password CLI, use [`op account add`](/cli/reference/management-commands/account/): ```shell theme={null} op account add ``` 1Password CLI will prompt you to enter your [sign-in address](https://support.1password.com/sign-in-troubleshooting#if-youre-asked-for-a-sign-in-address), email address, [Secret Key](https://support.1password.com/secret-key/), and 1Password account password. > [!TIP] > > For non-interactive shells in local environments, sign in with the [1Password desktop app integration](/cli/app-integration/) instead. > > For non-interactive shells in remote environments, authenticate with a [service account](/service-accounts/) or a [Connect server](/connect/). #### Set a custom account shorthand 1Password CLI uses account shorthands to refer to each of the accounts you add. The default shorthand is your [sign-in address](https://support.1password.com/sign-in-troubleshooting#if-youre-asked-for-a-sign-in-address) subdomain (for example, `my` for `my.1password.com`). To set a custom shorthand, include the `--shorthand` flag when you add an account. For example, to add an account with the shorthand `personal`: ```shell theme={null} op account add --shorthand personal ``` ### Step 2: Sign in If you added your accounts to 1Password CLI manually, you'll need to use the [manual sign-in command](/cli/reference/commands/signin/) to sign in. This command also works with the [app integration](/cli/app-integration) turned on, so you can use it in scripts to provide compatibility for all users regardless of their sign-in method. > [tab] Bash, Zsh, sh, fish > > ```shell theme={null} > eval "$(op signin)" > ``` > [tab] PowerShell > > ```powershell theme={null} > Invoke-Expression "$(op signin)" > ``` After you sign in, 1Password CLI creates a session token and sets the `OP_SESSION` environment variable to it. Include the `--raw` flag to get a token you can export manually. Session tokens expire after 30 minutes of inactivity, after which you’ll need to sign in again and save a new token. To sign out, use the command [`op signout`](/cli/reference/commands/signout/). ### Optional: Switch between accounts with the `--account` flag If you've added multiple accounts and are using an interactive terminal, 1Password CLI will prompt you to select the account you want to sign in to. Use the arrow keys to select an account, then press the Return key to sign in. In most shells, you can bypass the prompt to select an account using the `--account` flag with your [account shorthand, sign-in address, or ID](#appendix-find-an-account-shorthand-or-id). This option isn't available in PowerShell. For example: > [tab] Bash, Zsh, sh, fish > > ```shell theme={null} > eval "$(op signin --account personal)" > ``` To always sign in to the same account, set the `OP_ACCOUNT` environment variable to your [account shorthand, sign-in address, or ID](#appendix-find-an-account-shorthand-or-id). > [tab] Bash, Zsh, sh > > ```shell theme={null} > export OP_ACCOUNT=my.1password.com > ``` > [tab] fish > > ```shell theme={null} > set -x OP_ACCOUNT my.1password.com > ``` > [tab] PowerShell > > ```powershell theme={null} > $Env:OP_ACCOUNT = "my.1password.com" > ``` You can sign in to multiple accounts at the same time, then use the `--account` flag to specify which account should execute each command. If you don't specify an account, 1Password CLI will default to the account you most recently signed in to. For example, to sign in to accounts with the shorthands `personal` and `agilebits`: > [tab] Bash, Zsh, sh, fish > > ```shell theme={null} > eval "$(op signin --account personal)" && eval "$(op signin --account agilebits)" > ``` > [tab] PowerShell > > ```powershell theme={null} > Invoke-Expression "$(op signin --account personal)"; Invoke-Expression "$(op signin --account agilebits)" > ``` To run the command `op vault list` in the account with the shorthand `personal`: ```shell theme={null} op vault list --account personal ``` Then to run the same command in the `agilebits` account: ```shell theme={null} op vault list --account agilebits ``` You can also [specify a custom shorthand](#set-a-custom-account-shorthand) when you add an account. ## Troubleshooting If you've already [turned on the 1Password app integration](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration), you'll need to turn it off before you can add an account on the command line. ## Learn more * [Integrate 1Password CLI with the 1Password desktop app](/cli/app-integration/) * [About the security of the 1Password desktop app integration](/cli/app-integration-security/) ## Appendix: Find an account shorthand or ID 1Password CLI uses account shorthands to refer to each of the accounts you've added. To see all the accounts you've added, their shorthands, and account details, run `op account list`. ```shell theme={null} op account list #code-result SHORTHAND URL EMAIL USER UUID my https://my.1password.com wendy.c.appleseed@gmail.com A10S... agilebits https://agilebits-inc.1password.com wendy_appleseed@agilebits.com ONJ9... ``` You can use the shorthand, sign-in address, or user ID to refer to a specific account in your commands. # Unlock 1Password CLI with SSO Source: https://www.1password.dev/cli/sign-in-sso > [!NOTE] > > This feature is only available as part of [1Password Unlock with SSO](https://support.1password.com/sso/). If your 1Password administrator has [set up 1Password Unlock with SSO](https://support.1password.com/sso/), you can sign in to 1Password CLI with your identity provider. If the 1Password account you sign in to with SSO doesn't allow biometric unlock, you'll be prompted to allow 1Password CLI access to the 1Password app when you sign in. ## Requirements Before you start, you'll need to: 1. [Join your team](https://support.1password.com/explore/team-member/), or [switch to unlock with SSO](https://support.1password.com/sso-get-started/). 2. Install the latest version of 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux). 3. Sign in to 1Password for [Mac](https://support.1password.com/sso-sign-in/#in-the-apps/), [Windows](https://support.1password.com/sso-sign-in/#in-the-apps/), or [Linux](https://support.1password.com/sso-sign-in/#in-the-apps/) using SSO. 4. Install [the latest Password CLI build](/cli/get-started/). > [!TIP] > > **Installing inside WSL?** The desktop app integration authenticates over a local connection to the 1Password app on your Windows host, so it isn't available to a CLI binary installed inside the Linux side of WSL. Install 1Password CLI on Windows, then call the Windows `op.exe` from your WSL shell (or add it to your WSL `PATH`) — the same approach used by the [1Password SSH agent WSL integration](/ssh/integrations/wsl/). ## Step 1: Connect 1Password CLI with the 1Password app To turn on the app integration and set up 1Password CLI to authenticate with your identity provider: > [tab] Mac > > 1. Open and unlock the [1Password app](https://1password.com/downloads/). > 2. Select your account or collection at the top of the sidebar. > 3. Navigate to **Settings** > **Developer**. [Open Developer settings](onepassword://settings/developers) if 1Password is installed on this device. > 4. Select **Integrate with 1Password CLI**. > 5. If you want to authenticate 1Password CLI with your fingerprint, turn on **[Touch ID](https://support.1password.com/touch-id-mac/)** in the app. > > ![The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.](/static/img/developer-integrations-cli-light.png) > ![The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.](/static/img/developer-integrations-cli-dark.png) > [tab] Windows > > 1. Open and unlock the [1Password app](https://1password.com/downloads/). > 2. Select your account or collection at the top of the sidebar. > 3. Turn on **[Windows Hello](https://support.1password.com/windows-hello/)** in the app. > 4. Navigate to **Settings** > **Developer**. [Open Developer settings](onepassword://settings/developers) if 1Password is installed on this device. > 5. Select **Integrate with 1Password CLI**. > > ![The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.](/static/img/developer-integrations-cli-light.png) > ![The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.](/static/img/developer-integrations-cli-dark.png) > [tab] Linux > > 1. Open and unlock the [1Password app](https://1password.com/downloads/). > 2. Select your account or collection at the top of the sidebar. > 3. Navigate to **Settings** > **Security**. [Open Security settings](onepassword://settings/security) if 1Password is installed on this device. > 4. Turn on **[Unlock using system authentication](https://support.1password.com/system-authentication-linux/)**. > 5. Navigate to **Settings** > **Developer**. [Open Developer settings](onepassword://settings/developers) if 1Password is installed on this device. > 6. Select **Integrate with 1Password CLI**. > > ![The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.](/static/img/developer-integrations-cli-light.png) > ![The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.](/static/img/developer-integrations-cli-dark.png) ## Step 2: Sign in with SSO Once the 1Password app integration is turned on, open the terminal and type [`op signin`](/cli/get-started/#step-3-enter-any-command-to-sign-in). Use the arrow keys to select your SSO-enabled account from the list of all accounts added to your 1Password app. 1Password CLI will prompt you to authenticate. ```shell theme={null} op signin ``` ```shell highlight={2} theme={null} Select account [Use arrows to move, type to filter] > ACME Corp (acme.1password.com) AgileBits (agilebits.1password.com) Add another account ``` After you sign in for the first time, 1Password CLI will automatically sign in to your most recently used account. If you want to [sign in to a different account](/cli/use-multiple-accounts/), you can use the `--account` flag or an environment variable. ## Troubleshooting * **Prompted for a Secret Key instead of SSO?** This means the CLI is trying to sign in directly instead of through the app integration. Confirm the app integration is turned on (Step 1), then try again. * **If the account doesn't allow biometric unlock**, you'll be prompted to allow 1Password CLI access to the 1Password app the first time you sign in instead of using your fingerprint. * **Managed devices**: your organization's administrator controls who has 1Password Unlock with SSO turned on. If you don't see the option, check with your administrator. ## Get help If something isn't working, join the discussion in our [Developer community](/community) or ask in [Developer Slack](/joinslack). ## Learn more * [Set up 1Password Unlock with SSO](https://support.1password.com/sso/) * [Get started with 1Password Unlock with SSO](https://support.1password.com/sso-get-started/) * [Sign in to 1Password with SSO](https://support.1password.com/sso-sign-in/) * [Link new apps and browsers to unlock with SSO](https://support.1password.com/sso-linked-apps-browsers/) * [If you're having trouble unlocking 1Password with SSO](https://support.1password.com/sso-troubleshooting/) # Unlock 1Password CLI with Microsoft Source: https://www.1password.dev/cli/sign-in-sso-azure > [!NOTE] > > This feature is only available as part of the [Unlock with Microsoft beta](https://support.1password.com/cs/sso-azure/). If your 1Password administrator has [configured Unlock with SSO](https://support.1password.com/cs/sso-configure-azure/), you can sign in to 1Password CLI with Microsoft. During the beta period, Unlock with SSO will be available only for Microsoft using the OpenID Connect (OIDC) protocol. Additional platforms, identity providers, and protocols will be available in the future. If the 1Password account you sign in to with Microsoft doesn't allow biometric unlock, you'll be prompted to allow 1Password CLI access to the 1Password app when you sign in. ## Requirements Before you start, you'll need to: 1. [Join your team](https://support.1password.com/cs/sso-get-started-azure/#join-your-team), or [switch to unlock with Microsoft](https://support.1password.com/cs/sso-get-started-azure/#switch-to-unlock-with-microsoft). 2. Install the nightly release of 1Password for [Mac](https://support.1password.com/betas/?mac), [Windows](https://support.1password.com/betas/?windows), or [Linux](https://support.1password.com/betas/?linux). 3. Sign in to 1Password for [Mac](https://support.1password.com/cs/sso-sign-in-azure/#in-the-apps/), [Windows](https://support.1password.com/cs/sso-sign-in-azure/#in-the-apps/), or [Linux](https://support.1password.com/cs/sso-sign-in-azure/#in-the-apps/) using Microsoft. 4. Install [the latest 1Password CLI beta build](https://app-updates.agilebits.com/product_history/CLI2#beta). ## Step 1: Connect 1Password CLI with the 1Password app To turn on the app integration and set up 1Password CLI to authenticate with Microsoft: > [tab] Mac > > 1. Open and unlock the [1Password app](https://1password.com/downloads/). > 2. Select your account or collection at the top of the sidebar. > 3. Navigate to **Settings** > **Developer**. [Open Developer settings](onepassword://settings/developers) if 1Password is installed on this device. > 4. Select **Integrate with 1Password CLI**. > 5. If you want to authenticate 1Password CLI with your fingerprint, turn on **[Touch ID](https://support.1password.com/touch-id-mac/)** in the app. > > ![The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.](/static/img/developer-integrations-cli-light.png) > ![The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.](/static/img/developer-integrations-cli-dark.png) > [tab] Windows > > 1. Open and unlock the [1Password app](https://1password.com/downloads/). > 2. Select your account or collection at the top of the sidebar. > 3. Turn on **[Windows Hello](https://support.1password.com/windows-hello/)** in the app. > 4. Navigate to **Settings** > **Developer**. [Open Developer settings](onepassword://settings/developers) if 1Password is installed on this device. > 5. Select **Integrate with 1Password CLI**. > > ![The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.](/static/img/developer-integrations-cli-light.png) > ![The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.](/static/img/developer-integrations-cli-dark.png) > [tab] Linux > > 1. Open and unlock the [1Password app](https://1password.com/downloads/). > 2. Select your account or collection at the top of the sidebar. > 3. Navigate to **Settings** > **Security**. [Open Security settings](onepassword://settings/security) if 1Password is installed on this device. > 4. Turn on **[Unlock using system authentication](https://support.1password.com/system-authentication-linux/)**. > 5. Navigate to **Settings** > **Developer**. [Open Developer settings](onepassword://settings/developers) if 1Password is installed on this device. > 6. Select **Integrate with 1Password CLI**. > > ![The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.](/static/img/developer-integrations-cli-light.png) > ![The 1Password Developer settings pane with the Integrate with 1Password CLI option selected.](/static/img/developer-integrations-cli-dark.png) ## Step 2: Sign in with Microsoft Once the 1Password app integration is turned on, open the terminal and type [`op signin`](/cli/get-started/#step-3-enter-any-command-to-sign-in). Use the arrow keys to select your Microsoft-enabled account from the list of all accounts added to your 1Password app. 1Password CLI will prompt you to authenticate. ```shell theme={null} op signin ``` ```shell highlight={2} theme={null} Select account [Use arrows to move, type to filter] > ACME Corp (acme.1password.com) AgileBits (agilebits.1password.com) Add another account ``` After you sign in for the first time, 1Password CLI will automatically sign in to your most recently used account. If you want to [sign in to a different account](/cli/use-multiple-accounts/), you can use the `--account` flag or an environment variable. ## Get help If the 1Password account you sign in to with Microsoft doesn't allow biometric unlock, you'll be prompted to allow 1Password CLI access to the 1Password app when you sign in. ## Learn more * [About Unlock with Microsoft](https://support.1password.com/cs/sso-azure/) * [Configure Unlock 1Password with Microsoft](https://support.1password.com/cs/sso-configure-azure/) * [Get started with Unlock 1Password with Microsoft](https://support.1password.com/sso-get-started/) * [Sign in to 1Password with Microsoft](https://support.1password.com/cs/sso-sign-in-azure/) * [Link new apps and browsers to unlock with Microsoft](https://support.1password.com/sso-linked-apps-browsers/) * [If you're having trouble unlocking 1Password with SSO](https://support.1password.com/sso-troubleshooting/) # Manage SSH keys Source: https://www.1password.dev/cli/ssh-keys ## Requirements Before you can use 1Password CLI to manage your SSH keys, you'll need to: * [Sign up for 1Password](https://1password.com/pricing/password-manager). * [Install 1Password CLI](/cli/get-started#step-1-install-1password-cli) (`2.20.0` or later). ## Generate an SSH key You can use [`op item create`](/cli/reference/management-commands/item#item-create) with the `ssh` item category to generate a new SSH key. To import an existing SSH key, [use the 1Password desktop app](/ssh/manage-keys/#import-an-ssh-key). ```shell theme={null} op item create --category ssh --title "My SSH Key" ``` 1Password CLI generates an SSH key and saves it as a new item in 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, then prints the key to stdout with the private key redacted. The item includes the key type, private key, public key, and its fingerprint. By default, 1Password CLI creates an Ed25519 key. To create an RSA key instead, use the `--ssh-generate-key` flag to specify `RSA`. Include the number of bits to specify a custom size: 2048, 3072 or 4096 (default). For example, to generate a 2048-bit RSA key: ```shell theme={null} op item create --category ssh --title "RSA SSH Key" --ssh-generate-key RSA,2048 ``` ## Get a private key To get an SSH key's private key, use [`op read`](/cli/reference/commands/read/) with a [secret reference](/cli/secret-reference-syntax/) for the item's `private key` field. Include the `ssh-format` query parameter with `openssh` to get the private key in the OpenSSH format. ```shell theme={null} op read "op://Private/ssh keys/ssh key/private key?ssh-format=openssh" #code-result -----BEGIN OPENSSH PRIVATE KEY----- b3BlbnNzaC1rZXktdjEAAAAACmFlczI1Ni1jdHIAAAAGYmNyeXB0AAAAGAAAABD3rRrf8J ruD0CxZTYfpbTYAAAAEAAAAAEAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIJ5B/GnxX6t9jMwQ G7QE7r5daJLkMKTZhNZhWfvzK2y+AAAAkLgQAivYu/+12/YrZhK5keIAZf4ZgsZsZ2JI2q qbx23PqgO93oGy1iCxXe3kngQL4cM6lwOZPsZPKCinkN6KxEr6RnXqFRHJbMpOiGeZhTuD rjeo77HqFdxDqDeckB77XCKL0Ew28H5JlM/WO31XR3Z4VBAgTe+BQLjrFV8WU5UX38hpBJ PMJyRsK72ZUDDaGQ== -----END OPENSSH PRIVATE KEY----- ``` ## Learn more * [Supported SSH key types](/ssh/manage-keys#supported-ssh-key-types) * [Use 1Password for SSH & Git](/ssh/) * [Manage your SSH keys in the 1Password app](/ssh/manage-keys/) * [Sign your Git commits with SSH](/ssh/git-commit-signing/) * [Workflow: Secure your SSH & Git workflows](/get-started/secure-ssh-git-workflows) # Uninstall 1Password CLI Source: https://www.1password.dev/cli/uninstall > [!WARNING] > > Make sure you have access to your Secret Key and account password before removing 1Password account information from your device. ## Step 1: Remove your 1Password account information Your 1Password CLI configuration file contains account details for accounts you've signed in to on the command line using your account password and Secret Key. It does not contain information for accounts you've signed in to using the 1Password desktop app integration. Your config file can be found in one of the following locations: `~/.op/config`, `~/.config/op/config`, or `~/.config/.op/config`. To remove all account information from your config file: ```shell theme={null} op account forget --all ``` ## Step 2: Uninstall 1Password CLI > [tab] Mac > > **Mac** > > > [tab] homebrew > > > > To uninstall 1Password CLI with homebrew: > > > > ```shell theme={null} > > brew uninstall 1password-cli > > ``` > > > [tab] Manual > > > > To manually uninstall 1Password CLI, run: > > > > ```shell theme={null} > > rm /usr/local/bin/op > > ``` > [tab] Windows > > > [tab] Scoop > > > > To uninstall 1Password CLI with Scoop: > > > > ```powershell theme={null} > > scoop uninstall 1password-cli > > ``` > > > [tab] winget > > > > To uninstall 1Password CLI with winget: > > > > ```powershell theme={null} > > winget uninstall 1password-cli > > ``` > > > [tab] Manual > > > > To uninstall 1Password CLI on a Windows PC: > > > > 1. Open Powershell **as an administrator**. > > 2. Run the following command: > > > > ```shell theme={null} > > Remove-Item -Recurse -Force "C:\Program Files\1Password CLI" > > ``` > [tab] Linux > > To uninstall 1Password CLI on Linux, run: > > ```shell theme={null} > rm /usr/local/bin/op > ``` The 1Password CLI directory and all of its contents will be deleted. # Upgrade to 1Password CLI 2 Source: https://www.1password.dev/cli/upgrade *Learn how to [upgrade to 1Password CLI 2](#step-1-choose-an-upgrade-strategy) from an earlier version, and [update your scripts](#step-2-update-your-scripts) to the new command syntax.* > [!WARNING] > > **1Password CLI 1 is deprecated** > > 1Password CLI 1 is deprecated as of **October 1, 2024**. Upgrade to 1Password CLI 2 to avoid disruptions with scripts or integrations that use version 1. ### About 1Password CLI 2 We released version 2 of the 1Password CLI in March 2022. Since then, more than 96% of users have adopted the latest version. 1Password CLI 2 includes a number of changes to the schema to make the tool easier to use as well as new features to help you provision secrets. #### New schema 1Password CLI 2 introduces a noun-verb command structure that groups commands by topic rather than by operation. You can find all available topics with `op --help`, and see the commands avaialble for each topic with `op --help`. Topics include: * [vault](/cli/reference/management-commands/vault/) * [item](/cli/reference/management-commands/item/) * [document](/cli/reference/management-commands/document/) * [user](/cli/reference/management-commands/user/) * [group](/cli/reference/management-commands/group/) * [account](/cli/reference/management-commands/account/) * [connect](/cli/reference/management-commands/connect/) * [events-api](/cli/reference/management-commands/events-api/) Other schema changes include: * The default output is now a human-friendly, tabular schema.\ [Learn how to change the default output to JSON.](#json-default) * The JSON output schema now contains more useful information. * Improved stdin processing allows you to chain more commands together. * The new schema uses flags instead of positional arguments. #### Secrets provisioning To help you provision secrets locally, 1Password CLI 2 allows you to load secrets directly from 1Password in environment variables and configuration files. With secrets provisioning, you can replace your plaintext secrets with references to the secrets stored in 1Password and load them at runtime in your scripts, applications, and other workflows. #### Integrate 1Password CLI with the 1Password desktop app You can sign in to 1Password CLI 2 with the accounts you've added to the 1Password desktop app, then authenticate your accounts on the command line with biometrics. #### Shell plugins To simplify and secure your workflow, 1Password CLI 2 introduces shell plugins that allow you to securely authenticate third-party command-line tools using biometrics. #### Package manager installation 1Password CLI 2 supports easier installation with package managers including Apt, Yum, Alpine, and tar. You can [find all changes in the changelog](https://releases.1password.com/developers/cli/). To share feedback with us, [visit the support community forum](https://1password.community/categories/cli-beta). ## Step 1: Choose an upgrade strategy There are multiple ways to upgrade to 1Password CLI 2. You can upgrade immediately or gradually, depending on your workflow and toolchain. ### Upgrade immediately The quickest way to upgrade to 1Password CLI 2 is to overwrite your existing installation. This is a good option if you have a small team who can upgrade their local installations simultaneously. 1. Use `which op` (or `(Get-Command op).Path` on Windows) to get the directory of the current installation. 2. [Download 1Password CLI 2](https://app-updates.agilebits.com/product_history/CLI2) and move `op` to the same directory, overwriting the existing copy. 3. To verify the installation, check the version number: ```shell theme={null} op --version ``` 4. [Update your scripts to use the 1Password CLI 2 syntax.](#step-2-update-your-scripts) Make sure everyone on your team upgrades to 1Password CLI 2. After you update your scripts, they won't work with earlier versions of 1Password CLI. ### Upgrade gradually If you're not ready to upgrade immediately, you can use Docker to upgrade individual projects or use both versions of 1Password CLI side-by-side. We will continue to support version 1 for one year after version 2 is released. #### Use Docker to upgrade individual projects If you want to upgrade project by project, you can Dockerize your workflow so that each team member uses the version of 1Password CLI in a Docker image for a specific project. This is a good option for large teams, because it doesn't require each team member to update a local installation. 1. [Use the 1Password CLI Docker image](https://hub.docker.com/r/1password/op) or use your own image and [add the CLI](/cli/get-started/). Your Dockerfile should look like this: ``` FROM 1password/op:2 COPY ./your-script.sh /your-script.sh CMD ["/your-script.sh"] ``` 2. After upgrading to 1Password CLI 2, [update your scripts](#step-2-update-your-scripts) to use the new command syntax. This approach also sets you up to move your scripts to headless environments such as CI/CD pipelines. #### Use both versions of 1Password CLI If your scripts depend on the local installation on each team member's machine, and you still want to migrate gradually, this is your best option. Each team member should do the following: 1. Rename the earlier version of 1Password CLI `op1`. 2. Find and replace all occurences of `op` with `op1`. 3. Install [1Password CLI 2](https://app-updates.agilebits.com/product_history/CLI2) inside your `$PATH`. > [!WARNING] > > For macOS 1Password CLI 2 has to be moved *exactly* to `/usr/local/bin/op`.\\ > > For Linux, it is recommended to be moved to `/usr/local/bin/op`. 4. [Update your scripts](#step-2-update-your-scripts) one-by-one to use the new `op`. You can continue to use your current scripts with the earlier version of 1Password CLI installed as `op1`. 5. When you've updated all your scripts and are ready to upgrade, uninstall the earlier version of 1Password CLI. 6. Find and replace all occurrences of `op1` in your scripts to `op`. ## Step 2: Update your scripts If you've been using an earlier version of 1Password CLI in scripts, you'll need to update your scripts to the new syntax. After you install 1Password CLI 2, use the following table to update your scripts. It shows all the updated commands and associated changes to arguments or flags. | Old command | CLI 2 command | Notes | | - | - | - | | [create vault](/cli/v1/reference/#create-vault) | [vault create](/cli/reference/management-commands/vault/#vault-create) | | | [get vault](/cli/v1/reference/#get-vault) | [vault get](/cli/reference/management-commands/vault/#vault-get) | | | [edit vault](/cli/v1/reference/#edit-vault) | [vault edit](/cli/reference/management-commands/vault/#vault-edit) | `--travel-mode=on/off` flag introduced | | [delete vault](/cli/v1/reference/#delete-vault) | [vault delete](/cli/reference/management-commands/vault/#vault-delete) | allows piped input when the `-` argument is provided | | [list vaults](/cli/v1/reference/#list-vaults) | [vault list](/cli/reference/management-commands/vault/#vault-list) |
  • by default, lists vaults you have read access to
  • to see all the vaults you can manage, include `--permission manage`
| | [list users --vault](/cli/v1/reference/#list-users) | [vault user list](/cli/reference/management-commands/vault/#vault-user-list) | | | [add group](/cli/v1/reference/#add-group) | [vault group grant](/cli/reference/management-commands/vault/#vault-group-grant) |
  • `--permission` flag must be used to specify the permissions to grant
  • granting allow\_viewing, allow\_editing and allow\_managing is equivalent to granting all permissions
  • `group` and `vault` arguments changed to `--group` and `--vault` flags
| | [remove group](/cli/v1/reference/#remove-group) | [vault group revoke](/cli/reference/management-commands/vault/#vault-group-revoke) |
  • `--permission` flag must be used to specify the permissions to revoke
  • revoking allow\_viewing, allow\_editing, and allow\_managing is equivalent to revoking all permissions
  • `group` and `vault` arguments changed to `--group` and `--vault` flags
| | [add user](/cli/v1/reference/#add-user) \ \ | [vault user grant](/cli/reference/management-commands/vault/#vault-user-grant) |
  • `--permission` flag must be used to specify the permissions to grant
  • granting allow\_viewing, allow\_editing and allow\_managing is equivalent to granting all permissions
  • `user` and `vault` arguments changed to `--user` and `--vault` flags
| | [remove user](/cli/v1/reference/#remove-user) \ \ | [vault user revoke](/cli/reference/management-commands/vault/#vault-user-revoke) |
  • `--permission` flag must be used to specify the permissions to revoke
  • revoking allow\_viewing, allow\_editing and allow\_managing is equivalent to revoking all permissions
  • `user` and `vault` arguments changed to `--user` and `--vault` flags
| | [signin](/cli/v1/reference/#signin) \ | [account add](/cli/reference/management-commands/account/#account-add) |
  • for new accounts/urls
  • the password can be piped in if email, address, and secret key are provided via flag
| | [signin](/cli/v1/reference/#signin) --list | [account list](/cli/reference/management-commands/account/#account-list) | account list will format its output based on output format selection (JSON vs human readable) | | [forget account](/cli/v1/reference/#forget) | [account forget](/cli/reference/management-commands/account/#account-forget) | new `-—all` flag for forgetting all accounts | | [get account](/cli/v1/reference/#get-account) | [account get](/cli/reference/management-commands/account/#account-get) | | | [confirm user](/cli/v1/reference/#confirm) | [user confirm](/cli/reference/management-commands/user/#user-confirm) | allows piped input when the `-` argument is provided | | [create user](/cli/v1/reference/#create-user) | [user provision](/cli/reference/management-commands/user/#user-provision) | `email` and `name` arguments changed to `--email` and `--name` flags | | [delete user](/cli/v1/reference/#delete-user) | [user delete](/cli/reference/management-commands/user/#user-delete) | allows piped input when the `-` argument is provided | | [edit user](/cli/v1/reference/#edit-user) | [user edit](/cli/reference/management-commands/user#user-edit) | allows piped input when the `-` argument is provided | | [reactivate user](/cli/v1/reference/#reactivate) | [user reactivate](/cli/reference/management-commands/user/#user-reactivate) | allows piped input when the `-` argument is provided | | [suspend user](/cli/v1/reference/#suspend) | [user suspend](/cli/reference/management-commands/user/#user-suspend) | `--deauthorize-devices-after` flag accepts any duration unit, not just seconds | | [list users](/cli/v1/reference/#list-users) | [user list](/cli/reference/management-commands/user#user-list) | | | [get user](/cli/v1/reference/#get-user) | [user get](/cli/reference/management-commands/user/#user-get) |
  • added `-—me` flag to get the currently authenticated user
  • `—publickey` changed to `—public-key`
| | [create connect server](/cli/v1/reference/#create-connect-server) | [connect server create](/cli/reference/management-commands/connect/#connect-server-create) | add `—-server` flag instead of using an argument for specifying the related server | | [delete connect server](/cli/v1/reference/#delete-connect-server) | [connect server delete](/cli/reference/management-commands/connect/#connect-server-delete) | allows piped input when the `-` argument is provided | | [edit connect server](/cli/v1/reference/#edit-connect-server) | [connect server edit](/cli/reference/management-commands/connect/#connect-server-edit) | | | [list connect servers](/cli/v1/reference/#list-connect-servers) | [connect server list](/cli/reference/management-commands/connect/#connect-server-list) | | | - | [connect server get](/cli/reference/management-commands/connect/#connect-server-get) | | | [create connect token](/cli/v1/reference/#create-connect-token) | [connect token create](/cli/reference/management-commands/connect/#connect-token-create) | | | [delete connect token](/cli/v1/reference/#delete-connect-token) | [connect token delete](/cli/reference/management-commands/connect/#connect-token-delete) | | | [edit connect token](/cli/v1/reference/#edit-connect-token) | [connect token edit](/cli/reference/management-commands/connect/#connect-token-edit) | argument name changed from `jti` to `token` | | [list connect tokens](/cli/v1/reference/#list-connect-tokens) | [connect token list](/cli/reference/management-commands/connect/#connect-token-list) | ConnectVault.ACL is now displayed in lowercase\_with\_underscores | | [add connect server](/cli/v1/reference/#add-connect-server) | [connect vault grant](/cli/reference/management-commands/connect/#connect-vault-grant) | `server` and `vault` arguments changed to `--server` and `--vault` flags | | [remove connect server](/cli/v1/reference/#remove-connect-server) | [connect vault revoke](/cli/reference/management-commands/connect/#connect-vault-revoke) | `server` and `vault` arguments changed to `--server` and `--vault` flags | | [manage connect add group](/cli/v1/reference/#manage-connect-add) | [connect group grant](/cli/reference/management-commands/connect/#connect-group-grant) | `server` and `group` arguments changed to `--server` and `--group` flags | | [manage connect remove group](/cli/v1/reference/#manage-connect-remove) | [connect group revoke](/cli/reference/management-commands/connect/#connect-group-revoke) | `server` and `group` arguments changed to `--server` and `--group` flags | | [create item](/cli/v1/reference/#create-item) | [item create](/cli/reference/management-commands/item/#item-create) |
  • `--template` flag to specify item template file replaces encode item as an argument
  • `category` argument changed to `--category` flag
  • Template JSON format has changed. [Learn more about the new format.](#appendix-json)
| | [delete item](/cli/v1/reference/#delete-item) | [item delete](/cli/reference/management-commands/item/#item-delete) | allows piped input when the `-` argument is provided | | [edit item](/cli/v1/reference/#edit-item) | [item edit](/cli/reference/management-commands/item/#item-edit) | new `--tags`, `--title`, `--url` flags | | [get item](/cli/v1/reference/#get-item) | [item get](/cli/reference/management-commands/item/#item-get) | | | [list items](/cli/v1/reference/#list-items) | [item list](/cli/reference/management-commands/item/#item-list) | | | [list templates](/cli/v1/reference/#list-templates) | [item template list](/cli/reference/management-commands/item/#item-template-list) | | | [get template](/cli/v1/reference/#get-template) | [item template get](/cli/reference/management-commands/item/#item-template-get) | | | [create group](/cli/v1/reference/#create-group) | [group create](/cli/reference/management-commands/group/#group-create) | | | [delete group](/cli/v1/reference/#delete-group) | [group delete](/cli/reference/management-commands/group/#group-delete) | allows piped input when the `-` argument is provided | | [edit group](/cli/v1/reference/#edit-group) | [group edit](/cli/reference/management-commands/group/#group-edit) | allows piped input when the `-` argument is provided | | [list groups](/cli/v1/reference/#list-groups) | [group list](/cli/reference/management-commands/group/#group-list) | | | [get group](/cli/v1/reference/#get-group) | [group get](/cli/reference/management-commands/group/#group-get) | | | [add user](/cli/v1/reference/#add-user) \ \ | [group user grant](/cli/reference/management-commands/group/#group-user-grant) | `user` and `group` arguments changed to `--user` and `--group` flags | | [remove user](/cli/v1/reference/#remove-user) \ \ | [group user revoke](/cli/reference/management-commands/group/#group-user-revoke) | `user` and `group` args changed to `--user` and `--group` flags | | [op list users --group \](/cli/v1/reference/#list-users) | [group user list](/cli/reference/management-commands/group/#group-user-list) | op list users `--group GROUP` still works | | [delete trash](/cli/v1/reference/#delete-trash) | - | deprecated | | [create document](/cli/v1/reference/#create-document) | [document create](/cli/reference/management-commands/document/#document-create) | `--filename` flag changed to `--file-name` flag | | [edit document](/cli/v1/reference/#edit-document) | [document edit](/cli/reference/management-commands/document/#document-edit) | `--filename` flag changed to `--file-name` flag | | [list documents](/cli/v1/reference/#list-documents) | [document list](/cli/reference/management-commands/document/#document-list) | | | [get document](/cli/v1/reference/#get-document) | [document get](/cli/reference/management-commands/document/#document-get) | | | [delete document](/cli/v1/reference/#delete-document) | [document delete](/cli/reference/management-commands/document/#document-delete) | | | [create integration events-api](/cli/v1/reference/#create-integration-events-api) | [events-api create](/cli/reference/management-commands/events-api/#events-api-create) | | | [list events](/cli/v1/reference/#list-events) | - | Use [1Password Events API](/events-api/) instead. | | [encode](/cli/v1/reference/#encode) | - | deprecated, use `create item --template=file.json` instead | | [get totp](/cli/v1/reference/#get-totp) | [item get --otp](/cli/reference/management-commands/item/#item-get) | | ## Appendix: Change default output to JSON The default output format for 1Password CLI 2 is a human-readable, tabular schema. You can change the default to machine-readable JSON in two ways: * For a single command, include the `--format json` flag with your command. For example, `op item get --format json`. * To always default to JSON, set the `$OP_FORMAT` environment variable to `json`. ## Appendix: Item JSON template You can expect to see several formatting improvements and field name changes in 1Password CLI 2 [item JSON templates](/cli/item-template-json/). **Old template** ```json theme={null} { "fields": [ { "designation": "username", "name": "username", "type": "T", "value": "" }, { "designation": "password", "name": "password", "type": "P", "value": "" } ], "notesPlain": "", "passwordHistory": [], "sections": [] } ``` **New template** ```json theme={null} { "title": "", "category": "LOGIN", "fields": [ { "id": "username", "type": "STRING", "purpose": "USERNAME", "label": "username", "value": "" }, { "id": "password", "type": "CONCEALED", "purpose": "PASSWORD", "label": "password", "value": "" }, { "id": "notesPlain", "type": "STRING", "purpose": "NOTES", "label": "notesPlain", "value": "" } ] } ``` This is how 1Password CLI 1 template fields correspond to 1Password CLI 2: **Item** | 1Password CLI 1 | 1Password CLI 2 | Notes | | - | - | - | | `uuid` | | | | `templateUuid` | `category` | | | `details` | - | replaced by `sections` and `fields` | **Section** | 1Password CLI 1 | 1Password CLI 2 | Notes | | - | - | - | | `name` | `id` | | | `title` | `label` | | | `fields` | - | moved separately | **Field** | 1Password CLI 1 | 1Password CLI 2 | | - | - | | `n` | `id` | | `k` | `type` | | `t` | `label` | | `v` | `value` | | - | `section` | ## Get help If you need help upgrading to 1Password CLI 2, [contact 1Password Support](mailto:integrations@1password.com) or join our [Developer Slack workspace](/joinslack) and ask a question in the `#cli` channel. ## Learn more * [Get started with 1Password CLI 2](/cli/get-started/) * [1Password CLI 2 release notes](https://releases.1password.com/developers/cli/) # Use cases Source: https://www.1password.dev/cli/use-cases 1Password CLI allows you to securely provision secrets in development environments, use scripts to manage items and provision team members at scale, and authenticate with biometrics in the terminal. ## Eliminate plaintext secrets in code ![A 1Password Environment with several secrets added to it.](/static/img/environments/overview/environments-app-light.png) You can store your project secrets in [1Password Environments](/environments), then use 1Password CLI to [securely read those secrets into your applications and scripts](/cli/secrets-environment-variables). Environments are dynamic: if you update your variables in 1Password, the changes will be reflected in your project without needing to update the code directly. You can also share Environments with other people on your team, so everyone can stay in sync. For example, you can create an Environment for a development context, like `iOS App Staging`, then use [`op run --environment `](/cli/reference/commands/run#load-variables-from-environments) to provision your app with your staging secrets. Changing to a different development context like production is as simple as pointing to a different ID associated with an Environment that stores your production values. > [!TIP] > > You can also replace hardcoded secrets in your code using [secret references](/cli/secret-references). ### Learn more * [Load secrets into the environment](/cli/secrets-environment-variables) * [Get started with 1Password Environments](/environments) * [Workflow: Secure local development](/get-started/secure-developer-secrets) ## Automate administrative tasks ![1password.com open to show the people who have access to a vault alongside a terminal window displaying the same information.](https://mintcdn.com/ab-634991b8/pfc4yDcmGyZA8XDs/static/img/cli/use-case-it-top.png?fit=max\&auto=format\&n=pfc4yDcmGyZA8XDs\&q=85\&s=add7cd0bb39fd4af3f4a4626fc41e397) With 1Password CLI, IT administrators can set up scripts to automate common tasks, like [provisioning users](/cli/provision-users/), [managing permissions](/cli/grant-revoke-vault-permissions/), [managing items](/cli/reference/management-commands/item/), and generating custom reports. For example, this script will loop through each vault the person who runs the script has access to and provide: * the vault name * the number of items in the vault * the last time the vault's contents were updated * the users and groups that have access to the vault along with their permissions ```bash vault_details.sh theme={null} #!/usr/bin/env bash for vault in $(op vault list --format=json | jq --raw-output '.[] .id') do echo "" echo "Vault Details" op vault get $vault --format=json | jq -r '.|{name, items, updated_at}' sleep 1 echo "" echo "Users" op vault user list $vault sleep 1 echo "" echo "Groups" op vault group list $vault sleep 1 echo "" echo "End of Vault Details" sleep 2 clear echo "" echo "" done ``` ### Learn more See our [repository of example 1Password CLI scripts](https://github.com/1Password/solutions) for inspiration for your own projects. You'll find scripts that can help you: * [Provision new users from a CSV](https://github.com/1Password/solutions/tree/main/1password/scripted-provisioning/) * [Audit or manage existing users](https://github.com/1Password/solutions/tree/main/1password/user-management/) - [Manage your vaults and groups](https://github.com/1Password/solutions/tree/main/1password/account-management/) - [Create, update, and share items](https://github.com/1Password/solutions/tree/main/1password/item-management/) To learn more about how to accomplish these tasks with 1Password CLI, see the following guides: * [Create items](/cli/item-create/) * [Add and remove team members](/cli/provision-users/) * [Grant and revoke vault permissions](/cli/grant-revoke-vault-permissions/) ## Sign in to any CLI with your fingerprint With our [shell plugin ecosystem](/cli/shell-plugins/), you can use 1Password to securely authenticate all your command-line tools. Store your CLI access credentials in your 1Password vaults then sign in to your CLIs with your fingerprint instead of entering your credentials manually or storing them in an unencrypted format on your computer. Shell plugins unlock the ability to securely share credentials between team members. Store a token in a shared 1Password vault, and all people with access to the vault will be able to sign in with them. And you can use shell plugins across [multiple environments](/cli/shell-plugins/environments/), so you don't have to spend time signing in and out between projects. For example, the [ngrok shell plugin](/cli/shell-plugins/ngrok/) can securely tunnel the local app to the internet for a web development project running on your computer. The ngrok authtoken is not stored anywhere on the computer. When the ngrok CLI is run, the shell plugin provisions the authtoken as an environment variable for the ngrok binary to consume, and when the process exits, the environment variable is cleared. ### Learn more Get started with one of our most popular shell plugins: [GitHub](/cli/shell-plugins/github/) [AWS](/cli/shell-plugins/aws/) [Homebrew](/cli/shell-plugins/homebrew/) [GitLab](/cli/shell-plugins/gitlab/) [OpenAI](/cli/shell-plugins/openai/) [postgresql](/cli/shell-plugins/postgresql/) [Terraform](/cli/shell-plugins/terraform/) [DigitalOcean](/cli/shell-plugins/digitalocean/) [Heroku](/cli/shell-plugins/heroku/) [ngrok](/cli/shell-plugins/ngrok/) [CircleCI](/cli/shell-plugins/circleci/) [Vault](/cli/shell-plugins/hashicorp-vault/) Or choose a plugin from [our library of more than 40 command-line tools](/cli/shell-plugins/) to get started with. If the tool you want to use isn't supported yet, you can [build your own plugin](/cli/shell-plugins/contribute/). You can also: * [Test shell plugins](/cli/shell-plugins/test/) * [Use shell plugins to switch between environments](/cli/shell-plugins/environments/) * [Use shell plugins with multiple accounts](/cli/shell-plugins/multiple-accounts/) # Use multiple 1Password accounts with 1Password CLI Source: https://www.1password.dev/cli/use-multiple-accounts When you [use the 1Password desktop app integration to sign in to 1Password CLI](/cli/app-integration/), you can access any 1Password account you've added to the app on the command line. By default, all 1Password CLI commands are executed with the account you most recently signed in to, unless an account is specified with the [`--account` flag](#specify-an-account-per-command-with-the-account-flag). ## Choose an account to sign in to with `op signin` To choose an account to sign in to, run [`op signin`](/cli/reference/commands/signin/) and select the account you want to sign in to from the list of accounts added to your 1Password app. ```shell highlight={2} theme={null} op signin #code-result Select account [Use arrows to move, type to filter] > ACME Corp (acme.1password.com) AgileBits (agilebits.1password.com) Add another account ``` If you don't see the account you want to use, you may need to [add it to the 1Password app](https://support.1password.com/add-account/). ## Specify an account per command with the `--account` flag You can execute a command with a specific account by including the `--account` flag along with the account's [sign-in address (with or without https://) or ID](#find-an-account-sign-in-address-or-id). For example, to get a list of all vaults in an account with the sign-in address `my.1password.com`: ```shell theme={null} op vault ls --account my.1password.com ``` You can use the `--account` flag to specify different accounts in scripts. For example: ```shell theme={null} PASSWORD_1="$(op read --account agilebits-inc.1password.com op://my-vault/some-item/password)" PASSWORD_2="$(op read --account acme.1password.com op://other-vault/other-item/password)" ``` ## Set an account with the `OP_ACCOUNT` environment variable If you only want to sign in to a specific account, set the `OP_ACCOUNT` environment variable to the account's [sign-in address or ID](#find-an-account-sign-in-address-or-id). You can also use this to specify an account in scripts. > [tab] Bash, Zsh, sh > > ```shell theme={null} > export OP_ACCOUNT=my.1password.com > ``` > [tab] fish > > ```shell theme={null} > set -x OP_ACCOUNT my.1password.com > ``` > [tab] PowerShell > > ```powershell theme={null} > $Env:OP_ACCOUNT = "my.1password.com" > ``` ## Find an account sign-in address or ID To find details about all the accounts you've added to the 1Password app, run `op account list`. ```shell theme={null} op account list #code-result $ op account list URL EMAIL USER ID my.1password.com wendy.c.appleseed@gmail.com JDFU... agilebits-inc.1password.com wendy_appleseed@agilebits.com ASDU... ``` You can use the sign-in address listed under `URL` or the unique identifier listed under `USER ID` to refer to the account. ## Learn more * [Use the 1Password desktop app to sign in to 1Password CLI](/cli/app-integration/) # User states Source: https://www.1password.dev/cli/user-states When you fetch information about users with [`op user list`](/cli/reference/management-commands/user#user-list) or [`op user get`](/cli/reference/management-commands/user#user-get), 1Password CLI returns each person's current account state. | User state | Description | | - | - | | `ACTIVE` | The user is active. | | `RECOVERY_STARTED` | [Account recovery](/cli/recover-users) has been started for the user. | | `RECOVERY_ACCEPTED` | The user has created their new account password and is waiting to be [confirmed again by an administrator](https://support.1password.com/recovery/#complete-recovery). | | `SUSPENDED` | The user is suspended. | | `TRANSFER_STARTED` | The user has been provisioned, but hasn't set up their account. | | `TRANSFER_SUSPENDED` | The user was provisioned and didn't set up their account before they were deprovisioned. | # About vault permissions Source: https://www.1password.dev/cli/vault-permissions When using scripts to [grant or revoke vault permissions](/cli/grant-revoke-vault-permissions/), you must include any dependent permissions in the command. The vault permissions available to you depend on your 1Password account type. > [tab] 1Password Business > > 1Password Business includes the following permissions: > > * **view\_items**: view items in a vault. > * **create\_items**: create items in a vault. > * **edit\_items**: edit items in a vault. > * **archive\_items**: archive items in a vault. > * **delete\_items**: delete items in a vault. > * **view\_and\_copy\_passwords**: view concealed passwords and copy them to the clipboard. > * **view\_item\_history**: view and restore previous versions of items in the vault. > * **import\_items**: move or copy items into the vault. > * **export\_items**: save items in the vault to an unencrypted file that other apps can read. > * **copy\_and\_share\_items**: copy items between vaults, or share them outside of 1Password. > * **print\_items**: print the contents of items in the vault > * **manage\_vault**: allows a team member to grant and revoke access to the vault, change permissions for others, and delete the vault. Owners will always have permission to manage vaults. > > 1Password Business also includes the broader permissions available in 1Password Teams: > > * **allow\_viewing**: view items in a vault, view concealed passwords and copy them to the clipboard. > * Includes the granular permissions: `view_items`, `view_and_copy_passwords`, `view_item_history`. > * **allow\_editing**: create, edit, move, print, copy, archive, and delete items in the vault. > * Includes the granular permissions: `create_items`, `edit_items`, `archive_items`, `delete_items`, `import_items`, `export_items`, `copy_and_share_items`, `print_items`. > * **allow\_managing**: grant and revoke access to the vault, change permissions for others, and delete the vault. Owners will always have permission to manage vaults. > * Includes the granular permission: `manage_vault`. > > The vault permission `move_items` is automatically added when the permissions below are all added: > > ``` > view_items, edit_items, archive_items, view_and_copy_passwords, > view_item_history, copy_and_share_items > ``` > > In order to move an item, a user must have access to both the vault where an item is located and the destination vault. > > **Permission dependencies** > > In 1Password Business, all vault permissions have a hierarchical relationship in which narrower permissions require broader permissions to be granted alongside them. Permission dependencies are cumulative, so if a narrower permission is several levels down, it requires all of the broader permissions above it. > > For example, to grant the narrower permission `delete_items` you must also grant the permissions `edit_items`, `view_and_copy_passwords`, and `view_items`. > > Similarly, to revoke a broader permission like `view_items`, any narrower dependent permissions that have already been granted must be revoked alongside it. > > ![Vault permissions presented as a taxonomic tree](https://mintcdn.com/ab-634991b8/pfc4yDcmGyZA8XDs/static/img/cli/vault-permissions.png?fit=max\&auto=format\&n=pfc4yDcmGyZA8XDs\&q=85\&s=4c50f5dab809ecd600b29a2194b4556a) > > | permission | requirements | > | - | - | > | `create_items` | `view_items` | > | `view_and_copy_passwords` | `view_items` | > | `edit_items` | `view_and_copy_passwords` , `view_items` | > | `archive_items` | `edit_items`, `view_and_copy_passwords`, `view_items` | > | `delete_items` | `edit_items`, `view_and_copy_passwords`, `view_items` | > | `view_item_history` | `view_and_copy_passwords`, `view_items` | > | `import_items` | `create_items`, `view_items` | > | `export_items` | `view_item_history`, `view_and_copy_passwords`, `view_items` | > | `copy_and_share_items` | `view_item_history`, `view_and_copy_passwords`, `view_items` | > | `print_items` | `view_item_history`, `view_and_copy_passwords`, `view_items` | > [tab] 1Password Teams > > 1Password Teams includes three permissions: > > * **allow\_viewing**: view items in a vault, view concealed passwords and copy them to the clipboard. > * Includes the granular permissions: `view_items`, `view_and_copy_passwords`, `view_item_history`. > * **allow\_editing**: create, edit, move, print, copy, archive, and delete items in the vault. > * Includes the granular permissions: `create_items`, `edit_items`, `archive_items`, `delete_items`, `import_items`, `export_items`, `copy_and_share_items`, `print_items`. > * **allow\_managing**: grant and revoke access to the vault, change permissions for others, and delete the vault. Owners will always have permission to manage vaults. > * Includes the granular permission: `manage_vault`. > > **Permission dependencies** > > | permission | requirements | > | - | - | > | `allow_editing` | `allow_viewing` | > | `allow_managing` | | > > To grant the permission `allow_editing`, you must also grant the broader permission `allow_viewing`. Similarly, to revoke `allow_viewing`, you must also revoke `allow_editing`. > [tab] 1Password Families > > 1Password Families includes three permissions: > > * **allow\_viewing**: view items in a vault, view concealed passwords and copy them to the clipboard. > * Includes the granular permissions: `view_items`, `view_and_copy_passwords`, `view_item_history`. > * **allow\_editing**: create, edit, move, print, copy, archive, and delete items in the vault. > * Includes the granular permissions: `create_items`, `edit_items`, `archive_items`, `delete_items`, `import_items`, `export_items`, `copy_and_share_items`, `print_items`. > * **allow\_managing**: grant and revoke access to the vault, change permissions for others, and delete the vault. Owners will always have permission to manage vaults. > * Includes the granular permission: `manage_vault`. > > **Permission dependencies** > > | permission | requirements | > | - | - | > | `allow_editing` | `allow_viewing` | > | `allow_managing` | | > > To grant the permission `allow_editing`, you must also grant the broader permission `allow_viewing`. Similarly, to revoke `allow_viewing`, you must also revoke `allow_editing`. ## Learn more * [Grant and revoke vault permissions](/cli/grant-revoke-vault-permissions/) * [Work with vaults](/cli/reference/management-commands/vault/) * [Workflow: Programmatically manage your organization](/get-started/manage-organization) # Verify the authenticity of 1Password CLI Source: https://www.1password.dev/cli/verify To confirm the authenticity of 1Password CLI, the tool and all its updates are digitally signed and offered exclusively by 1Password. Always get updates directly from 1Password, and always [check to make sure that you have the latest version](/cli/reference/update/). > [tab] Mac > > ### ZIP file > > To confirm that the contents of the 1Password CLI ZIP file are authentic, unzip the file, then run the following command in the unzipped folder: > > ```shell theme={null} > gpg --keyserver keyserver.ubuntu.com --receive-keys 3FEF9748469ADBE15DA7CA80AC2D62742012EA22 > gpg --verify op.sig op > ``` > > ### Package file > > To confirm the 1Password CLI installer file is authentic, you can verify the digital signature before installation. > > 1. Open the 1Password CLI installer. If you see "This package will run a program to determine if the software can be installed", select **Continue**. This will not begin the installation. > 2. Select the lock icon in the top right corner of the installer window. If you don't see the lock icon, the package is unsigned, and you shouldn't install it. > 3. Select **Developer ID Installer: AgileBits Inc. (2BUA8C4S2C)**. If you see a different developer ID, or the certificate doesn't have a green checkmark indicating that it's valid, don't install the package. > 4. Select the triangle next to Details and scroll down. > 5. Make sure that the SHA-256 fingerprint in the installer matches one of the following fingerprints. If they match, the signature is verified. Select **OK** and continue installation. > > ![The 1Password CLI installer window showing the developer ID and fingerprints.](https://mintcdn.com/ab-634991b8/pfc4yDcmGyZA8XDs/static/img/cli/cli-fingerprint-2025.png?fit=max\&auto=format\&n=pfc4yDcmGyZA8XDs\&q=85\&s=0a986955341e3f20a3218ed5cff4c743) > > | Hash | Fingerprint | > | - | - | > | SHA‑256 | CA B5 78 06 1B 02 09 FB 70 93 4D A3 44 EF 6F EB CD 32 79 B1 C0 74 C5 4B 0D 7D 55 57 43 B9 D8 9F | > | SHA‑256 | 14 1D D8 7B 2B 23 12 11 F1 44 08 49 79 80 07 DF 62 1D E6 EB 3D AB 98 5B C9 64 EE 97 04 C4 A1 C1 | > > The installer automatically verifies the files in the package. If any file has an issue, installation stops without changes to your system, and you'll see a message that the installer encountered an error. > [tab] Windows > > To confirm the 1Password CLI installer for Windows is authentic, verify that the signing certificate for `op.exe` was issued to AgileBits by Microsoft Corporation, and that the [Extended Key Usage (EKU)](https://learn.microsoft.com/azure/artifact-signing/concept-certificate-management#subscriber-identity-validation-eku) is correct. > > 1. Open PowerShell as an Administrator. > > 2. Verify that the certificate was issued to AgileBits: > > ```powershell theme={null} > Get-AuthenticodeSignature -FilePath .\op.exe | Select-Object -ExpandProperty SignerCertificate | Select-Object Subject > #code-result open > Subject > ------- > CN=Agilebits, O=Agilebits, L=Toronto, S=Ontario, C=CA > ``` > > 3. Verify the certificate was issued by Microsoft Corporation: > > ```powershell theme={null} > Get-AuthenticodeSignature -FilePath .\op.exe | Select-Object -ExpandProperty SignerCertificate | Select-Object Issuer > #code-result open > Issuer > ------ > CN=Microsoft ID Verified CS AOC CA 02, O=Microsoft Corporation, C=US > ``` > > 4. Verify the EKU matches 1Password's EKU of `1.3.6.1.4.1.311.97.661420558.769123285.207353056.500447802`: > > ```powershell theme={null} > Get-AuthenticodeSignature -FilePath .\op.exe | Select-Object -ExpandProperty SignerCertificate | Select-Object -ExpandProperty EnhancedKeyUsageList > #code-result open > FriendlyName ObjectId > ------------ -------- > 1.3.6.1.4.1.311.97.1.0 > Code Signing 1.3.6.1.5.5.7.3.3 > 1.3.6.1.4.1.311.97.661420558.769123285.207353056.500447802 > ``` # Developer community Source: https://www.1password.dev/community Join the 1Password developer community: upcoming events, Developer Slack, the developer newsletter, and open source projects. Meet the people building with 1Password. Come to an event, ask questions in Slack, get updates in your inbox, and contribute to our open source projects. ## Join the conversation > [card] [Developer Slack](/joinslack) > > Ask questions in product channels (`#cli`, `#sdk`, `#ssh-agent-config`, and more) and hear about events first. > [card] [Developer newsletter](https://1password.com/developer-newsletter) > > Product updates, new guides, and upcoming events for 1Password developer tools in your inbox. > [card] [Events](#upcoming-events) > > Meetups, workshops, and office hours with the 1Password developer team, in person and online. ## Open source We build a lot of our developer tools in the open, from SDKs and shell plugins to Kubernetes and Terraform integrations. > [card] [Shell plugins](https://github.com/1Password/shell-plugins) > > Add biometric sign-in to any CLI. Contributions welcome. > [card] [Typeshare](https://github.com/1Password/typeshare) > > Sync type definitions between Rust and other languages. > [card] [1Password for Open Source](https://github.com/1Password/for-open-source) > > Get a free 1Password team account for your open source project. [See all open source projects](/open-source) ## Learn > [card] [1Password Academy](https://www.1password.academy/path/1password-developer-tools) > > Take the free learning path for the CLI, SSH, and secrets management. > [card] [AI-readable docs](/ai-readable-docs) > > Use these docs from Claude, Cursor, and other AI tools. ## Upcoming events Meetups, workshops, and office hours with the 1Password developer team, in person and online. [Upcoming 1Password developer events](https://luma.com/embed/calendar/cal-cJuyYn7TBhczK23/events) [See all events and subscribe to the calendar on Luma](https://luma.com/1password) ## Follow us * [**@1PasswordDev on X**](https://x.com/1PasswordDev): announcements and new docs. * [**1Password on GitHub**](https://github.com/1Password): open source projects and SDKs. * [**1Password on YouTube**](https://www.youtube.com/1PasswordVideos): product walkthroughs and talks. * [**1Password on LinkedIn**](https://www.linkedin.com/company/1password) * [**r/1Password on Reddit**](https://www.reddit.com/r/1Password) ## Featured community projects Check out some of the tools, articles, and videos contributed by 1Password’s developer community. To add your own project to the public directory, use the GitHub workflow below. [Add your project](https://github.com/1Password/developer-community-projects) #### [chezmoi by @twpayne](https://github.com/twpayne/chezmoi) October 30, 2018 • Manage your dotfiles across multiple diverse machines, securely. #### [Put `glab` at your fingertips with the GitLab CLI by Kai Armstrong](https://about.gitlab.com/blog/2022/12/07/introducing-the-gitlab-cli/) December 6, 2022 • We want to integrate GitLab with the tools our developers already use and love. #### [Community Office Hours: Git Signing Commits with 1Password by Gitpod](https://www.youtube.com/watch?v=u2aCOtMqtc4) November 16, 2022 • In this Gitpod Community Office Hours, 1Password Developer Floris van der Grinten talks about using 1Password to sign Git commits #### [Short: Commit your .env secrets to GitHub by Chris Biscardi](https://www.youtube.com/shorts/t3pZyyj3OUE) January 6, 2023 • In this Short, Chris shows us how to store and access your secrets using secret references. #### [op.nvim by @mrjones2014](https://github.com/mrjones2014/op.nvim) July 29, 2022 • 1Password for Neovim! Built using the 1Password CLI, Go, and Lua. ## Community guidelines * [**Code of Conduct**](/code-of-conduct) — expectations for everyone in our Slack and related spaces. * [**Community projects disclaimer**](/community/disclaimer) — how we present third-party projects and listings on this site. ## Archives * [**June 2023 Hashnode #BuildWith1Password hackathon**](/community/june-2023-hackathon) — historical resources and workshop links from the event (past dates; content kept for reference). ## Newsletter If you subscribed to developer updates, your confirmation flow may end on [**Thank you for subscribing**](/dev-subscribe/thank-you). # 1Password Connect Source: https://www.1password.dev/connect 1Password Connect is a self-hosted server that gives your apps and infrastructure access to 1Password items and vaults through a REST API. 1Password Connect Servers allow you to securely access your 1Password items and vaults in your company's apps and cloud infrastructure using a private REST API. Because Connect servers cache your data in your infrastructure, they allow unlimited re-requests after the server fetches your secrets. The only request quotas that apply to Connect servers are the internal rate limits 1Password employs to keep our services stable and available. These only apply when a Connect server fetches secrets for the first time, like when the Connect server starts. You can integrate a Connect server into your infrastructure and communicate with it over HTTP using one of the Connect SDK libraries (such as [Go](https://github.com/1Password/connect-sdk-go), [Python](https://github.com/1Password/connect-sdk-python), or [JavaScript](https://github.com/1Password/connect-sdk-js)) or using a custom integration. > [!TIP] > > **Not sure if Connect servers are for you?** > > See the [Secrets Automation comparison table](/secrets-automation/#comparison). ![The Connect server is part of your environment, and communicates to Your Apps using access tokens and a REST API.](https://mintcdn.com/ab-634991b8/P8nNS8jHoY1I7R9r/static/img/connect-diagram.png?fit=max\&auto=format\&n=P8nNS8jHoY1I7R9r\&q=85\&s=70b961d4ea5fa816b3da9b73907f09eb) ## Use cases You can use 1Password Connect to accomplish a variety of tasks: Availability ### Reduce latency and downtime Deploy a Connect server in your infrastructure, giving you complete control. Self-hosting also reduces latency and has security benefits, as only your services can interact with Connect. You can also deploy redundant Connect servers to further increase availability. CI/CD pipelines ### Load secrets into CI/CD pipelines Use a Connect server to automatically access your secrets in continuous integration environments. You can use a Connect server to use 1Password items in your CI/CD pipeline for testing and deploying code. Doing so maintains security and avoids using sensitive information with a personal account. [Learn more](/ci-cd/) Web services ### Provision web services with secrets Use a Connect server to provision an account with a secret stored in 1Password. If a web service needs access to a database (and the credentials for the database are in 1Password), you can use a Connect server to provision an account with the needed secret and allow the web service to access the secret during test runs. Infrastructure secrets ### Secure infrastructure secrets Use a Connect server to make sure infrastructure secrets aren't tied to a personal user account. Secrets management ### Automate secrets management Use a Connect server to automate scripts to manage secrets. Using a Connect server helps you implement the principle of least privilege and avoid the limitations of personal accounts (for example, SSO and MFA requirements). [Learn more](/connect/manage-connect) Development workflows ### Streamline development workflows Use a Connect server to securely share and manage infrastructure secrets to streamline development workflows. Integration ### Secure Kubernetes environments Use a Connect server to access and sync 1Password secrets in a Kubernetes environment. [Learn more](/k8s/integrations) ## Get started Learn how to get started and how to create, manage, and integrate with Connect servers. Get started # Use Connect with Ansible Source: https://www.1password.dev/connect/ansible-collection The [1Password Connect Ansible collection](https://github.com/1Password/ansible-onepasswordconnect-collection) contains modules that allow you to interact with your 1Password Connect deployment from [Ansible](https://docs.ansible.com/ansible/latest/getting_started/basic_concepts.html) playbooks. The modules communicate with the [Connect API](/connect/api-reference/) to support managing 1Password vaults and items through create, read, update, and delete operations. ## Requirements You must complete the following requirements before you can use the 1Password Connect Ansible collection: * [Create and deploy a Connect server.](/connect/get-started/#step-1) * Install [Ansible](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html) version 7.x or later. * Install [Ansible Core](https://docs.ansible.com/core.html) version 2.14 or later. * Install [Python](https://www.python.org/downloads/) version 3.8 or later. ## Get started Use the following instructions to get started with the 1Password Ansible collection: 1. [Install the 1Password collection.](#step-1-install-the-collection) 2. [Use the 1Password collection in an Ansible playbook.](#step-2-use-the-collection-in-an-ansible-task) 3. Explore the [example playbooks](#examples). ### Step 1: Install the collection Install the `onepassword.connect` collection from [Ansible Galaxy.](https://galaxy.ansible.com/onepassword/connect) ```shell theme={null} ansible-galaxy collection install onepassword.connect ``` > [!NOTE] > > The 1Password Ansible collection is also available for the [Red Hat Ansible Automation Platform.](https://www.redhat.com/en/technologies/management/ansible) ### Step 2: Use the collection in an Ansible task Use the `onepassword.connect` collection in an Ansible task: 1. Add `onepassword.connect` to the task `collections`. ```yaml playbook.yaml highlight={2} theme={null} collections: - onepassword.connect # Specify the 1Password collection ``` 2. Provide the [Connect server access token](/connect/concepts#connect-server-access-token) using the `token` variable in the Ansible task or the `OP_CONNECT_TOKEN` environment variable. You must set this value in each Ansible task. It's [best practice](#sensitive-data) to use a local variable to provide the Connect server access token because it's [more secure.](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_environment.html#working-with-language-specific-version-managers) The following example sets the `connect_token` variable to the Connect token value, then references it for the `token` field. ```yaml playbook.yaml highlight={2,7} theme={null} vars: connect_token: "" # Set the Connect server access token collections: - onepassword.connect # Specify the 1Password collection tasks: - onepassword.connect.generic_item: token: "{{ connect_token }}" ``` 3. Provide the Connect server hostname, IP address, or URL through the `hostname` variable in the Ansible task or the `OP_CONNECT_HOST` environment variable. You must set this value in each Ansible task. ```yaml playbook.yaml highlight={2} theme={null} environment: OP_CONNECT_HOST: # Set the Connect server hostname collections: - onepassword.connect # Specify the 1Password collection ``` ## Examples Explore the following examples to learn how to perform specific tasks: * [Create an item.](#create-an-item) * [Update an item.](#update-an-item) * [Find an item by name.](#find-an-item-by-name) * [Get the value of a field.](#get-the-value-of-a-field) ### Create an item The following example uses the [`generic_item` module](#generic_item) to create a 1Password item. It also creates the `Random Code` value with a custom `generator_recipe`. ```yaml playbook.yaml theme={null} - name: Create 1Password Secret hosts: localhost vars: connect_token: "" # Set the Connect server access token environment: OP_CONNECT_HOST: # Set the Connect server hostname collections: - onepassword.connect # Specify the 1Password collection tasks: - onepassword.connect.generic_item: token: "{{ connect_token }}" # Pass the Connect server access token variable vault_id: "" # Set the 1Password vault ID title: Club Membership state: present fields: - label: Codeword value: "hunter2" section: "Personal Info" field_type: concealed - label: Random Code generate_value: on_create # Generate the value on creation generator_recipe: length: 16 include_symbols: no no_log: true # Turn off logs to avoid logging sensitive data register: op_item # Note: register is Ansible syntax ``` ### Update an item The following example uses the [`generic_item` module](#generic_item) to update a 1Password item. It also sets the `generate_value` setting to `always`, which means 1Password generates a new value for the field each time you run the playbook. > [!WARNING] > > The update operation completely replaces the item matching the `title` or `uuid` field. You will lose any properties that you don't provide in the task definition. > > To avoid losing data, store the items created by Ansible in a vault that's scoped in a way that only the Connect server can access it. ```yaml playbook.yaml theme={null} - name: Update a 1Password Secret hosts: localhost vars: connect_token: "" # Set the Connect server access token environment: OP_CONNECT_HOST: # Set the Connect server hostname OP_VAULT_ID: "" # Set the 1Password vault ID collections: - onepassword.connect # Specify the 1Password collection tasks: - onepassword.connect.generic_item: token: "{{ connect_token }}" # Pass the Connect server access token variable title: Club Membership # uuid: 1ff75fa9fexample -- or use an Item ID to locate an item instead state: present fields: - label: Codeword field_type: concealed - label: Dashboard Password generate_value: always # Generate a new value every time the playbook runs generator_recipe: # Provide a custom password recipe length: 16 include_symbols: no no_log: true # Turn off logs to avoid logging sensitive data ``` ### Find an item by name The following example uses the [`item_info` module](#item_info) to find a 1Password item by name. ```yaml playbook.yaml theme={null} hosts: localhost vars: connect_token: "" # Set the Connect server access token environment: OP_CONNECT_HOST: # Set the Connect server hostname collections: - onepassword.connect # Specify the 1Password collection tasks: - name: Find the item with the label "Staging Database" in the vault "Staging Env" item_info: token: "{{ connect_token }}" item: Staging Database vault: Staging Env no_log: true # Turn off logs to avoid logging sensitive data register: op_item ``` ### Get the value of a field The following example uses the [`field_info` module](#field_info) to get the value of a specific field in a 1Password item. ```yaml playbook.yaml theme={null} hosts: localhost vars: connect_token: "" # Set the Connect server access token environment: OP_CONNECT_HOST: # Set the Connect server hostname collections: - onepassword.connect # Specify the 1Password collection tasks: - name: Find a field labeled "username" in an item named "MySQL Database" in a specific vault field_info: token: "{{ connect_token }}" # Pass the Connect token variable item: MySQL Database field: username vault: # Set the 1Password vault ID no_log: true # Turn off logs to avoid logging sensitive data register: op_item - name: Print the field definition ansible.builtin.debug: msg: "{{ op_item.field }}" ``` ## Reference Refer to the following sections to learn about the available [variables](#variables) and [modules](#modules). ### Variables All [modules](#modules) support the following variable definitions. You can either explicitly define the value on the Ansible task or let Ansible fall back to an environment variable to use the same value across all tasks. | Module variable | Environment variable | Description | | - | - | - | | `hostname` | `OP_CONNECT_HOST` | Specifies the hostname, IP address, or URL where your Connect server is deployed. | | `token` | `OP_CONNECT_TOKEN` | Specifies the string value of your Connect server access token. | | `vault_id` | `OP_VAULT_ID` | (Optional) The UUID of a 1Password vault. It must be a vault the Connect server token has access to. | > [!WARNING] > > Module variables take precedence over environment variables. If you plan to use an environment variable, make sure the corresponding module variable is absent. ### Modules The 1Password Ansible collection has the following modules: * [`generic_item` module](#generic_item) * [`item_info` module](#item_info) * [`field_info` module](#field_info) #### `generic_item` You can use the `generic_item` module to create, update, and delete 1Password items. > [!WARNING] > > **State is important** > > The `generic_item` module follows [Ansible's `present`/`absent` state pattern.](https://docs.ansible.com/ansible/2.8/user_guide/playbooks_best_practices.html#always-mention-the-state) > > Behavior when the state is `present` (`state: present`): > > * If the module can't find a matching item by its `uuid` or `title`, it creates a new item with the defined values. > * If the module finds a matching item on the server, it completely replaces the old item with a new item defined by the playbook values. > > Behavior when the state is `absent` (`state: absent`): > > * If the module can't find the item by its `uuid` or `title`, no action is taken. > * If the module finds an item matching the `uuid` or `title`, it deletes the item. Otherwise, no action is taken. When you use the `generic_item` module to create or update a 1Password item, you can have 1Password generate a field's value. You can specify one of three settings for `generate_value`: | `generate_value` setting | Effect | | - | - | | `never` **(Default)** | Don't generate the field value. Use the `value` parameter instead. | | `on_create` | Generate the value when creating the field. | | `always` | Generate a new value for the field every time the playbook is run. Overwrites the `value` parameter. | The following example generates a value (with a custom recipe) for the `Random Code` field by using the `on_create` setting and supplying a custom `generator_recipe`. ```yaml playbook.yaml highlight={20-24} theme={null} - name: Create 1Password Secret hosts: localhost vars: connect_token: "" # Set the Connect server access token environment: OP_CONNECT_HOST: # Set the Connect server hostname collections: - onepassword.connect # Specify the 1Password collection tasks: - onepassword.connect.generic_item: token: "{{ connect_token }}" # Pass the Connect token variable vault_id: "" # Set the 1Password vault ID (optional) title: Club Membership state: present fields: - label: Codeword value: "hunter2" section: "Personal Info" field_type: concealed - label: Random Code generate_value: on_create # Generate the field value on creation generator_recipe: # Provide a custom password recipe length: 16 include_digits: no no_log: true # Turn off logs to avoid logging sensitive data register: op_item ``` #### `item_info` Use the `item_info` module to search for or get information about a 1Password item (such as the fields or metadata). > [!NOTE] > > When you search for an item, 1Password first searches for the `uuid` (if it's provided), then searches for the `title`. When searching for an item by its `title`, the module uses a case-sensitive, exact-match query. #### `field_info` Use the `onepassword.connect.field_info` module to get the value of an item field. The `field_info` module first finds the item by title or UUID, then searches for the requested field by name. If you provide a `section`, the module only searches within that item section. If you don't provide a section, the field name must be unique within the item. The search method compares field names using the [`unicodedata.normalize`](https://docs.python.org/3/library/unicodedata.html#unicodedata.normalize) function and the `NKFD` form. ## Best practices Consider the following best practices when using the 1Password Ansible collection. * [Turn off task logging.](#turn-off-task-logging) * [Avoid using environment variables for sensitive information.](#sensitive-data) ### Turn off task logging It's best practice to turn off task logging for any tasks that interact with 1Password Connect. Ansible might print sensitive information if `no_log` is unset or set to `false`. To turn off logging, set `no_log` to `true`: ```yaml playbook.yaml highlight={9} theme={null} collections: - onepassword.connect # Specify the 1Password collection tasks: - name: Find the item with the label "Staging Database" in the vault "Staging Env" item_info: token: "{{ connect_token }}" # Pass the Connect token variable item: Staging Database vault: Staging Env no_log: true # Turn off logs to avoid logging sensitive data register: op_item ``` ### Avoid using environment variables for sensitive information It's best practice to use a local variable to set sensitive information, such as the Connect server access token, because [Ansible environment variables](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_environment.html) are normally passed in plain text. # 1Password Connect Server API reference Source: https://www.1password.dev/connect/api-reference Use the Connect API to read and manage the vaults and items your Connect server can access, and to check the server's health and activity. You need a running [Connect server](/connect/get-started) and an [access token](/connect/manage-connect/#manage-access-tokens). > [card] [Try the API in your browser](/connect/api-reference/get-vaults) > > Paste your token, enter your Connect server address, and send a real request from the docs. ## Endpoints * [List vaults](/connect/api-reference/get-vaults) * [Get vault details](/connect/api-reference/get-vault-by-id) * [List items](/connect/api-reference/get-vault-items) * [Add an item](/connect/api-reference/create-vault-item) * [Get item details](/connect/api-reference/get-vault-item-by-id) * [Replace an item](/connect/api-reference/update-vault-item) * [Delete an item](/connect/api-reference/delete-vault-item) * [Update a subset of item attributes](/connect/api-reference/patch-vault-item) * [List files](/connect/api-reference/get-item-files) * [Get file details](/connect/api-reference/get-item-file-by-id) * [Get file content](/connect/api-reference/download-item-file-by-id) * [List API activity](/connect/api-reference/get-api-activity) * [Check the server heartbeat](/connect/api-reference/get-heartbeat) * [Check server health](/connect/api-reference/get-server-health) * [Get Prometheus metrics](/connect/api-reference/get-prometheus-metrics) To view the API in another tool, download the [1Password Connect API specification file (1.8.1)](https://i.1password.com/media/1password-connect/1password-connect-api_1.8.1.yaml). ## Requirements Before you can use the 1Password Connect Server API, you'll need to: * [Sign up for 1Password.](https://1password.com/pricing/password-manager) * [Set up a Secrets Automation workflow.](/connect/get-started/#step-1). * [Deploy 1Password Connect](/connect/get-started/#step-2-deploy-1password-connect-server) in your infrastructure. ## Request headers Each request to the API has to be authenticated with an [access token](/connect/manage-connect/#manage-access-tokens). Provide it and specify the content type: ```text theme={null} Authorization: Bearer Content-type: application/json ``` ## Try it in the docs Every endpoint has a **Try it** panel with its parameters, example requests and responses. **1. Get an access token** Create a token for your Connect server. See [Manage access tokens](/connect/manage-connect/#manage-access-tokens). **2. Start with a read-only call** Open [Get heartbeat](/connect/api-reference/get-heartbeat) to check the server is up, then [List vaults](/connect/api-reference/get-vaults) to see which vaults your token can read. **3. Point it at your server and paste your token** Select **Try it**, enter your Connect server's address, and paste your token in the **Authorization** field. **4. Send it, or copy the code** Select **Send** to see the live response, or copy the request as cURL, Python, JavaScript, Go, and more. > [!NOTE] > > The **Try it** panel sends requests from the docs, so it can't reach a Connect server that only listens on localhost or a private network. In that case, copy the cURL request from the example panel and run it on a machine that can reach your server. ## Response object models ### APIRequest object | Parameter | Type | Description | | - | - | - | | `requestID` | string | The UUID for the request. | | `timestamp` | dateTime | Date and time of the request. | | `action` | string | The action taken. One of: | | `result` | string | The result of the action. One of: | | `actor` | object | An [Actor object](#apirequest-actor-object). | | `resource` | object | A [Resource object](#apirequest-resource-object). | #### APIRequest: Actor object | Parameter | Type | Description | | - | - | - | | `id` | string | The UUID of the Connect server that made the request. | | `account` | string | The UUID of the 1Password account the request went to. | | `jti` | string | The UUID of the access token used to authenticate the request. | | `userAgent` | string | The user agent string specified in the request. | | `ip` | string | The IP address the request originated from. | #### APIRequest: Resource object | Parameter | Type | Description | | - | - | - | | `type` | string | The resource requested. One of: | | `vault` | object | An object containing an `id` property with the value of the UUID of the vault requested. | | `item` | object | An object containing an `id` property with the value of the UUID of the item requested. | | `itemVersion` | integer | The version of the item. | ### ErrorResponse object ```json theme={null} { status: 401, message: "Invalid or missing token" } ``` | Parameter | Type | Description | | - | - | - | | `status` | integer | The HTTP status code. | | `message` | string | A message detailing the error. | ### Vault object ```json theme={null} { "id": "ytrfte14kw1uex5txaore1emkz", "name": "Demo", "attributeVersion": 1, "contentVersion": 72, "items": 7, "type": "USER_CREATED", "createdAt": "2021-04-10T17:34:26Z", "updatedAt": "2021-04-13T14:33:50Z" } ``` | Parameter | Type | Description | | - | - | - | | `id` | string | The UUID of the vault. | | `name` | string | The name of the vault. | | `description` | string | The description for the vault. | | `attributeVersion` | integer | The version of the vault metadata. | | `contentVersion` | integer | The version of the vault contents. | | `items` | integer | Number of active items in the vault. | | `type` | string | The type of vault. One of: | | `createdAt` | dateTime | Date and time when the vault was created. | | `updatedAt` | dateTime | Date and time when the vault or its contents were last changed. | ### Item object ```json theme={null} { "id": "2fcbqwe9ndg175zg2dzwftvkpa", "title": "Secrets Automation Item", "tags": [ "connect", "\ud83d\udc27" ], "vault": { "id": "ftz4pm2xxwmwrsd7rjqn7grzfz" }, "category": "LOGIN", "sections": [ { "id": "95cdbc3b-7742-47ec-9056-44d6af82d562", "label": "Security Questions" } ], "fields": [ { "id": "username", "type": "STRING", "purpose": "USERNAME", "label": "username", "value": "wendy" }, { "id": "password", "type": "CONCEALED", "purpose": "PASSWORD", "label": "password", "value": "mjXehR*uCj!aoe!iktt9KMtWb", "entropy": 148.0838165283203, "passwordDetails": { "entropy": 148, "generated": true, "strength": "FANTASTIC", "history": [ "U-Trxf98hT_GTgNmA.a!pQp3U", "_ciCJpYuCB*E7@oRTto4JB4.3" ] } }, { "id": "notesPlain", "type": "STRING", "purpose": "NOTES", "label": "notesPlain" }, { "id": "a6cvmeqakbxoflkgmor4haji7y", "type": "URL", "label": "Example", "value": "https://example.com" }, { "id": "boot3vsxwhuht6g7cmcx4m6rcm", "section": { "id": "95cdbc3b-7742-47ec-9056-44d6af82d562" }, "type": "CONCEALED", "label": "Recovery Key", "value": "s=^J@GhHP_isYP>LCq?vv8u7T:*wBP.c" }, { "id": "axwtgyjrvwfp5ij7mtkw2zvijy", "section": { "id": "95cdbc3b-7742-47ec-9056-44d6af82d562" }, "type": "STRING", "label": "Random Text", "value": "R)D~KZdV!8?51QoCibDUse7=n@wKR_}]" } ], "files": [ { "id": "6r65pjq33banznomn7q22sj44e", "name": "testfile.txt", "size": 35, "content_path": "v1/vaults/ftz4pm2xxwmwrsd7rjqn7grzfz/items/2fcbqwe9ndg175zg2dzwftvkpa/files/6r65pjq33banznomn7q22sj44e/content", }, { "id": "oyez5gf6xjfptlhc3o4n6o6hvm", "name": "samplefile.png", "size": 296639, "content_path": "v1/vaults/ftz4pm2xxwmwrsd7rjqn7grzfz/items/2fcbqwe9ndg175zg2dzwftvkpa/files/oyez5gf6xjfptlhc3o4n6o6hvm/content", } ], "createdAt": "2021-04-10T17:20:05.98944527Z", "updatedAt": "2021-04-13T17:20:05.989445411Z" } ``` | Parameter | Type | Description | | - | - | - | | `id` | string | The UUID of the item. | | `title` | string | The title of the item. | | `vault` | object | An object containing an `id` property whose value is the UUID of the vault the item is in. | | `category` | string | | | `urls` | array | Array of [URL objects](#item-url-object) containing URLs for the item. | | `favorite` | boolean | Whether the item is marked as a favorite. | | `tags` | array | An array of strings of the tags assigned to the item. | | `version` | integer | The version of the item. | | `createdAt` | dateTime | Date and time when the item was created. | | `updatedAt` | dateTime | Date and time when the vault or its contents were last changed. | | `lastEditedBy` | string | UUID of the account that last changed the item. | #### Item: Field object ```json theme={null} { "section": { "id": "95cdbc3b-7742-47ec-9056-44d6af82d562" }, "type": "STRING", "generate": true, "label": "Random Text" } ``` | Parameter | Type | Description | | - | - | - | | `purpose` or `type` | string | | | `value` | string | The value to save for the field. You can specify a `generate` field instead of `value` to create a password or other random information for the value. | | `generate` | boolean | Generate a password and save in the value for the field. By default, the password is a 32-characters long, made up of letters, numbers, and symbols. To customize the password, include a `recipe` field. | | `recipe` | object | A [GeneratorRecipe object](#item-generatorrecipe-object). | | `section` | object | An object containing the UUID of a section in the item. | #### Item: File object ```json theme={null} { "id": "6r65pjq33banznomn7q22sj44e", "name": "testfile.txt", "size": 35, "content_path": "v1/vaults/ftz4pm2xxwmwrsd7rjqn7grzfz/items/2fcbqwe9ndg175zg2dzwftvkpa/files/6r65pjq33banznomn7q22sj44e/content", "content": "VGhlIGZ1dHVyZSBiZWxvbmdzIHRvIHRoZSBjdXJpb3VzLgo=", "section": { "id": "95cdbc3b-7742-47ec-9056-44d6af82d562" }, } ``` | Name | Type | Description | | - | - | - | | `id` | string | The UUID of the file. | | `name` | string | The name of the file. | | `size` | integer | The size of the file in bytes. | | `content_path` | string | The path to download the contents of the file. | | `content` | string | The Base64-encoded contents of the file, if `inline_files` is set to `true`. | | `section` | object | An object containing the UUID of a section in the item. | #### Item: GeneratorRecipe object The recipe is used in conjunction with the "generate" property to set the character set used to generate a new secure value. ```json theme={null} { "length": 55, "characterSets": [ "LETTERS", "DIGITS" ] } ``` | Name | Type | Description | | - | - | - | | `length` | integer | The length of the password to generate. *Optional.* | | `characterSets` | array | An array containing of the kinds of characters to include. *Optional.* Possible values: | | `excludeCharacters` | string | A list of all characters that should be excluded from generated passwords. *Optional.* | #### Item: PasswordDetails object ```json theme={null} { "entropy": 148, "generated": true, "strength": "FANTASTIC", "history": [ "U-Trxf98hT_GTgNmA.a!pQp3U", "_ciCJpYuCB*E7@oRTto4JB4.3" ] } ``` | Name | Type | Description | | - | - | - | | `entropy` | integer | The unpredictability of the password, measured in bits. | | `generated` | boolean | Whether the password was generated using the password generator. | | `strength` | string | The strength of the password. One of: | | `history` | array | An array of strings containing the previous passwords of the item. | #### Item: Section object ```json theme={null} { "id": "95cdbc3b-7742-47ec-9056-44d6af82d562" "label": "Security Questions", } ``` | Name | Type | Description | | - | - | - | | `id` | string | A unique identifier for the section. | | `label` | string | The label for the section. | #### Item: URL object ```json theme={null} { "label": "website", "primary": true, "href": "https://example.com" } ``` | Name | Type | Description | | - | - | - | | `label` | string | The label for the URL. | | `primary` | boolean | Whether this is the primary URL for the item. | | `href` | string | The address. | ### Server Health object ```json theme={null} { "name": "1Password Connect API", "version": "1.2.1", "dependencies": [ { "service": "sync", "status": "TOKEN_NEEDED" }, { "service": "sqlite", "status": "ACTIVE", "message": "Connected to ~/1password.sqlite" } ] } ``` | Name | Type | Description | | - | - | - | | `name` | string | Name of the server | | `version` | string | Version info of the Connect server | | `dependencies` | array | An array of [Service Dependencies](#server-health-dependency-object). | #### Server Health: Dependency object | Name | Type | Description | | - | - | - | | `service` | string | Name of the dependency | | `status` | string | The service's reported status | | `message` | string | Extra information about the dependency's status. *Optional.* | # Create a new Item Source: https://www.1password.dev/connect/api-reference/create-vault-item /openapi/connect_server_api.yaml post /vaults/{vaultUuid}/items # Delete an Item Source: https://www.1password.dev/connect/api-reference/delete-vault-item /openapi/connect_server_api.yaml delete /vaults/{vaultUuid}/items/{itemUuid} # Get the content of a File Source: https://www.1password.dev/connect/api-reference/download-item-file-by-id /openapi/connect_server_api.yaml get /vaults/{vaultUuid}/items/{itemUuid}/files/{fileUuid}/content # Retrieve a list of API Requests that have been made. Source: https://www.1password.dev/connect/api-reference/get-api-activity /openapi/connect_server_api.yaml get /activity # Ping the server for liveness Source: https://www.1password.dev/connect/api-reference/get-heartbeat /openapi/connect_server_api.yaml get /heartbeat # Get the details of a File Source: https://www.1password.dev/connect/api-reference/get-item-file-by-id /openapi/connect_server_api.yaml get /vaults/{vaultUuid}/items/{itemUuid}/files/{fileUuid} # Get all the files inside an Item Source: https://www.1password.dev/connect/api-reference/get-item-files /openapi/connect_server_api.yaml get /vaults/{vaultUuid}/items/{itemUuid}/files # Query server for exposed Prometheus metrics Source: https://www.1password.dev/connect/api-reference/get-prometheus-metrics /openapi/connect_server_api.yaml get /metrics See Prometheus documentation for a complete data model. # Get state of the server and its dependencies. Source: https://www.1password.dev/connect/api-reference/get-server-health /openapi/connect_server_api.yaml get /health # Get Vault details and metadata Source: https://www.1password.dev/connect/api-reference/get-vault-by-id /openapi/connect_server_api.yaml get /vaults/{vaultUuid} # Get the details of an Item Source: https://www.1password.dev/connect/api-reference/get-vault-item-by-id /openapi/connect_server_api.yaml get /vaults/{vaultUuid}/items/{itemUuid} # Get all items for inside a Vault Source: https://www.1password.dev/connect/api-reference/get-vault-items /openapi/connect_server_api.yaml get /vaults/{vaultUuid}/items # Get all Vaults Source: https://www.1password.dev/connect/api-reference/get-vaults /openapi/connect_server_api.yaml get /vaults # Update a subset of Item attributes Source: https://www.1password.dev/connect/api-reference/patch-vault-item /openapi/connect_server_api.yaml patch /vaults/{vaultUuid}/items/{itemUuid} Applies a modified [RFC6902 JSON Patch](https://tools.ietf.org/html/rfc6902) document to an Item or ItemField. This endpoint only supports `add`, `remove` and `replace` operations. When modifying a specific ItemField, the ItemField's ID in the `path` attribute of the operation object: `/fields/{fieldId}` # Update an Item Source: https://www.1password.dev/connect/api-reference/update-vault-item /openapi/connect_server_api.yaml put /vaults/{vaultUuid}/items/{itemUuid} # Deploy 1Password Connect Server on AWS ECS Fargate with CloudFormation Source: https://www.1password.dev/connect/aws-ecs-fargate 1Password Connect works with [AWS Fargate.](https://docs.aws.amazon.com/AmazonECS/latest/userguide/what-is-fargate.html) AWS Fargate lets you leverage Amazon Elastic Container Service (ECS) to run containers without the need to manage clusters. ## Requirements Before you can use 1Password CLI with your Connect server, you must: * [Sign up for 1Password](https://1password.com/pricing/password-manager). * [Create a 1Password Connect server](/connect/get-started/#step-1) in your infrastructure. * Sign up with [AWS Fargate.](https://docs.aws.amazon.com/AmazonECS/latest/userguide/what-is-fargate.html) ## Example You can use 1Password's [example CloudFormation template (`connect-server.yaml`)](https://github.com/1Password/connect/blob/main/examples/aws-ecs-fargate/connect-server.yaml) as a starting place for deploying Connect on AWS Fargate. The example [CloudFormation template](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-whatis-concepts.html#cfn-concepts-templates) creates the necessary networking resources, ECS resources, rules, groups, and policies. See [Resources](#resources) for more details. The result is a publicly accessible hostname that routes requests to a 1Password Connect Server deployment running in AWS Fargate. > [!TIP] > > You can also use this example CloudFormation file to deploy into an existing [AWS virtual private cloud (VPC)](https://docs.aws.amazon.com/vpc/latest/privatelink/concepts.html) or an existing [Amazon Elastic Container (AWS ECS)](https://docs.aws.amazon.com/ecs/) cluster. You can modify it using a text editor or using Amazon's [CloudFormation Designer](https://console.aws.amazon.com/cloudformation/designer) tool. ### Resources The example CloudFormation template creates the following network resources: * A virtual private cloud (VPC) * Two public subnets * An [Internet gateway](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-internetgateway.html) * An [Application Load Balancer (ALB)](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/introduction.html) The example CloudFormation template creates the following ECS resources: * An [ECS cluster](https://docs.aws.amazon.com/AmazonECS/latest/userguide/clusters-concepts.html) * Two [task definitions](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/fargate-tasks-services.html) * A `1password/connect-api` container * A `1password/connect-sync` container ## Get started To use the example `connect-server.yaml` file to deploy a Connect server on AWS Fargate (using CloudFormation): 1. [Start the **AWS Create Stack** wizard.](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-create-stack.html#cfn-using-console-initiating-stack-creation) 2. Select the example [`connect-server.yaml` file](https://github.com/1Password/connect/blob/main/examples/aws-ecs-fargate/connect-server.yaml) as the stack template. See [Selecting a stack template.](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-using-console-create-stack-template.html) 3. Provide a Base64 URL encoded version of your Connect server's `1password-credentials.json` file. When importing this CloudFormation template, it prompts you to provide a Base64 URL encoded version of the `1password-credentials.json`. You can generate this encoded value with the following shell command: ```shell theme={null} cat 1password-credentials.json | base64 | tr '/+' '_-' | tr -d '=' | tr -d '\n' ``` # Use 1Password CLI with a Connect server Source: https://www.1password.dev/connect/cli You can use 1Password CLI with a [Connect server](/connect/) to provision secrets and retrieve items on the command line. ## Requirements Before you can use 1Password CLI with a Connect server, you must: * [Sign up for 1Password](https://1password.com/pricing/password-manager). * [Deploy 1Password Connect](/connect/get-started/#step-2-deploy-1password-connect-server). * Make a Connect server accessible to your production environment. * [Install 1Password CLI in your production environment.](/cli/install-server/) * Set the `OP_CONNECT_HOST` and `OP_CONNECT_TOKEN` environment variables to a Connect server's credentials in your production environment. ## Get started After you complete the requirement steps, you can use the following 1Password CLI commands with a Connect server: * [`op run`](/cli/reference/commands/run/) * [`op inject`](/cli/reference/commands/inject/) * [`op read`](/cli/reference/commands/read/) * [`op item get --format json`](/cli/reference/management-commands/item/#item-get) Vist the command documentation for more information. ## Continuous integration (CI) environments You can also use 1Password CLI with a Connect server in a continuous integration (CI) pipeline. 1Password CLI allows you to use [secret references](/cli/secret-references/) in place of plaintext secrets in code. You can configure a CI environment to pass different sets of secrets for different environments. Secret references work well within infrastructure as code tools and CI configurations because you can define them alongside other configurations. ### GitLab CI example The following code block shows an example GitLab CI configuration file that implements a MySQL service. See [GitLabs `.gitlab-ci.yml` documentation.](https://docs.gitlab.com/ee/ci/yaml/) ```yaml .gitlab-ci.yml theme={null} services: - mysql variables: # Configure mysql service (https://hub.docker.com/_/mysql/) MYSQL_DATABASE: op://prod/mysql/database MYSQL_USERNAME: op://prod/mysql/username MYSQL_PASSWORD: op://prod/mysql/password connect: image: mysql script: - echo "SELECT 'OK';" | op run -- mysql --user="$MYSQL_USERNAME" --password="$MYSQL_PASSWORD" --host=mysql "$MYSQL_DATABASE" ``` To authenticate 1Password CLI in the CI pipeline, add the `OP_CONNECT_HOST` and `OP_CONNECT_TOKEN` environment variables to a CI configuration file. The presence of these environment variables tells 1Password CLI to use the Connect server to fetch secrets. The following code block expands the GitLab CI example to include the Connect environment variables. ```yaml .gitlab-ci.yml theme={null} services: - mysql variables: # Configure mysql service (https://hub.docker.com/_/mysql/) MYSQL_DATABASE: op://prod/mysql/database MYSQL_USERNAME: op://prod/mysql/username MYSQL_PASSWORD: op://prod/mysql/password # Configure 1Password CLI to use Connect OP_CONNECT_HOST: :8080 OP_CONNECT_TOKEN: token connect: image: mysql script: - echo "SELECT 'OK';" | mysql --user="$MYSQL_USERNAME" --password="$MYSQL_PASSWORD" --host=mysql "$MYSQL_DATABASE" ``` ## Learn more * [Load secrets into the environment](/cli/secrets-environment-variables/) * [Load secrets into config files](/cli/secrets-config-files/) * [Workflow: Secure your deployments](/get-started/secure-deployment) * [Workflow: Build integrations with 1Password](/get-started/build-integrations) # Connect concepts Source: https://www.1password.dev/connect/concepts Learn about the concepts involved with 1Password Connect. ## Connect servers A Connect server is a tool you can deploy in your network that allows you to manage and sync 1Password items from within your infrastructure. ## Credentials There are two important pieces of information for authenticating Connect servers: * The `1password-credentials.json` file * The Connect server access token ### `1password-credentials.json` When you create a Connect server, a credentials file named `1password-credentials.json` is generated uniquely for that Connect server. It contains all the information you need to [deploy the Connect server](/connect/get-started/#step-2-deploy-1password-connect-server). ### Connect server access token A Connect server access token is an authentication string that allows the Connect server to authenticate with 1Password services, such as the [Connect REST API](/connect/api-reference/). When you create a Connect server, you select the vaults that it can access. Connect servers can only access the vaults you explicitly allow them to access through a Connect server token. Each Connect server can have one or more access tokens, which allows for more fine-tuned [access control](/connect/security/#access-control). Connect server access tokens can only access information in the vaults you grant them access to. This allows you more granular control over the vaults a Connect server deployment can access. For example, you can grant a Connect token access to a specific subset of the vaults the Connect server has access to. Learn more about [how to manage access tokens](/connect/manage-connect#manage-access-tokens). Learn more about [1Password Connect server security](/connect/security/). ## Connect containers Each Connect server deployment consists of two Docker containers running in the same network: * The [Connect sync container](#connect-sync-container) * The [Connect API container](#connect-api-container) Both containers require a shared volume to store an encrypted copy of your data. Learn more about [configuring your Connect server](/connect/server-configuration/). ### Connect sync container The Connect sync container keeps information on the Connect server in sync with 1Password.com. View it on Docker Hub: [`1password/connect-sync`.](https://hub.docker.com/r/1password/connect-sync) ### Connect API container The Connect API container serves [Connect REST API](/connect/api-reference/). View it on Docker Hub: [`1password/connect-api`.](https://hub.docker.com/r/1password/connect-api) ## Environment variables Connect servers have a collection of environment variables you can use to provide information about the Connect server to integrations, such as [1Password CLI](/connect/cli/) or [CI/CD pipeline tools](/ci-cd/). These environment variables are distinct from the [configuration environment variables](/connect/server-configuration/#environment-variables). | Environment variable | Description | Example | | - | - | - | | `OP_CONNECT_HOST` | Specifies the hostname, IP address, or URL where your Connect server is deployed. | `http://localhost:8080` | | `OP_CONNECT_TOKEN` | Specifies the string value of your Connect server token. | N/A | # Get started with a 1Password Connect server Source: https://www.1password.dev/connect/get-started 1Password Connect servers are a type of [Secrets Automation workflow](/secrets-automation/) that allows you to securely access your 1Password items and vaults in your company's apps and cloud infrastructure. [Getting Started with 1Password Connect](https://www.youtube.com/embed/PMwxZxZT2Pc) ## Requirements Before you can create a 1Password Secrets Automation workflow as a Connect server, make sure you complete the prerequisite tasks. The tasks vary depending on how you plan to deploy. > [tab] Docker > > * [Sign up for a 1Password account](https://1password.com/pricing/password-manager). > * [Create a vault](https://support.1password.com/create-share-vaults/) for the Connect server to access. Connect servers 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, or your default [Shared](https://support.1password.com/1password-glossary/#shared-vault) vault. > * Make sure you belong to [a group with permission to manage Secrets Automation](/connect/manage-connect/). > * Make sure you have a deployment environment for Docker. You can use a cloud service provider or your local machine. > [tab] Kubernetes > > * [Sign up for a 1Password account](https://1password.com/pricing/password-manager). > * [Create a vault](https://support.1password.com/create-share-vaults/) for the Connect server to access. Connect servers 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, or your default [Shared](https://support.1password.com/1password-glossary/#shared-vault) vault. > * Make sure you belong to [a group with permission to manage Secrets Automation](/connect/manage-connect/). > * Make sure you have a deployment environment for Kubernetes with [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/), and [Helm](https://helm.sh/) installed. You can use a cloud service provider or your local machine. ## Deployment Use the following instructions to deploy a 1Password Connect Server. ### Step 1: Create a Secrets Automation workflow You can create a Connect server Secrets Automation workflow through the 1Password.com dashboard or 1Password CLI. Following these instructions creates: * A `1password-credentials.json` file. It contains the credentials necessary to deploy 1Password Connect Server. * An access token. Use this in your applications or services to authenticate with the [Connect REST API](/connect/api-reference/). You can [issue additional tokens later](/connect/manage-connect/#create-a-token). > [tab] 1Password.com > > 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. > 2. Open the [Secrets Automation workflow creation wizard](https://start.1password.com/developer-tools/infrastructure-secrets/connect).\ > Or, navigate to **Developer** > **Directory**, select **Other** under Infrastructure Secrets Management, then select **Create a Connect server**. > 3. Follow the onscreen instructions to create a Secrets Automation environment, set up your first access token, and deploy a Connect server. Make sure to save your credentials file and token in 1Password. > > You can find your new Secrets Automation workflow under "Connect servers" on the [**Developer**](https://start.1password.com/developer-tools/active) page. > [tab] 1Password CLI > > You can use the [1Password CLI](https://1password.com/downloads/command-line) [`op connect` command](/cli/reference/management-commands/connect/) to set up a Secrets Automation workflow with a Connect server. > > 1. Make sure you have the latest version of [1Password CLI](/cli/get-started/) on your machine. > > 2. Switch to the directory where you want to create the `1password-credentials.json`. > > Creating a Connect server automatically generates the `1password-credentials.json` file in the current directory. This file contains the credentials you'll need to deploy the Connect server. If a `1password-credentials.json` file already exists in the current directory, 1Password CLI will ask if you want to overwrite it. > > 3. Create a Connect server and grant it access to a shared vault using the [`op connect server create` command](/cli/reference/management-commands/connect/#connect-server-create). > > ```shell theme={null} > op connect server create --vaults > ``` > > > [!TIP] > > > > Omit the `--vaults` flag to create a Connect server without granting it access to a vault. You can grant the Connect server access to shared vaults later using the [`op connect vault grant` command](/cli/reference/management-commands/connect/#connect-vault-grant). > > If the Connect server or vault name contains one or more spaces, enclose the name in quotation marks (for example, `“My Server Name”`). You don't need to enclose strings in quotation marks if they don't contain spaces (for example, `myServerName`). > > ``` > op connect server create "My Server Name" --vault "My Vault Name" > ``` > > 4. Create a token for the Connect server using the [`op connect token create` command](/cli/reference/management-commands/connect/#connect-token). > > ```shell theme={null} > op connect token create --server --vault > ``` > > > [!TIP] > > > > Looking up a Connect server by its ID is more efficient than using the Connect server's name. See [Unique identifiers (IDs)](/cli/reference/#unique-identifiers-ids). > > > > You can find the ID of a Connect server by running [`op connect server list`](/cli/reference/management-commands/connect/#connect-server-list). > > If successful, 1Password CLI returns a token string that you can use in your applications or services to authenticate with the [Connect server REST API](/connect/api-reference/). You can [issue additional tokens later.](/connect/manage-connect/#create-a-token) > > 5. Save the token in 1Password so you don't lose it. > > You can have multiple tokens for the same Connect server but each Connect server has its own distinct set of tokens. See the [`op connect token` command reference](/cli/reference/management-commands/connect/#connect-token). > [!TIP] > > Export your Connect server access token as an environment variable. Doing so might prove useful if you decide to configure another tool like the [Kubernetes Injector](/k8s/injector/), [Kubernetes Operator](/k8s/operator/), or other integrations. However, keep in mind that the recommended way to use the Connect server token with Kubernetes is as a Kubernetes Secret. > > ```shell theme={null} > export OP_CONNECT_TOKEN= > ``` ### Step 2: Deploy a 1Password Connect Server > [tab] Docker > > To deploy a Connect server using a Docker Compose file, you'll need to start two Docker images: > > * [1password/connect-api](https://hub.docker.com/r/1password/connect-api) serves the Connect server REST API. > > * [1password/connect-sync](https://hub.docker.com/r/1password/connect-sync) keeps the information available on the Connect server in sync with 1Password.com. > > > [!NOTE] > > > > If you aren't familiar with Docker or Docker Compose, refer to the [Docker Compose documentation](https://docs.docker.com/compose/) for more information. > > 1. Make sure you have [Docker](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/) on your machine. > > 2. Create a Docker Compose file to deploy the 1Password Connect Server containers in the directory where you saved your `1password-credentials.json` file. You can also use the example [`docker-compose.yaml` file](https://i.1password.com/media/1password-connect/docker-compose.yaml). > > If the credentials file is in the other directory, update the `volumes` section to point to the correct credentials file location. > > > [!TIP] > > > > You can set any of the [Connect server environment variables](/connect/server-configuration/) in the `docker-compose.yaml` file by adding an environment attribute to each container. Doing so lets you specify things like the `1password-credentials.json` file location, the log level, and the HTTP port. Refer to the [Docker environment attribute documentation](https://docs.docker.com/compose/environment-variables/set-environment-variables/) for more information. > > 3. Make sure Docker is running. You can [check if the Docker daemon is running](https://docs.docker.com/config/daemon/troubleshoot/#check-whether-docker-is-running) with the `docker info` command in a terminal application. > > 4. Start the Docker containers with Docker Compose. Run the following command in the directory with the `docker-compose.yaml` file. > > ```shell theme={null} > docker compose up > ``` > > > [!TIP] > > > > You can run the containers in the background using the `-detach` flag or the `-d` flag. Refer to the [`docker compose up` reference](https://docs.docker.com/engine/reference/commandline/compose_up/) for more information. > > By default, you can access the Connect REST API through port `8080` on the local host. Refer to the [1Password Connect server API reference](/connect/api-reference/) for more information. > > #### Test the Connect server REST API > > You can make sure the [Connect server REST API](/connect/api-reference/) is accessible using a [`curl`](https://curl.se/docs/manpage.html) command, one of the 1Password Connect server API endpoints, and the token you created. > > 1. Export the Connect server access token as an environment variable. This is the same token you created in [Step 1](#step-1). Alternatively, you can replace `$OP_API_TOKEN` with the token string in the `curl` request. > > > [!TIP] > > > > If you forgot your token, you can create another one with the [`op connect token create` command](/cli/reference/management-commands/connect/#connect-token-create). > > ```shell theme={null} > export OP_API_TOKEN="" > ``` > > 2. Use the following example [`curl`](https://curl.se/docs/manpage.html) command to list the vaults connected to the Connect server. > > ```shell theme={null} > curl \ > -H "Accept: application/json" \ > -H "Authorization: Bearer $OP_API_TOKEN" \ > http://localhost:8080/v1/vaults > ``` > > To stop the Docker containers, run `docker compose down`. > [tab] Kubernetes > > You can deploy a Connect server with Kubernetes. The easiest way to do this is with the [1Password Connect and Operator Helm chart](/k8s/helm/). > > > [!WARNING] > > > > Before you start, you must have a Kubernetes cluster deployed. If you don't already have a cluster, you can create one locally using [minikube](https://minikube.sigs.k8s.io/docs/start/) or use the [Play with Kubernetes](https://labs.play-with-k8s.com/) playground. > > 1. Make sure you have [Docker](https://docs.docker.com/engine/install/) installed and running on your machine. > > 2. Install the latest [Helm](https://helm.sh) release. > > 3. Add the 1Password Helm chart repository. > > The following command adds the [1Password Helm chart repository](/k8s/helm/) to your local instance of Helm. This allows you to download and install all the charts from 1Password's GitHub repository. > > ```shell theme={null} > helm repo add 1password https://1password.github.io/connect-helm-charts/ > ``` > > 4. Install the 1Password Connect server using Helm. > > The following command deploys the 1Password Connect server using the `1password-credentials.json` file. > > > [!TIP] > > > > You can find the `1password-credentials.json` file in the directory where you created the Connect server. > > ```shell theme={null} > helm install connect 1password/connect --set-file connect.credentials=1password-credentials.json > ``` > > #### Other ways to deploy > > Here are some ways you can deploy a Connect server on a Kubernetes cluster: > > ##### Deploy without Helm > > You can deploy a Connect server on a Kubernetes cluster without using Helm charts. See the [sample Kubernetes deployment](https://github.com/1Password/connect/tree/main/examples/kubernetes) on 1Password's GitHub that uses [cert-manager](https://cert-manager.io/) to provision a TLS (transport layer security) certificate for an external domain. > > ##### Deploy alongside the Kubernetes Operator > > The 1Password Connect Kubernetes Operator integrates [Kubernetes Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) with 1Password. It also auto-restarts deployments when 1Password items are updated. [Learn more about the Kubernetes Operator](/k8s/operator/). ### Step 3: Set up applications and services to get information from 1Password Applications and services get information from 1Password through REST API requests to a Connect server. The requests are authenticated with an access token. [Create a new token](/connect/manage-connect/#create-a-token) for each application or service you use. #### Languages [Go](https://github.com/1Password/connect-sdk-go) [Node.js](https://github.com/1Password/connect-sdk-js) [Python](https://github.com/1Password/connect-sdk-python) #### Plugins [Terraform provider](https://github.com/1Password/terraform-provider-onepassword) [Kubernetes integrations](/k8s/integrations) [Hashicorp Vault backend](https://github.com/1Password/vault-plugin-secrets-onepassword) [Ansible collection](/connect/ansible-collection) If your language or platform isn't listed, you can [build your own client using the 1Password Connect Server REST API](/connect/api-reference/). You can also [use 1Password CLI](/connect/cli/) with your Connect server to provision secrets and retrieve item information on the command line. ## Get help To change the vaults a token has access to, [issue a new token](/connect/manage-connect/#create-a-token). To get help and share feedback, join the discussion with the [1Password Support Community](https://1password.community/categories/secrets-automation/). # Hashicorp Vault backend Source: https://www.1password.dev/connect/hashicorp # Manage Connect servers Source: https://www.1password.dev/connect/manage-connect > [!NOTE] > > As of Feb 27, 2025, all 1Password customers have unlimited access to Connect. A Connect server is a type of [Secrets Automation workflow](/secrets-automation/) that allows you to securely access your 1Password items and vaults in your company's apps and cloud infrastructure using a private REST API provided by 1Password Connect Server. You can use 1Password.com or the [Connect REST API](/connect/api-reference/) to:
  • Control which team members and applications have [access to which Connect server access tokens](#manage-access).
  • Monitor and audit [access](#vault-access) and [item usage](#monitor-item-usage).
  • Secure applications by choosing when Connect server access tokens expire.
  • [Create](#create-a-token) and [revoke](#revoke-a-token) Connect server access tokens.
![](https://mintcdn.com/ab-634991b8/Ul-COtb5ywadNlrP/static/img/secrets-automation-billing.png?fit=max\&auto=format\&n=Ul-COtb5ywadNlrP\&q=85\&s=a4958e6eb56c21f24e882c9947a68c67) ## Manage permissions With 1Password Business or 1Password Teams, you can manage Connect server permissions with [groups](#manage-global-permissions), or more granularly, with [environments](#manage-environment-permissions). This allows for enforcement of security best practices. [Learn more about Connect security.](/connect/security/) > [!TIP] > > You can also manage group access using [automated provisioning](https://support.1password.com/scim/). ### Manage global permissions Groups allow you to specify one or more users who can access Connect servers. To assign groups (such as Owners and Administrators) to manage Connect servers: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools/active) in the sidebar. 3. Select [**Permissions**](https://start.1password.com/developer-tools/permissions) at the top of the page, then select [**Secrets Automation**](https://start.1password.com/developer-tools/permissions/C). 4. In the Managers section, select **Manage**, then choose the groups you want to manage Connect servers. 5. Select **Update Groups**. ![Manage Secrets Automation managers](https://mintcdn.com/ab-634991b8/9g9fZmRyYnb5i5sQ/static/img/manage-managers.png?fit=max\&auto=format\&n=9g9fZmRyYnb5i5sQ\&q=85\&s=cf84a1831180bcfa09f302caa301efc0) ### Manage environment permissions Environments allow you to override global permissions (with groups) for a specific Connect server environment. To assign groups (such as Owners and Administrators) to manage a specific Connect server: 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. Select [**Permissions**](https://start.1password.com/developer-tools/permissions) at the top of the page, then select [**Secrets Automation**](https://start.1password.com/developer-tools/permissions/C). 4. In the Environments section, select **Manage**. 5. In the Permissions section, select **Manage**, then choose the groups you want to manage Connect servers in the environment. 6. Select **Update Groups**. ## Manage access tokens You can use [Connect server access tokens](/connect/concepts#connect-server-access-token) to authenticate with your Connect server in your applications and services. * [Create an access token.](#create-a-token) * [Set an access token expiration.](#set-a-token-expiration) * [Revoke an access token.](#revoke-a-token) * [Rename an access token.](#rename-a-token) ### Create a token To create a Connect server access token: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools/active) in the sidebar. 3. Select **Connect servers** at the top of the page, then choose the Secrets Automation environment where you want to create an access token. 4. Select **New Token**. 5. Follow the onscreen instructions to issue the token. > [!WARNING] > > You can't edit the vaults a token can access after you create it. If you want to change the vaults a token can access, you must revoke the token and create a new one. Connect server access tokens support up to 100 vaults each. If you grant a Connect token access to more than 100 vaults, the server may reject requests. ### Set a token expiration When you create a Connect server access token, you can set the token's expiration time to 30, 90, or 180 days. When the expiration time elapses, 1Password revokes the token. To create a token with an expiration date: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools/active) in the sidebar. 3. Select **Connect servers** at the top of the page, then choose the Secrets Automation environment where you want to create an access token. 4. Select **New Token**. 5. Set the "Expires After" to **30 days**, **90 days**, or **180 days**. 6. Follow the onscreen instructions. ### Revoke a token To revoke a Connect server access token: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools/active) in the sidebar. 3. Select **Connect servers** at the top of the page, then choose the Secrets Automation environment where you want to manage access tokens. 4. Select next to the token you want to revoke, then select **Revoke**. ### Rename a token To rename a Connect server access token: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools/active/) in the sidebar. 3. Select **Connect servers** at the top of the page, then choose the Secrets Automation environment where you want to manage access tokens. 4. Select next to the token you want to rename, then select **Rename** and enter a new name. ## Grant or revoke access to vaults To grant or revoke access to vaults: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools/active) in the sidebar. 3. Select **Connect servers** at the top of the page, then choose the Secrets Automation environment where you want to grant or revoke access to vaults. 4. In the Vaults section, select **Manage** and choose the vaults you want to add or remove. 5. Select **Update Vaults**. You can't grant Connect servers access to 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, or your default [Shared](https://support.1password.com/1password-glossary/#shared-vault) vault. ![Manage which vaults have access to each token](https://mintcdn.com/ab-634991b8/9g9fZmRyYnb5i5sQ/static/img/manage-vault-access.png?fit=max\&auto=format\&n=9g9fZmRyYnb5i5sQ\&q=85\&s=852bd667f2913c7ae4ac9505dac3bd49) ## Monitor item usage Connect servers send [reports about item usage](https://support.1password.com/reports/#create-a-usage-report-for-a-team-member-service-account-or-vault) to the 1Password server every time an item is accessed so you can monitor item usage. > [!NOTE] > > Item usage information might take a few hours to sync with 1Password.com. To view item usage for a Connect server: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools/active) in the sidebar. 3. Select **Connect servers** at the top of the page, then choose the Secrets Automation environment (Connect server) you want to monitor. 4. Under Version, select **More Actions** > **View Item Usage Report**. For more information, visit [Create reports in 1Password Business](https://support.1password.com/reports/). ### About Connect server item usage Items accessed through a Connect server update specific fields in the following manner: * The **Action** field in the report always shows Display. * The **Used by** field always includes the name of the Connect server (not the Connect server access token). Connect servers only report item usage when they have a working connection to the 1Password server. If a Connect server can't reach the 1Password server (for example, when it updates or restarts), it might lose item usage information from that time period. Item usage reporting continues when the Connect server has a working connection to the 1Password server again. # Go Source: https://www.1password.dev/connect/sdks/languages/golang # Node.js Source: https://www.1password.dev/connect/sdks/languages/javascript # Python Source: https://www.1password.dev/connect/sdks/languages/python # About 1Password Connect Server security Source: https://www.1password.dev/connect/security You can deploy one or more 1Password Connect servers in your infrastructure to act as a bridge between your applications and the 1Password service. Connect servers allow you to securely share information from 1Password with your applications, tools, and pipelines through the [Connect REST API](/connect/api-reference/). Review the sections on the page to learn more about Connect server security. For information about 1Password security practices, visit the [1Password Security homepage](https://1password.com/security). ## Access control When you [create a Connect server](/connect/get-started/), you select the vaults it can access. Connect servers can only access the vaults you explicitly allow them to access through a [Connect server access token](#connect-server-access-tokens). ### Authorization Only authorized clients can get information from a Connect server. When a client application, service, or API requests information from a Connect server, the HTTP request must have an `Authorization` header containing an authorization token. Otherwise, the Connect server rejects the request. Authorization tokens are only valid for the Connect server they're created for. They're signed by the key for the 1Password account the Connect server uses, using the [ES256 signing algorithm.](https://datatracker.ietf.org/doc/html/rfc7518) ### Usage reports [Usage reports](https://support.1password.com/reports/#create-a-usage-report-for-a-team-member-service-account-or-vault) can be created for users or vaults. Usage reports for team members include information on the number of vaults, groups, and items a team member can access, an overview of vaults where a team member has accessed items, when those items were last accessed, and the action performed. Usage reports for vaults include a list of items showing when they were last accessed, the action performed, and the team member who performed the action. These reports can be helpful when offboarding team members. ## Connect server access tokens A Connect server access token is an authentication string that allows the Connect server to authenticate with 1Password. Each Connect server can have one or more Connect server access tokens, which allows for more fine tuned [access control](#access-control). Connect server tokens can only access information in the vaults you granted them access to. This allows you more granular control over the vaults a Connect server deployment can access. For example, you can grant a Connect server token access to a specific subset of the vaults the Connect server has access to. ### Token rotation You can't change or update Connect server access tokens. If a Connect server token becomes compromised, you must create a new token. To rotate a Connect server access token: 1. [Create a new Connect server access token.](/connect/manage-connect#create-a-token) 2. Update all references to the old Connect token. 3. [Revoke access to the old Connect token.](/connect/manage-connect/#revoke-a-token) ## Security model The Connect server security model has the following guarantees: * A Connect server access token can only read items from vaults you've explicitly given it `READ` access to. * A Connect server access token can only update, delete, and create items for vaults it has you've given it `WRITE` access to. * You can only give a Connect token access to vaults that you have access to. * A Connect server access token associated with a deleted account can't authenticate. * You can't use a Connect server access token to create another Connect server access token. ## Credentials file Creating a Connect server generates a credentials file named `1password-credentials.json`. This file has the following components: | Component | Description | | - | - | | `verifier` | Connect servers use the `verifier` as part of an additional authentication of the bearer token. | | `encCredentials` | The `encCredentials` contains the encrypted credentials necessary for the associated service account. | | `uniqueKey` | The `uniqueKey` identifies the Connect server between its two running processes: the client-facing service and the synchronization service. | | `version` | The `version` indicates the Connect server version number. | | `deviceUuid` | The `deviceUuid` contains the UUID of the device. | ## Responsible disclosure 1Password requests you practice responsible disclosure if you discover a vulnerability. If you find a vulnerability in 1Password, [submit a report on HackerOne.](https://hackerone.com/1password) # Configure your Connect server Source: https://www.1password.dev/connect/server-configuration This article documents Connect server [environment variables](#environment-variables) and special configuration options, such as [TLS](#tls) and [manual bus configuration](#manual-bus-configuration). 1Password Connect Server consists of two containers running in the same network: * The Connect API container ([`1password/connect-api`](https://hub.docker.com/r/1password/connect-api)) * The Connect sync container ([`1password/connect-sync`](https://hub.docker.com/r/1password/connect-sync)) Both containers require a shared volume to store an encrypted copy of your data. ## Requirements Before you can configure your 1Password Connect Server, you must: * [Sign up for 1Password](https://1password.com/pricing/password-manager). * [Setup a Connect server](/connect/get-started/). ## Environment variables The following table lists the available environment variables, their description, and the containers that support them. Most of the environment variables apply to the Connect API and Connect sync containers, but some only apply to the Connect API container. | **Environment variable** | **Description** | **Container support** | | - | - | - | | `OP_SESSION` | The path to the `1password-credentials.json` file. You can also set the value to the [Base64-encoded content of the `1password-credentials.json` file](/connect/aws-ecs-fargate/#get-started). **Acceptable values**: A full file path to the `1password-credentials.json` file. **Default value**: `~/.op/1password-credentials.json` | • Connect API • Connect sync | | `OP_HTTP_PORT` | The port for the HTTP server. **Acceptable values**: Any available port number. **Default value**: `8080` | • Connect API • Connect sync | | `OP_LOG_LEVEL` | The logging level of the container. **Acceptable values**: `info`, `error`, `debug` **Default value**: `info` | • Connect API • Connect sync | | `XDG_DATA_HOME` | The path in which to create the `.op/data/` directory. See [Data volume](#data-volume). **Acceptable values**: A valid file path. **Default value**: `/home/opuser/.op/data` | • Connect API • Connect sync | | `OP_BUS_PORT` | The port for listening to incoming bus connections from other containers. See [Manual bus configuration](#manual-bus-configuration) for more details. **Acceptable values**: Any available port number. **Default value**: A random free port | • Connect API • Connect sync | | `OP_BUS_PEERS` | A comma-separated list of `[hostname]:[bus port]` pairs of other containers to connect to. See [Manual bus configuration](#manual-bus-configuration) for more details. **Acceptable values**: A comma-separated list of `[hostname]:[bus port]` pairs. **Default value**: No default because this variable is optional. | • Connect API • Connect sync | | `OP_HTTPS_PORT` | The port for the HTTP server when using [TLS](#tls). **Acceptable values**: Any available port number. **Default value**: `8443` | • Connect API | | `OP_SYNC_TIMEOUT` | The time (in seconds) to wait for the initial sync to complete. **Acceptable values**: A time duration (for example, `1h`, `30m`, `20s`). **Default value**: `10s` (10 seconds) | • Connect API | | `OP_TLS_KEY_FILE` | The path to the private key file. Only use this environment variable if you plan to [use TLS with your own certificate](#tls-custom). **Acceptable values**: A valid file path. **Default value**: No default because this variable is optional. | • Connect API | | `OP_TLS_CERT_FILE` | The path to the certificate file. This should be the full certificate chain. Only use this environment variable if you plan to [use TLS with your own certificate](#tls-custom). **Acceptable values**: A valid file path. **Default value**: No default because this variable is optional. | • Connect API | | `OP_TLS_USE_LETSENCRYPT` | Only use this environment variable if you want to [use TLS with a Lets Encrypt certificate](#tls-lets-encrypt). **Acceptable values**: Any value (for example, `1`, `true`, or `yes`). **Default value**: No default because this variable is optional. | • Connect API | | `OP_TLS_DOMAIN` | The (sub-)domain for which to request a certificate. The DNS records for this domain must point to the Connect server. See [TLS](#tls). **Acceptable values**: Any domain (or subdomain) name. **Default value**: No default because this variable is optional. | • Connect API | ### Data volume The default location of the shared volume is `/home/opuser/.op/data`. If you set the `XDG_DATA_HOME` environment variable to a path other than `/home/opuser/`, make sure you mount your data volume at the same path. ### TLS By default, 1Password Connect Server is configured for use within a trusted network. If you plan to use Connect outside a trusted network, consider configuring [Transport Layer Security (TLS).](https://www.cloudflare.com/learning/ssl/transport-layer-security-tls/) You can configure TLS for the connection between your application and Connect by [providing your own certificate](#tls-custom) or letting Connect request a certificate [using Let's Encrypt](#tls-lets-encrypt). Connect listens on the port defined by the `OP_HTTPS_PORT` environment variable (default `8443`) when you use TLS. #### Use your own certificate Connect can use a PEM-encoded private key and certificate by setting the following two environment variables for the Connect API container: 1. Set `OP_TLS_KEY_FILE` to the path to the private key file. 2. Set `OP_TLS_CERT_FILE` to the path to the certificate file. This should be the full certificate chain. #### Use Let's Encrypt Connect can also request a certificate from the [Let's Encrypt](https://letsencrypt.org/) Certificate Authority (CA). For this, you must set two environment variables for the Connect API container: 1. Set `OP_TLS_USE_LETSENCRYPT` to any value. 2. Set `OP_TLS_DOMAIN` to the (sub-)domain for which to request a certificate. The DNS records for this domain must point to the Connect server. As long as Connect is running, its HTTPS listener must be reachable on a public IP at port `443` (either by setting `OP_HTTPS_PORT=443` or by forwarding traffic at port `443` to the Connect server's `OP_HTTPS_PORT` value). This makes sure the Connect server can refresh its Let's Encrypt certificate. ### Manual bus configuration > [!WARNING] > > Manual bus configuration only works with Connect server [version 1.5.0](https://github.com/1Password/connect/blob/main/CHANGELOG.md#v150) and later. By default, the two containers (Connect API and Connect sync) automatically discover and connect to the shared bus. This discovery mechanism requires the `NET_BROADCAST` capability, which you can't always grant to containers. However, it’s possible to manually configure the shared bus. To manually configure the shared bus: 1. Assign a static port for the bus by setting the `OP_BUS_PORT` environment variable to a free port for both containers. 2. Set the `OP_BUS_PEERS` environment variable for the Connect API container to `[hostname]:[bus port]`, where `hostname` is the name of the Connect sync container and `bus port` the value of `OP_BUS_PORT` for the Connect sync container. 3. Set the `OP_BUS_PEERS` environment variable for the Connect sync container to `[hostname]:[bus port]`, where `hostname` is the name of the application container and `bus port` is the value of `OP_BUS_PORT` for the Connect API container. The following examples show the configuration values necessary for the Connect API container and the Connect sync container. > [tab] Connect API container > > The following example sets environment variables for a Connect API container called `op-connect-api`. > > ```txt theme={null} > OP_BUS_PORT=11223 > OP_BUS_PEERS=op-connect-api:11223 > ``` > [tab] Connect sync container > > The following example sets environment variables for a Connect sync container called `op-connect-sync`. > > ```txt theme={null} > OP_BUS_PORT=11223 > OP_BUS_PEERS=op-connect-sync:11223 > ``` ## Examples The [1Password Connect repository](https://github.com/1Password/connect) has example Connect server configurations using Kubernetes, Docker Compose, and AWS Fargate. * [Example Kubernetes deployment](https://github.com/1Password/connect/tree/main/examples/kubernetes) * [Example Docker Compose deployment](https://github.com/1Password/connect/tree/main/examples/docker/compose) * [Example AWS Fargate deployment](https://github.com/1Password/connect/tree/main/examples/aws-ecs-fargate) # 1Password Environments Source: https://www.1password.dev/environments 1Password Environments store project secrets as environment variables you can share with your team and load into your apps, local .env files, and AI coding tools. A 1Password Environment holds the secrets for one project or stage, like `dev` or `staging`, separate from the rest of your vaults. Your app, terminal, CI/CD, or AI agent reads them from 1Password when it needs them, so they never sit in a plaintext `.env` file. **1. Create an Environment** In the 1Password app, go to **Developer** > **View Environments** > **New environment**. [Details](#create-an-environment) **2. Add your secrets** Import an existing `.env` file or add key-value pairs. [Details](#add-secrets-to-an-environment) **3. Use them where your code runs** Pick one way to load them: * [Local .env file](/environments/local-env-file): a file 1Password mounts for your app, with nothing written to disk. * [1Password CLI or SDKs](/environments/read-environment-variables): read secrets in your terminal or Go, JavaScript, and Python code. * [MCP server](/environments/mcp-server): let Claude Code, Cursor, and other agents use them. * [AWS Secrets Manager](/environments/aws-secrets-manager) or the [Credential Broker](/brokered-access): for cloud and machine workflows. > [!WARNING] > > When sharing an Environment with others and reading its contents outside of 1Password, review the Environment's values carefully before using them in any program or workflow. What you store in 1Password is exactly what we provide when you read your Environment. [Video overview of 1Password Environments and how they help you manage project secrets.](https://www.youtube.com/embed/mrhtzh05jG4) ## Requirements Before you can use Environments, you'll need to: * [Sign up for 1Password](https://1password.com/pricing/password-manager). * Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux). \ This feature is not available in 1Password for iOS or Android. * Have an Owner or Administrator [turn the Environments policy on](#turn-the-environments-policy-on-or-off) from the 1Password admin console. ## Create an Environment 1. In the 1Password desktop app, go to **Developer** > **View Environments**. 2. Select **New environment**. 3. Enter a name for the new environment, then select **Save**. If you have multiple 1Password accounts, you can select which account to save the environment to. > [!TIP] > > You can also use [1Password Developer Watchtower](/watchtower) to find `.env` files containing plaintext secrets on your device and [import them into Environments](/watchtower#import-plaintext-secrets-from-local-env-files). ## Add secrets to an Environment After you create an Environment, you can add your project secrets to it. Each secret is a key-value pair that includes a name (for example, `DB_HOST`, `DB_USER`, or `API_KEY`) and its value. To add secrets to an Environment, open and unlock the 1Password desktop app, navigate to **Developer** > **View Environments**, then select the Environment you want to update. You can add secrets in two ways: * If you have an existing `.env` file for your project, select **Import .env file**. 1Password will automatically import the environment variables from the file as secrets. * To manually add secrets, select **New secret**. Enter the secret's name in the **Name** field and its value in the **Value** field. Repeat this process for each secret you want to add. > [!NOTE] > > Values are hidden by default, which means they'll be masked in the output of CLI and SDK operations. To change this, select the vertical ellipsis next to the secret, then select **Show value by default**. You can add, edit, or remove secrets from your Environment at any time. To update your secrets, open the Environment and select **Edit**. ## Use your Environments in your workflows In the 1Password desktop app, you can configure each Environment to fit your workflow: * [**Local `.env` file**](/environments/local-env-file): Create a locally mounted `.env` file to make your secrets available during local development without writing plaintext secrets to disk. * [**Agent hook**](/environments/agent-hook-validate): Use 1Password's hook to validate your locally mounted `.env` files with supported IDEs and agents like Cursor and GitHub Copilot. * [**Programmatically read Environments**](/environments/read-environment-variables): Read secrets from your Environments, then pass them to applications and scripts using 1Password CLI or 1Password SDKs. * [**AWS Secrets Manager**](/environments/aws-secrets-manager): Sync secrets from 1Password to AWS Secrets Manager. ## Manage your Environments > [!TIP] > > 1Password Environments return values exactly as they are entered. Format your values as you would in a standard `.env` file. For example: > > * If a value contains a space, enclose the value in quotation marks: `"bar baz"` > * If a value contains special characters, escape them with a `\`: `\$100` Values are hidden by default, but you can toggle the visibility on or off in the **Actions** column. You can also delete secrets from this column. Select **Edit** within the environment to add, edit, or delete secrets at a later time. ### Rename or remove an Environment If you want to rename or remove an Environment: 1. In the 1Password desktop app, go to **Developer** > **View Environments**. 2. Select the Environment you want to manage, then select **Manage Environment**. 3. Choose **Rename environment** or **Delete environment**. > [!WARNING] > > Deleted Environments cannot be restored and any associated integrations will stop working. 1Password will prompt you to confirm whether or not you want to delete your Environment before proceeding. ### Share an Environment If you're using a shared account, such as for a team or business, you can share Environments with your team members. Each Environment remains independent, allowing you to work across multiple environments in different accounts while keeping their secrets separate. Access must be granted for each Environment. To share an Environment: 1. In the 1Password desktop app, go to **Developer** > **View Environments**. 2. Select the Environment you want to share, then select **Manage environment** > **Manage access**. You'll be redirected to the Admin Console. 3. Select **Manage**, then search for and select the team members or groups you want to add to your Environment. 4. To adjust permissions for team members or groups added to your Environment, select the People or Groups tab in the "Environment access" screen. Next to the team member or group name, select the ellipsis and choose to allow viewing, allow editing, or allow managing. To remove a team member or group from an Environment, return to the "Manage access" screen. Select the People or Groups tab in the "Environment access" screen, then select the ellipsis next to the team member or group name you want to remove and select **Remove Access**. ### Sort and search Environments You can curate your Environments view to surface information you need in the way that best supports your work. From the Environments page in the 1Password desktop app (**Developer** > **View Environments**), select the arrow next to the **Name** column to organize Environments alphabetically or reverse-alphabetically. Search for Environments from anywhere in the 1Password app [using the top-level search bar](https://support.1password.com/search-1password/) to navigate to your Environments directly. Enter the name of an Environment in the search, then select it to go directly to that Environment's details page. You can also sort or search for specific secrets within Environments. Within an Environment's details page, select the arrow next to the secrets **Name** column to organize secrets alphabetically or reverse-alphabetically. To search secrets, select **+ Add secret** then enter a secret name in the **Search secrets** bar. ## Turn the Environments policy on or off Owners and Administrators can turn Environments on or off from the 1Password Admin Console. This controls whether all users in an account have access to the Environments feature. If Environments are turned off, any previously created Environments and integrations will become inaccessible to users until the policy is re-enabled. No data is deleted when the policy is turned off. Full access to all previously created Environments will be restored if the policy is turned back on. If a user tries to access previously available Environments after the policy is turned off, they’ll see a message that the policy has been turned off with instructions to contact an Administrator if they need access. To turn the Environments policy on or off: 1. Sign in to 1Password.com with your administrator or owner account. 2. From the sidebar, go to **Policies** then select **Sharing and permissions**. 3. Select **Developer permissions**. 4. Scroll to the **Environments** toggle, then turn it on or off. 5. Follow the confirmation steps, then scroll to the bottom of the page and select **Save**. ## Learn more * [Access secrets from 1Password through local `.env` files](/environments/local-env-file) * [Use 1Password's agent hook to validate local .env files from 1Password Environments](/environments/agent-hook-validate) * [Sync secrets between 1Password and AWS Secrets Manager (beta)](/environments/aws-secrets-manager) * [Programmatically read Environments with 1Password CLI or 1Password SDKs](/environments/read-environment-variables) * [1Password Developer Watchtower](/watchtower) * [Workflow: Secure your developer secrets](/get-started/secure-developer-secrets) * [Workflow: Secure local development](/get-started/secure-developer-secrets) * [Workflow: Secure your deployments](/get-started/secure-deployment) # Use the 1Password agent hook to validate local .env files from 1Password Environments Source: https://www.1password.dev/environments/agent-hook-validate > [!NOTE] > > [1Password agent hooks](https://github.com/1Password/agent-hooks/) run automated checks on your 1Password setup inside supported agents and IDEs, so required resources are in place before an agent executes commands. The hook on this page validates locally mounted `.env` files. If you use Cursor, it's bundled in the [1Password Developer Tools plugin for Cursor](/environments/cursor-plugin), along with an agent skill and MCP server configuration. You can use the [1Password local `.env` file validation hook](https://github.com/1Password/agent-hooks/blob/main/hooks/1password-validate-mounted-env-files/README.md) with supported IDEs and agents to validate that [locally mounted `.env` files](/environments/local-env-file/) from 1Password Environments are properly set up before the agent executes shell commands. If any required `.env` files are missing or invalid, the hook prevents the agent from executing and the agent provides instructions for how to fix the issue. The hook currently supports Claude Code, Cursor, GitHub Copilot, and Windsurf. ## Requirements * [1Password subscription](https://1password.com/pricing/password-manager) * 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux) * [`sqlite3`](https://sqlite.org/index.html) installed and available in your PATH * [Claude Code](https://code.claude.com/docs/en/overview), [Cursor](https://cursor.com/home), [GitHub Copilot](https://github.com/features/copilot), or [Windsurf](https://windsurf.com/) > [!NOTE] > > **Windows not supported** > > Local `.env` files for 1Password Environments are currently only supported on Mac and Linux. If you're on Windows, the hook will skip the validation checks. ## Step 1: Set up your Environments To use the hook, you'll first need to: 1. [Create one or more Environments](/environments) in 1Password to store your project secrets. 2. [Configure locally mounted `.env` files](/environments/local-env-file) for them. ## Step 2: Install the hook in your project > [tab] Claude Code > > To install the 1Password hook for Claude Code, you'll need to: > > 1. Clone the [1Password Agent Hooks repository.](https://github.com/1Password/agent-hooks) > 2. Follow the instructions to [run the install script.](https://github.com/1Password/agent-hooks/blob/main/README.md#initial-setup) > > You can run `claude --debug` to see hook matches and exit codes in your session. > [tab] Cursor > > The `.env` file validation hook is included as part of the [1Password Developer Tools plugin for Cursor](/environments/cursor-plugin), which also installs the `1password-environments` agent skill and 1Password Environments MCP Server configuration. To install it: > > 1. Open Cursor and navigate to the **Cursor Agents** window. > > 2. In the left sidebar, select **Customize**. > > 3. Select **Plugins** in the top menu. > > 4. Search for **1Password Developer Tools** then select **Add**. > > 5. Restart Cursor. > > > [!TIP] > > > > You can also install the plugin: > > > > * From the command palette: Enter `Cmd+Shift+P` on Mac or `Ctrl+Shift+P` on Linux, enter **Plugins: Install Plugin**, then search for **1Password Developer Tools**. > > * In the Cursor Agent window: Run `/add-plugin 1password`. > > After you install the plugin, restart Cursor and tell the Cursor Agent to perform a task that requires running a shell command. If your `.env` files are properly configured, the command will proceed. Otherwise the Agent will guide you through fixing the issue. > > To confirm the hook worked as expected, open Cursor, then navigate to **Settings** > **Hooks** > **Execution Log**. > [tab] GitHub Copilot > > To install the 1Password hook for GitHub Copilot, you'll need to: > > 1. Clone the [1Password Agent Hooks repository.](https://github.com/1Password/agent-hooks) > 2. Follow the instructions to [run the install script.](https://github.com/1Password/agent-hooks/blob/main/README.md#initial-setup) > [tab] Windsurf > > To install the 1Password hook for Windsurf, you'll need to: > > 1. Clone the [1Password Agent Hooks repository.](https://github.com/1Password/agent-hooks) > 2. Follow the instructions to [run the install script.](https://github.com/1Password/agent-hooks/blob/main/README.md#initial-setup) ## Step 3: Choose how you want the hook to validate your `.env` files ### Default mode By default, the hook will check the 1Password desktop app to find `.env` files related to your project based on the file path you configured in 1Password Environments. ### Configured mode Alternatively, you can create a `.1password/environments.toml` file at the root of your project that specifies which locally mounted `.env` files to validate. The hook only validates the specified files. To do this, the hook parses the TOML file to extract mount paths from the `mount_paths` array field. Mount paths can be relative to the project root or absolute. For example: ```toml .1password/environments.toml theme={null} mount_paths = ["application.env", "billing.env"] ``` The `mount_paths` field must be explicitly defined in the TOML file. If the file exists but doesn't contain a `mount_paths` field, the hook will log a warning and fall back to default mode. If no `.env` files are specified in the TOML file, all commands will be allowed to run. ## How it works 1Password hooks are custom scripts that run before or after specific stages of the agent loop. Each hook runs as a spawned process that communicates with the agent over standard input and output using JSON in both directions. Hooks can observe, block, or modify the agent's behavior as it runs. The 1Password local `.env` file validation hook is designed to be used with the event that runs before command execution in your agent. When configured, the hook prevents the agent from proceeding when required environment files are not available. For example, in Cursor the hook works with the [`beforeShellExecution` event](https://cursor.com/docs/agent/hooks#hook-events), while in GitHub Copilot it works with the [`preToolUse` event.](https://docs.github.com/en/copilot/tutorials/copilot-cli-hooks#5-enforce-policies-with-pretooluse) When the agent tries to run a command, the hook first checks for a `.1password/environments.toml` file in the current project directory. If a TOML file exists and contains the required `mount_paths` field, the agent validates only the specified `.env` files. If no TOML file exists, the agent queries the 1Password desktop app for all `.env` files mounted in the project directory. The hook then confirms that each `.env` file discovered for the project is enabled, the mount file exists, and the file is a valid FIFO (named pipe). If all required `.env` files are enabled and configured correctly, the command execution is allowed to proceed. If one or more required `.env` files are missing, disabled, or invalid, the hook prevents the agent from proceeding and the agent provides an error message with steps to fix the issue. The hook uses a "fail open" approach in default mode. If it can't access the 1Password database, the hook logs a warning and allows subsequent commands to proceed. This makes sure development can proceed if the 1Password app is not installed or the database is unavailable. Similarly, if a TOML file exists but no `.env` files are specified, the command is allowed to proceed. ### Configuration examples #### Single .env file ```toml .1password/environments.toml theme={null} mount_paths = [".env"] ``` Only `.env` is validated. Other environment files are ignored. #### Multiple `.env` files ```toml .1password/environments.toml theme={null} mount_paths = [".env", "billing.env", "database.env"] ``` Only the three declared `.env` files are validated. #### No validation ```toml .1password/environments.toml theme={null} mount_paths = [] ``` No `.env` files are validated. All commands are allowed. #### Default mode No `.1password/environments.toml` file exists or the `mount_paths` field has been improperly defined. The hook discovers and validates all mounts configured in 1Password that are within the project directory. ## Troubleshooting The hook logs information to `/tmp/1password-hooks.log` for troubleshooting. Check this file if you encounter issues. Log entries include timestamps and detailed information about: * Database queries and results * Mount validation checks * Permission decisions * Error conditions Learn more about [troubleshooting agent hooks.](https://github.com/1Password/agent-hooks/tree/main/hooks/1password-validate-mounted-env-files#debugging) ## Learn more * [Access secrets from 1Password through local `.env` files](/environments/local-env-file) * [Use the 1Password Developer Tools plugin for Cursor to manage Environments and validate local `.env` files](/environments/cursor-plugin) * [1Password Agent Hooks repository](https://github.com/1Password/agent-hooks/) * [Cursor Hooks](https://cursor.com/docs/agent/hooks) * [GitHub Copilot hooks](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks) * [Workflow: Secure AI access](/get-started/secure-ai-access) * [Workflow: Secure local development](/get-started/secure-developer-secrets) [Video walkthrough of secure AI coding with the 1Password hook for Cursor agentic coding IDE.](https://www.youtube.com/embed/D5WKhGRxhsE) # Sync secrets from 1Password to AWS Secrets Manager (beta) Source: https://www.1password.dev/environments/aws-secrets-manager Beta Use the 1Password AWS Secrets Manager integration to centralize secrets management and simplify your workflow. [Create an Environment with secrets in 1Password](/environments/), then securely sync those secrets to AWS Secrets Manager. > [!TIP] > > **Share your feedback** > > To share your thoughts about the integration with us, submit your feedback using our [feedback form.](https://forms.gle/3NUc7g3ywL4moksD7) ## Requirements Before you can use the 1Password AWS Secrets Manager integration, you'll need to: 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. [Install the 1Password desktop app.](https://1password.com/downloads) 3. [Create an environment](/environments#create-an-environment) to use with AWS Secrets Manager. 4. Have an AWS account with the ability to create IAM resources. ## Set up the AWS Secrets Manager integration ### Step 1: Navigate to the AWS configuration page in 1Password 1. In the 1Password desktop app, select **Developer** in the sidebar, then select **View Environments**. 2. Find the name of the environment you created for AWS Secrets Manager and select **View environment**. 3. Under **Connect to**, select the **Connect** button next to AWS Secrets Manager. This opens the AWS Secrets Manager configuration page, where you can set up the integration to sync the environment from 1Password to AWS Secrets Manager. ### Step 2: Register the 1Password Secrets Sync SAML provider Authentication to your AWS account happens through SAML. You'll need to register the 1Password Secrets Sync SAML provider within your AWS account. #### 2.1: Download the SAML metadata from 1Password On the AWS Secrets Manager configuration page in 1Password, select **Download SAML metadata**. This will download a `saml-metadata.xml` file to your Downloads folder. #### 2.2 Add the SAML provider in AWS 1. [Sign in to the AWS Management Console](https://console.aws.amazon.com/) and navigate to the [Identity and Access Management (IAM) console.](https://console.aws.amazon.com/iam/) 2. From the navigation pane, select **Identity providers**, then select **Add provider**. 3. Configure the following provider details: * **Provider type**: Select **SAML** as the provider type, if it's not already selected. * **Provider name**: Enter the name you want to use for the identity provider. For example: `1PasswordSecretsSync`. * **Metadata document**: Select **Choose file**, then select the **`saml-metadata.xml`** file you saved to your Downloads folder in the previous step. 4. Scroll to the bottom of the page and select **Add provider**. You should see a message that says the provider was added. #### 2.3 Add the SAML provider ARN to the 1Password configuration page 1. In the [identity providers area of the IAM console](https://console.aws.amazon.com/iam/home#/identity_providers), search the list for the provider you added. 2. Select the provider name to open its details. 3. Copy the **ARN** from the **Summary** section. 4. In the 1Password app, paste the ARN you copied from AWS into the **SAML provider ARN** field. ### Step 3: Create an IAM policy for managing secrets 1. From the navigation pane of the [AWS IAM console](https://console.aws.amazon.com/iam/), select **Policies**, then select **Create policy**. 2. Select **JSON** as the policy editor. 3. Copy the following permission statement and paste it into the policy editor window, replacing any default content already in the editor: ```json theme={null} { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:RestoreSecret", "secretsmanager:PutSecretValue", "secretsmanager:CreateSecret", "secretsmanager:DeleteSecret", "secretsmanager:TagResource", "secretsmanager:UpdateSecret" ], "Resource": "*" } ] } ``` 4. Select **Next**. 5. On the "Review and create" page, enter a name for the policy in the **Policy name** field. For example: `1PasswordSecretsSync`. You can optionally add a description in the **Description** field. 6. Scroll to the bottom of the page and select **Create policy**. You should see a message that says the policy was created. ### Step 4: Create an IAM role for the sync integration #### 4.1: Create the IAM role in AWS 1. From the navigation pane of the [AWS IAM console](https://console.aws.amazon.com/iam/), select **Roles**, then select **Create role**. 2. From the list of trusted entity types, select **SAML 2.0 federation**. 3. Select the **SAML 2.0–based provider** menu, then select the SAML provider you created in [step 2](#2-2-add-the-saml-provider-in-aws). 4. In the Condition section, select **Add condition** and configure the following fields: * **Key**: Select **SAML:sub** from the menu. * **Condition**: Select **StringEquals** from the menu. * **Value**: Go back to the 1Password configuration page and select **Copy SAML subject**. Then paste the SAML subject in the **Value** field. 5. Select **Next**. 6. Select the checkbox next to the policy you just created, then scroll to the bottom of the page and select **Next**. \ Only select the checkbox and not the name of the policy itself. 7. On the "Name, review, create" page, enter a name for the IAM role in the **Role name** field. You can optionally add a description in the **Description** field. 8. Scroll to the bottom of the page and select **Create role**. You should see a message that says the policy was created. #### 4.2 Add the IAM role ARN to the 1Password configuration page 1. In the [Roles area of the IAM console](https://console.aws.amazon.com/iam/home#/roles), search the list for the role you added. 2. Select the role name to open its details. 3. Copy the **ARN** from the **Summary** section. 4. In the 1Password app, paste the ARN you just copied from AWS into the **IAM role ARN** field. ### Step 5: Configure the target region and secret name in 1Password 1. In the 1Password app, find the **Target region** field in the configuration page. Enter the AWS Secrets Manager region where you want to sync your Environment. For example: **`us-east-1`** or **`eu-central-1`**. If you're not sure what region your account uses, [go to the AWS console](https://console.aws.amazon.com/) and check which region is displayed in the URL. For example: `https://us-east-1.console.aws.amazon.com/console/home/`. 2. 1Password automatically populates the **Target secret name** field with the name of your environment. You can edit this field if you want to change the name of the secret, or you can edit the name of the secret in AWS later. AWS Secrets Manager does not allow duplicate names, so make sure it’s unique. 3. (Optional) If you use a custom KMS key with AWS Secrets Manager, you can enter [the key's ID or ARN](https://docs.aws.amazon.com/kms/latest/developerguide/find-cmk-id-arn.html) in the **KMS key ID** field. AWS will then encrypt your secrets with this key. If you set a value for this field, make sure the IAM role has the [required KMS permissions.](https://docs.aws.amazon.com/secretsmanager/latest/userguide/security-encryption.html) ### Step 6: Create the AWS Secrets Manager integration in 1Password 1. Review the configuration details in 1Password. 2. When you've finished, select **Create integration** in the 1Password app. ### Step 7: Test the connection and enable the integration in 1Password Select **Test connection** to test the connection to AWS. This creates and immediately deletes a placeholder value in AWS Secrets Manager, to ensure the correct permissions have been granted for the sync integration. If everything is set up correctly and the test is successful, select the toggle to enable the integration and start syncing to AWS Secrets Manager. ### Step 8: Sync your secrets from 1Password to AWS After you enable the AWS Secrets Manager integration, any secrets saved in your Environment will be synced to AWS Secrets Manager. With the secrets synced to AWS Secrets Manager, you can use one of the [methods provided by AWS](https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieving-secrets.html) to load the secrets into your application or workload on AWS. ## How the integration works The secrets sync integration runs on 1Password's [Confidential Computing platform](https://blog.1password.com/confidential-computing/), leveraging [AWS Nitro Enclaves](https://docs.aws.amazon.com/enclaves/latest/user/nitro-enclave.html), to ensure a reliable, always-on sync to AWS Secrets Manager. This allows you to set up the integration once per environment, only requiring AWS credentials to create the IAM resources. After the integration is set up, you can invite team members to edit the environment in 1Password without needing to provide AWS credentials to each person. ![A diagram that illustrates how the integration works. When you change an environment secret in the 1Password desktop app, it triggers a sync to the Confidential Computing platform (AWS Nitro Enclave) which 1Password uses for syncing secrets. The change is then propagated securely from the Confidential Computing platform to the AWS Secrets Manager, then from AWS to the application running on AWS that uses the environment secret.](https://mintcdn.com/ab-634991b8/pfc4yDcmGyZA8XDs/static/img/aws-how-integration-works.png?fit=max\&auto=format\&n=pfc4yDcmGyZA8XDs\&q=85\&s=9b54df0917bd3f0d69ee4b5c8cd6e58e) Learn more about some [limitations of the integration](#limitations). ## Manage the integration ### Update your environment secrets If you need to add, update, or remove any secrets, [make the changes in your 1Password Environment](/environments#manage-your-environments), then save your changes to trigger another sync from 1Password to AWS Secrets Manager. ### Stop using the integration You can disable the AWS Secrets Manager integration to temporarily stop syncing your environment secrets from 1Password to AWS, or delete the integration to remove it. In the 1Password desktop app, navigate to the Environment you're using with AWS Secrets Manager and toggle the switch on the AWS Secrets Manager card to **Disabled** to stop syncing your environment. Or select the vertical ellipsis > **Delete integration** to remove the integration. ## Troubleshooting | Error | Troubleshooting steps | | - | - | | The IAM role doesn't have the necessary permissions to manage secrets in AWS Secrets Manager. | Check the policy attached to your IAM role in AWS and make sure the role's IAM policy is [configured correctly](#step-3-create-an-iam-policy-for-managing-secrets). | | The sync integration failed to assume the IAM role. | Make sure that the [SAML provider is registered correctly](#step-2-register-the-1password-secrets-sync-saml-provider) and that the [IAM role](#step-4-create-an-iam-role-for-the-sync-integration) has the right [trust policy attached](#step-3-create-an-iam-policy-for-managing-secrets). | | There's an outage or internal error within the AWS platform. | [Check the AWS Health Dashboard](https://docs.aws.amazon.com/health/latest/ug/aws-health-account-views.html) for any events affecting AWS services in your account and try again later. [Contact 1Password support](mailto:support@1password.com) if the problem persists. | | The KMS key is invalid or can’t be used. | [Verify the KMS key exists in AWS](https://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html) and that it has an IAM policy that allows it to be used with [AWS Secrets Manager.](https://docs.aws.amazon.com/secretsmanager/latest/userguide/security-encryption.html) | | The AWS Secrets Manager quota has been reached. | Try again later or remove resources to stay within the [AWS Secrets Manager quotas.](https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_limits.html) | | The environment exceeds the maximum size allowed in AWS Secrets Manager (64 KB). | [Create additional environments](/environments#create-an-environment) so you can split the large environment into multiple smaller environments. Then set up a separate integration for each one so all your secrets are synced. | | The SAML subject isn't set correctly in the IAM role's trust policy. | [Update the IAM role’s trust policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_update-role-trust-policy.html) to set the correct SAML subject as the `saml:sub` condition. | | A secret with the configured name already exists in AWS Secrets Manager. | [Set a different target secret name](#step-5-configure-the-target-region-and-secret-name-in-1password) on the configuration page in 1Password, or [delete the secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_delete-secret.html) in AWS Secrets Manager that uses the same name. | If you encounter problems that you can't resolve with these steps, try [deleting the integration](#stop-using-the-integration) and setting it up again. Or [contact 1Password support](mailto:support@1password.com) for more help. ## Limitations There are some limitations to consider if you use the beta integration. * The integration supports unidirectional (one-way) syncing from 1Password to AWS Secrets Manager. Changes made to environment secrets in AWS Secrets Manager won't be synced to 1Password. * If you have environment secrets in AWS Secrets Manager that require auto-rotation, you should continue to manage them there. This will prevent environment secrets becoming out of sync between AWS and 1Password. * It's best practice to maintain one definitive copy of a secret in 1Password, either as a 1Password item or as a secret in a 1Password Environment. Keeping multiple copies of the same secret could lead to different versions becoming out of sync. * There's a 64KB size limit for Environments synced to AWS Secrets Manager. An example of where you might run into this limit is if you're defining environment variables for a monolithic application. In this scenario, you could split secrets out into separate Environments, each with its own sync integration. ## Learn more * [1Password Environments](/environments) * [Access secrets from 1Password through local `.env` files](/environments/local-env-file) * [Workflow: Secure your deployments](/get-started/secure-deployment) * [Workflow: Secure local development](/get-started/secure-developer-secrets) # Use Claude Code with 1Password Environments Source: https://www.1password.dev/environments/claude-plugin Give Claude Code the 1Password Environments workflow and connect it to the 1Password Environments MCP server. Beta The [1Password Developer Tools plugin for Claude Code](https://github.com/1Password/1password-claude-plugin) connects [1Password Environments](/environments) to [Claude Code.](https://code.claude.com/docs/en/overview) The plugin includes: * An MCP configuration for the [1Password MCP server](/environments/mcp-server), which allows Claude Code to manage your Environments with secure authorization prompts. * An agent skill that supplies Claude Code with end-to-end workflows for interacting with 1Password Environments. ## Requirements * [1Password subscription](https://1password.com/pricing/password-manager) * 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux) * [Claude Code](https://code.claude.com/docs/en/overview), in the Claude desktop app or version 2.1.273 or later in your terminal or IDE. > [!NOTE] > > **Platform support** > > The [1Password MCP server](/environments/mcp-server) and [locally mounted `.env` files](/environments/local-env-file) are currently only supported on Mac and Linux. ## Step 1: Set up your Environments Before you get started, you can set up the [Environments](/environments/) that Claude Code will interact with. 1. [Create one or more Environments](/environments) in 1Password to store your project secrets. 2. [Configure locally mounted `.env` files](/environments/local-env-file) for them. You can also wait and [use the plugin to import your existing `.env` file](#have-claude-code-import-an-environment-and-make-it-available-in-your-project) and mount a local `.env` file destination on your behalf. ## Step 2: Install the plugin To install the plugin: 1. Open your terminal, go to your project directory, then enter `claude` to start a Claude Code session. 2. Enter `/plugin` to open the plugin panel on the **Discover** tab. 3. Type **1Password Developer Tools** to search, then press `Enter` on the 1Password Developer Tools plugin. 4. Choose an installation scope: * **User scope**: Install the plugin for yourself in every project on your device. * **Project scope**: Install the plugin for everyone who works in the repository. * **Local scope**: Install the plugin for yourself in the current repository only. > [!TIP] > > You can also install the plugin: > > * From the Claude desktop app or [claude.ai](https://claude.ai), select **Customize** > **Plugins** > **Discover**, search for **1Password Developer Tools**, then select **Add**. The plugin syncs to Claude Code the next time you start a session signed in to the same Claude account. > * From the 1Password marketplace, open a Claude Code session and run `/plugin marketplace add 1Password/1password-claude-plugin`, then run `/plugin install 1password@1password`. Installing the plugin registers the `1password-environments` agent skill and the MCP server configuration at the same time. ## Step 3: Turn on the MCP server in 1Password > [!NOTE] > > 1Password Enterprise Password Manager admins can turn the MCP server feature on and off. To do so, [sign in](https://start.1password.com/signin/) to your account on 1Password.com, then go to **Policies** > **Agentic permissions** and turn the **Local MCP server** option on or off as needed. The plugin's MCP configuration connects Claude Code to the [1Password MCP server](/environments/mcp-server). To turn the server on: 1. Open the 1Password desktop app. 2. Go to **Settings** > **Developer** and select **Integrate with MCP clients**. To confirm Claude Code connected to the server, start a new Claude Code session and ask it to list your 1Password Environments. If the server is connected, you'll get an authorization prompt from the 1Password desktop app. In a terminal, you can also enter `/mcp` to open the MCP panel and check the status of the **1Password** server. ## Step 4: Use Claude Code to manage your Environments Now that you have the plugin installed, you can ask Claude Code to manage your Environments on your behalf. When you first prompt Claude Code to access an Environment, you'll get a secure authorization prompt from the 1Password desktop app that allows you to choose whether Claude Code has permission to list and create Environments. ### Have Claude Code import an Environment and make it available in your project If you have a plaintext `.env` file in your codebase, you can ask Claude Code to import its contents into a 1Password Environment as secrets. Claude Code will create the Environment then mount it at the same file path as the original file, so your project secrets are available without being tracked by Git or stored in plaintext on your device. > [!WARNING] > > After Claude Code imports your `.env` file, make sure to rotate all secrets that were previously stored in plaintext. Moving your project secrets to 1Password protects them going forward, but doesn't mitigate any past exposure, such as in your Git history or your coding agent memory. The `1password-environments` agent skill directs Claude Code to take the following steps when you prompt it to import an existing `.env` file into 1Password: 1. Read the `.env` file to get its variable names and values, then pass the values to 1Password without printing them in chat. 2. Create the Environment, or resolve the one you named. If an Environment with the name already exists, Claude Code stops and asks how you want to proceed instead of creating a duplicate. You can choose to merge the new secrets into the existing Environment or create a new Environment with a different name. 3. Add the secrets, with API keys, tokens, passwords, private keys, and connection strings set to concealed in 1Password. 4. Mount the Environment at the original `.env` file's path as a [local `.env` file](/environments/local-env-file). When Claude Code needs to access the Environment, you'll get a secure authorization prompt that allows you to choose its permissions. ![Claude Code importing a .env file into 1Password using the 1password-environments skill, with a 1Password authorization prompt to list and create environments.](https://mintcdn.com/ab-634991b8/lbjuyDsM44WulO7u/static/img/environments/1password-plugin-claude.png?fit=max\&auto=format\&n=lbjuyDsM44WulO7u\&q=85\&s=6b9cd97620c25f169bf98a3d6028d85e) > [card] [Learn more about how local .env files work](/environments/local-env-file#how-it-works) > > The contents of locally mounted `.env` files aren't tracked by Git or stored on your device, and are only available at the moment you access them. ### Manage your Environments from Claude Code The [1Password MCP server](/environments/mcp-server) lets you use Claude Code to manage your 1Password Environments with secure authorization prompts. The MCP server only sees secret names, and never returns secret values stored in 1Password to the agent. Your secrets stay safe in 1Password and are only accessed by authorized processes. You can prompt Claude Code to perform tasks like: * "List my 1Password Environments" * "Create an Environment from my project `.env` file" * "Import `.env` into 1Password and mount it here" * "Mount my staging Environment as `.env` in this repo" * "What secrets are in my production Environment?" * "Add a placeholder for my OpenAI API key" * "Create a new Environment called `my-app-dev`" > [!WARNING] > > Make sure to rotate any secrets you import to 1Password that were previously stored in plaintext in your codebase or `.env` files. Moving your project secrets to 1Password secures them going forward, but doesn't mitigate any past exposure, such as in your Git history or your coding agent memory. The 1Password desktop app may prompt for approval when Claude Code connects to the MCP server or accesses an Environment. > [card] [Learn more about the 1Password MCP server](/environments/mcp-server) > > See how the MCP server handles authorization, why your secrets stay out of the agent's context, and how to use it with other MCP clients. ## Troubleshooting ### If Claude Code can't connect to the MCP server on macOS 27 Golden Gate If you updated to macOS 27 Golden Gate and the 1Password server shows `MCP error -32000: Connection closed` in Claude Code, even though you've turned on "Integrate with MCP clients", macOS may be blocking Claude Code from accessing data from the 1Password app. To allow access: 1. Open **System Settings** > **Privacy & Security** > **Files & Folders**. 2. Select the Claude app if you use Claude Code in the Claude desktop app. If you run `claude` in a terminal, select the terminal app instead. If you use a terminal built into an editor, like Visual Studio Code or Cursor, select the editor. 3. Turn on the setting that starts with "Data shared by 1Password". 4. Quit and reopen the app, then start a new Claude Code session and enter `/mcp` to check the status of the 1Password server. If you use Claude Code in more than one app, turn on the setting for each one. ## Learn more * [1Password Environments](/environments) * [Access secrets from 1Password through local `.env` files](/environments/local-env-file) * [1Password MCP server](/environments/mcp-server) # Use Cursor with 1Password Environments Source: https://www.1password.dev/environments/cursor-plugin Give Cursor Agent the 1Password Environments workflow, validate locally mounted .env files, and connect to the 1Password MCP server. Beta The [1Password Developer Tools plugin for Cursor](https://github.com/1Password/cursor-plugin) connects [1Password Environments](/environments) to [Cursor.](https://cursor.com/home) The plugin includes: * An MCP configuration for the [1Password Environments MCP Server](/environments/mcp-server), which allows Cursor to manage your Environments with secure authorization prompts. * An agent skill that supplies Cursor Agent with end-to-end workflows for interacting with 1Password Environments. * A hook that runs before Cursor Agent executes shell commands to confirm your [locally mounted `.env` files](/environments/local-env-file) are set up correctly. ## Requirements * [1Password subscription](https://1password.com/pricing/password-manager) * 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux) * [Cursor](https://cursor.com/home) * [`sqlite3`](https://sqlite.org/index.html) installed and available in your PATH, for the validation hook. It's pre-installed on Mac, and available through your package manager on Linux. > [!NOTE] > > **Platform support** > > The [1Password Environments MCP server](/environments/mcp-server) and [locally mounted `.env` files](/environments/local-env-file) are currently only supported on Mac and Linux. On Windows, the validation hook exits without a decision, so it never blocks Cursor Agent from running commands. ## Step 1: Set up your Environments Before you get started, you can set up the [Environments](/environments/) that Cursor Agent will interact with. 1. [Create one or more Environments](/environments) in 1Password to store your project secrets. 2. [Configure locally mounted `.env` files](/environments/local-env-file) for them. You can also wait and [use the plugin to import your existing `.env` file](#have-cursor-import-an-environment-and-make-it-available-in-your-project) and mount a local `.env` file destination on your behalf. ## Step 2: Install the plugin The 1Password Developer Tools plugin is available from the [Cursor marketplace.](https://cursor.com/marketplace) To install it: 1. Open Cursor and navigate to the **Cursor Agents** window. 2. In the left sidebar, select **Customize**. 3. Select **Plugins** in the top menu. 4. Search for **1Password Developer Tools** then select **Add**. 5. Restart Cursor. > [!TIP] > > You can also install the plugin: > > * From the command palette: Enter `Cmd+Shift+P` on Mac or `Ctrl+Shift+P` on Linux, enter **Plugins: Install Plugin**, then search for **1Password Developer Tools**. > * In the Cursor Agent window: Run `/add-plugin 1password`. Installing the plugin registers the validation hook, the `1password-environments` agent skill, and the MCP server configuration at the same time. ## Step 3: Turn on the MCP server in 1Password > [!NOTE] > > 1Password Enterprise Password Manager admins can turn the MCP server feature on and off. To do so, [sign in](https://start.1password.com/signin/) to your account on 1Password.com, then go to **Policies** > **Agentic permissions** and turn the **Local MCP server** option on or off as needed. The plugin's MCP configuration connects Cursor to the [1Password Environments MCP Server](/environments/mcp-server). To turn the server on: 1. Open the 1Password desktop app. 2. Go to **Settings** > **Developer** and select **Integrate with MCP clients**. To confirm Cursor connected to the server: 1. Open Cursor and select **Cursor** in the menu bar, then select **Settings** > **Cursor Settings**. 2. In the left sidebar, select **Tools & MCPs** and look for the 1Password server. ## Step 4: Use Cursor to manage your Environments Now that you have the plugin installed, you can ask Cursor to manage your Environments on your behalf. When you first prompt Cursor to access an Environment, you'll get a secure authorization prompt from the 1Password desktop app that allows you to choose whether Cursor has permission to list and create Environments. ### Have Cursor import an Environment and make it available in your project If you have a plaintext `.env` file in your codebase, you can ask Cursor to import its contents into a 1Password Environment as secrets. Cursor will create the Environment then mount it at the same file path as the original file, so your secrets are available without being tracked by Git or stored in plaintext on your device. > [!WARNING] > > After Cursor imports your `.env` file, make sure to rotate all secrets that were previously stored in plaintext. Moving your project secrets to 1Password protects them going forward, but doesn't mitigate any past exposure, such as in your Git history or your coding agent memory. When you ask Cursor Agent to move an existing `.env` file into 1Password, the `1password-environments` agent skill directs it to: 1. Read the `.env` file to get its variable names and values, then pass the values to 1Password without printing them in chat. 2. Create the Environment, or resolve the one you named. If an Environment with the name already exists, the Agent stops and asks how you want to proceed instead of creating a duplicate. You can choose to merge the new secrets into the existing Environment or create a new Environment with a different name. 3. Add the secrets, marking API keys, tokens, passwords, private keys, and connection strings as concealed. 4. Mount the Environment at the original `.env` file's path, then verify the resulting [local `.env` file](/environments/local-env-file). When Cursor needs to access the Environment, you'll get a secure authorization prompt that allows you to choose its permissions. ![Cursor Agent importing a .env file into 1Password using the 1password-environments skill, with a 1Password authorization prompt to list and create environments.](https://mintcdn.com/ab-634991b8/FqTN4hPxQCxb_fec/static/img/cursor-agent-flow.png?fit=max\&auto=format\&n=FqTN4hPxQCxb_fec\&q=85\&s=186acb9ea53a0c51a70ca4e79696d46f) > [card] [Learn more about how local .env files work](/environments/local-env-file#how-it-works) > > The contents of locally mounted `.env` files aren't tracked by Git or stored on your device, and are only available at the moment you access them. ### Validate your local .env file setup When Cursor Agent tries to run a command, the 1Password hook makes sure any locally mounted `.env` files from 1Password Environments are properly set up before the agent executes. If any required `.env` files are missing or invalid, the hook prevents the agent from running and the agent provides instructions for how to fix the issue. By default, the hook checks the 1Password desktop app to find locally mounted `.env` files related to your project based on the file path destinations configured in your Environments. To validate only specific files instead, [create a `.1password/environments.toml` file at the root of your project with a `mount_paths` array](/environments/agent-hook-validate#step-3-choose-how-you-want-the-hook-to-validate-your-env-files). > [card] [Learn more about the local .env file validation hook](/environments/agent-hook-validate) > > See how the hook discovers your mounted files, the validation modes you can configure, and how to use it with other agents and IDEs. ### Manage your Environments from Cursor The [1Password Environments MCP server](/environments/mcp-server) lets you use Cursor Agent to manage your 1Password Environments with secure authorization prompts. The MCP server only sees secret names, and never returns secret values stored in 1Password to the agent. Your secrets stay safe in 1Password and are only accessed by authorized processes. You can prompt Cursor Agent to perform tasks like: * "List my 1Password Environments" * "Create an Environment from my project `.env` file" * "Import `.env` into 1Password and mount it here" * "Mount my staging Environment as `.env` in this repo" * "What secrets are in my production Environment?" * "Add a placeholder for my OpenAI API key" * "Create a new Environment called `my-app-dev`" > [!WARNING] > > Make sure to rotate any secrets you import to 1Password that were previously stored in plaintext in your codebase or `.env` files. Moving your project secrets to 1Password secures them going forward, but doesn't mitigate any past exposure, such as in your Git history or your coding agent memory. The 1Password desktop app may prompt for approval when Cursor connects to the MCP server or accesses an Environment. > [card] [Learn more about the 1Password Environments MCP Server](/environments/mcp-server) > > See how the MCP server handles authorization, why your secrets stay out of the agent's context, and how to use it with other MCP clients. ## Troubleshooting ### If Cursor can't connect to the MCP server on macOS 27 Golden Gate If you updated to macOS 27 Golden Gate and the 1Password server shows `MCP error -32000: Connection closed` in Tools & MCPs, even though you've turned on "Integrate with MCP clients", macOS may be blocking Cursor from accessing data from the 1Password app. To allow access: 1. Open **System Settings** > **Privacy & Security** > **Files & Folders**. 2. Select **Cursor**. 3. Turn on the setting that starts with "Data shared by 1Password". The rest of the name depends on which 1Password apps you’ve installed. 4. Quit and reopen Cursor, then go to **Settings** > **Tools & MCPs** to check the status of the 1Password server. ## Telemetry The validation hook emits opt-in telemetry so 1Password can understand plugin adoption and how often common failure modes happen, like a missing file or a disabled mount. Events are only recorded if you've turned on product telemetry in the 1Password desktop app. They include the hook name and version, the client, the validation mode, the number of mounts checked, and whether the hook allowed or blocked the command. They don't include file paths, file contents, Environment names, or workspace paths. Telemetry runs after the hook returns its decision to Cursor, so it can never change whether a command is allowed. To turn telemetry off: 1. Open the 1Password desktop app. 2. Select your account or collection at the top of the sidebar, then select **Manage Accounts**. 3. Select **Usage data** then deselect **Share information about your usage**. ## Learn more * [1Password Environments](/environments) * [Access secrets from 1Password through local `.env` files](/environments/local-env-file) * [1Password local `.env` file validation hook](/environments/agent-hook-validate) * [1Password Environments MCP Server](/environments/mcp-server) # Access secrets from 1Password through local .env files Source: https://www.1password.dev/environments/local-env-file Locally mounted `.env` files allow secure access to the secrets you've stored in [1Password Environments](/environments) from your device, without needing to keep them in a plaintext `.env` file on your local device. By creating a local `.env` file path, your secrets become both safe and simple to access. > [!NOTE] > > This feature is currently only supported in 1Password for Mac and Linux at this time. [Video walkthrough of setting up a local .env file with 1Password Environments.](https://www.youtube.com/embed/W0SNYmdVD0o) ## Mount your `.env` file To configure a local `.env` file path, you'll need to use the 1Password desktop app to create a new [Environment](/environments#create-an-environment) or navigate to an existing one you want to configure. Within your Environment: 1. Under **Connect to**, select the **Connect** button next to "Local .env file". 2. Select **Choose file path** and choose the path on your device where you want to create your local `.env` file. 3. Select **Mount .env file**. You can disable a local `.env` file to remove it from your device. In your environment, toggle the **Enabled** option on or off as needed. You can have up to 25 enabled local `.env` files per device. > [!NOTE] > > If you have an existing `.env` file tracked by Git at the path you want to mount a new `.env` file at, you'll first need to delete the existing file and commit the change. After this is done you can safely mount your new `.env` file at the desired path. > > If you don’t delete and commit the existing file, Git operations may fail and indicate that the mounted `.env` file generated by 1Password is being tracked. In practice, the file can’t actually be committed and its contents will never enter the staging area, so your secrets remain safe. However, commands like `git status` may still show it as a change until you’ve committed the removal of the original file. > [!TIP] > > You can also use [1Password Developer Watchtower](/watchtower) to discover `.env` files containing plaintext secrets on your device, [import them into Environments](/watchtower#import-plaintext-secrets-from-local-env-files), and mount your `.env` files. ## Verify with your terminal To confirm that you can access your Environment's secrets on your device, you can read your secrets using the `cat` shell command. 1. From your terminal, navigate to the directory where your `.env` file is saved. Run the following command, replacing `.env` with the name you've given your file: ```shell theme={null} cat .env ``` 2. Select **Authorize** in the authorization prompt that pops up. Upon approval, your Environment's contents will be returned. Your terminal only reads your secrets one time, and doesn't write them to disk. Authorization lasts until 1Password locks so you won't have to re-approve additional read requests while 1Password remains unlocked. ### Dotenv library compatibility You can use your language's supported `.env` libraries to load secrets into your projects and work with your environment variables. Use of local `.env` files with 1Password Environments is compatible with the following libraries: | Language / Tool | Library | Compatible | | - | - | - | | C# | [`DotNetEnv`](https://github.com/tonerdo/dotnet-env) | Yes | | Docker Compose | [Built-in support for `.env` files](https://docs.docker.com/compose/how-tos/environment-variables/set-environment-variables/) | Yes | | Go | [`godotenv`](https://github.com/joho/godotenv) | Yes | | Java | [`dotenv-java`](https://github.com/cdimascio/dotenv-java) | Yes | | JavaScript / Node.js | [`dotenv`](https://github.com/motdotla/dotenv) | Yes | | PHP | [`phpdotenv`](https://github.com/vlucas/phpdotenv) | Yes | | Python | [`python-dotenv`](https://github.com/theskumar/python-dotenv) | Yes, as of `v1.1.2` | | Ruby | [`dotenv`](https://github.com/bkeepers/dotenv) | Yes | | Rust | [`dotenvy` (main)](https://github.com/allan2/dotenvy) | Yes | | Rust | [`dotenvy` (v0.15.7)](https://github.com/allan2/dotenvy/tree/v0.15.7) | Yes, but requires that you pass in the `.env` filename, path, or contents directly. | ## How it works 1Password makes your Environment's secrets available as a `.env` file without actually storing the plaintext contents on your device. Instead, the file contents are passed directly to the reader process on demand through a UNIX-named pipe. 1Password mounts the `.env` file at the path you've specified on your device and automatically remounts it whenever 1Password restarts. This means that as long as 1Password is running, even if locked, the file is there and 1Password is ready to respond when you need to access your secrets. When your application tries to read the file, you'll receive an authorization prompt asking for approval to populate the `.env` file. The file will lock again [when 1Password locks](https://support.1password.com/auto-lock/). There's no distinction made between different processes reading the file. Once the file is unlocked, every process can read it until you lock 1Password or disable the `.env` file in 1Password. Although 1Password creates this file on your device, locally mounted `.env` files aren't tracked by Git and therefore your secrets aren't exposed by your version control system. The contents of these files are never stored on disk and are only available at the moment you access them, provided you've authenticated. Once read, the information is no longer available until you access it again. ![An authorization prompt is shown when you try to access a mounted \`.env\` file through your local terminal.](https://mintcdn.com/ab-634991b8/P8nNS8jHoY1I7R9r/static/img/environments-local-env-auth.png?fit=max\&auto=format\&n=P8nNS8jHoY1I7R9r\&q=85\&s=f0c41a08c8aa25779c162c775424569b) ## Limitations * Mounted local `.env` files are only supported in 1Password for Mac and Linux at this time. * Mounted local `.env` files aren't designed for concurrent access. If multiple processes try to read your local `.env` file at the same time, you may encounter delays or unexpected behaviors. For example, if you have the file open in an IDE while another application attempts to read it, this may result in conflicts. The first process to access the file will succeed in reading the secrets, while others may fail to read the contents. If you have the `.env` file open in an IDE or another application that is actively accessing it, you may need to close that session to allow other applications or terminal instances to read the file without interference. * When you're offline, you'll only be able to access the most recent contents synced to your device or local changes you've made. When you're back online, your Environment will update to reflect the latest changes you've saved in 1Password. * Some toolchains that aggressively watch `.env` files, such as Vite, can trigger a full dev server restart whenever a filesystem change event is detected and may not be compatible with local file mounts from 1Password Environments. Because FIFO mounts can emit filesystem events during open, close, or read operations, even when the underlying secret values haven't changed, these tools may incorrectly interpret this activity as a `.env` modification. This can cause an infinite restart loop. If your project does not rely on reloading or reacting to changes in `.env` files during development, configure your tool to avoid watching the mounted `.env` file for changes. For example, in Vite, add the following to your `vite.config.ts`. This prevents unnecessary dev server restarts while preserving normal HMR behavior for source files. ```typescript theme={null} import { defineConfig } from 'vite' export default defineConfig({ server: { watch: { ignored: ['**/.env'], // Replace with the name of your mounted env file }, }, }) ``` ## Learn more * [1Password Environments](/environments) * [Use 1Password's agent hook to validate local .env files from 1Password Environments](/environments/agent-hook-validate) * [Sync secrets between 1Password and AWS Secrets Manager (beta)](/environments/aws-secrets-manager) * [Workflow: Secure your developer secrets](/get-started/secure-developer-secrets) * [1Password Developer Watchtower](/watchtower) * [Workflow: Secure local development](/get-started/secure-developer-secrets) # 1Password Environments MCP Server Source: https://www.1password.dev/environments/mcp-server Connect MCP clients to 1Password Environments with secure authorization prompts, without returning secrets to the agent. The 1Password Environments MCP Server lets MCP clients such as [Claude Code](https://code.claude.com/docs/en/overview), [Codex](https://help.openai.com/en/articles/11096431-openai-codex-cli-getting-started), [Cursor](https://cursor.com/home), and [Kiro](https://kiro.dev/) securely manage your [1Password Environments](/environments). The server can only see the names of your secrets and Environments, and never returns the actual secret values stored in your Environments, which stay safe in 1Password. You can use the MCP server to: * Create, list, and rename Environments. * List the names of secrets stored in an Environment. * Add secrets to an Environment. * Create [locally mounted `.env` files](/environments/local-env-file) that make your secrets available on demand without writing them to disk. * List locally mounted `.env` files. [Learn more about 1Password's approach to MCP servers](https://1password.com/blog/where-mcp-fits-and-where-it-doesnt). ## How the 1Password Environments MCP Server works The 1Password Environments MCP Server runs locally on your computer as part of the 1Password desktop app. When your MCP client connects to the server or uses a [tool](#available-tools) that requires per-Environment approval, the 1Password app shows a secure authorization prompt. If you approve, the client can use the approved tool with the Environment again without prompting you until 1Password locks. By design, the server cannot return secret values stored in 1Password to the client, even if an agent requests them. This walkthrough shows how to use the MCP server for Codex: [Secure secrets for agentic workflows with 1Password MCP Server and Codex](https://youtube.com/embed/5eSAbPjMSYk) ## Requirements Before you can use the MCP server, you'll need to: * [Sign up for 1Password.](https://1password.com/pricing/password-manager) * [Install the 1Password desktop app](https://1password.com/downloads/). * [Create a 1Password Environment.](/environments#create-an-environment) * Have an MCP client that supports `stdio` transport. Remote-only MCP clients aren't currently supported. > [!NOTE] > > 1Password Enterprise Password Manager admins can turn the MCP server feature on and off. To do so, [sign in](https://start.1password.com/signin/) to your account on 1Password.com, then go to **Policies** > **Agentic permissions** and turn the **Local MCP server** option on or off as needed. ## Step 1: Turn on access to the MCP server In 1Password, go to **Settings** > **Developer**, then select **Integrate with MCP clients**. ## Step 2: Configure your MCP client Next, you’ll need to configure 1Password as a local MCP server within your MCP client. > [tab] Claude Code > > Beta > > To configure the 1Password MCP server, install the [1Password Developer Tools plugin for Claude Code](/environments/claude-plugin). The plugin registers the MCP configuration for you, along with an agent skill that gives Claude Code a full Environments setup workflow. > > 1. Open your terminal, go to your project directory, then enter `claude` to start a Claude Code session. > > 2. Add the 1Password marketplace: > > ```shell theme={null} > /plugin marketplace add 1Password/1password-claude-plugin > ``` > > 3. Install the plugin: > > ```shell theme={null} > /plugin install 1password@1password > ``` > > 4. Restart Claude Code, then enter `/mcp` to confirm the 1Password server is connected. > > Learn more about [the 1Password Developer Tools plugin for Claude Code](/environments/claude-plugin). > [tab] Codex > > > [!NOTE] > > > > Codex currently supports Mac and Linux. > > To configure the 1Password Environments MCP Server for Codex: > > 1. In Codex, go to **MCP servers** and select **+ Add server**. Make sure the toggle is turned on. > 2. In the **Command to launch** field, enter: > > ``` > 1password-mcp > ``` > > Next, update your `AGENTS.md` file to instruct Codex to explicitly use the MCP server without needing to ask. > > To do this, go to **Personalization** and fill in the **Custom instructions** field. For example, add the instruction: > > "Always use the 1Password Environments MCP Server if you need to work with the 1Password developer environments without me having to explicitly ask." > [tab] Cursor > > Beta > > To configure the 1Password Environments MCP Server, install the [1Password Developer Tools plugin for Cursor](/environments/cursor-plugin). The plugin registers the MCP configuration for you, along with a local `.env` file validation hook and an agent skill that gives Cursor Agent a full Environments setup workflow. > > 1. Open Cursor and navigate to the **Cursor Agents** window. > 2. In the left sidebar, select **Customize**. > 3. Select **Plugins** in the top menu. > 4. Search for **1Password Developer Tools** then select **Add**. > 5. Restart Cursor, then go to **Settings** > **Tools & MCP** to confirm the 1Password server is connected. > > Learn more about [the 1Password Developer Tools plugin for Cursor](/environments/cursor-plugin). > [tab] Kiro > > > [!NOTE] > > > > This feature is in beta. The Kiro plugin currently supports Mac and Linux. > > To configure the [1Password Environments MCP Server for Kiro](https://github.com/1Password/1password-kiro-plugin), you can either install the plugin from the Kiro Power Marketplace or from GitHub. > > #### Option 1: Install from the Kiro Power Marketplace > > 1. Search for "1Password Developer Environments" at [kiro.dev/powers.](https://kiro.dev/powers) > 2. Select **Add to Kiro** to open the installation page in Kiro. > 3. Select **+Install** to install the Power. > 4. Select **Try power** to validate your Environment and get started. > > #### Option 2: Install from GitHub > > 1. Select **Powers** in the Activity Bar, or open the Command Palette and search for **Powers: Focus on Installed view**. > 2. Select **Add Custom Power**. > 3. Select **Import Power from GitHub** from the menu options. > 4. Paste the repository URL: `https://github.com/1Password/1password-kiro-plugin` > 5. Select `1password-kiro-plugin` from the list of installed Powers. > 6. From the `Power: 1Password Developer Environments` screen, select **Try power** to validate your Environment and get started. > [tab] Other > > To manually configure the 1Password Environments MCP Server with any MCP client that supports `stdio` transport, add the `1password-mcp` command to your MCP client's configuration file. > > If your client uses a JSON MCP config file: > > ```json theme={null} > { > "mcpServers": { > "1password": { > "command": "1password-mcp" > } > } > } > ``` > > If your client uses a TOML config file: > > ```toml theme={null} > [mcp_servers.1password] > command = "1password-mcp" > ``` > > If you use [OpenCode](https://opencode.ai/docs/mcp-servers/), add the server to the `mcp` section of your `opencode.json` config file: > > ```json theme={null} > { > "$schema": "https://opencode.ai/config.json", > "mcp": { > "1password": { > "type": "local", > "command": ["1password-mcp"], > "enabled": true > } > } > } > ``` > > Then restart your client. ## Step 3: Ask your client to manage an Environment After you connect the MCP server, you can ask your client to perform tasks like: * "List my 1Password Environments" * "Create a local .env mount here" * "Show me the secret names in my project environment" * "Add a secret for my OpenAI API key" * "Create a new Environment called my-project" > [!WARNING] > > Make sure to rotate any secrets you import into 1Password that were previously stored in plaintext in your codebase or `.env` files. Moving your project secrets to 1Password secures them going forward, but doesn’t mitigate any past exposure, such as in your Git history or your coding agent memory. ### Available tools The following tools are exposed to MCP clients. The first time a client calls a tool to interact with a specific Environment, 1Password may prompt you to approve. | Tool | Description | | - | - | | `append_secrets` | Add or update secrets in a 1Password Environment. Make sure to rotate any secrets that were previously stored in plaintext in your codebase or .env files. | | `authenticate` | Authenticate with the 1Password desktop app to access 1Password Environment tools. | | `create_environment` | Create a new 1Password Environment in a specified account. Make sure to rotate any secrets that were previously stored in plaintext in your codebase or .env files. | | `rename_environment` | Rename a 1Password Environment in a specified account. | | `create_local_env_file` | Create a [locally mounted `.env` file](/environments/local-env-file) for a 1Password Environment that makes your secrets available on demand without writing them to disk. | | `list_environments` | **Read-only.** List all 1Password Environments in a specified account. | | `list_secrets` | **Read-only.** Retrieve a list of secret names stored in a 1Password Environment. | | `list_local_env_files` | **Read-only.** List all locally mounted `.env` files from a 1Password Environment. Local .env files currently only support Mac and Linux. | ## Troubleshooting ### If your MCP client can't connect on macOS 27 Golden Gate If you updated to macOS 27 Golden Gate and your MCP client shows `MCP error -32000: Connection closed`, or the MCP server log shows `Failed to start logger: Log cannot be written`, even though you've turned on "Integrate with MCP clients", macOS may be blocking your MCP client from accessing data from the 1Password app. To allow access: 1. Open **System Settings** > **Privacy & Security** > **Files & Folders**. 2. Select your MCP client app, like Claude, Cursor, or Codex. 3. Turn on the setting that starts with "Data shared by 1Password". The rest of the name depends on which 1Password apps you’ve installed. 4. Quit and reopen your MCP client app, then try again. If you use more than one MCP client, turn on the setting for each one. ## Learn more * [1Password Environments](/environments) * [Use 1Password's agent hook to validate local .env files from 1Password Environments](/environments/agent-hook-validate) * [Use the 1Password Developer Tools plugin for Claude Code to manage Environments](/environments/claude-plugin) * [Use the 1Password Developer Tools plugin for Cursor to manage Environments and validate local `.env` files](/environments/cursor-plugin) * [Get started with 1Password Developer](https://support.1password.com/developer) * [Manage team policies in 1Password Business: Sharing and permissions](https://support.1password.com/team-policies/#sharing-and-permissions) * [Workflow: Secure AI access](/get-started/secure-ai-access) # Connect 1Password Environments to NVIDIA OpenShell for secure agent access (beta) Source: https://www.1password.dev/environments/nvidia-openshell Keep secrets out of agent context with 1Password and NVIDIA OpenShell. Beta 1Password for NVIDIA OpenShell (beta) lets an agent use the developer secrets it needs without those secrets entering the agent's context. Connect a [1Password Environment](/environments) to an OpenShell sandbox, review the secrets and approved destinations, and set how long access lasts. Inside the sandbox, the agent only ever works with placeholder values. When it sends a request to a host you've approved, the gateway replaces the placeholders with the real secrets outside the sandbox and forwards the request. Requests to any other host don't receive the credential. With this integration, you can: * **Keep credentials out of agent context:** Agents can work with repositories, APIs, and services without seeing secret values. * **Set boundaries before work begins:** Review the Environment, secrets, destinations, permissions, and expiration before authorizing the connection. * **Use familiar developer workflows:** Organize project and agent secrets in 1Password Environments instead of distributing secrets through chat, local files, or scripts. * **Limit access to the task:** OpenShell controls where credentials can be used during the approved window, while you stay in control of the connection. [1Password for NVIDIA OpenShell: Give Agents Access Without Giving Them the Keys](https://youtube.com/embed/GCBhubQZ7KE) ## Requirements * A 1Password account. * [1Password for Mac](https://1password.com/downloads/mac) or [1Password for Linux](https://1password.com/downloads/linux). * [NVIDIA OpenShell](https://docs.nvidia.com/openshell/about/installation) installed, with a running gateway. * A coding agent that OpenShell supports, like Claude Code. ## How it works When you connect a 1Password Environment to an OpenShell gateway, 1Password transfers custody of the Environment's secrets to OpenShell for a defined time-to-live (TTL). OpenShell controls which services the agent can reach during that window. The agent sends requests from inside the sandbox using placeholder values, so it never sees your actual secrets. OpenShell replaces the placeholders with secret values only when a request matches the active network policy and the provider’s approved host. Secret values never enter the agent process or context. When the time window expires or if the request doesn't match, OpenShell stops replacing the placeholders, so requests that need the secret fail while the sandbox keeps running. OpenShell governs how the agent runs, which services it can reach, and where its inference requests go. OpenShell enforces these controls outside the agent's process, so the agent can't change or get around them. > [!TIP] > > **New to NVIDIA OpenShell?** [Learn how to get started.](https://docs.nvidia.com/openshell/about/installation) ## Step 1: Set up an Environment Set up an Environment in 1Password to store your project secrets for a specific project or development context. If you already have an Environment you want to use, skip to [step 2](#step-2-turn-on-the-integration). 1. In the 1Password desktop app, go to **Developer** > **View Environments**. 2. Select **New environment**. 3. Enter a name for the new Environment, then select **Save**. 4. Add the secrets for your project or import an existing `.env` file. ## Step 2: Turn on the integration 1. Open the 1Password desktop app. 2. Select your account or collection at the top of the sidebar, then navigate to **Settings** > **[Developer](onepassword://settings/developers)**. 3. Under Developer Integrations, select **Provision OpenShell providers**. ## Step 3: Connect the Environment to OpenShell To connect an Environment to OpenShell: 1. In the 1Password desktop app, select **Developer** in the sidebar, then select **View Environments**. 2. Find the name of the Environment you want to use and select **View environment**. 3. Under "Connect to", select the **Connect** button next to "OpenShell provider". You'll be prompted to configure the following: * **Provider name**: The name you'll pass to `openshell sandbox create --provider `. * Whether you want to use an existing [provider profile](https://docs.nvidia.com/openshell/dev/how-it-works/providers/profiles) or create your own: * **Existing profile:** Use a profile that's already been imported on your gateway, such as one for AWS or GitHub. A new gateway has no profiles until someone imports them. * **New profile:** 1Password creates a profile on your gateway for you. You set the host, port, and read/write permissions. * **Host:** The host a sandbox can make requests to. OpenShell only attaches this provider's credentials to requests for the approved host and port. * **Port:** The port a sandbox can reach on that host. Requests to any other port don't receive the credential. * **Allow writes:** Select this to allow write operations at the approved destination. If you leave it unselected, the provider allows read-only access. * **Secrets expire**: The duration of time that OpenShell will resolve placeholders in requests from the sandbox with your secrets. After expiration, the sandbox keeps running, but OpenShell stops resolving the placeholders. To restore access, approve a new connection. > [!TIP] > > The provider configuration prompt lists all required environment variables for your profile. If any of them are missing from your Environment, 1Password will alert you to add them before you can connect. After you configure your provider, select **Connect**. You'll be prompted to authorize OpenShell's access to your Environment with a detailed authorization prompt that includes the provider name, secrets, destinations, expiry, and your account name. ## Step 4: Run the setup command With the provider set up, you can now attach the provider to an OpenShell sandbox. OpenShell owns the sandbox and has custody of the credentials in your Environment for the time window you set. 1. In the 1Password desktop app, open the Environment. 2. In the "Connected to" section, select the ellipsis to the right of "OpenShell provider" then select **Copy setup commands**. 3. Paste and run the command in your terminal. The copied command creates a sandbox with your provider attached and starts a Bash shell. For example: ```shell theme={null} openshell sandbox create --provider -- bash ``` To start an agent, edit the command before you run it. Use `--from` to specify an image that contains the agent, and replace `bash` after `--` with the agent’s command. For example: ```shell theme={null} openshell sandbox create \ --from \ --provider \ -- claude ``` If your agent needs another credential, such as an API key, you can set up another OpenShell provider from a 1Password Environment. Add a `--provider` flag for each provider you want to attach. > [!TIP] > > Make sure your sandbox policy permits the network access your agent needs. If the agent will write to a service, such as pushing to GitHub, check that the credential in its attached provider has the required permissions too. See [OpenShell’s policy documentation](https://docs.nvidia.com/openshell/dev/how-it-works/policies/manage-policies/) to learn more about policy changes. ## Step 5: Test the connection In a terminal outside the sandbox, run the following command to confirm the provider is attached: ```shell theme={null} openshell provider list ``` You should see the provider name from 1Password in the list, along with the type and the number of keys. To test the integration, you can start an agent in the sandbox and give it a task that needs the credential. For example, if you set up a GitHub provider, ask the agent to create and push a branch. Replace `` and `` with your GitHub username or organization and repository name: ``` Write a `hello_world.py` script, commit it to a new branch called `test-openshell`, and push the branch to `https://github.com//`. ``` The agent sends the request with a placeholder, then OpenShell replaces it with your secret before forwarding the request to GitHub. The push only works if the provider allows writes and the sandbox's network policy permits access to your repository. Run `openshell term` in a terminal outside the sandbox to observe the request. If it fails, check the deny reason in the terminal output. ## Manage your workflows ### Reconnect an Environment to OpenShell To reconnect an expired Environment to OpenShell: 1. In the 1Password desktop app, select **Developer** in the sidebar, then select **View Environments**. 2. Find the name of the Environment you want to reconnect and select the ellipsis > **Send again**. ### Remove an Environment from OpenShell To remove an Environment from OpenShell: 1. In the 1Password desktop app, select **Developer** in the sidebar, then select **View Environments**. 2. Find the name of the Environment you want to remove and select the ellipsis > **Delete workflow**. ## Troubleshooting ### If you don't see the option to connect to OpenShell Make sure [1Password for Mac](https://1password.com/downloads/mac) or [1Password for Linux](https://1password.com/downloads/linux) is up to date. To check your current version: 1. Open the 1Password desktop app. 2. Select your account or collection at the top of the sidebar, then navigate to **Settings** > **About**. You may need to restart the app to download the latest release. ### If you can't connect an Environment to OpenShell Make sure you turned on **Provision OpenShell providers** in **Settings** > **Developer**. If 1Password alerts you that secrets are missing, add the required secrets for your provider profile to the Environment, then try again. ### If requests to a service fail OpenShell only replaces placeholders for the host and port in your provider profile. Requests to other hosts go out with the placeholder, so the service rejects them. To use another service, connect the Environment with a profile for that host. ### If requests fail after previously working Your secrets may have expired. After the time you set, the gateway stops replacing placeholders, so requests that need your secrets fail. To keep working, [reconnect the Environment](#reconnect-an-environment-to-openshell). ## Learn more * [1Password Environments](/environments) * [1Password Environments MCP Server](/environments/mcp-server) * [Workflow: Secure AI access](/get-started/secure-ai-access) # Programmatically read 1Password Environments Source: https://www.1password.dev/environments/read-environment-variables Learn how to get secrets stored in 1Password Environments using 1Password SDKs and CLI. You can programmatically retrieve the secrets stored in [1Password Environments](/environments) using [1Password SDKs](#sdks) or [1Password CLI](#cli). Both tools support local authentication with the 1Password desktop app or automated authentication with service accounts scoped to specific Environments. > [!WARNING] > > **Upcoming deprecation** > > The following functionality will be deprecated on November 17, 2026, and removed on January 20, 2027: > > * The `op environment read` command in 1Password CLI. To list the secrets in an Environment, use `op environment secret list` instead, available in [version `2.42.0` or later](https://app-updates.agilebits.com/product_history/CLI2). To pass secrets from an Environment to an application or script, use [`op run --environment`](#pass-environment-variables-to-an-application-or-script). > * The `get_variables()` function in 1Password SDKs, and the `GetVariablesResponse` and `EnvironmentVariable` types it returns. The new `list_secrets()` function will replace them. It takes an Environment name or ID and a `reveal` option, and returns a list of `EnvironmentSecret` objects directly, without a response wrapper. ## Choose your configuration ### Tool options * **1Password CLI**: Best for quick testing, shell scripts, CI/CD pipelines, Infrastructure as Code, build tools and task runners. * **1Password SDKs**: Best for native integrations with Go, Python, or JavaScript applications. ### Authentication options * **Local authentication with the 1Password desktop app**: Authenticate in the same way you unlock your [1Password desktop app](https://1password.com/downloads/), like with biometrics or your 1Password account password. Requires minimal setup with no token management. Enables human-in-the-loop approval for sensitive workflows. * **1Password Service Accounts**: Authenticate using a [service account token](/service-accounts/) scoped to the Environments you want to fetch. Best for shared building, automated access, and headless server authentication. Enables you to follow the [principle of least privilege](https://csrc.nist.gov/glossary/term/least_privilege) in your project. ### Decision guide Use the table below to find the best tool and authentication method for your specific use case. | Use case | Recommended tool | Authentication method | Why this approach | | - | - | - | - | | **Local development** on your machine | [CLI](#cli) or [SDK](#sdks) | Desktop app | Uses existing 1Password account credentials, making it seamless for individual developers working locally. No token management. | | **Quick testing** and exploration | [CLI](#cli) | Desktop app | Fastest way to test. Uses existing 1Password account credentials with minimal setup required. | | **Desktop applications** | [SDK](#sdks) | Desktop app | Better integration with application code. Desktop app authentication allows end users to authenticate with their own 1Password accounts. | | **Shell scripts** and automation tasks | [CLI](#cli) | Desktop app or service account | 1Password CLI is designed for shell scripting. Use 1Password desktop app for personal scripts, service accounts for shared/automated scripts. | | **CI/CD pipelines** (GitHub Actions, GitLab CI, etc.) | [CLI](#cli) | Service account | Service accounts provide non-interactive authentication perfect for automated workflows. 1Password CLI is lightweight and easy to integrate into pipeline scripts. | | **Application runtime** (production services) | [SDK](#sdks) | Service account | 1Password SDKs offer native language integration with better error handling and type safety. Service accounts enable secure, automated access without user interaction. | | **Server-side applications** | [SDK](#sdks) | Service account | 1Password SDKs offer robust error handling and connection pooling. Service accounts enable headless server authentication. | | **Docker containers and Kubernetes** | [SDK](#sdks) or [CLI](#cli) | Service account | Service accounts work well in containerized environments. Choose 1Password SDKs for application containers, 1Password CLI for init containers or sidecars. | | **Infrastructure as Code** (Terraform, Pulumi, etc.) | [CLI](#cli) | Service account | 1Password CLI can be easily invoked from IaC tools. Service accounts enable automated infrastructure provisioning. | | **Build tools and task runners** | [CLI](#cli) | Desktop app or service account | 1Password CLI integrates easily with build tools like Make, Gradle, or npm scripts. Use 1Password desktop app for developer builds. Service accounts support shared building. | ## Get an Environment's ID To fetch secrets from a 1Password Environment, you'll need its unique identifier (ID). You can get an Environment's ID in the [1Password desktop app](https://1password.com/downloads/): 1. Open and unlock the 1Password desktop app, then navigate to **Developer** > **View Environments**. 2. Select **View environment** next to the Environment you want to fetch. 3. Select **Manage environment** > **Copy environment ID**. ## Read Environments with 1Password SDKs ### Get secrets With [1Password SDKs](/sdks), you can retrieve the secrets stored in your 1Password Environments using the `get_variables()` function with the [Environment's ID](#get-an-environments-id). func (e \*EnvironmentsSource) GetVariables(ctx context.Context, environmentID string) (\*GetVariablesResponse, error) async getVariables(environmentId: string): Promise\ async def get\_variables(self, environment\_id: str) -> GetVariablesResponse The function returns a `GetVariablesResponse` object that contains a list of the secrets stored in the Environment. type GetVariablesResponse struct \{ Variables \[]EnvironmentVariable `json:"variables"` } interface GetVariablesResponse \{ variables: EnvironmentVariable\[]; } class GetVariablesResponse(BaseModel): variables: List\[EnvironmentVariable] Each secret in the response is returned as an `EnvironmentVariable` object that contains the secret's name (for example, `DB_HOST`), value, and whether the value is hidden by default. type EnvironmentVariable struct \{ Name string `json:"name"` Value string `json:"value"` Masked bool `json:"masked"` } interface EnvironmentVariable \{ name: string; value: string; masked: boolean; } class EnvironmentVariable(BaseModel): name: str value: str masked: bool > [!NOTE] > > By default, secrets in 1Password Environments have **"Hide value by default"** turned on. To change this, open an Environment, select the vertical ellipsis next to the secret, then select **Show value by default**. #### Examples > [tab] Service account > > Before running the following example: > > * Set `OP_SERVICE_ACCOUNT_TOKEN` to the token for a service account that has access to the Environment you want to fetch. > * Set `OP_ENVIRONMENT_ID` to the ID for your 1Password Environment. > > package main > > import ( > "context" > "fmt" > "os" > > "github.com/1password/onepassword-sdk-go" > ) > > func main() \\\{ > ctx := context.Background() > > // Initialize the SDK client > client, err := onepassword.NewClient( > ctx, > onepassword.WithServiceAccountToken(os.Getenv("OP\_SERVICE\_ACCOUNT\_TOKEN")), > onepassword.WithIntegrationInfo("My 1Password Integration", "v1.0.0"), > ) > if err != nil \\\{ > fmt.Fprintln(os.Stderr, err) > os.Exit(1) > \\} > > // Get all secrets from the Environment > environmentID := os.Getenv("OP\_ENVIRONMENT\_ID") > response, err := client.Environments().GetVariables(ctx, environmentID) > if err != nil \\\{ > fmt.Fprintln(os.Stderr, err) > os.Exit(1) > \\} > > // Process the secrets > for \_, v := range response.Variables \\\{ > visibility := "visible" > if v.Masked \\\{ > visibility = "hidden" > \\} > fmt.Printf("%s=%s (%s by default)\\\n", v.Name, v.Value, visibility) > \\} > \\} > > import \\\{ createClient \\} from "@1password/sdk"; > > const client = await createClient(\\\{ > auth: process.env.OP\_SERVICE\_ACCOUNT\_TOKEN, > integrationName: "My 1Password Integration", > integrationVersion: "v1.0.0", > \\}); > > // Get all secrets from the Environment > const environmentId = process.env.OP\_ENVIRONMENT\_ID; > const response = await client.environments.getVariables(environmentId); > > // Process the secrets > response.variables.forEach((\\\{ name, value, masked \\}) =\\> \\\{ > const visibility = masked ? "hidden" : "visible"; > console.log(\`\$\\\{name\\}=\$\\\{value\\} (\$\\\{visibility\\} by default)\`); > \\}); > > import asyncio > import os > from onepassword import Client > > async def main(): > \# Initialize and authenticate the client > client = await Client.authenticate( > auth=os.environ.get("OP\_SERVICE\_ACCOUNT\_TOKEN"), > integration\_name="My 1Password Integration", > integration\_version="v1.0.0", > ) > > \# Get all secrets from the Environment > environment\_id = os.environ.get("OP\_ENVIRONMENT\_ID") > response = await client.environments.get\_variables(environment\_id) > > \# Process the secrets > for var in response.variables: > visibility = "hidden" if var.masked else "visible" > print(f"\\\{var.name\\}=\\\{var.value\\} (\\\{visibility\\} by default)") > > asyncio.run(main()) > [tab] 1Password desktop app > > Before running the following example: > > * Replace `OP_ACCOUNT_NAME` in the code below with your 1Password account name as it appears at the top left sidebar in the 1Password desktop app. > * Set `OP_ENVIRONMENT_ID` to the ID for your 1Password Environment. > > package main > > import ( > "context" > "fmt" > "os" > > "github.com/1password/onepassword-sdk-go" > ) > > func main() \\\{ > ctx := context.Background() > > // Initialize the SDK client > client, err := onepassword.NewClient( > ctx, > onepassword.WithDesktopAppIntegration(os.Getenv("OP\_ACCOUNT\_NAME")), > onepassword.WithIntegrationInfo("My 1Password Integration", "v1.0.0"), > ) > if err != nil \\\{ > fmt.Fprintln(os.Stderr, err) > os.Exit(1) > \\} > > // Get all secrets from the Environment > environmentID := os.Getenv("OP\_ENVIRONMENT\_ID") > response, err := client.Environments().GetVariables(ctx, environmentID) > if err != nil \\\{ > fmt.Fprintln(os.Stderr, err) > os.Exit(1) > \\} > > // Process the secrets > for \_, v := range response.Variables \\\{ > visibility := "visible" > if v.Masked \\\{ > visibility = "hidden" > \\} > fmt.Printf("%s=%s (%s by default)\\\n", v.Name, v.Value, visibility) > \\} > \\} > > import \\\{ createClient, DesktopAuth \\} from "@1password/sdk"; > > const client = await createClient(\\\{ > auth: new DesktopAuth(process.env.OP\_ACCOUNT\_NAME), > integrationName: "My 1Password Integration", > integrationVersion: "v1.0.0", > \\}); > > // Get all secrets from the Environment > const environmentId = process.env.OP\_ENVIRONMENT\_ID; > const response = await client.environments.getVariables(environmentId); > > // Process the secrets > response.variables.forEach((\\\{ name, value, masked \\}) =\\> \\\{ > const visibility = masked ? "hidden" : "visible"; > console.log(\`\$\\\{name\\}=\$\\\{value\\} (\$\\\{visibility\\} by default)\`); > \\}); > > import asyncio > import os > from onepassword import Client, DesktopAuth > > async def main(): > \# Initialize and authenticate the client > client = await Client.authenticate( > auth=DesktopAuth(os.environ.get("OP\_ACCOUNT\_NAME")), > integration\_name="My 1Password Integration", > integration\_version="v1.0.0", > ) > > \# Get all secrets from the Environment > environment\_id = os.environ.get("OP\_ENVIRONMENT\_ID") > response = await client.environments.get\_variables(environment\_id) > > \# Process the secrets > for var in response.variables: > visibility = "hidden" if var.masked else "visible" > print(f"\\\{var.name\\}=\\\{var.value\\} (\\\{visibility\\} by default)") > > asyncio.run(main()) ## Read Environments with 1Password CLI With [1Password CLI](/cli), you can pass the secrets stored in your 1Password Environments to an application or script using `op run --environment`. You can also retrieve them from your 1Password Environments with `op environment read` (beta). ### Before you get started Before you get started, [install 1Password CLI](/cli/get-started#step-1-install-1password-cli). To use `op environment read`, you'll need the [latest beta build of 1Password CLI](https://app-updates.agilebits.com/product_history/CLI2#beta), version `2.33.0-beta.02` or later. Then choose your authentication method: * **Local authentication with the 1Password desktop app**: Authenticate in the same way you unlock your [1Password desktop app](https://1password.com/downloads/), like with biometrics or your 1Password account password. To set up local authentication, [turn on the 1Password CLI desktop app integration](/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). * **Service account**: Authenticate using a service account token that can only access the Environments you want to fetch. To authenticate using a service account token, [create a new service account](https://start.1password.com/developer-tools/infrastructure-secrets/serviceaccount/) with read access to the appropriate Environments. Then export your service account token: export OP\_SERVICE\_ACCOUNT\_TOKEN=\\\ set -x OP\_SERVICE\_ACCOUNT\_TOKEN \ \$Env:OP\_SERVICE\_ACCOUNT\_TOKEN = "\" ### Pass secrets to an application or script `op run --environment` is available in the stable release of 1Password CLI, version `2.41.0` or later. To pass secrets from a 1Password Environment to an application or script as environment variables, use [`op run`](/cli/reference/commands/run) with the `--environment` flag and the [Environment's ID](#get-an-environments-id), then pass the results to the application or script. 1Password CLI runs the application or script as a subprocess with your secrets loaded into the environment for the duration of the process. ```shell theme={null} op run --environment -- ``` > [!NOTE] > > By default, secrets in 1Password Environments have **"Hide value by default"** turned on. Hidden secrets are automatically concealed in stdout and stderr output. To change this, open an Environment, select the vertical ellipsis next to the secret, then select **Show value by default**. Or use the `--no-masking` flag with `op run`. #### Use with environment variables from multiple sources You can also use `op run` with multiple environments, or in combination with `.env` files or shell environment variables. When the same environment variable exists in multiple sources, 1Password CLI gives them the following precedence: 1. 1Password Environments (highest priority) 2. Environment files 3. Shell environment variables (lowest priorities) If a secret with the same name exists in multiple 1Password Environments, the last Environment specified takes precedence. #### Examples To print a single secret from a 1Password Environment, pass its name to `printenv`. Because Environment secrets are hidden by default, the value stays concealed in the output: ```shell theme={null} op run --environment blgexucrwfr2dtsxe2q4uu7dp4 -- printenv API_KEY #code-result ``` To run a script provisioned with the secrets from an Environment: ```shell theme={null} op run --environment blgexucrwfr2dtsxe2q4uu7dp4 -- ./my-script.sh ``` ### Get secrets (beta) > [!NOTE] > > **Beta feature** > > `op environment read` is available in the [latest beta build of 1Password CLI](https://app-updates.agilebits.com/product_history/CLI2#beta), version `2.33.0-beta.02` or later. To read secrets from a 1Password Environment, use `op environment read` with the [Environment's ID](#get-an-environments-id). 1Password CLI will return a list of the secrets in the Environment formatted as key-value pairs. ```shell theme={null} op environment read ``` #### Examples To get the secrets for a local development Environment with the ID `blgexucrwfr2dtsxe2q4uu7dp4`: ```shell theme={null} op environment read blgexucrwfr2dtsxe2q4uu7dp4 #code-result DB_HOST=localhost DB_USER=admin API_KEY=sk-abc123 ``` After you fetch the Environment, you can pipe the results to other tools. For example: ```shell theme={null} op environment read blgexucrwfr2dtsxe2q4uu7dp4 | grep DB_ ``` ## Learn more * [Access secrets from 1Password through local .env files](/environments/local-env-file) * [Use 1Password's agent hook to validate local .env files from 1Password Environments](/environments/agent-hook-validate) * [Sync secrets from 1Password to AWS Secrets Manager](/environments/aws-secrets-manager) * [Workflow: Secure local development](/get-started/secure-developer-secrets) * [Workflow: Secure your deployments](/get-started/secure-deployment) # 1Password Events API Source: https://www.1password.dev/events-api Use the 1Password Events API to get activity from your 1Password account and send it to your SIEM or other security tools. Use the 1Password Events API to send activity from your 1Password Business account to your security information and event management (SIEM) system. You can track: * **Audit events:** actions people take in the account, like changes to vaults, groups, and users. * **Item usage:** when items in shared vaults are viewed, copied, or edited. * **Sign-in attempts:** who signed in, when, and from where, with details on failed attempts. > [card] [Try the API in your browser](/events-api/reference/introspect) > > Paste your token, pick your region, and send a real request from the docs. No code needed. ## Quickstart 1. [Create an Events Reporting integration](/events-api/get-started) to get a bearer token and connect your SIEM. 2. Send your first request with the **Try it** panel (below). 3. Use the [example scripts](/events-api/generic-scripts) to pull events on a schedule. Want the background first? Read [About the Events API](/events-api/introduction). ## Try it in the docs Each endpoint page, like [Introspect](/events-api/reference/introspect), [Audit events](/events-api/reference/audit-events), [Item usages](/events-api/reference/items-usage), and [Sign-in attempts](/events-api/reference/sign-in-attempt), has a **Try it** panel. Paste your token, pick your region, and send a real request from your browser. No code needed. **1. Get a bearer token** Create an Events Reporting integration in your 1Password account to get a bearer token. [Get started](/events-api/get-started) walks you through it. **2. Start with a read-only call** Open [Introspect bearer token](/events-api/reference/introspect). It checks your token and shows which events it can read, without changing anything. **3. Pick your region and paste your token** Select **Try it**, choose the server that matches your account (1password.com, 1password.ca, 1password.eu, or ent.1password.com), then paste your token in the **Authorization** field. **4. Send it, then copy the code** Select **Send** to see the live response. The example panel turns the same request into cURL, Python, JavaScript, Go, and more, ready to paste into your integration. ## Reference documentation * Read the full [1Password Events API reference](/events-api/reference/). * Learn about [audit events](/events-api/audit-events/). * Learn about [item usage actions](/events-api/item-usage-actions). * Track [version changes](/events-api/changelog/). # Audit events Source: https://www.1password.dev/events-api/audit-events You can use the [1Password Events API](/events-api/reference/) to return audit events from the [audit log](https://support.1password.com/activity-log/) of your 1Password Business account and send them to your security information and event management (SIEM) system. Audit event data includes actions performed by team members in a 1Password account, such as changes made to the account, vaults, groups, users, and more. ## Read an event object When you use the 1Password Events API to fetch audit events from your 1Password Business account, the API will return a JSON array of [audit event objects](/events-api/reference#post-api-v2-auditevents). Event objects can include the following properties: * **`uuid`**: The unique identifier for the event. * **`timestamp`**: When the action was performed. * **`actor_uuid`**: The unique identifier for the team member who performed the action. * **`actor_details`**: The details of the team member who performed the action (including their UUID, name, and email address). * **`action`**: The type of action that was performed. * **`object_type`**: The type of object that the action was performed on. * **`object_uuid`**: The unique identifier for the object the action was performed on. * **`object_details`**: The details of the team member who is the object of the action (including their UUID, name, and email address). This property is only returned for events where the object of the action is a team member. * **`aux_id`**: The identifier that relates to additional information about the activity. * **`aux_uuid`**: The unique identifier that relates to additional information about the activity. * **`aux_details`**: The details of the team member who relates to the additional information about the activity (including their UUID, name, and email address). This property is only returned for events where the additional information about an activity relates to a team member. * **`aux_info`**: Additional information about the activity. * **`session`**: The information about the session, including the date and time the client signed in and started the session, the unique identifier of the device that signed into the session, and the IP address used. * **`location`**: The geolocation information of the client based on their IP address at the time the event was performed. To understand the activity an audit event object is describing, look at the `action`, `actor`, and `object` fields, as well as any `aux` fields that may be included. For example: ```json Example audit event object theme={null} { "uuid": "56YE2TYN2VFYRLNSHKPW5NVT5E", "timestamp": "2023-03-15T16:33:50-03:00", "actor_uuid": "4HCGRGYCTRQFBMGVEGTABYDU2V", "actor_details": { "uuid:": "4HCGRGYCTRQFBMGVEGTABYDU2V", "name": "Jeff Shiner", "email": "jeff_shiner@agilebits.com" }, "action": "join", "object_type": "gm", "object_uuid": "pf8soyakgngrphytsyjed4ae3u", "aux_id": 9277034, "aux_uuid": "K6VFYDCJKHGGDI7QFAXX65LCDY", "aux_details": { "uuid": "K6VFYDCJKHGGDI7QFAXX65LCDY", "name": "Wendy Appleseed", "email": "wendy_appleseed@agilebits.com" }, "aux_info": "A", "session": { "uuid": "A5K6COGVRVEJXJW3XQZGS7VAMM", "login_time": "2023-03-15T16:33:50-03:00", "device_uuid": "lc5fqgbrcm4plajd8mwncv2b3u", "ip": "192.0.2.254" }, "location": { "country": "Canada", "region": "Ontario", "city": "Toronto", "latitude": 43.5991, "longitude": -79.4988 } } ``` This example event shows that `Jeff Shiner` is the actor who performed the `"join" action` on a `[group membership](#group-membership)` (Jeff added someone to a group). And `Wendy Appleseed` is the team member who joined (was added to) the `Administrator group` as a `[group manager](#group-membership)`. To get more information about an object, such as the name of a group, you can check the description of the event in the [audit log](https://support.1password.com/activity-log/), or use the `object UUID` to [retrieve information about an object with 1Password CLI](/cli/reference#unique-identifiers-ids). Use the audit event tables below to learn more about what the different actions and objects mean and what output is returned for each type of event. A complete list of actions and objects can be found in the [appendix](#appendix). ## Audit events * [Accounts](#accounts) * [Delegate sessions](#delegate-sessions) * [Devices](#devices) * [Email changes](#email-changes) * [Family accounts](#family-accounts) * [Files](#files) * [Firewall rules](#firewall-rules) * [Groups](#groups) * [Group membership](#group-membership) * [Group vault access](#group-vault-access) * [Invites](#invites) * [Items](#items) * [Item sharing](#item-sharing) * [Managed companies](#managed-companies) * [Multi-factor authentication](#multi-factor-authentication) * [Packages](#packages) * [Provisioning](#provisioning) - [Reports](#reports) - [Service accounts](#service-accounts) - [Service account tokens](#service-account-tokens) - [Sign-in tokens](#sign-in-tokens) - [Slack app](#slack-app) - [SSO settings](#sso-settings) - [Stripe cards](#stripe-cards) - [Stripe payment methods](#stripe-payment-methods) - [Stripe subscriptions](#stripe-subscriptions) - [Templates](#templates) - [Unknown](#unknown) - [Users](#users) - [User vault access](#user-vault-access) - [User WebAuthn credentials (passkeys)](#passkeys) - [Vaults](#vaults) - [Verified domain](#verified-domain) ### Accounts Actions related to updating and confirming accounts.
Event Description Action Object Type Aux Info
Activate Account The account was activated. `activate` `account`
Update Account Account attributes, such as the name, were changed. `update` `account`
Delete Account The account was deleted. `delete` `account`
Update Account Domain The account domain was changed. `update` `account` domain
Change Account Type The account type was changed. `convert` `account` old account type, new account type
  • `I`: Individual account
  • `F`: Family account
  • `B`: Business account
Enable Duo Duo was enabled for the account. `enblduo` `account`
Update Duo Configuration The Duo configuration for the account was updated. `updatduo` `account`
Disable Duo Duo was disabled for the account. `disblduo` `account`
### Delegate sessions Actions related to delegating sessions.
Event Description Action Object type Aux info
Delegate Session A new delegated session was added. `dlgsess` `dlgdsess` session UUID
### Devices Actions related to authorizing and removing devices.
Event Description Action Object Type Aux Info
Add Device A device was added to the account. `create` `device` user ID, user UUID, user name, user email
Update Device A device was updated. `update` `device` user ID, user UUID, user name, user email
Delete Device A device was deleted. `delete` `device` user ID, user UUID, user name, user email
Delete Old Devices Old devices were deleted. `deolddev` `user`
Delete All Devices All devices were deleted. `dealldev` `user`
Reauthorize Device A device was reauthorized after being deauthorized `reauth` `device` user ID, user UUID, user name, user email
### Email changes Actions related to beginning and completing email changes for team members.
Event Description Action Object Type Aux Info
Begin Email Change An email change was requested by a user. `begin` `ec`
Complete Email Change A user's email was changed. `complete` `ec`
Propose Email Change An email change was proposed by an admin. `propose` `ec`
### Family accounts Actions related to linking and unlinking family accounts.
Event Description Action Object Type Aux Info
Add Family Member Account A team member linked their free family account. `rdmchild` `famchild`
Remove Family Member Account A team member unlinked their free family account. `detchild` `famchild`
### Files Actions related to creating documents.
Event Description Action Object Type Aux Info
Add File A file was uploaded to the account. `create` `file`
### Firewall rules Actions related to firewall settings.
Event Description Action Object type Aux info
Update Firewall Rules A firewall rule was added or updated. `updatfw` `account`
### Groups Actions related to creating, updating, and removing groups.
Event Description Action Object Type Aux Info
Create Group A group was created. `create` `group` group name\ Available for events that occurred after June 11, 2025.
Delete Group A group was deleted. `delete` `group` group name
Update Group A group was updated. `update` `group` group name
Purge Deleted Group A group was marked to be purged. `purge` `group`
Update Group Keyset A group keyset was replaced. `changeks` `group`
### Group membership Actions related to updating team members' group membership.
Event Description Action Object Type Aux Info
Join Group A user joined a group. `join` `gm` user ID, user UUID, user name, user email, user role
  • `R`: Group member
  • `A`: Group manager
Leave Group A user left a group. `leave` `gm` user ID, user UUID, user name, user email
Change Group Membership Role A user's group membership role was changed. `role` `gm` user ID, user UUID, user name, user email, user role
  • `R`: Group member
  • `A`: Group manager
### Group vault access Actions related to modifying groups' access to vaults.
Event Description Action Object Type Aux Info
Grant Group Vault Access A group was granted access to a vault. `grant` `gva` group ID, group UUID, Access Control List
Revoke Group Vault Access A group's access to a vault was revoked. `revoke` `gva` group ID, group UUID
Update Group Vault Access A group's vault access was updated. `update` `gva` group ID, group UUID, Access Control List
### Invites Actions related to inviting team members and guests.
Event Description Action ObjectType AuxInfo
Create Invite An invite was created. `create` `invite` The email address the invite was sent to.
Update Invite An invite was updated. `update` `invite` The email address the invite was sent to.
### Items Actions related to creating, editing, archiving, and deleting items.
Event Description Action ObjectType AuxInfo
Patch Vault Items Vault items were added or updated. `patch` `items` Vault Content Version, number of items added or updated.
Delete Trashed Vault Items Vault items in the trash were deleted. `delete` `items` Vault Content Version, number of items deleted.
Purge Deleted Vault Items Deleted vault items were marked to be purged. `purge` `items` Number of items that were marked to be purged.
Purge Vault Item History Archived vault items were marked to be purged. `purge` `itemhist` item ID, item UUID
### Item sharing Actions related to [sharing items](https://support.1password.com/share-items/).
Event Description Action Object Type Aux Info
Share Item An item was shared externally. `share` `item` vault ID, vault UUID, shared item UUID
Delete Item Share A shared item link was deleted. `delshare` `item` vault ID, vault UUID, shared item UUID
Update Item Share Settings The account's item sharing settings were updated. `uisas` `account`
### Managed companies Actions related to a managed service provider (MSP) creating, launching into, and unlinking managed companies.
Event Description Action Object Type Aux Info
Add Managed Company A managed company was added to an MSP account. `create` `mngdacc`
Launch Into Managed Company An MSP technician launched into a managed company. `launchi` `mngdacc` The ID and UUID of the launched session.
Unlink Managed Company A managed company was unlinked from an MSP account. `unlink` `mngdacc`
### Multi-factor authentication Actions related to enabling, updating, and removing multi-factor authentication.
Event Description Action Object Type Aux Info
Enable Multi-Factor Authentication Multi-factor authentication was enabled. `enblmfa` `user` multi-factor authentication ID, multi-factor authentication type
Update Multi-Factor Authentication Multi-factor authentication was updated. `updatmfa` `user` multi-factor authentication ID, multi-factor authentication type
Disable Multi-Factor Authentication Multi-factor authentication was disabled. `disblmfa` `user` multi-factor authentication ID, multi-factor authentication type
Disable Multi-Factor Authentication For All Users Multi-factor authentication was disabled for everyone in the account. `disblmfa` `account`
Disable Multi-Factor Authentication Type For All Users Multi-factor authentication of a certain type was disabled for everyone in the account. `disblmfa` `account` multi-factor authentication type
### Packages Actions related to team members sending a copy of an item within 1Password.
Event Description Action Object Type Aux Info
Send Package A user sent an item to another user. `sendpkg` `user` package UUID
### Provisioning Actions related to provisioning new team members.
Event Description Action Object Type Aux Info
Send Provisioning Email A provisioning email was sent. `sendts` `user`
Resend Provisioning Email A provisioning email was resent. `resendts` `user`
Resend All Provisioning Emails All provisioning emails were resent. `prsndall` `invite`
### Reports Actions related to viewing and exporting reports.
Event Description Action ObjectType AuxInfo
Export Report A user exported a report. `export` `report` report UUID, report type
View Report A user viewed a report. `view` `report` report UUID, report type
### Service accounts Actions related to adding service accounts.
Event Description Action Object Type Aux Info
Create Integration A service account was created. `create` `sa` The type of service account.
Set Expiration Integration An expiration time was set for a user-managed service account. `expire` `sa` The type of service account.
### Service account tokens Actions related to registering, updating, and revoking access tokens for service accounts.
Event Description Action Object Type Aux Info
Create Token A service account token was registered. `create` `satoken` token name
Rename Token A service account token name was updated. `trename` `satoken` token name
Verify Token A service account token signature was registered. `tverify` `satoken` token name
Revoke Token A service account token was revoked. `trevoke` `satoken` token name
### Sign-in tokens Actions related to creating, ratcheting, and signing in with sign-in tokens for Unlock with SSO.
Event Description Action Object Type Aux Info
Sign In With Sign-In Token A sign-in token was used to log in. `ssotknv` `ssotkn`
### Slack app Actions related to connecting or removing a Slack app.
Event Description Action Object Type Aux Info
Enable Slack App A Slack app was connected to the account. `create` `slackapp`
Disable Slack App A Slack app was removed from the account. `delete` `slackapp`
Update Slack App A connected Slack app was updated. `update` `slackapp`
### SSO settings Actions related to setting up [Unlock with SSO](https://support.1password.com/sso-get-started/).
Event Description Action Object Type Aux Info
Enable SSO Unlock with SSO was enabled. `enblsso` `sso`
Disable SSO Unlock with SSO was disabled. `disblsso` `sso`
Change SSO Authentication Policy The SSO authentication policy was changed. `chngpsso` `sso`
Change SSO Grace Period Authentication Count The SSO grace period authentication count was changed. `chngasso` `sso`
Change SSO Grace Period Duration The SSO grace period duration was changed. `chngdsso` `sso`
Add an SSO Group. An SSO group was added. `addgsso` `sso` group UUID
Delete an SSO Group. An SSO group was deleted. `delgsso` `sso` group UUID
### Stripe cards Actions related to creating, updating, and removing Stripe cards.
Event Description Action Object Type Aux Info
Add Card A new Stripe card was created. `create` `card` card ID, card UID
Update Card A Stripe card was updated. `update` `card` card ID, card UID
Delete Card A Stripe card was deleted. `delete` `card` card ID, card UID
### Stripe payment methods Actions related to adding Stripe payment methods.
Event Description Action Object Type Aux Info
Add Payment Method A new Stripe payment method was created. `create` `pm` payment method ID, payment method UUID
Delete Payment Method A Stripe payment method was deleted. `delete` `pm` payment method ID, payment method UUID
### Stripe subscriptions Actions related to creating, updating, and canceling Stripe subscriptions.
Event Description Action Object Type Aux Info
Create Subscription A new Stripe subscription was created. `create` `sub` subscription ID, subscription UUID
Update Subscription A Stripe subscription was updated. `update` `sub` subscription ID, subscription UUID
Cancel Subscription A Stripe subscription was canceled. `cancel` `sub` subscription ID, subscription UUID
### Templates Actions related to adding, updating, hiding, and deleting templates.
Event Description Action Object Type Aux Info
Add Template A template was added. `create` `template` template name
Update Template A template was updated. `update` `template` template name
Hide Template A template was hidden. `hide` `template` template name
Unhide Template A template was shown (after being hidden). `unhide` `template` template name
Delete Template A template was deleted. `delete` `template` template name
### Unknown Unknown events.
Event Description Action ObjectType AuxInfo
Unknown Events An unknown action occurred. `unknown` `unknown`
### Users Actions related to changes to team members' accounts attributes.
Event Description Action Object Type Aux Info
Upgrade User A guest was promoted to a family or team member. `upguest` `user`
Change User State From A user's state was changed. `verify`, `join`, `activate`, `reactive`, `suspend`, `delete`, or `beginr` `user`
Begin User Recovery A user recovery was initiated. `beginr` `user`
Complete User Recovery A user recovery was completed. `completr` `user`
Cancel User Recovery A user recovery was canceled. `cancelr` `user`
Mark User Away For Travel A user was marked as away for travel. `trvlaway` `user`
Mark User Back From Travel A user was marked as back from travel. `trvlback` `user`
Change User Keyset A user's keyset changed. `changeks` `user`
Change 1Password Account Password A user changed their 1Password account password. `changemp` `user`
Change Secret Key A user changed their Secret Key. `changesk` `user`
Change Name A user changed their name. `changenm` `user`
Change Language A user changed their preferred language. `changela` `user`
Enroll Trusted Device A user set up a trusted device to unlock with SSO. `tdvcsso` `user` device UUID
Set up Single Sign-On Authentication A user set up their 1Password account to unlock with SSO. `sdvcsso` `user`
### User migration Actions related to migrating users.
Event Description Action Object Type Aux Info
Migrating User Created A user migration was started. `create` `miguser` user email
Migrating User Complete A user migration was marked complete. `musercom` `miguser`
Migrating User Declined A user migration was marked declined. `muserdec` `miguser`
### User vault access Actions related to changes to team members' access to vaults.
Event Description Action Object Type Aux Info
Grant User Vault Access A user was granted access to a vault. `grant` `uva` user ID, user UUID, user name, user email, Access Control List
Revoke User Vault Access A user's access to a vault was revoked. `revoke` `uva` user ID, user UUID, user name, user email
Update User Vault Access A user's vault access was updated. `update` `uva` user ID, user UUID, user name, user email, Access Control List
### User WebAuthn credentials (passkeys) Actions relating to creating and deleting [passkeys](https://support.1password.com/save-use-passkeys/) used to sign in to 1Password.
Event Description Action Object Type Aux Info
Create User Webauthn Credential A passkey was created to sign in to 1Password. `create` `cred`
Delete User Webauthn Credential A passkey used to sign in to 1Password was deleted. `delete` `cred`
### Vaults Actions related to creating, updating, and removing vaults.
Event Description Action Object Type Aux Info
Add Vault A vault was added. `create` `vault`
Delete Vault A vault was deleted. `delete` `vault`
Mark Vault To Be Purged A vault was marked for purging. `purge` `vault`
Update Client Access The client access value for a vault was updated. `update` `vault` The new client access value.
Update Attributes A vault name or description was changed. `updatea` `vault`
Export Vault A vault was exported. `export` `vault`
### Verified domain Actions related to verifying domains.
Event Description Action ObjectType AuxInfo
Add Verified Domain A domain was verified. `vrfydmn` `account` domain
Update Verified Domain A verified domain was updated. `uvrfydmn` `account` domain
Delete Verified Domain A verified domain was removed. `dvrfydmn` `account` domain
## Appendix ### Action values Possible values for `action` include:
API output Action
`activate` Activate
`addgsso` Add an SSO group
`begin` Begin
`beginr` Begin recovery
`cancel` Cancel
`cancelr` Cancel recovery
`changeks` Change keyset
`changela` Change language
`changemp` Change 1Password account password
`changenm` Change name
`changesk` Change Secret Key
`chngasso` Change SSO grace period authentication count
`chngdsso` Change SSO authentication policy
`chngpsso` Change SSO grace period duration
`complete` Complete
`completr` Complete recovery
`convert` Convert
`create` Create
`dealldev` Deauthorize all devices
`delete` Delete
`delgsso` Delete an SSO Group
`delshare` Delete shared item link
`deolddev` Deauthorize old devices
`detchild` Remove family member account
`disblduo` Disable Duo
`disblmfa` Disable multi-factor authentication
`disblsso` Disable SSO
`dlgsess` Delegate a new session
`dvrfydmn` Delete verified domain
`enblduo` Enable Duo
`enablmfa` Enable multi-factor authentication
`enblsso` Enable SSO
`expire` Expire
`export` Export
`grant` Grant
`hide` Hide
`join` Join
`launchi` Launch into managed company
`leave` Leave
`musercom` Complete migrating user
API output Action
`muserdec` Decline migrating user
`patch` Modify or update
`propose` Propose
`provsn` Provision
`prsndall` Resend all provisioning emails
`purge` Permanently delete
`rdmchild` Add family member account
`reactive` Reactivate
`reauth` Reauthorize
`resendts` Resend provisioning email
`revoke` Revoke
`role` Update group membership role
`sdvcsso` Set up SSO authentication
`sendpkg` Send an item to another user
`sendts` Send provisioning email
`share` Share an item externally
`ssotkn` Create sign-in token
`ssotknr` Ratchet sign-in token
`ssotknv` Sign in with sign-in token
`suspend` Suspend
`tdvcsso` Enroll trusted device
`trename` Rename token
`trevoke` Revoke token
`trvlaway` Set as away for travel
`trvlback` Set as back from travel
`tverify` Verify token signature
`uisas` Update item sharing administrator settings
`unhide` Unhide
`unknown` Unknown
`unlink` Unlink managed company
`updatduo` Update Duo
`update` Update
`updatea` Update attributes
`updatfw` Update firewall rules
`updatmfa` Update multi-factor authentication
`upguest` Update guest
`uvrfydmn` Update verified domain
`view` View
`verify` Verify
`vrfydmn` Add verified domain
### Object values Possible values for `objectType` include:
API output Object
`account` 1Password account
`card` Stripe card
`cred` Credentials
`device` Device
`dlgdsess` Delegated session
`ec` Email change
`famchild` Linked family account
`file` File
`gm` Group membership
`group` Group
`gva` Group vault access
`invite` Invite
`item` Item
`itemhist` Item history
`items` Items
`mngdacc` Managed account
`miguser` Migrating user
API output Object
`mngdacc` Managed account
`miguser` Migrating user
`plan` Plan
`pm` Stripe payment method
`report` Report
`sa` Service account
`satoken` Service account token
`slackapp` Slack app
`sso` SSO
`ssotkn` SSO token
`sub` Stripe subscription
`template` Template
`user` User
`uva` User vault access
`vault` Vault
`vaultkey` Vault key
# Authorization Source: https://www.1password.dev/events-api/authorization Every call to the 1Password Events API must be authorized with a valid [JWT-encoded](https://datatracker.ietf.org/doc/html/rfc7519) bearer token in the HTTP [request header](/events-api/request-headers/). The token authenticates the client and authorizes it to access specific resources (events), without exposing 1Password account credentials. ## Pass bearer tokens in your API requests Bearer tokens are passed to the Events API through the `Authorization` header in your request. ### Step 1: Get a bearer token You'll get a bearer token when you [set up a new Events Reporting integration](/events-api/get-started#step-1-set-up-an-events-reporting-integration), or when you [issue a new token](#issue-a-bearer-token) in an existing integration. When you generate the token, you'll choose which events the token is scoped to, then save the token in 1Password. After you set up the integration, you can also [issue or revoke tokens](#manage-bearer-tokens) at any time. ### Step 2: Create an API request When you make a call to the Events API, you must include the `Authorization` [request header](/events-api/request-headers/) with your bearer token. The following example uses [curl](https://curl.se/) on the command line to make a GET request to the [`introspect` endpoint](/events-api/reference#get-%2Fapi%2Fv2%2Fauth%2Fintrospect). API calls to this endpoint allow you to check that your bearer token is valid and confirm which events it's authorized to access. 1. In your terminal, format your curl request using the following structure: ```shell theme={null} curl --request GET \ --url /api/v2/auth/introspect \ --header 'Authorization: Bearer ' ``` 2. Replace the `{''}` placeholder in the endpoint with the [events URL for your 1Password account](/events-api/servers/). 3. Replace `{''}` in the `Authorization` header with the token for your Events Reporting integration. * Option 1: Copy the credential field from the bearer token you saved in 1Password, then paste it in the authorization header. For example: ```shell theme={null} --header 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6IjNyaTN0NDR0anZvZmNmbWc0Z2tsNWk2b2FpIiwidHlwIjoiSldUIn0...' ``` The `...` at the end of the bearer token here indicates it's been truncated for the example. You'll need to include the full credential string for your token. * Option 2: [Use an environment variable to load your API token](/events-api/generic-scripts#usage) to avoid revealing your bearer token in plaintext. You'll need to use double quotes for the authorization header to allow for variable expansion. For example: ```shell theme={null} --header "Authorization: Bearer ${EVENTS_API_TOKEN}" ``` ### Step 3: Send the API request Send the API request from the terminal. For example: ```shell theme={null} curl --request GET \ --url https://events.1password.com/api/v2/auth/introspect \ --header "Authorization: Bearer ${EVENTS_API_TOKEN}" ``` If you've installed [jq](https://jqlang.github.io/jq/), you can add `| jq` at the end of your request to pretty-print the JSON response. If your token is authenticated, the API will return a [`200` response](/events-api/reference#responses) that includes the events (features) scoped to your token. For example: ```json theme={null} { "uuid": "OK41XEGLRTH4YKO5YRTCPNX3IU", "issued_at": "2025-10-17T16:32:50-03:00", "features": [ "auditevents", "itemusages", "signinattempts" ], "account_uuid": "M4E2SWNZAZFTRGQGDNS2E5A4MU" } ``` If you get a `401 Unauthorized` error, make sure your bearer token is in the `Authorization` header and is formatted correctly. Learn more about [status codes in the Events API](/events-api/status-codes/). ## Manage bearer tokens After you set up your Events Reporting integration, you can [issue](#issue-a-bearer-token) additional bearer tokens, [revoke](#revoke-a-bearer-token) tokens, and [verify the scope](#verify-the-scope-of-a-bearer-token) of existing tokens. ### Issue a bearer token To issue a new bearer token for an existing integration: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com and select **[Integrations](https://start.1password.com/integrations/active)** in the sidebar. 2. Choose the Events Reporting integration where you want to issue a token and select **Add a token**. 3. Set up a new bearer token: * **Token Name**: Enter a name for the token. * **Expires After**: (Optional) Choose when the token will expire: 30 days, 90 days, or 180 days. The default setting is Never. * **Events to Report**: Choose which events the token can access. The default setting includes all events: sign-in attempts, item usages, and audit events. 4. Select **Issue Token**. 5. On the "Save your token" page, select **Save in 1Password**. Choose the vault where you want to save your token, then select **Save**. \ Your bearer token will be saved as an [API Credential item](https://support.1password.com/item-categories/#api-credential) in 1Password. If you set a bearer token to expire, you can also edit the item you saved in 1Password if you want to add the token's expiry date. ### Revoke a bearer token > [!WARNING] > > Your SIEM will stop ingesting events after a token is revoked. To minimize downtime, issue a replacement token before you revoke one. To revoke a bearer token: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com and select **[Integrations](https://start.1password.com/integrations/active)** in the sidebar. 2. Choose the Events Reporting integration where you want to revoke a token. 3. Select the gear button next to the token you want to revoke, then select **Revoke**. ### Verify the scope of a bearer token To verify a bearer token's scope, check the integration details on 1Password.com: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com and select **[Integrations](https://start.1password.com/integrations/active)** in the sidebar. 2. Choose the Events Reporting integration where you want to verify the scope of a token. 3. Locate your bearer token in the Tokens section and check which events it can access. You will also see when or if the token is set to expire. Alternatively, you can make a [GET request to the introspection endpoint](/events-api/reference#get-%2Fapi%2Fv2%2Fauth%2Fintrospect) to verify which events are scoped to the token. # 1Password Events API v3 (beta) Source: https://www.1password.dev/events-api/beta Learn about the 1Password Events API v3 beta, how it differs from the v2 Events API, and where to get started. The 1Password Events API v3 (version 3) beta is the next version of the [1Password Events API](/events-api). It's built on an updated audit logging model that gives you a more complete view of the activity in your business or enterprise account. Use the v3 beta to retrieve events from your 1Password account and send them to your security information and event management (SIEM) system. Instead of calling a separate endpoint for each type of event, the v3 beta brings your account's events together in a single [audit events endpoint](/events-api/beta/reference/get-v3-auditevents) (`GET /api/v3/auditevents`). Each event uses the same structured format, so you can see who performed an action, what was affected, and where and how it happened, all in one place. [Learn more about the beta API.](#about-the-v3-beta-api) ## Requirements Before you can use the v3 beta, you'll need: * A [1Password Business](https://1password.com/business-security) or [1Password Enterprise Password Manager](https://1password.com/product/enterprise-password-manager) account (not included with 1Password Teams). * Permissions to manage integrations in your 1Password account (for example, as an [owner](https://support.1password.com/groups/#owners), [administrator](https://support.1password.com/groups/#administrators), or member of the [Security group](https://support.1password.com/groups/#security)). ## Quickstart [Start here](/events-api/beta/get-started) to set up an Events Reporting integration and send your first request to the v3 beta. ## Guides * [Manage your Events Reporting integrations](/events-api/beta/manage-integrations) and issue or revoke bearer tokens. * Read the [API conventions](/events-api/beta/conventions) to learn how to authenticate, structure requests, and interpret responses and errors. * Track new features and changes in the [beta roadmap and changelog](/events-api/beta/roadmap). ## Reference Use the [API reference](/events-api/beta/reference) to learn more about the v3 beta endpoint. * [Retrieve audit events](/events-api/beta/reference/get-v3-auditevents) * [Audit events catalog](/events-api/beta/audit-events) ## About the v3 beta API ### A single endpoint for all events The v2 Events API uses individual endpoints for different types of events: `auditevents`, `itemusages`, and `signinattempts`. Each endpoint has its own response schema, so your integration needs to call and process each one separately. The v3 beta consolidates these with a single `/api/v3/auditevents` endpoint. See the [audit events catalog](/events-api/beta/audit-events) for a list of the events the endpoint can return. ### A consistent event structure Every v3 event uses the same structure, regardless of the type of action. Each event includes: * An `action` in a `target.attribute.verb` format. For example: `vault.access.update`. * The `actor` who performed the action, such as a user or a service account. * The `targets` affected by the action, each with its own type and details. * The `context` about where and how the action occurred, including the account, client, device, location, operating system, and session. * A `diff` with the old and new values, for events that represent a change. * A `correlation_id` to identify audit events that originated from the same bulk action. Learn more about the [audit event object](/events-api/beta/reference/get-v3-auditevents). ### Simpler requests and pagination The v3 beta follows the [API Enhancement Proposal (AEP) design standards.](https://aep.dev/) Requests use the `GET` method with query parameters, instead of `POST` requests with a cursor object in the request body. Pagination uses a `next_page_token` that's only returned when there are more results to retrieve. Learn more about [pagination](/events-api/beta/conventions#pagination) and [continuous polling](/events-api/beta/conventions#continuous-polling) in the v3 beta. ## Compare v2 and v3 | | v2 (production) | v3 (beta) | | - | - | - | | **Authorization** | A bearer token scoped to each event type you want to retrieve. | A bearer token scoped to audit events. | | **Endpoints** | Separate endpoints for each event type: `POST /api/v2/auditevents`, `POST /api/v2/itemusages`, and `POST /api/v2/signinattempts`. | A single endpoint for your account's events: `GET /api/v3/auditevents`. | | **Base URLs** | [Events API servers](/events-api/servers) for your account's region. | [Events API servers](/events-api/beta/conventions#base-urls) for your account's region. | | **Request method** | `POST` with a JSON request body. | `GET` with query parameters. No request body. | | **Pagination** | A `cursor` and `has_more` flag in the response. Pass the cursor in the request body of the next request. | A `next_page_token` in the response when more results are available. Pass it in the `page_token` query parameter of the next request. | | **Date and time filters** | `start_time` and `end_time` in the request body. | `start_time` and `end_time` query parameters that filter on when events were ingested by 1Password (`insert_time`). | | **Response format** | A different schema for each endpoint. | The same structured event schema for every event. | | **Event timestamps** | A single `timestamp` field. | Separate fields for `create_time` (when the event occurred) and `insert_time` (when 1Password received it). | ## Use v2 and v3 together The v3 beta uses the same [Events Reporting integrations](/events-api/beta/manage-integrations) and bearer tokens as v2. If you want to use the v2 and v3 APIs together, you can choose one of the following options: * Use the same integration and bearer token for both the v2 and v3 API. Make sure the [token scope](/events-api/beta/manage-integrations#token-scopes) includes audit events. * Use the same integration for both the v2 and v3 API, but [issue separate bearer tokens](/events-api/beta/manage-integrations#issue-a-bearer-token) for each version. * [Create separate integrations](/events-api/beta/manage-integrations#create-an-integration) and bearer tokens for each version. # Audit events catalog Source: https://www.1password.dev/events-api/beta/audit-events Reference catalog of the audit events returned by the 1Password Events API v3 beta, organized by category and subcategory. > [!NOTE] > > The API can fetch event data from the last 120 days. To access event information prior to that, you can use the [audit log](https://support.1password.com/audit-log/) in your 1Password Business account. This catalog provides an extensive, but non-exhaustive, list of audit event actions the API can return, organized by category and type of event. The API may return events that aren't included in this reference. The `action` for each event follows a `target.attribute.verb` format. For example: **Event action**: `service-account.token.create` * **Target**: The object the action was performed on (`service-account`). * **Attribute**: (Optional) Additional context about the action, when present (`token`). * **Verb**: The action that was performed (`create`). **Meaning**: A token was created for a service account. For the full shape of an audit event object, see the [v3 audit events reference](/events-api/beta/reference/get-v3-auditevents). ## Access tokens Actions related to issuing and revoking API access tokens. ## Accounts Actions related to managing and updating your organization's account. ### Account lifecycle ### Account name ### Account promotions ### Allowed domains ### Firewall rules ### Linked family accounts ### Verified domains ## Billing Actions related to billing information, invoices, and managing Stripe payment data. ### Billing information ### Billing invoice ### Promotions ### Stripe cards ### Stripe payment methods ### Stripe subscriptions ## Credential broker Actions related to the configurations, grants, and credentials for the 1Password Credential Broker. ### Credential broker configuration ### Credential broker grant ### Vault item ## Custom email templates Actions related to updating custom email templates in your organization's account. ## Devices Actions related to people managing the devices they use to access your organization's account. ## Files Actions related to adding documents, images, and other files to your organization's account. ## Groups Actions related to managing groups and group access. ### Group keyset ### Group lifecycle ### Group membership ## Integrations Actions related to managing third-party integrations connected to your organization's account. ### Automated provisioning ### Slack app ## Invitations Actions related to sending invitations to people to join your organization's account. ## Item sharing settings Actions related to changing the settings of a shared item. ## Machine identities Actions related to managing workload identities and workload identity providers. ### Machine identity delegation ### Machine identity workload ### Workload identity provider ## Managed accounts Actions related to managed service provider (MSP) accounts and managed companies. ### Copy vaults ### External Account Manager group permissions ### Federated sessions ### Managed company lifecycle ### MSP group permissions ### MSP link requests ### MSP role permissions ### MSP user role permissions ## Managed credentials Actions related to managing credentials and the accessors, policies, and signed keys that govern them. ### Concealed fields ### Credential accessors ### Credential management ### Credential policies ### Signed keys ## Multi-factor authentication Actions related to multi-factor authentication (MFA) at the account and user level. ### Account MFA ### User MFA ## OAuth apps Actions related to managing the OAuth apps connected to your organization's account. ## OIDC issuers Actions related to managing OpenID Connect (OIDC) issuers. ## Policies Actions related to managing policies for your organization's account. ### Duo ### Policy ## Policy templates Actions related to managing policy templates and how they're applied to child accounts. ### Policy template ### Policy template child account ### Policy template override ### Policy template policy ## Recovery keys Actions related to creating and deleting recovery codes in your account. Recovery codes are only available for individual and family accounts. These events may be returned if you previously upgraded from a personal account with a generated recovery code to a business or enterprise account. ## Reports Actions related to viewing and exporting reports for security issues, account activity, and team insights. ## Service accounts Actions related to managing service accounts and their tokens. ### Service account lifecycle ### Service account tokens ## Settings Actions related to managing settings in your organization's account, such as email notifications. ## Sign-in attempts Actions related to successful and failed attempts to sign in to a 1Password account. ## SSO settings Actions related to managing the single sign-on (SSO) configuration for your organization's account and the groups it applies to. ### SSO configuration ### SSO groups ## Users Actions related to managing users in your organization's account. ### Email changes ### Migrating user ### Sign-in tokens ### User delegated session ### User lifecycle ### User keyset ### User migration ### User passkey ### User password ### User provisioning email ### User recovery ### User secret key ### User SSO ### User trusted device ## Vaults Actions related to managing vaults and vault access, and tracking when changes are made to items in a vault. ### Vault access ### Vault item changes ### Vault lifecycle ## Vault items Actions related to vault item maintenance. ### Item history ### Item purge ### Item sharing ## Vault item templates Actions related to managing vault item templates. ## Vault item usages Actions related to end-user interactions with the items in a vault. Item usage events are captured from both employee and shared vaults in your organization's account. ### Vault item ### Vault item agentic autofill ### Vault item concealed field ### Vault item sign in with # API conventions Source: https://www.1password.dev/events-api/beta/conventions Conventions used across the 1Password Events API v3 beta, including authorization, resource paths, query parameters, pagination, rate limits, and error handling. The Events API v3 beta is a REST-style API that supports standard HTTP methods and follows the [OpenAPI 3.0.1 specification.](https://spec.openapis.org/oas/v3.0.1.html) All communication between clients and servers is over HTTPS. The following conventions apply across the v3 beta API, including how to authorize and structure requests, and interpret responses and errors. ## Authentication All calls to the v3 beta endpoint must be authenticated with a valid [JWT-encoded](https://datatracker.ietf.org/doc/html/rfc7519) bearer token scoped to include audit events. You'll get a bearer token when you [set up an Events Reporting integration](/events-api/beta/get-started#step-1-set-up-an-events-reporting-integration). Send the bearer token in the `Authorization` header of every request, prefixed with `Bearer`: ``` Authorization: Bearer ``` For example: ```shell theme={null} curl --request GET \ --url "https://events.1password.com/api/v3/auditevents" \ --header "Authorization: Bearer " ``` If your bearer token is missing, malformed, or invalid, the API returns a `401 Unauthorized` response. Learn more about [how to manage bearer tokens for Events Reporting integrations](/events-api/beta/manage-integrations#manage-bearer-tokens). ## Endpoints The basic structure of an endpoint URL for the v3 beta API includes the base URL and the endpoint path. The endpoint path includes the API endpoint version and the resource you want to access. ### Base URLs The v3 beta endpoint is currently hosted on the same Events API servers as the production API. Use the base URL that matches the [region of your 1Password account](https://support.1password.com/regions/): | Base URL | Description | | - | - | | `https://events.1password.com` | Server for accounts hosted on 1password.com. | | `https://events.ent.1password.com` | Server for accounts hosted on ent.1password.com. | | `https://events.1password.ca` | Server for accounts hosted on 1password.ca. | | `https://events.1password.eu` | Server for accounts hosted on 1password.eu. | > [!NOTE] > > It's possible these servers could change during the beta or when the v3 endpoint moves to production. You can use the [Events API beta roadmap and changelog](/events-api/beta/roadmap) to track changes. ### Endpoint paths Endpoint paths are appended to the base URL and include the endpoint version and the target resource. The v3 beta API has one endpoint: * [`GET /api/v3/auditevents`](/events-api/beta/reference/get-v3-auditevents): Retrieve audit events for actions performed by team members within a 1Password account. To call the endpoint, append the path to your base URL: ```text theme={null} /api/v3/auditevents ``` Check the [API reference documentation](/events-api/beta/reference) for more information about the endpoint. ## Requests ### Request methods The beta API currently supports a single HTTP method: | Method | Usage | | - | - | | `GET` | Retrieve audit events. For example: [`GET /api/v3/auditevents`](/events-api/beta/reference/get-v3-auditevents). | > [!NOTE] > > The v1 and v2 API endpoints continue to use POST requests with a cursor object in the request body. ### Request headers Requests to the beta endpoint require the `Authorization` header: * **`Authorization`**: Your bearer token, prefixed with `Bearer`. Required on every request. See [Authentication](#authentication). ```shell theme={null} Authorization: Bearer ``` ### Request bodies The v3 beta endpoint doesn't use a request body. Pagination and time filters are passed as query parameters. ## Query parameters You can use query parameters in your API request as optional modifiers after the endpoint path. Use a query separator (`?`) at the end of the endpoint path, then add any query parameters you want to include, separated by a query delimiter (`&`). For example, you can retrieve audit events ingested within a specific time window and set the maximum number of events to return per page: ```text theme={null} GET https://events.1password.com/api/v3/auditevents?start_time=2026-05-01T00:00:00Z&end_time=2026-06-01T00:00:00Z&max_page_size=100 ``` Check the [API reference documentation](/events-api/beta/reference/get-v3-auditevents) for more information about the query parameters. ### Filtering The `/api/v3/auditevents` endpoint supports the following date and time parameters: * `start_time`: The earliest insertion time for which to retrieve events (exclusive), filtered on when events were ingested by 1Password. Only events whose insertion time is strictly greater than this value are returned. Invalid if `page_token` is specified. * `end_time`: The latest insertion time for which to retrieve events (exclusive), filtered on when events were ingested by 1Password. Only events whose insertion time is strictly less than this value are returned. Invalid if `page_token` is specified. These parameters filter on the time that events were ingested by 1Password (`insert_time`), not the time they occurred (`create_time`). Learn more about [dates and times in the API](#dates-and-times). ### Pagination The beta API uses cursor-based pagination. Use the `max_page_size` and `page_token` query parameters to page through results: * `max_page_size`: The maximum number of events to return in a single response. If you don't include `max_page_size`, or if you set it to `0`, the server default of `100` is used. The endpoint accepts any positive value, but it returns no more than `1000` events per page. * `page_token`: An opaque string that identifies the next page of results to retrieve. Every successful (`200`) response includes the `audit_events` array at the top level. If there are more pages of events to retrieve, the response also includes a `next_page_token` you can pass to the next request. When the response includes a `next_page_token`, use that token in the `page_token` query parameter of your next request. You can continue making requests until there are no more events. If a response doesn't include a token, that indicates there are no more pages of results to retrieve. > [!WARNING] > > Don't use the `start_time` or `end_time` query parameters in a request that also uses the `page_token` query parameter. Doing so will result in a `400` bad request error. #### Pagination workflow The following example shows a typical pagination workflow: 1. Initial request: Make a GET call to `/api/v3/auditevents` with any combination of `max_page_size`, `start_time`, and `end_time` parameters you need. 2. Check the response: Process the `audit_events` array. Check for a `next_page_token` at the top level of the response to see if there are more pages. If there's a token, continue to step 3. If there's an empty `audit_events` array with no `next_page_token`, that means there are no new events yet. Wait and poll again. 3. Subsequent requests: If there are more pages of events, call the endpoint again using the value of the `next_page_token` in the `page_token` query parameter of your next request. For example: ```shell theme={null} curl --request GET \ --url "https://events.1password.com/api/v3/auditevents?page_token=CAESCwiY84XSBhC0qu9uGgYIgO600wYg_qXh7fMzKhpXNFRTRVA3UDVSSFBCQUpKM1JDWkdYTFpESQ" \ --header "Authorization: Bearer " ``` Repeat this process until the response no longer includes a `next_page_token`, which means you've received all events for the requested time window. To keep receiving new events as they arrive, see [continuous polling](#continuous-polling). #### Continuous polling You can use continuous polling with your integration to call the endpoint on a regular schedule. This allows the integration to retrieve new events as they become available and keep your copy of audit events continuously up to date. To continue the polling loop after the initial pagination is complete: 1. Record the `insert_time` of the last event in the response. 2. Wait until the next scheduled check for new events (the polling interval you set up in your integration). 3. Make a new request using the recorded `insert_time` as the `start_time` parameter. For example: ```shell theme={null} curl --request GET \ --url "https://events.1password.com/api/v3/auditevents?start_time=2026-05-29T18:36:31.883698939Z" \ --header "Authorization: Bearer " ``` 4. Process the events in the response. If the response includes a `next_page_token`, continue the [pagination workflow](#pagination-workflow) using the `page_token` query parameter. Otherwise, record the `insert_time` of the last event in the response and repeat this loop with that value as your new `start_time`. No deduplication of the boundary event is required when polling. ## Responses The API returns JSON for all responses. A successful request returns `200 OK` with an `audit_events` array at the top level. If more pages of results are available, the response also includes a `next_page_token`. When there are no events for the parameters you requested, the `audit_events` array is empty. > [!NOTE] > > The `payload` object can vary by event type for the items in `targets` and the `old_value` and `new_value` objects in `diff`. The fields in these objects are specific to each type and might not use the same naming style as the other fields in the response. For example, a `diff` can include `aclDescription` rather than `acl_description`. Learn more about [error responses](#errors) and [paginated responses](#pagination). ### Dates and times Every audit event includes two date and time fields, both in [RFC 3339 format](https://datatracker.ietf.org/doc/html/rfc3339): * `create_time`: When the event occurred. * `insert_time`: When the event was received and stored by 1Password. The `start_time` and `end_time` query parameters filter on `insert_time`, not `create_time`. This means a single response can include events whose `create_time` falls outside the query window, as long as the events were ingested within it. This is most likely to happen for events that take time to reach 1Password, such as those from offline clients that sync later. Because the endpoint filters on `insert_time`, events that arrive later will surface in the next poll that uses a `start_time` strictly before their `insert_time`. Your [continuous polling](#continuous-polling) loop will receive these events without any special handling. ## Rate limits Requests to the beta endpoint are rate limited to: * 600 requests per minute * 30,000 requests per hour The API uses standard HTTP headers to communicate your current rate limit window and remaining quota. Responses from `GET /api/v3/auditevents` may include the following headers: * `RateLimit-Limit`: The total number of requests allowed for the current time window. * `RateLimit-Remaining`: How many requests you can still make in the current window. * `RateLimit-Reset`: The time when the current rate limit window resets, as a Unix timestamp (the number of seconds since January 1, 1970, 00:00:00 UTC). To find how many seconds remain, subtract the current Unix time from this value. If you exceed the allowed rate, the API returns a `429 Too Many Requests` response with a `Retry-After` header that indicates how many seconds to wait before making another request. When you receive `429 Too Many Requests`, you should: 1. Stop sending additional requests to the endpoint. 2. Wait for the number of seconds specified in the `Retry-After` header. 3. Resume requests, ideally with backoff and retry logic in your client. ## Errors The API uses standard HTTP status codes to indicate the result of a request. A `2xx` code indicates success. A `4xx` code indicates a problem with the request (for example, missing authorization or invalid input). A `5xx` code indicates an unexpected server error. Error responses use the standard error shape defined by [AEP-193.](https://aep.dev/193/) The `type` field is a machine-readable error type identifier, and the `message` field is a human-readable description of the error. | Status | Meaning | | - | - | | `400 Bad Request` | A request parameter is invalid. For example, `start_time` or `end_time` was sent with `page_token`. | | `401 Unauthorized` | The bearer token is missing, malformed, or invalid. | | `429 Too Many Requests` | The rate limit was exceeded. See [Rate limits](#rate-limits). | | `500 Internal Server Error` | An unexpected error occurred. Retry the request later. | Check the [status codes](/events-api/status-codes) page for more information about Events API status codes. # Get started with the 1Password Events API (beta) Source: https://www.1password.dev/events-api/beta/get-started Learn how to set up an Events Reporting integration and start using the 1Password Events v3 beta API. You can use the 1Password Events beta API to retrieve audit events from your business or enterprise account and send them to your security information and event management (SIEM) system. The beta API introduces a [new audit events endpoint](/events-api/beta/reference/get-v3-auditevents) (`/api/v3/auditevents`) that uses the HTTP GET method and cursor-based pagination with query parameters. Audit events include information about the actor, the target of the action, contextual information (like where the session originated), and more. Learn more about the [v3 API conventions](/events-api/beta/conventions) and [how the v2 and v3 APIs compare](/events-api/beta#compare-v2-and-v3). ## Requirements Before you get started with the beta API, you'll need: * A [1Password Business](https://1password.com/business-security) or [1Password Enterprise Password Manager](https://1password.com/product/enterprise-password-manager) account (not included with 1Password Teams). * Permissions to manage integrations in your 1Password account (for example, as an [owner](https://support.1password.com/groups/#owners), [administrator](https://support.1password.com/groups/#administrators), or member of the [Security group](https://support.1password.com/groups/#security)). ## Step 1: Set up an Events Reporting integration To use the API, you'll need to [set up an Events Reporting integration](#set-up-a-new-integration) in your account on 1Password.com. If you've already set one up, you can also [use an existing integration](#use-an-existing-integration). ### Set up a new integration 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Integrations**](https://start.1password.com/integrations/directory) in the sidebar. If you've set up other integrations in your account, you'll also need to select **Directory** on the Integrations page. 3. In the Events Reporting section, choose your SIEM from the list. If your SIEM isn't listed, select **Other**. 4. Enter a name for the integration, then select **Add Integration**. 5. Set up a bearer token: * **Token Name**: Enter a name for the token. * **Expires After**: (Optional) Choose when the token will expire: 30 days, 90 days, 180 days, or Never (default). * **Events to Report**: Choose which events the token can access. The default scope includes all events: sign-in attempts, item usages, and audit events. Learn more about [token scopes](/events-api/beta/manage-integrations#token-scopes). 6. Select **Issue Token**. 7. On the "Save your token" page, select **Save in 1Password**. Choose the vault where you want to save your token, then select **Save**. \ Your bearer token will be saved as an [API Credential item](https://support.1password.com/item-categories/#api-credential) in 1Password. 8. Select **View Integration Details**. You can issue or revoke bearer tokens for your Events Reporting integration at any time. Learn more about [how to manage your integrations and bearer tokens](/events-api/beta/manage-integrations). ### Use an existing integration If you've already set up an Events Reporting integration and want to use the same integration for different versions of the API, follow these steps: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Integrations**](https://start.1password.com/integrations/directory) in the sidebar. 3. Select the Events Reporting integration you want to use. 4. Select **Add a token** to issue a new bearer token for the integration. \ Or use an existing bearer token. Confirm that the integration has an active bearer token scoped to access audit events, and verify that you can access the saved token in 1Password. 5. Set up your new bearer token: * **Token Name**: Enter a name for the token. * **Expires After**: (Optional) Choose when the token will expire: 30 days, 90 days, 180 days, or Never (default). * **Events to Report**: Choose which events the token can access. The default scope includes all events: sign-in attempts, item usages, and audit events. Learn more about [token scopes](/events-api/beta/manage-integrations#token-scopes). 6. Select **Issue Token**. 7. On the "Save your token" page, select **Save in 1Password**. Choose the vault where you want to save your token, then select **Save**. \ Your bearer token will be saved as an [API Credential item](https://support.1password.com/item-categories/#api-credential) in 1Password. 8. Select **View Integration Details**. You can issue or revoke bearer tokens for your Events Reporting integration at any time. Learn more about [how to manage your integrations and bearer tokens](/events-api/beta/manage-integrations). ## Step 2: Find your Events API base URL The `/api/v3/auditevents` beta endpoint currently uses the same Events API servers as the v2 production endpoint. Choose the base URL that matches the [region](https://support.1password.com/regions/) where your 1Password account is hosted: | If your account is hosted on: | Your base URL is: | | - | - | | `1password.com` | `https://events.1password.com` | | `ent.1password.com` | `https://events.ent.1password.com` | | `1password.ca` | `https://events.1password.ca` | | `1password.eu` | `https://events.1password.eu` | You'll use this base URL together with the v3 `auditevents` path. For example: ```text theme={null} https://events.1password.com/api/v3/auditevents ``` ## Step 3: Send a test request with curl Use [curl](https://curl.se/) on the command line to send a test request and confirm your integration is working. ### 3.1: Create a curl request In your terminal, format your request using the following structure: ```shell theme={null} curl --request GET \ --url "/api/v3/auditevents" \ --header "Authorization: Bearer " ``` Replace the placeholders with your own values: * ``: The Events API base URL for your 1Password account. For example: `https://events.1password.com`. * ``: The bearer token for your Events Reporting integration. To filter or paginate the results, add any of the following optional query parameters after the endpoint path, starting with `?` and separated by `&`: * `max_page_size`: The maximum number of events to return in a single response. If you don't include the `max_page_size` parameter, or if you set it to `0`, the server default of `100` is used. The endpoint accepts any positive value, but it returns no more than `1000` events per page. * `start_time`: The earliest insertion time for which to retrieve events (exclusive), filtered on when events were ingested by 1Password. Uses [RFC 3339 format.](https://datatracker.ietf.org/doc/html/rfc3339) For example: `2026-01-01T00:00:00Z`. * `end_time`: The latest insertion time for which to retrieve events (exclusive), filtered on when events were ingested by 1Password. Uses [RFC 3339 format.](https://datatracker.ietf.org/doc/html/rfc3339) For example: `2026-01-12T23:59:59Z`. If you omit the `start_time` and `end_time` parameters, the endpoint will return a page of events using the service-defined default time range. ### 3.2: Send a curl request The following example sends a GET request to the [`/api/v3/auditevents` endpoint](/events-api/beta/reference/get-v3-auditevents), using the curl command structure from the example above. Adjust the query parameters as needed. ```shell theme={null} curl --request GET \ --url "/api/v3/auditevents?max_page_size=1&start_time=2026-01-01T00:00:00Z&end_time=2026-01-12T23:59:59Z" \ --header "Authorization: Bearer " ``` For better readability, you can also provide the query parameters on separate lines using `--data-urlencode` flags. Include the `--get` flag so curl adds the parameters to the URL as a query string instead of sending them in the request body. ```shell theme={null} curl --get \ --url "/api/v3/auditevents" \ --header "Authorization: Bearer " \ --data-urlencode "max_page_size=1" \ --data-urlencode "start_time=2026-01-01T00:00:00Z" \ --data-urlencode "end_time=2026-01-12T23:59:59Z" ``` ### 3.3: Review the response Review the response to confirm that the `audit_events` array contains the expected event data. ```json Example response expandable theme={null} { "audit_events": [ { "action": "vault.access.update", "actor": { "email": "wendy_appleseed@agilebits.com", "name": "Wendy Appleseed", "type": "user", "id": "4HCGRGYCTRQFBMGVEGTABYDU2V" }, "category": "vault", "context": { "account": { "name": "AgileBits", "id": "VZSYVT2LGHTBWBQGUJAIZVRABM" }, "client": { "name": "1Password Extension", "version": "81224010" }, "device": { "model": "149.0.7827.22", "name": "Chrome extension", "id": "xa2p3x45d6vbk7noqnom89rxqm" }, "location": { "city": "Toronto", "ip_address": "192.0.2.254", "latitude": 43.6425, "longitude": -79.3870, "region_code": "CA" }, "origin": "Admin Console", "os": { "name": "MacOSX", "version": "26.5.0" }, "session": { "login_time": "2026-05-29T18:29:46.871840158Z", "id": "X6TARAEE2NGKFLMK5POQBZ4U2Q" }, "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/149.0.0.0 Safari/537.36" }, "correlation_id": "BENRUNBI3JCPPLFFRZTQA6XWIZ", "create_time": "2026-05-29T18:36:31Z", "diff": { "new_value": { "acl": 15730674, "aclDescription": [ "manage", "reveal-password", "read-item", "update-item", "create-item", "archive-item", "delete-item", "view-item-history", "send-item" ] }, "old_value": { "acl": 15730672, "aclDescription": [ "read-item" ] }, "type": "user-vault-access-change" }, "insert_time": "2026-05-29T18:36:31.883698939Z", "targets": [ { "payload": { "type": "U", "typeDescription": "user-created", "id": "lc5fqgbrcm4plajd8mwncv2b3u" }, "type": "vault" }, { "payload": { "email": "wendyappleseed+1@1password.com", "name": "Wendy Appleseed", "id": "OYBARQG5SNEFZHGYT4NDXCHGNI" }, "type": "user" } ], "id": "A5K6COGVRVEJXJW3XQZGS7VAMM" } ], "next_page_token": "CAESCwiY84XSBhC0qu9uGgYIgO600wYg_qXh7fMzKhpXNFRTRVA3UDVSSFBCQUpKM1JDWkdYTFpESQ" } ``` If the response doesn't return any events (the `audit_events` array is empty), try adjusting your `start_time` and `end_time` parameters. If there are more events available than can be returned in a single response, the beta endpoint returns an opaque `next_page_token` at the top level of the response. To request the next page of results, pass the `next_page_token` value in the `page_token` query parameter. For example: ```shell theme={null} curl --request GET \ --url "/api/v3/auditevents?page_token=CAESCwiY84XSBhC0qu9uGgYIgO600wYg_qXh7fMzKhpXNFRTRVA3UDVSSFBCQUpKM1JDWkdYTFpESQ" \ --header "Authorization: Bearer " ``` You can continue calling the endpoint with each `next_page_token` value that gets returned until the response no longer includes a token. Learn more about [pagination](/events-api/beta/conventions#pagination) and [continuous polling](/events-api/beta/conventions#continuous-polling) in the beta API. ## Step 4: Test the beta endpoint After you've confirmed your Events API integration is working, you can test the beta `/api/v3/auditevents` endpoint with your SIEM. ## Try out more examples You can use the interactive API playground on the [endpoint reference page](/events-api/beta/reference/get-v3-auditevents) to try more example requests. Select **Try it** in the endpoint header, enter your own values in the input fields, then send requests directly from the playground. > [!WARNING] > > Requests you send from the API playground are routed through the documentation platform's proxy service. If you prefer to keep your access tokens strictly between your systems and 1Password, copy a code example and run it with your own tools instead. To use examples from the API playground with another tool, select the dropdown menu on a code example and choose which language option you want. Select copy , then paste the example code into your preferred testing tool. You can also download the OpenAPI specification file for the [1Password Events API beta specification (3.0.0) ](/static/files/events-api/events-api-beta_3.0.0_2026-06-25.yaml), then use it to feed into code-generation tools, create mock servers, or import into API clients. # Manage your Events Reporting integrations Source: https://www.1password.dev/events-api/beta/manage-integrations Learn how to create, view, and delete Events Reporting integrations, and how to issue, rotate, verify, and revoke bearer tokens for the 1Password Events API. Create an Events Reporting integration to connect your business or enterprise account to the 1Password Events API, and use the integration to manage the bearer tokens for authenticating requests. You can use the same Events Reporting integration and bearer tokens with both the [v2 production API](/events-api) and the [v3 beta](/events-api/beta). You can also use separate integrations for each version. ## Requirements To manage Events Reporting integrations, you'll need: * A [1Password Business](https://1password.com/business-security) or [1Password Enterprise Password Manager](https://1password.com/product/enterprise-password-manager) account (not included with 1Password Teams). * Permissions to manage integrations in your 1Password account (for example, as an [owner](https://support.1password.com/groups/#owners), [administrator](https://support.1password.com/groups/#administrators), or member of the [Security group](https://support.1password.com/groups/#security)). ## Manage your Events Reporting integrations ### Create an integration When you create a new Events Reporting integration, you'll also issue its first bearer token. 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Integrations**](https://start.1password.com/integrations/directory) in the sidebar. If you've set up other integrations in your account, you'll also need to select **Directory** on the Integrations page. 3. In the Events Reporting section, choose your SIEM from the list. If your SIEM isn't listed, select **Other**. 4. Enter a name for the integration, then select **Add Integration**. 5. Set up a bearer token: * **Token Name**: Enter a name for the token. * **Expires After**: (Optional) Choose when the token will expire: 30 days, 90 days, 180 days, or Never (default). * **Events to Report**: Choose which events the token can access. The default scope includes all events: sign-in attempts, item usages, and audit events. Learn more about [token scopes](#token-scopes). 6. Select **Issue Token**. 7. On the "Save your token" page, select **Save in 1Password**. Choose the vault where you want to save your token, then select **Save**. \ Your bearer token will be saved as an [API Credential item](https://support.1password.com/item-categories/#api-credential) in 1Password. 8. Select **View Integration Details**. After you create the integration, use the bearer token to [send a test request](/events-api/beta/get-started#step-3-send-a-test-request-with-curl), then connect your account to your SIEM. ### View or delete an integration To see the details of an Events Reporting integration you've already set up: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com and select [**Integrations**](https://start.1password.com/integrations/active) in the sidebar. 2. In the Events Reporting section, select the integration you want to see its details. In the Tokens section, you'll see the name, scope, and expiry information for each bearer token that's been issued. You can also [issue new tokens](#issue-a-bearer-token) or [revoke tokens](#revoke-a-bearer-token) for the integration. If you need to change the name of the integration, or connect to a different SIEM or client, you'll need to [create a new integration](#create-an-integration). To delete an integration: 1. Select **More Actions** on the integration details page, then select **Delete**. 2. Enter your account password, then select **Delete Integration**. ## Manage bearer tokens You can issue one or more bearer tokens for your Events Reporting integration. For example, you can issue separate tokens for different SIEMs or environments, or issue a token for the v3 beta while your v2 integration continues to use its existing token. You can [issue](#issue-a-bearer-token), [rotate](#rotate-a-bearer-token), and [revoke](#revoke-a-bearer-token) bearer tokens at any time. ### Token scopes When you issue a bearer token, you'll choose which events it can access. The v3 beta endpoint only requires a token scoped to audit events. If you want to use the same token with v2 endpoints, you can also scope it to include item usages and sign-in attempts. This won't impact how the token is used with the v3 beta API. To verify which events an existing bearer token can access, check the integration details on 1Password.com: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com and select [**Integrations**](https://start.1password.com/integrations/active) in the sidebar. 2. Choose the Events Reporting integration where you want to verify the scope of a token. 3. Locate your bearer token in the Tokens section and check which events it can access. You'll also see when or if the token is set to expire. [Learn more about the beta API.](/events-api/beta#about-the-v3-beta-api) ### Issue a bearer token To issue a new bearer token for an existing integration: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com and select [**Integrations**](https://start.1password.com/integrations/active) in the sidebar. 2. Choose the Events Reporting integration where you want to issue a token and select **Add a token**. 3. Set up a new bearer token: * **Token Name**: Enter a name for the token. * **Expires After**: (Optional) Choose when the token will expire: 30 days, 90 days, 180 days, or Never (default). * **Events to Report**: Choose which events the token can access. The default scope includes all events: sign-in attempts, item usages, and audit events. Learn more about [token scopes](#token-scopes). 4. Select **Issue Token**. 5. On the "Save your token" page, select **Save in 1Password**. Choose the vault where you want to save your token, then select **Save**. \ Your bearer token will be saved as an [API Credential item](https://support.1password.com/item-categories/#api-credential) in 1Password. If you set a bearer token to expire, you can also edit the token item you saved in 1Password to add the token's expiry date. ### Rotate a bearer token To replace a bearer token without interrupting event ingestion: 1. [Issue a new bearer token](#issue-a-bearer-token) in the same integration, scoped to audit events. \ If the bearer token is also used for v2, include any additional scopes that are required. 2. Update your SIEM or client to use the new token. 3. Confirm your SIEM or client is receiving events with the new token. 4. [Revoke the old token](#revoke-a-bearer-token). If your token is set to expire, rotate it before the expiry date. ### Revoke a bearer token > [!WARNING] > > Your SIEM will stop ingesting events after a token is revoked. To minimize downtime, [rotate the token](#rotate-a-bearer-token), then issue the replacement token before you revoke the old one. To revoke a bearer token: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com and select [**Integrations**](https://start.1password.com/integrations/active) in the sidebar. 2. Choose the Events Reporting integration where you want to revoke a token. 3. Select the gear button next to the token you want to revoke, then select **Revoke**. Requests that use a revoked token return a `401 Unauthorized` response. ## Learn more * [About the Events API beta](/events-api/beta) * [Get started with the beta API](/events-api/beta/get-started) * [Beta API conventions](/events-api/beta/conventions) # 1Password Events API beta reference Source: https://www.1password.dev/events-api/beta/reference Complete reference documentation for the 1Password Events API v3 beta. This reference documents the endpoint in the 1Password Events API v3 beta. The endpoint page includes the parameters, response schemas, and an interactive playground you can use to send test requests. For more information about authorization, pagination, and how the beta API works, review the beta [API conventions](/events-api/beta/conventions). ## Endpoints ### Audit events * [GET /api/v3/auditevents](/events-api/beta/reference/get-v3-auditevents): Retrieve audit events for actions performed by team members within a 1Password account. See the [audit events catalog](/events-api/beta/audit-events) for a list of the audit event actions the endpoint can return. ## OpenAPI specification The Events API beta follows the [OpenAPI 3.0.1 specification.](https://spec.openapis.org/oas/v3.0.1.html) To work with the API in another tool, download the specification: * [1Password Events API beta specification (3.0.0) ](/static/files/events-api/events-api-beta_3.0.0_2026-06-25.yaml) # Retrieve audit events (v3 beta) Source: https://www.1password.dev/events-api/beta/reference/get-v3-auditevents openapi/events_api_v3_beta.yaml GET /api/v3/auditevents Get a list of v3 audit events for actions performed by team members within a 1Password account. Retrieve event data from your 1Password account to determine who performed an action and when, like when a team member edits an item's password or invites another team member to a shared vault. Use the `start_time` and `end_time` parameters to filter events by the time they were ingested by 1Password (`insert_time`), not the time they occurred (`create_time`). To continue polling for new events, start a new request using the `insert_time` of the last event as the value for `start_time`. Learn more about [continuous polling](/events-api/beta/conventions#continuous-polling) in the beta API. Use `max_page_size` to set the number of events returned per page (100 by default, up to 1000). If more results are available, the response includes a `next_page_token` at the top level. Pass it in the `page_token` query parameter to fetch the next page. > [!WARNING] > > Don't use the `start_time` or `end_time` query parameters in a request that also uses the `page_token` query parameter. Doing so will result in a `400` bad request error. If the response is successful but there aren't any events for the parameters you requested, the `audit_events` array is empty (`[]`). This endpoint is rate limited. Requests that exceed the limit return a `429 Too Many Requests` error and include a `Retry-After` header. [Learn more about rate limits.](/events-api/beta/conventions#rate-limits) See the [API conventions](/events-api/beta/conventions) for more information about authentication, pagination, filtering, and error handling. # Events API beta roadmap and changelog Source: https://www.1password.dev/events-api/beta/roadmap Learn more about the new and improved features coming to the Events API. You can use the beta roadmap to track the phased rollout of new and improved features planned for the Events API. This page will be updated periodically to indicate when: * A new or improved feature is ready for public beta testing * A beta feature moves into production * A planned feature is added, changed, or removed from the roadmap > [!NOTE] > > All planned features have now been added to the beta. ## Planned features | Feature area | Plan | Phase/Status | Additional information | | - | - | - | - | | Audit events | Create new v3 endpoint for audit events, based on updated audit logging model. | Public beta | Beta endpoint available for testing: [`GET /api/v3/auditevents`](/events-api/beta/reference/get-v3-auditevents). | | Audit log | Rename Activity Log to Audit Log and update to use new audit logging model. | Public beta | Learn more about the [beta audit log](https://support.1password.com/audit-log/). See the [audit events catalog](/events-api/beta/audit-events) for a list of audit event actions. | | Item usages | Add item usage events to the beta. | Public beta | The [`/api/v3/auditevents`](/events-api/beta/reference/get-v3-auditevents) beta endpoint now returns item usage events. | | Sign-in attempts | Add sign-in attempt events to the beta. | Public beta | The [`/api/v3/auditevents`](/events-api/beta/reference/get-v3-auditevents) beta endpoint now returns sign-in attempt events. | ## Beta changelog This section includes information about additive and breaking changes made to the v3 Events API throughout the beta, starting from the public beta release. ### 2026-10-28 **Summary**: * [Sign-in attempt events](/events-api/beta/audit-events#sign-in-attempts) are now returned for 1Password accounts. * Specification file: [1Password Events API beta specification (3.0.0) ](/static/files/events-api/events-api-beta_3.0.0_2026-06-25.yaml) (no changes). **Details**: * Additive This is a non-breaking update to the [`/api/v3/auditevents`](/events-api/beta/reference/get-v3-auditevents) response. The response now includes successful and failed sign-in attempt events for 1Password accounts. ### 2026-08-24 **Summary**: * [Item usage events](/events-api/beta/audit-events#vault-item-usages) are now returned for employee vaults. * Specification file: [1Password Events API beta specification (3.0.0) ](/static/files/events-api/events-api-beta_3.0.0_2026-06-25.yaml) (no changes). **Details**: * Additive This is a non-breaking update to the [`/api/v3/auditevents`](/events-api/beta/reference/get-v3-auditevents) response. The response now includes item usage events for employee vaults (previously only captured from shared vaults). ### 2026-07-09 **Summary**: * [Item usage events](/events-api/beta/audit-events#vault-item-usages) have been added and are now returned by the API for shared vaults. * Specification file: [1Password Events API beta specification (3.0.0) ](/static/files/events-api/events-api-beta_3.0.0_2026-06-25.yaml) (no changes). **Details**: * Additive This is a non-breaking update to the [`/api/v3/auditevents`](/events-api/beta/reference/get-v3-auditevents) response. The response now includes events for actions taken on items in a vault, when applicable. ### 2026-06-25 **Summary**: * The v3 audit events endpoint has been aligned with the [API Enhancement Proposal (AEP) design standards.](https://aep.dev/) This update changes continuous polling, renames several pagination parameters, flattens the response envelope, replaces the event timestamp with separate creation and ingestion times, and standardizes the error response. You'll need to update your client to adapt polling behavior and to consume the new field names and response shape. * Specification file: [1Password Events API beta specification (3.0.0) ](/static/files/events-api/events-api-beta_3.0.0_2026-06-25.yaml). **Details**: * **Pagination**: * Breaking The response no longer includes a `next_page_token` when there are no more results to return. Previously, the API always returned a token, including on the final page of a response and when no events were available. Polling integrations that replayed the most recent token to check for new events must now track the `insert_time` of the last received event and use it as the `start_time` on subsequent requests. Learn more about [pagination](/events-api/beta/conventions#pagination) and [continuous polling](/events-api/beta/conventions#continuous-polling) in the beta API. * Breaking The `start_time` query parameter is now exclusive (previously inclusive). Only events with an `insert_time` strictly greater than `start_time` are returned. * Breaking Removed the `has_more: false` flag. The end of results is now signaled by the absence of `next_page_token` in the response. * Breaking The `start_time` and `end_time` query parameters now filter on `insert_time`. * Breaking Renamed the `page_size` query parameter to [`max_page_size`](/events-api/beta/reference/get-v3-auditevents) in accordance with [AEP-158.](https://aep.dev/158/) If the parameter is omitted or set to `0`, the server default of `100` will be used. The endpoint accepts any positive value, but returns no more than `1000` events per page. * Breaking Renamed the `next_page_token` query parameter to [`page_token`](/events-api/beta/reference/get-v3-auditevents). The response field is still called `next_page_token`. * **Response shapes**: * Breaking Flattened the successful response envelope, and `audit_events` and `next_page_token` are now top-level fields. The previous `data` and `meta` wrappers are no longer used. * Breaking Standardized the error response on the [AEP-193](https://aep.dev/193/) error shape: `{ "type": "...", "message": "..." }`. Replaces the previous nested `ErrorResponse` / `Error.Message` structure. * **Date and time of events**: * Breaking Removed the `timestamp` field on each audit event. Replaced with the new `create_time` and `insert_time` fields. * Breaking New required `create_time` field on each [audit event](/events-api/beta/reference/get-v3-auditevents). RFC 3339 timestamp indicating when the event occurred. * Breaking New required `insert_time` field on each [audit event](/events-api/beta/reference/get-v3-auditevents). RFC 3339 timestamp indicating when the event was received and stored by 1Password. * **Event states**: * Additive New `diff` element on audit events that represent a change. Returns a [`Diff` object](/events-api/beta/reference/get-v3-auditevents) with `type`, `new_value`, and `old_value` fields. * **Other changes**: * Breaking Renamed the `userAgent` field to `user_agent` in the [`Context` object](/events-api/beta/reference/get-v3-auditevents) to use lower\_snake\_case for JSON field names, in accordance with [AEP-140.](https://aep.dev/140/) * Breaking Renamed the `region` field to `region_code` in accordance with [AEP-143.](https://aep.dev/143/) Uses [Unicode CLDR region codes](https://cldr.unicode.org/), for example: `CA`, `DE`, and `US`. * Breaking New required `name` property on the [`Device` object](/events-api/beta/reference/get-v3-auditevents). * Additive New optional `correlation_id` field on the [`AuditEvent` object](/events-api/beta/reference/get-v3-auditevents) for audit events that originated from the same bulk action. ### 2026-01-13 **Summary**: * **Public release of the Events API v3 beta**. We've launched the v3 beta of the 1Password Events API. The beta introduces a new audit logging model that provides a more comprehensive view of the actions being performed in a 1Password account. * Specification file: [1Password Events API specification (3.0.0) ](https://i.1password.com/media/1password-events-reporting/1password-events-api_3.0.0.yaml). **Details**: * A new [v3 audit events beta endpoint](/events-api/beta/reference/get-v3-auditevents): `/api/v3/auditevents` that returns structured audit event data. Audit event data includes information about who performed an action, what was affected, and context about where and how the action occurred. * A new `GET` HTTP method for audit events. * Cursor-based pagination with query parameters for `page_size`, `start_time`, `end_time`, and `next_page_token`. * A new [beta audit log](https://support.1password.com/audit-log/) to monitor events that happen on your team from your 1Password.com account. # 1Password Events API changelog Source: https://www.1password.dev/events-api/changelog This changelog tracks notable changes to the 1Password Events API and provides information about when changes were made and what changed. ## Summary of changes | Version | Date | Type | Description | Details | | - | - | - | - | - | | 1.4.1 | September 2025 | Improvement | Added an account UUID property to the introspect response object. | [View details](#september-2025) | | 1.4.0 | November 2024 | New feature | Added V2 endpoints for sign-in attempts and item usage with external user and MSP support. (*Breaking change* \*) | [View details](#november-2024) | | 1.3.0 | September 2024 | New feature | Added V2 audit events endpoint with external user and MSP support. (*Breaking change* \*) | [View details](#september-2024) | | 1.2.0 | November 2023 | New feature | Added passkey credential support to audit events. | [View details](#november-2023) | | 1.2.0 | August 2023 | Improvement | Enhanced user details in audit event responses. | [View details](#august-2023) | | 1.2.0 | November 2022 | New feature | Added audit events endpoint and reporting capabilities. | [View details](#november-2022) | | 1.2.0 | March 2022 | Improvement | Added geolocation info and SSO actions. | [View details](#march-2022) | | 1.1.0 | September 2021 | Improvement | Added internal server error handling. | [View details](#september-2021) | | 1.1.0 | August 2021 | New feature | Added V2 introspection endpoint. (*Breaking change* \*) | [View details](#august-2021) | | 1.0.0 | July 2021 | Initial release | Initial public release of the 1Password Events API. | [View details](#july-2021) | **\*** Breaking changes are backwards-incompatible changes that require an upgrade to use. When breaking changes are released, we'll continue to support previous versions of the API and you can choose when to upgrade your API version. **September 2025** version 1.4.1 Added a new `account_UUID` property to the introspect endpoint (/api/v2/auth/introspect). You can now confirm the account a bearer token was issued from. This is particularly relevant to managed service providers (MSPs) that manage multiple accounts. **November 2024** version 1.4.0 Added new V2 endpoints with external user and MSP functionality: * POST /api/v2/signinattempts * POST /api/v2/itemusages Changes include: * New SignInAttemptV2 schema: * Added `account_uuid` field * Added `federated` sign-in type * Uses enhanced UserV2 schema * New ItemUsageV2 schema: * Added `account_uuid` field * Uses enhanced UserV2 schema * New SignInAttemptUserTypes enum for user type classification ### Breaking changes V2 endpoints introduce new required fields and response structures. If upgrading from V1: * Response schemas include new required fields * User objects now include type classification * New enums added for MSP functionality ### Migration impact V1 endpoints continue to be supported. Migration to V2 endpoints is only required if you're an MSP provider and you need to access MSP-related event data for your account or the accounts of your managed companies. New integrations can use V2 endpoints regardless of MSP needs. **September 2024** version 1.3.0 Added new V2 audit events endpoint with MSP support: * POST /api/v2/auditevents Changes include: * New AuditEventV2 schema: * Added `actor_type` field * Added `actor_account_uuid` field * Added `account_uuid` field * Added AuditEventActorTypes enum * Added new actions: * `expire` * `launchi` * `unlink` * Added `mngdacc` object type for managed accounts **November 2023** version 1.2.0 * Added "cred" object type for passkey authentication * Fixed latitude field name in Location schema **August 2023** version 1.2.0 Enhanced AuditEvent schema with detailed user information: * Added `actor_details` * Added `object_details` * Added `aux_details` **November 2022** version 1.2.0 * Added audit events endpoint (/api/v1/auditevents) * Added new schemas: * AuditEvent * AuditEventItems * AuditEventActions * AuditEventObjectTypes * Session **March 2022** version 1.2.0 * Added Location object to sign-in attempts and item usage events: * `country` * `region` * `city` * `longitude` * `latitude` * Added new item usage actions: * `select-sso-provider` * `enter-item-edit-mode` **September 2021** version 1.1.0 * Added 500 Internal Server Error response to all endpoints **August 2021** version 1.1.0 Added V2 introspection endpoint: * New introspection endpoint (/api/v2/auth/introspect) * V1 endpoint marked as deprecated * Added IntrospectionV2 schema with consistent naming **July 2021** Version 1.0.0 Initial [public release of the 1Password Events API](https://blog.1password.com/introducing-events-api/), including: * Introspection endpoint * JWT authentication * Item usage endpoint * Sign-in attempts endpoint * Cursor-based pagination # Events API conventions Source: https://www.1password.dev/events-api/conventions Every request to the 1Password Events API follows the conventions on this page. To authenticate your requests, see [Authorization](/events-api/authorization). ## Servers and base URLs The API service ID (`events`) and the server that hosts your 1Password account form the base URL you'll use for the API endpoints. | If your account is hosted on: | Your base URL is: | | - | - | | `1password.com` | `https://events.1password.com` | | `ent.1password.com` | `https://events.ent.1password.com` | | `1password.ca` | `https://events.1password.ca` | | `1password.eu` | `https://events.1password.eu` | ## Endpoints ### Endpoint structure Each API endpoint starts with a [base URL](#servers-and-base-urls), followed by the resource or operation path: ```text theme={null} base_url/path ``` Replace the `base_url` placeholder with the appropriate base URL for your 1Password account and use the `path` of the operation or resource you want to access: [`introspect`](/events-api/reference#get-%2Fapi%2Fv2%2Fauth%2Fintrospect), [`auditevents`](/events-api/reference#post-%2Fapi%2Fv2%2Fauditevents), [`itemusages`](/events-api/reference#post-%2Fapi%2Fv2%2Fitemusages), or [`signinattempts`](/events-api/reference#post-%2Fapi%2Fv2%2Fsigninattempts). For example, if your 1Password account is hosted on `ent.1password.com` and you want to retrieve a list of audit events, you would use the following URL to make a call to the `auditevents` endpoint: ```http Structure of an API endpoint theme={null} https://events.ent.1password.com/api/v2/auditevents ``` ### Endpoint versions The Events API supports both V1 and V2 endpoints for audit events, item usages, and sign-in attempts. The V2 endpoints in this reference provide additional information about users and accounts for managed service providers (MSPs). V1 endpoints remain fully supported for existing integrations that don't require the additional MSP account and user type information. Choose the appropriate version based on your needs: * Use V2 endpoints if you need MSP-related event data or if you're just starting with the Events API. * Use V1 endpoints if you have existing integrations and you don't require the additional MSP data. See the [API changelog](/events-api/changelog/) to learn more about the changes in the V2 endpoints and previous versions of the API. ## Request methods The Events API accepts the following standard HTTP request methods: * GET requests to the [`introspect`](/events-api/reference#get-%2Fapi%2Fv2%2Fauth%2Fintrospect) endpoint return information about the events a bearer token has access to and the account where the token was issued. * POST requests to the [`auditevents`](/events-api/reference#post-%2Fapi%2Fv2%2Fauditevents), [`itemusages`](/events-api/reference#post-%2Fapi%2Fv2%2Fitemusages), and [`signinattempts`](/events-api/reference#post-%2Fapi%2Fv2%2Fsigninattempts) endpoints return information about various activities in a 1Password account. Depending on which endpoint is called, the request returns one of the following: * Successful and failed attempts to sign in to a 1Password account. * Information about every use of an item stored in a shared vault in the account. * Audit events for actions performed by team members in the account. ## Request headers Requests to the Events API must include the correct header(s): * `Authorization`: Each GET and POST request to the Events API must be [authorized with a bearer token](/events-api/authorization/) scoped to access event data for that feature. You'll include your token in the authorization header. * `Content-Type`: Each POST request requires a `Content-Type` header to indicate the media type of the resource being sent in the request body. All data for the Events API is sent and received as JSON, so you'll need to specify `application/json` as the content type. GET requests don't contain a request body and therefore don't require this header. An example of a request header: ```text theme={null} Authorization: Bearer YOUR_BEARER_TOKEN Content-type: application/json ``` ## Pagination The Events API uses cursor-based pagination, which is useful for working with large datasets. In response to each request, the API returns a unique ID (cursor) that indicates where you left off retrieving data. On the next call, you can provide that cursor to continue fetching events starting from the next point in the dataset so no records are missed. There are two types of cursors used in calls to the API: a [reset cursor](#reset-cursor) and a [cursor](#cursor) (also called a continuing cursor). ### Reset cursor A reset cursor is used for the first request you make to the API to create a new point from which to start fetching data. You can also use a reset cursor any time you need to reset the parameters of your cursor – such as the number of records to return with each request – or go back to an earlier point in the records. For the first POST request you make to the API, you must include a `ResetCursor` object with an optional start time, end time, and limit parameters in the request body. The return will include a `cursor` in the response body that you can save to use in the next call made to the API. If no parameters are provided, the API will use the default values indicated in the schema. For example: > [tab] Example reset cursor request > > ```json theme={null} > { > "limit": 100, > "start_time": "2023-03-15T16:32:50-03:00", > "end_time": "2023-03-15T17:32:50-03:00" > } > ``` > [tab] ResetCursor object schema > > | Name | Type | Description | > | - | - | - | > | `limit`* (optional)* | number | The number of events to return in a single request. Specify a limit from 1 to 1000. If not specified, `limit` will default to 100. To return additional events, use the cursor position for subsequent requests. | > | `start_time`* (optional)* | string | The date and time to start retrieving events. Uses the [RFC 3339 standard.](https://datatracker.ietf.org/doc/html/rfc3339) If not specified, `start_time` will default to one hour before specified `end_time`. If no `end_time` is specified, `start_time` will default to one hour ago. | > | `end_time`* (optional)* | string | The date and time to stop retrieving events. Uses the [RFC 3339 standard.](https://datatracker.ietf.org/doc/html/rfc3339) | ### Cursor The `cursor` is a persistent checkpoint that marks your exact position in the event stream and remains valid across API sessions. For continued calling of the API, you should save the cursor you receive from each response. In your next call to the API, include the cursor from the previous response in the request body to start fetching data from the last indicated position. This allows you to resume from where you left off without missing any events. > [tab] Example cursor > > ```json theme={null} > { > "cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK" > } > ``` > [tab] Cursor object schema > > | Name | Type | Description | > | - | - | - | > | `cursor` | string | Cursor to fetch more data, if available, or continue the polling process. Use the cursor returned in the response body of your previous to the endpoint. For example: `aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK`. | The 1Password Events API apps for [Splunk](https://support.1password.com/events-reporting-splunk/) and [Elastic](https://support.1password.com/events-reporting-elastic/) will automatically store the `cursor` position for future requests. ## Rate limits The Events API has the following limits: * 600 requests per minute * 30,000 requests per hour Exceeding these limits will return the following error: ```text theme={null} 429 Too many requests ``` ## HTTP status codes Calls to the 1Password Events API may return the following HTTP status codes: | Code | Message | Description / Recommended action | | - | - | - | | `200` | OK | The request was successful and the server returned a JSON object or an array of objects. Recommended action: No action is required. | | `400` | Bad Request | The server could not understand the request due to invalid syntax. Recommended action: Check the [API reference](/events-api/reference/) and documentation [about the API](/events-api/introduction/) to make sure your request is properly formatted. | | `401` | Unauthorized | Authentication has failed or wasn't provided. Recommended action: Check that your request includes the [`Authorization` header](#request-headers), and make sure your bearer token is valid and scoped to access the requested resource. [Learn more about authorizing API requests.](/events-api/authorization/) | | `429` | Too Many Requests | The rate limit has been exceeded. Recommended action: Wait until the applicable rate-limit window (per-minute or per-hour) resets, then try again. [Learn more about Events API rate limits.](#rate-limits) | | `500` | Internal Server Error | The server encountered an unexpected condition that prevented it from fulfilling the request. Recommended action: Retry your request after a brief wait. If the issue persists, check the [1Password status page](https://status.1password.com/) to verify the Events API service is operational, or [contact 1Password Support](https://support.1password.com/contact/) for help. | # 1Password Events API generic scripts Source: https://www.1password.dev/events-api/generic-scripts > [!NOTE] > > If you're new to Events Reporting, [learn how to get started with 1Password Events API](/events-api/get-started/). To help you get started with the 1Password Events API we've put together a [repository of example scripts](https://github.com/1Password/events-api-generic) across several languages, including [JavaScript](https://github.com/1Password/events-api-generic/blob/main/eventsapi.js), [Python](https://github.com/1Password/events-api-generic/blob/main/eventsapi.py), [Ruby](https://github.com/1Password/events-api-generic/blob/main/eventsapi.rb), [Go](https://github.com/1Password/events-api-generic/blob/main/eventsapi.go), and [PHP.](https://github.com/1Password/events-api-generic/blob/main/eventsapi.php) The scripts will print up to 20 sign-in attempts and item usage events from the last 24 hours. ## Requirements Before implementing any of the examples, or your own scripts, you'll need to generate a bearer token and store it in your 1Password account. To get a bearer token, you can: * [Set up a new Events Reporting integration.](/events-api/get-started#step-1-set-up-an-events-reporting-integration) * [Issue a new token](/events-api/authorization#issue-a-bearer-token) in an existing integration. * [Generate a token with 1Password CLI.](/cli/reference/management-commands/events-api/#events-api-create) ## Usage All scripts use the `EVENTS_API_TOKEN` environment variable to load your API token. We recommend setting `EVENTS_API_TOKEN` to a [secret reference](/cli/secret-reference-syntax/) that points to where your bearer token is saved in 1Password, to avoid revealing the token in plaintext. Then you can use [`op run`](/cli/reference/commands/run/) with [1Password CLI](/cli/) to securely provision the token at runtime. [Learn more about securely loading secrets from the environment.](/cli/secrets-environment-variables/) For example, to set the `EVENTS_API_TOKEN` environment variable with an environment file, then use [`op run`](/cli/reference/commands/run/) to run the PHP `eventsapi.php` script with the variable provisioned: ```shell events.env theme={null} EVENTS_API_TOKEN="op://Vault/Item/token" ``` ``` op run --env-file="./events.env" -- php eventsapi.php ``` To export the `EVENTS_API_TOKEN` environment variable, then use [`op run`](/cli/reference/commands/run/) to run the Go `eventsapi.go` script with the variable provisioned: > [tab] bash, sh, zsh, fish > > ```shell theme={null} > EVENTS_API_TOKEN="op://Vault/Item/token" op run -- go run eventsapi.go > ``` > [tab] Powershell > > 1. Export the necessary environment variables: > > ```powershell theme={null} > $Env:EVENTS_API_TOKEN = "op://Vault/Item/token" > ``` > > 2. Run op run -- with your command for starting the app: > > ```powershell theme={null} > op run -- go run eventsapi.go > ``` ## Learn more * [Get started with the 1Password Events API](/events-api/get-started/) * [Issue or revoke bearer tokens for the Events API](/events-api/authorization#manage-bearer-tokens) * [About 1Password Events Reporting security](https://support.1password.com/events-reporting-security/) * [Workflow: Get data and analytics for your account](/get-started/get-data-and-analytics) # Get started with the 1Password Events API Source: https://www.1password.dev/events-api/get-started You can use the 1Password Events API to set up an integration between your 1Password Business account and your security information and event management (SIEM) system. ## Requirements Before you get started, you'll need to [sign up for a 1Password Business account](https://1password.com/pricing/password-manager). If you already have a business account, you'll need to be an [owner](https://support.1password.com/1password-glossary/#owner) or [administrator](https://support.1password.com/1password-glossary/#administrator) to set up an Events Reporting integration. ## Step 1: Set up an Events Reporting integration You can set up an Events Reporting integration in your 1Password Business account: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Select [**Integrations**](https://start.1password.com/integrations/directory) in the sidebar. If you've set up other integrations in your account, you'll also need to select **Directory** on the Integrations page. 3. In the Events Reporting section, choose your SIEM from the list. If your SIEM isn't listed, select **Other**. 4. Enter a name for the integration, then select **Add Integration**. 5. Set up a bearer token: * **Token Name**: Enter a name for the token. * **Expires After**: (Optional) Choose when the token will expire: 30 days, 90 days, or 180 days. The default setting is Never. * **Events to Report**: Choose which events the token can access. The default scope includes all events: sign-in attempts, item usages, and audit events. 6. Select **Issue Token**. 7. On the "Save your token" page, select **Save in 1Password**. Choose the vault where you want to save your token, then select **Save**. \ Your bearer token will be saved as an [API Credential item](https://support.1password.com/item-categories/#api-credential) in 1Password. 8. Select **View Integration Details**. You can issue or revoke bearer tokens for your Events Reporting integration at any time. Learn more about [how to manage bearer tokens](/events-api/authorization#manage-bearer-tokens). ## Step 2: Test the integration Before you connect your 1Password account with your SIEM, you can send a test request to the Events API using [curl](https://curl.se/) on the command line. Specify the [endpoint](/events-api/endpoints/) along with any required [request headers](/events-api/request-headers/) and data. ### 1. Create a curl request In your terminal, format your curl request using the following structure: ```shell theme={null} curl --request \ --url / \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "limit": , "start_time": "", "end_time": "" }' ``` The `Content-Type` header and the `--data` flag with [pagination](/events-api/pagination/) content are only used in `POST` requests to the Events API. Replace the highlighted content with your preferred values: `{''}` The [HTTP request method](/events-api/request-methods/) you want to use for your request. For example: `POST`. `{''}` The [base URL](/events-api/servers/) of the server used for events in your 1Password account. For example: `https://events.1password.com`. `{''}` The path of the [endpoint](/events-api/endpoints/) you want to use. For example: `/api/v2/signinattempts`. `{''}`: The bearer token you generated in [step 1](#step-1-set-up-an-events-reporting-integration). You can use one of the following options: * Option 1: Copy the credential field from the bearer token you saved in 1Password, then paste it in the authorization header. For example: ```shell theme={null} --header 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6IjNyaTN0NDR0anZvZmNmbWc0Z2tsNWk2b2FpIiwidHlwIjoiSldUIn0...' ``` The `...` at the end of the bearer token here indicates it's been truncated for the example. You'll need to include the full credential string for your token. * Option 2: [Use an environment variable to load your API token](/events-api/generic-scripts#usage) to avoid revealing your bearer token in plaintext. You'll need to use double quotes for the authorization header to allow for variable expansion. For example: ```shell theme={null} --header "Authorization: Bearer ${EVENTS_API_TOKEN}" ``` `{''}` The optional [pagination limit](/events-api/pagination/) for the maximum number of event records you want returned per page. (POST requests only.) Choose a value from `1` to `1000`. `{''}` The optional [RFC 3339-formatted](https://datatracker.ietf.org/doc/html/rfc3339) date and time (UTC) for when you want to start and stop retrieving events. (POST requests only.) For example: `2025-10-31T09:00:00Z`. The pagination limit, start time, and end time data is all optional. If you don't want to include them in your POST request, use an empty request body for the `--data` flag: ```shell theme={null} --data '{}' ``` ### 2. Send a curl request Send your formatted curl request from the terminal. The following example sends a POST request to the [`signinattempts` endpoint](/events-api/reference#post-%2Fapi%2Fv2%2Fsigninattempts), using the curl command structure from the example above. ```json theme={null} curl --request POST \ --url https://events.1password.com/api/v2/signinattempts \ --header 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6Imt6aXJ4NHQ0Mm1laDVwbmFhcm4yYjZucXN1IiwidHlwIjoiSldUIn0...' \ --header 'Content-Type: application/json' \ --data '{ "limit": 1, "start_time": "2025-10-31T09:00:00Z", "end_time": "2025-10-31T17:00:00Z" }' #code-result { "cursor": "ZX8DAQETRWxhc3RpY3NlYXJjaEN1cnNvcgH_gAABBQEFTGltaXQBBAABCVN0YXJ0VGltZQH_ggABB0VuZFRpbWUB_4IAAQtTZWFyY2hBZnRlcgEEAAEKVGllQnJlYWtlcgEMAAAACv-BBQEC_4QAAABL_4ABAgEPAQAAAA7gjFYQAAAAAP7UAQ8BAAAADuCSBYgAAAAA_tQB-gM0JEhDqgEaQlRYUFUzM1ZOTkJLVERST0lGRUVUQkZQNlUA", "has_more": true, "items": [ { "uuid": "BTXPU33VNNBKTDROIFEETBFP6U", "session_uuid": "DU72R2RHZRHUTOYHMG44EDG4UI", "timestamp": "2025-10-31T13:45:49.203617068Z", "country": "CA", "category": "success", "type": "credentials_ok", "details": null, "client": { "app_name": "1Password for Mac", "app_version": "81118011", "platform_name": "Wendy’s MacBook Pro", "platform_version": "MacBookPro18,2", "os_name": "MacOSX", "os_version": "15.7.1", "ip_address": "192.0.2.254" }, "location": { "country": "CA", "region": "Ontario", "city": "Toronto", "latitude": 43.5991, "longitude": -79.4988 }, "target_user": { "uuid": "ETWZJTQCSRFPVOX74KERGHPBTU", "name": "Wendy Appleseed", "email": "wendy_appleseed@agilebits.com", "type": "user" }, "account_uuid": "4XHKKHXODJANPD6ZTBAXK4IM7E" } ] } ``` ### 3. Review the response Review the response that was returned to check that the request was successful. The example request above shows a successful `200` response, with JSON objects detailing the sign-in attempt event(s) and a cursor for continued calling of the API. See the [response schema for the `signinattempts` endpoint](/events-api/reference#responses-3) for more information. If the request was successful but your 1Password account didn't contain any events within the parameters of your request, the response will still return an object with a [cursor string](/events-api/pagination#cursor). For example: ```json theme={null} { "cursor": "ZX8DAQETRWxhc3RpY3NlYXJjaEN1cnNvcgH_gAABBQEFTGltaXQBBAABCVN0YXJ0VGltZQH_ggABB0VuZFRpbWUB_4IAAQtTZWFyY2hBZnRlcgEEAAEKVGllQnJlYWtlcgEMAAAACv-BBQEC_4QAAAAn_4ABAgEPAQAAAA7gfNhwAAAAAP__AQ8BAAAADuB84vwAAAAA__8A", "has_more": false, "items": [] } ``` If you made a call to a different endpoint, check the [Events API reference](/events-api/reference/) for the appropriate response object schema. If you see an error, learn more about [HTTP status codes and recommended actions for error messages](/events-api/status-codes). ## Step 3: Connect your 1Password account to your SIEM ### Use a pre-built connector Many SIEMs already support connecting with 1Password. To use a pre-built connector, [check if your SIEM is in the list of supported applications or services](https://support.1password.com/events-reporting/#step-2-connect-your-1password-account-to-your-siem). If it is, you can follow the provided link for documentation on how to connect your 1Password account. If your SIEM isn't listed, you can also check the documentation for that service for any information they might have about connecting to a 1Password account. ### Build your own integration If your SIEM doesn't have a pre-built connector, you can build your own client to send your 1Password account activity to your SIEM. Use the [Events API reference](/events-api/reference/) and documentation to learn more about how the API works. To help you get started, you can refer to the [example scripts in our GitHub repository](https://github.com/1Password/events-api-generic/) for JavaScript, Python, Ruby, Go, and PHP. Learn more about [how to use the example scripts](/events-api/generic-scripts/). ## Learn more * [Try your first call: Introspect bearer token](/events-api/reference/introspect) * [1Password Events API reference](/events-api/reference/) * [1Password Events API generic scripts](/events-api/generic-scripts/) * [GitHub repository of example scripts](https://github.com/1Password/events-api-generic/) # About the 1Password Events API Source: https://www.1password.dev/events-api/introduction The 1Password Events API is a REST-style API that follows the [OpenAPI 3.0 Specifications.](https://spec.openapis.org/oas/latest.html) All communication between clients and servers are over HTTPS. You can use your preferred language and tools for testing and implementing the Events API. The examples in the [API reference](/events-api/reference/) use [curl](https://curl.se/) on the command line to demonstrate example requests. You can replace the values in any request with your own to receive information about events in your 1Password account. The API can access data from the last 120 days. If you need to access data from more than 120 days ago, you can [use the audit log in your 1Password account](https://support.1password.com/activity-log/). ## Requirements Before you can use the 1Password Events API, you'll need to: * [Sign up for 1Password Business](https://1password.com/pricing/password-manager). * [Set up an Events Reporting integration](/events-api/get-started) in your 1Password account. * [Create a bearer token](/events-api/authorization#step-1-get-a-bearer-token) and select the event features it can access. # Item usage actions Source: https://www.1password.dev/events-api/item-usage-actions You can use the [1Password Events API](/events-api/reference/) to send your 1Password account activity to your security information and event management (SIEM) system, including item usage. [ItemUsage objects](/events-api/reference#post-%2Fapi%2Fv2%2Fitemusages) contain actions, which describe how an item was used. > [!WARNING] > > Actions are only captured from client apps using 1Password 8.4.0 or later. > > Item usage activity is only sent when client apps sync to the 1Password server. Not all item usage triggers a sync, so there may be delays before actions are received. ## Item usage action values Possible values for `action` include: * `enter-item-edit-mode` * `export` * `fill` * `other` * `reveal` * `secure-copy` - `select-sso-provider` - `server-create` - `server-fetch` - `server-update` - `share` The behaviors that trigger each type of action are grouped below by 1Password client type. ### enter-item-edit-mode
Client Behavior
1Password apps Add an item to Favorites.\ Edit an item.\ Usage is recorded upon selecting Edit, whether or not the item is modified.
### export
Client Behavior
1Password apps Download a file.\ Duplicate and save an item to another account.\ Export 1Password account data as a 1PUX or CSV file.\ Usage is recorded for *every* exported item.Move an item to another account.
### fill
Client Behavior
1Password apps Fill an item by selecting:
  • "Open and fill"
  • "Type in window" (Windows only)
1Password in the browser Fill an item by selecting:
  • Autofill
  • Auto-Type (Windows only)
  • Open & Fill
  • An item from the inline menu in a form field
### other Item usage actions are only captured from devices using 1Password 8.4.0 or later. The `other` value indicates the action was performed using an earlier version of 1Password and is unknown.
Client Behavior
1Password apps Action is unknown.
### reveal
Client Behavior
1Password apps Preview a file.\ Reveal a password.\ Show a password in large type.
1Password in the browser Reveal a password.\ Show a password in large type.
### secure-copy
Client Behavior
1Password apps Copy an item field.\ Copy an item's password history.
1Password in the browser Copy an item field.\ Copy an item in JSON format.
### select-sso-provider
Client Behavior
1Password in the browser Sign in to a site using a sign-in provider.
### server-create The `server` prefix indicates that the action occurred on the server rather than in the client app.
Client Behavior
1Password apps Duplicate an item.\ Move an item.
1Password.com Create an item.\ Duplicate an item.
1Password CLI Create an item.
1Password Connect server Create an item.
### server-fetch The `server` prefix indicates that the action occurred on the server rather than the client app. `server-fetch` is a special kind of action type that isn't used by most clients. It's only used when the client reporting the usage is a web server, like 1Password Connect server.
Client Behavior
1Password apps Download a file.\ Preview a file.
1Password.com Open an item.
1Password CLI Open an item.
1Password Connect server Get all of an item's files.\ Get the contents of a file.\ Get the details of a file.\ Get the details of an item.
### server-update The `server` prefix indicates that the action occurred on the server rather than the client app.
Client Behavior
1Password apps Add an item to Favorites.\ Archive an item.\ Delete an item.\ Edit an item.\ Move an item.\ Restore an item.
1Password in the browser Add an item to Favorites.\
1Password.com Add an item to Favorites.\ Archive an item.\ Delete an item.\ Edit an item.\ Restore an item.
1Password CLI Archive an item.\ Delete an item.\ Edit an item.
1Password Connect server Delete an item.\ Edit an item.\ Replace an item.
### share
Client Behavior
1Password apps Copy an item in JSON format.\ Duplicate an item.\ Move an item.\ Share a link to an item.
1Password.com Share a link to an item.
## Learn more * [Get started with 1Password Events Reporting](https://support.1password.com/events-reporting/) * [1Password Events API reference](/events-api/reference/) * [Get started with 1Password Events Reporting and Elastic](https://support.1password.com/events-reporting-elastic/) * [Get started with 1Password Events Reporting and Splunk](https://support.1password.com/events-reporting-splunk/) * [1Password command-line tool: Full documentation](/cli/reference/) * [Workflow: Get data and analytics for your account](/get-started/get-data-and-analytics) # 1Password Events API reference Source: https://www.1password.dev/events-api/reference > [!TIP] > > **Want to send a live request?** Each endpoint has its own page with a **Try it** panel: [Introspect](/events-api/reference/introspect), [Audit events](/events-api/reference/audit-events), [Item usages](/events-api/reference/items-usage), and [Sign-in attempts](/events-api/reference/sign-in-attempt). This API reference documents the latest version of the [1Password Events API specifications (1.4.1)](https://i.1password.com/media/1password-events-reporting/1password-events-api_1.4.1.yaml). Learn more about [API versions](/events-api/conventions#endpoints). > [!NOTE] > > **About pagination** > > All POST endpoints in this API use cursor-based pagination. Your request body must include either a [`ResetCursor`](/events-api/conventions#pagination) object (for your first request) or the `cursor` value from a previous response (for all subsequent requests). > > The cursor is a persistent checkpoint that marks your exact position in the event stream and remains valid across API sessions. You should store the cursor you receive in each response so you can always resume from where you left off without missing any events. Learn more about [how cursors work](/events-api/conventions#pagination). ## GET /api/v2/auth/introspect ```text theme={null} base_url/api/v2/auth/introspect ``` A GET call to this endpoint returns a list of events (features) a bearer token is authorized to access, including one or more of: audit events, item usage, and sign-in attempts. It also returns the UUID of the account where the token was issued. ### Parameters No parameters. ### Requests Use the full URL of the `introspect` endpoint with your [bearer token](/events-api/authorization/) and the required [request headers](/events-api/conventions#request-headers). A GET request doesn't include a body, so the content type header isn't needed. For example: ```shell theme={null} curl --request GET \ --url base_url/api/v2/auth/introspect \ --header 'Authorization: Bearer YOUR_BEARER_TOKEN' ``` ### Responses
200
Returns an `Introspection` object
400
Bad request
401
Unauthorized access
500
Internal server error
A successful `200` response returns an `Introspection` object with information about the token. > [tab] Example introspection response > > ```json theme={null} > { > "uuid": "OK41XEGLRTH4YKO5YRTCPNX3IU", > "issued_at": "2023-03-05T16:32:50-03:00", > "features": [ > "auditevents", > "itemusages", > "signinattempts" > ], > "account_uuid": "M4E2SWNZAZFTRGQGDNS2E5A4MU" > } > ``` > [tab] IntrospectionV2 object schema > > | Name | Type | Description | > | - | - | - | > | `uuid` | string | The UUID of the Events Reporting integration. | > | `issued_at` | string | The date and time the token was issued. Uses the [RFC 3339 standard.](https://datatracker.ietf.org/doc/html/rfc3339) | > | `features` | array of strings | | > | `account_uuid` | string | The UUID of the account where the bearer token was issued. | ## POST /api/v2/auditevents ```text theme={null} base_url/api/v2/auditevents ``` A POST call to this endpoint returns information about actions performed by team members within a 1Password account. Events include when an action was performed and by whom, along with details about the type and object of the action and any other information about the activity. MSP accounts include additional information about the actor's account and type. Learn more about [audit events](/events-api/audit-events/). This endpoint requires a [bearer token](/events-api/authorization/) with the `auditevents` feature. You can make an [introspection call](#get-%2Fapi%2Fv2%2Fauth%2Fintrospect) to the API to verify if your token is authorized to access audit events. ### Parameters No parameters. ### Requests Use the full URL of the `auditevents` endpoint with your [bearer token](/events-api/authorization/) and the required [request headers](/events-api/conventions#request-headers). You must include a [ResetCursor](/events-api/conventions#pagination) object or the [cursor](/events-api/conventions#pagination) from a previous response in the request body. > [tab] Example audit events request with a reset cursor > > ```shell theme={null} > curl --request POST \ > --url base_url/api/v2/auditevents \ > --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \ > --header 'Content-Type: application/json' \ > --data '{ > "limit": 100, > "start_time": "2023-03-15T16:32:50-03:00" > }' > ``` > [tab] Example audit events request with a continuing cursor > > ```shell theme={null} > curl --request POST \ > --url base_url/api/v2/auditevents \ > --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \ > --header 'Content-Type: application/json' \ > --data '{ > "cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK" > }' > ``` ### Responses A successful `200` response returns an `AuditEventItemsV2` object wrapping cursor properties and an array of `AuditEventV2` objects. The included cursor is a persistent checkpoint that marks your current position in the event stream. Save this value and include it in the request body of your next call to this endpoint. Learn more about [how cursors work](/events-api/conventions#pagination).
200
Returns an `AuditEventItemsV2` object
400
Bad request
401
Unauthorized access
500
Internal server error
> [tab] Example audit event response > > ```json theme={null} > { > "cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK", > "has_more": true, > "items": [ > { > "uuid": "56YE2TYN2VFYRLNSHKPW5NVT5E", > "timestamp": "2023-03-15T16:33:50-03:00", > "actor_uuid": "4HCGRGYCTRQFBMGVEGTABYDU2V", > "actor_details": { > "uuid:": "4HCGRGYCTRQFBMGVEGTABYDU2V", > "name": "Jeff Shiner", > "email": "jeff_shiner@agilebits.com" > }, > "action": "join", > "object_type": "gm", > "object_uuid": "pf8soyakgngrphytsyjed4ae3u", > "aux_id": 9277034, > "aux_uuid": "K6VFYDCJKHGGDI7QFAXX65LCDY", > "aux_details": { > "uuid": "K6VFYDCJKHGGDI7QFAXX65LCDY", > "name": "Wendy Appleseed", > "email": "wendy_appleseed@agilebits.com" > }, > "aux_info": "R", > "session": { > "uuid": "A5K6COGVRVEJXJW3XQZGS7VAMM", > "login_time": "2023-03-15T16:33:50-03:00", > "device_uuid": "lc5fqgbrcm4plajd8mwncv2b3u", > "ip": "192.0.2.254" > }, > "location": { > "country": "Canada", > "region": "Ontario", > "city": "Toronto", > "latitude": 43.5991, > "longitude": -79.4988 > } > } > ] > } > ``` > [tab] AuditEventV2 object schemas > > #### AuditEventItemsV2 object schema > > | Name | Type | Description | > | - | - | - | > | `cursor` | string | Cursor to return more event data or to continue polling. | > | `has_more` | boolean | Whether there's more data to be returned using the cursor. If the value is `true`, there may be more events. If the value is `false`, there are no more events at this time. Save the cursor and use it in your next polling request to to resume from where you left off and avoid missing events. | > | `items` | array | An array of [AuditEventV2 objects](#auditeventv2-object-schema). | > > ##### AuditEventV2 object schema > > | Name | Type | Description | > | - | - | - | > | `uuid` | string | The UUID of the action event. | > | `timestamp` | string | The date and time when the action was performed. Uses the [RFC 3339 standard.](https://datatracker.ietf.org/doc/html/rfc3339) | > | `actor_uuid` | string | The UUID of the user who performed the action. | > | `actor_details` | object | A [user object](#userv2-object-schema). | > | `actor_type` | string | | > | `actor_account_uuid` | string | The UUID of the account the user belongs to. | > | `account_uuid` | string | The UUID of the account where the action was performed. | > | `action` | string | | > | `object_type` | string | | > | `object_uuid` | string | The unique identifier for the object the action was performed on. | > | `object_details` | object | An [object details object](#object-details-object-schema). Returned if the object is a user. | > | `aux_id` | integer | The identifier for someone or something that provides additional information about the activity. For example, the ID of a device that a user adds or removes from an account. | > | `aux_uuid` | string | The unique identifier for someone or something that provides additional information about the activity. For example, the UUID of a team member who joins or leaves a group in an account. | > | `aux_details` | object | An [aux details object](#aux-details-object-schema). Returned if the aux details relate to a user. | > | `aux_info` | string | Additional information about the activity. | > | `session` | object | A [session object](#session-object-schema). | > | `location` | object | A [location object](#location-object-schema) that contains details about the geolocation of the client based on the client's IP address at the time the event was performed. | > > ###### UserV2 object schema > > | Name | Type | Description | > | - | - | - | > | `uuid` | string | The UUID of the user who performed the action. | > | `name` | string | The name of the user who performed the action. | > | `email` | string | The email address of the user who performed the action. | > | `user_type` (MSP accounts only) | string | | > | `user_account_uuid` (MSP accounts only) | string | The UUID of the user's account. | > > ###### Object details object schema > > | Name | Type | Description | > | - | - | - | > | `uuid` | string | The UUID of the user who is the object of the action. | > | `name` | string | The name of the user who is the object of the action. | > | `email` | string | The email address of the user who is the object of the action. | > > ###### Aux details object schema > > | Name | Type | Description | > | - | - | - | > | `uuid` | string | The UUID of the user related to the additional information about the activity. For example, the user who was added to or removed from the account or vault or whom created or deleted the device. | > | `name` | string | The name of the user related to the additional information about the activity. | > | `email` | string | The email address of the user related to the additional information about the activity. | > > ###### Session object schema > > | Name | Type | Description | > | - | - | - | > | `uuid` | string | The UUID of the session. | > | `login_time` | string | The date and time the client signed in and started the session. Uses the [RFC 3339 standard.](https://datatracker.ietf.org/doc/html/rfc3339) | > | `device_uuid` | string | The UUID of the device signed in to the session. | > | `ip` | string | The IP address used for the session. | > > ###### Location object schema > > | Name | Type | Description | > | - | - | - | > | `country` | string | The country where the action was performed. | > | `region` | string | The region where the action was performed. | > | `city` | string | The city where the action was performed. | > | `longitude` | number | A coordinate that specifies the longitudinal location for where the action was performed. | > | `latitude` | number | A coordinate that specifies the latitudinal location for where the action was performed. | ## POST /api/v2/itemusages ```text theme={null} base_url/api/v2/itemusages ``` A POST call to this endpoint returns information about items in shared vaults that have been modified, accessed, or used. Events include the name and IP address of the user who accessed the item, when the item was accessed, and the vault where the item is stored. Learn more about [item usage actions](/events-api/item-usage-actions/). This endpoint requires a [bearer token](/events-api/authorization/) with the `itemusages` feature. You can make an [introspection call](#get-%2Fapi%2Fv2%2Fauth%2Fintrospect) to the API to verify if your token is authorized to access sign-in events. ### Parameters No parameters. ### Requests Use the full URL of the `itemusages` endpoint with your [bearer token](/events-api/authorization/) and the required [request headers](/events-api/conventions#request-headers). You must include a [ResetCursor](/events-api/conventions#pagination) object or the [cursor](/events-api/conventions#pagination) from a previous response in the request body. > [tab] Example item usage request with a reset cursor > > ```shell theme={null} > curl --request POST \ > --url base_url/api/v2/itemusages \ > --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \ > --header 'Content-Type: application/json' \ > --data '{ > "limit": 100, > "start_time": "2023-03-15T16:32:50-03:00" > }' > ``` > [tab] Example item usage request with a continuing cursor > > ```shell theme={null} > curl --request POST \ > --url base_url/api/v2/itemusages \ > --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \ > --header 'Content-Type: application/json' \ > --data '{ > "cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK" > }' > ``` ### Responses
200
Returns an `ItemUsageV2` response object
400
Bad request
401
Unauthorized access
500
Internal server error
A successful `200` response returns an `ItemUsageItemsV2` object wrapping cursor properties and an array of `ItemUsageV2` objects. The included cursor is a persistent checkpoint that marks your current position in the event stream. Save this value and include it in the request body of your next call to this endpoint. Learn more about [how cursors work](/events-api/conventions#pagination). > [tab] Example item usage response > > ```json theme={null} > { > "cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK", > "has_more": true, > "items": [ > { > "uuid": "56YE2TYN2VFYRLNSHKPW5NVT5E", > "timestamp": "2023-03-15T16:33:50-03:00", > "used_version": 0, > "vault_uuid": "VZSYVT2LGHTBWBQGUJAIZVRABM", > "item_uuid": "SDGD3I4AJYO6RMHRK8DYVNFIDZ", > "user": { > "uuid": "4HCGRGYCTRQFBMGVEGTABYDU2V", > "name": "Wendy Appleseed", > "email": "wendy_appleseed@agilebits.com" > }, > "client": { > "app_name": "1Password Browser", > "app_version": "20240", > "platform_name": "Chrome", > "platform_version": "string", > "os_name": "MacOSX", > "os_version": "13.2", > "ip_address": "192.0.2.254" > }, > "location": { > "country": "Canada", > "region": "Ontario", > "city": "Toronto", > "latitude": 43.5991, > "longitude": -79.4988 > }, > "action": "secure-copy" > } > ] > } > ``` > [tab] ItemUsageV2 object schemas > > #### ItemUsageItemsV2 object schema > > | Name | Type | Description | > | - | - | - | > | `items` | array | An array of [ItemUsageV2 objects](#itemusagev2-object-schema). | > | `cursor` | string | Cursor to return more event data or to continue polling. | > | `has_more` | boolean | Whether there's more data to be returned using the cursor. If the value is `true`, there may be more events. If the value is `false`, there are no more events at this time. Save the cursor and use it in your next polling request to to resume from where you left off and avoid missing events. | > > ##### ItemUsageV2 object schema > > | Name | Type | Description | > | - | - | - | > | `uuid` | string | The UUID of the event. | > | `timestamp` | string | The date and time of the event. [RFC 3339 standard.](https://datatracker.ietf.org/doc/html/rfc3339) | > | `used_version` | integer | The version of the item that was accessed. | > | `vault_uuid` | string | The UUID of the vault the item is in. | > | `item_uuid` | string | The UUID of the item that was accessed. | > | `action` | string | | > | `user` | object | A [user object](#userv2-object-schema-1). | > | `client` | object | A [client object](#client-object-schema). | > | `location` | object | A [location object](#location-object-schema-1) that contains details about the geolocation of the client based on the client's IP address at the time the event was performed. | > | `account_uuid` (MSP accounts only) | string | The UUID of the account where the action was performed. | > > ###### UserV2 object schema > > | Name | Type | Description | > | - | - | - | > | `uuid` | string | The UUID of the user that accessed the item or attempted to sign in to the account. | > | `name` | string | The name of the user, hydrated at the time the event was generated. | > | `email` | string | The email address of the user, hydrated at the time the event was generated. | > | `user_type` (MSP accounts only) | string | | > | `user_account_uuid` (MSP accounts only) | string | The UUID of the user's account. | > > ###### Client object schema > > | Name | Type | Description | > | - | - | - | > | `app_name` | string | The name of the 1Password app the item was accessed from. | > | `app_version` | string | The version number of the app. | > | `platform_name` | string | The name of the platform the item was accessed from. | > | `platform_version` | string | The version of the browser or computer where 1Password is installed or the CPU of the machine where the 1Password command-line tool is installed. | > | `os_name` | string | The name of the operating system the item was accessed from. | > | `os_version` | string | The version of the operating system the item was accessed from. | > | `ip_address` | string | The IP address the item was accessed from. | > > ###### Location object schema > > | Name | Type | Description | > | - | - | - | > | `country` | string | The country where the item was accessed. | > | `region` | string | The region where the item was accessed. | > | `city` | string | The city where the item was accessed. | > | `longitude` | number | A coordinate that specifies the longitudinal location for where the item was accessed. | > | `latitude` | number | A coordinate that specifies the latitudinal location for where the item was accessed. | ## POST /api/v2/signinattempts ```text theme={null} base_url/api/v2/signinattempts ``` A POST call to this endpoint returns information about sign-in attempts. Events include the name and IP address of the user who attempted to sign in to the account, when the attempt was made, and – for failed attempts – the cause of the failure. For MSP accounts, events also include additional information about the user's account and type. This endpoint requires a [bearer token](/events-api/authorization/) with the `signinattempts` feature. You can make an [introspection call](#get-%2Fapi%2Fv2%2Fauth%2Fintrospect) to the API to verify if your token is authorized to access sign-in events. ### Parameters No parameters. ### Requests Use the full URL of the `signinattempts` endpoint with your [bearer token](/events-api/authorization/) and the required [request headers](/events-api/conventions#request-headers). You must include a [ResetCursor](/events-api/conventions#pagination) object or the [cursor](/events-api/conventions#pagination) from a previous response in the request body. > [tab] Example request with a reset cursor > > ```shell theme={null} > curl --request POST \ > --url base_url/api/v2/signinattempts \ > --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \ > --header 'Content-Type: application/json' \ > --data '{ > "limit": 100, > "start_time": "2023-03-15T16:32:50-03:00" > }' > ``` > [tab] Example request with a continuing cursor > > ```shell theme={null} > curl --request POST \ > --url base_url/api/v2/signinattempts \ > --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \ > --header 'Content-Type: application/json' \ > --data '{ > "cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK" > }' > ``` ### Responses
200
Returns a `SignInAttemptItemsV2` object
400
Bad request
401
Unauthorized access
500
Internal server error
A successful `200` response returns a `SignInAttemptItemsV2` object wrapping cursor properties and an array of `SignInAttemptV2` objects. The included cursor is a persistent checkpoint that marks your current position in the event stream. Save this value and include it in the request body of your next call to this endpoint. Learn more about [how cursors work](/events-api/conventions#pagination). > [tab] Example sign-in attempt response > > ```json theme={null} > { > "cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK", > "has_more": true, > "items": [ > { > "uuid": "56YE2TYN2VFYRLNSHKPW5NVT5E", > "session_uuid": "A5K6COGVRVEJXJW3XQZGS7VAMM", > "timestamp": "2023-03-15T16:32:50-03:00", > "category": "firewall_failed", > "type": "continent_blocked", > "country": "France", > "details": { > "value": "Europe" > }, > "target_user": { > "uuid": "IR7VJHJ36JHINBFAD7V2T5MP3E", > "name": "Wendy Appleseed", > "email": "wendy_appleseed@agilebits.com" > }, > "client": { > "app_name": "1Password Browser", > "app_version": "20240", > "platform_name": "Chrome", > "platform_version": "string", > "os_name": "MacOSX", > "os_version": "13.2", > "ip_address": "192.0.2.254" > }, > "location": { > "country": "Canada", > "region": "Ontario", > "city": "Toronto", > "latitude": 43.5991, > "longitude": -79.4988 > } > } > ] > } > ``` > [tab] SignInAttemptsV2 object schemas > > #### SignInAttemptItemsV2 object schema > > | Name | Type | Description | > | - | - | - | > | `items` | array | An array of [SignInAttemptsV2 objects](#signinattemptsv2-object-schema). | > | `cursor` | string | Cursor to return more event data or to continue polling. | > | `has_more` | boolean | Whether there's more data to be returned using the cursor. If the value is `true`, there may be more events. If the value is `false`, there are no more events at this time. Save the cursor and use it in your next polling request to to resume from where you left off and avoid missing events. | > > ##### SignInAttemptsV2 object schema > > | Name | Type | Description | > | - | - | - | > | `uuid` | string | The UUID of the event. | > | `session_uuid` | string | The UUID of the session that created the event. | > | `timestamp` | string | The date and time of the sign-in attempt. Uses the [RFC 3339 standard.](https://datatracker.ietf.org/doc/html/rfc3339) | > | `category` | string | | > | | `type` | string | > | `country` | string | The country code of the event. Uses the [ ISO 3166 standard.](https://www.iso.org/iso-3166-country-codes.html) | > | `details` | object | A [details object](#details-object-schema) that contains additional information about the sign-in attempt. | > | `target_user` | object | A [user object](#userv2-object-schema-2). | > | `client` | object | A [client object](#client-object-schema-1). | > | `location` | object | A [location object](#location-object-schema-2) that contains details about the geolocation of the client based on the client's IP address at the time the event was performed. | > | `account_uuid` (MSP accounts only) | string | The UUID of the account where the action was performed. | > > ###### Details object schema > > | Name | Type | Description | > | - | - | - | > | `value` | string | The additional information about the sign-in attempt, such as any firewall rules that prevent a user from signing in. For example, in the event of a sign-in attempt blocked by firewall rules, the value is the country, continent, or IP address of the sign-in attempt. | > > ###### UserV2 object schema > > | Name | Type | Description | > | - | - | - | > | `uuid` | string | The UUID of the user that accessed the item or attempted to sign in to the account. | > | `name` | string | The name of the user, hydrated at the time the event was generated. | > | `email` | string | The email address of the user, hydrated at the time the event was generated. | > | `user_type` (MSP accounts only) | string | | > | `user_account_uuid` (MSP accounts only) | string | The UUID of the user's account. | > > ###### Client object schema > > | Name | Type | Description | > | - | - | - | > | `app_name` | string | The name of the 1Password app the item was accessed from. | > | `app_version` | string | The version number of the app. | > | `platform_name` | string | The name of the platform the item was accessed from. | > | `platform_version` | string | The version of the browser or computer where 1Password is installed or the CPU of the machine where the 1Password command-line tool is installed. | > | `os_name` | string | The name of the operating system the item was accessed from. | > | `os_version` | string | The version of the operating system the item was accessed from. | > | `ip_address` | string | The IP address the item was accessed from. | > > ###### Location object schema > > | Name | Type | Description | > | - | - | - | > | `country` | string | The country where the sign-in attempt was made. | > | `region` | string | The region where the sign-in attempt was made. | > | `city` | string | The city where the sign-in attempt was made. | > | `longitude` | number | A coordinate that specifies the longitudinal location where the sign-in attempt was made. | > | `latitude` | number | A coordinate that specifies the latitudinal location where the sign-in attempt was made. | ## ErrorResponse object > [tab] Example error response > > ```json theme={null} > { > status: 401, > message: "Unauthorized access" > } > ``` > [tab] ErrorResponse object schema > > | Name | Type | Description | > | - | - | - | > | `status` | integer | The HTTP status code. | > | `message` | string | A message detailing the error. | # Retrieve audit events (v2) Source: https://www.1password.dev/events-api/reference/audit-events /openapi/events_api.yaml post /api/v2/auditevents Retrieves audit events for actions performed by team members within a 1Password account # Introspect bearer token (v2) Source: https://www.1password.dev/events-api/reference/introspect /openapi/events_api.yaml get /api/v2/auth/introspect Performs introspection of the provided Bearer JWT token # Retrieve item usages (v2) Source: https://www.1password.dev/events-api/reference/items-usage /openapi/events_api.yaml post /api/v2/itemusages Retrieves events for each usage of an item stored in a shared vault within a 1Password account # Retrieve sign-in attempts (v2) Source: https://www.1password.dev/events-api/reference/sign-in-attempt /openapi/events_api.yaml post /api/v2/signinattempts Retrieves events for both successful and failed attempts to sign into a 1Password account # Get started with 1Password developer tools Source: https://www.1password.dev/get-started Start using 1Password developer tools: a 10-minute developer quickstart, setup guides for the CLI, service accounts, SSH, Environments, AI agents, and SDKs, and guides by scenario. ## New here? Start with a quickstart > [card] [I'm a developer](/get-started/developer-quickstart) > > Install the CLI, create an Environment, and run your app with secrets from 1Password. About 10 minutes. > [card] [I'm setting up my team](/get-started/administrator-quickstart) > > Stream account activity to your security tools, set team policies, create shared vaults and Environments, and roll out developer tools. Integrating 1Password into a product you sell? Use the [partner quickstart](/get-started/partner-quickstart). ## Set up one tool Already know what you need? Each of these gets one tool working in a few minutes. > [card] [1Password CLI](/cli/get-started) > > Install the CLI and sign in with the 1Password app. The starting point for most workflows. > [card] [Service accounts](/service-accounts/get-started) > > Create a scoped token for CI/CD, servers, and scripts that run without a person. > [card] [SSH & Git](/ssh/get-started) > > Store SSH keys in 1Password and approve Git pushes and commit signing with your fingerprint. > [card] [Environments](/environments/local-env-file) > > Replace plaintext .env files with a file 1Password mounts for your app. > [card] [AI agents and MCP](/security-for-ai) > > Give Claude Code, Cursor, and other agents project secrets without plaintext .env files on disk. > [card] [SDKs](/sdks) > > Work with 1Password from Go, JavaScript, or Python. ## Guides by scenario End-to-end guides that combine several tools: * [Secure local development](/get-started/secure-developer-secrets): use secrets in your terminal, IDE, and projects without plaintext. * [Secure your deployments](/get-started/secure-deployment): load secrets into CI/CD, containers, and production apps. * [Secure AI access](/get-started/secure-ai-access): give AI agents credentials without storing them in plaintext. * [Build integrations](/get-started/build-integrations): build scripts and apps that work with your 1Password account. * [Manage your organization](/get-started/manage-organization): automate groups, vaults, and permissions. * [Get data and analytics](/get-started/get-data-and-analytics): send account activity to your security tools. # Administrator quickstart Source: https://www.1password.dev/get-started/administrator-quickstart Set up the 1Password app and CLI for admin workflows, connect the Events API to your SIEM, and prepare your team to use 1Password developer tools. > [!TIP] > > To use 1Password developer tools to manage your organization, you'll need a [1Password Business](https://1password.com/business-security), [1Password Enterprise](https://1password.com/enterprise-security), or [1Password Teams](https://1password.com/product/teams-small-business-password-manager) account, and an [owner](https://support.1password.com/1password-glossary/#owner) or [administrator](https://support.1password.com/1password-glossary/#administrator) role. ## Step 1: Install the 1Password app Install 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux) and sign in with your administrator account. After you install the app: 1. Open the 1Password app and select your account or collection at the top of the sidebar. 2. Navigate to **Settings** > **Security**. 3. Turn on the setting to unlock the app using [Touch ID](https://support.1password.com/touch-id-mac/), [Windows Hello](https://support.1password.com/windows-hello/), or [Linux system authentication](https://support.1password.com/system-authentication-linux/). This allows you to authenticate most developer tools with your fingerprint. ## Step 2: Install 1Password CLI 1Password CLI (`op`) is the fastest way to get started programmatically managing your team. To install [1Password CLI](/cli), run the following command or [download the latest release](https://app-updates.agilebits.com/product_history/CLI2). > [tab] homebrew > > ```shell theme={null} > brew install 1password-cli > ``` > [tab] winget > > ```shell theme={null} > winget install 1password-cli > ``` > [!TIP] > > See the [full CLI installation guide](/cli/get-started) for requirements and additional Windows, Linux, and manual installation options. Then turn on the app integration to sign in with the accounts you’ve added to the app and authenticate requests using your fingerprint. 1. Open the 1Password app and select your account or collection at the top of the sidebar. 2. Navigate to **Settings** > [**Developer**](onepassword://settings/developers). 3. Select **Integrate with 1Password CLI**. Enter any command to sign in. For example, to list all the vaults you have access to: ```shell theme={null} op vault list ``` > [!TIP] > > You can also use [1Password SDKs](/sdks) to build integrations with Go, JavaScript, or Python. ## Step 3: Monitor account activity You can use the [1Password Events API](/events-api/) to stream activity from your 1Password account into your SIEM. 1. On 1Password.com, go to **Integrations** > **Events Reporting**. 2. Choose your SIEM from the list or select **Other**. 3. Name the integration and issue a bearer token scoped to the event types you need. Make sure to save the token in 1Password. 4. Configure your SIEM to pull events from the API. > [card] [Get started with the Events API](/events-api/get-started) > > Step-by-step setup for creating an Events Reporting integration, testing requests with curl, and connecting your SIEM. ## Step 4: Configure team policies With 1Password Business, you can set policies for how people in your organization sign in to and use their 1Password accounts, including how they use developer tools. To manage developer policies, [sign in](https://start.1password.com/signin) to your account on 1Password.com, select [Policies](https://start.1password.com/policies) in the sidebar, then select **Manage** under the "Sharing and permissions" policy. > [!TIP] > > You can set team member policies if you’re an owner, administrator, or part of a group with the [Manage Settings](https://support.1password.com/groups/#appendix-default-permissions) permission. ### Local disk scanning Turn on **Allow local disk scanning** to generate the [developer secrets discovery report](https://support.1password.com/developer-secrets-report/). This lets you see if there are any plaintext developer secrets located on team members' local disks that need to be mitigated, such as unencrypted SSH private keys and `.env` files with plaintext environment variables. Team members can also use local disk scanning with [1Password Developer Watchtower](/watchtower) in the desktop app, so they can find and fix issues early and build stronger secret management habits over time. ### Developer permissions Turn on **Allow automatic creation of SSH configuration file** so your team can connect to hosts with SSH keys stored in 1Password using [SSH Bookmarks](/ssh/bookmarks/). Turn on **Allow developers to use Environments to manage their project secrets and use them in tools and workflows** to let your team manage project secrets using [1Password Environments](/environments). ### Sidebar navigation By default, team members can see developer tools and integrations in the sidebar when they sign in to their account on 1Password.com. If you choose to hide these tabs, people outside the Owners and Administrators groups won't be able to see them in the sidebar, and will only be able to access existing active tools or integrations with a link. For ease of use, we recommend keeping these tabs visible for your team. ### 1Password browser extension Turn on **Require team members to add the extension during account setup** to require your team to install the 1Password browser extension. They can use the browser extension to [autofill SSH public keys](/ssh/public-key-autofill), which makes it easier to set up Git commit signing and SSH. The browser extension also provides automatic prompts to save certain developer credentials in 1Password, like when you [create an AWS access key](/cli/shell-plugins/aws#before-you-begin-create-and-save-an-aws-access-key). Under **Autofill access**, make sure **SSH items** are selected as an item type team members can autofill with 1Password. This allows your team to [autofill SSH public keys](/ssh/public-key-autofill). ### Biometrics and unlock settings Many 1Password developer tools have the option to authenticate using the 1Password desktop app with biometrics. Make sure your unlock and auto-lock policy allows biometric unlock (Touch ID, Windows Hello, or Linux system authentication) so your developers can use these tools without friction. You can configure this under **Authentication** > **Unlock and auto-lock** in your team policies. > [card] [Manage team policies](https://support.1password.com/team-policies/) > > Full list of configurable policies. ## Step 5: Set up shared resources With policies in place, set up the shared resources you'll need to effectively roll out 1Password developer tools to your engineering team. ### Environments [1Password Environments](/environments) let you organize project secrets as collections of environment variables that your team can share and access directly in their code. Instead of each developer maintaining their own `.env` files, which can easily get out of date, you can create an Environment in 1Password and share it with the appropriate people on your team. Then when you update the Environment, the change is reflected for everyone who needs it. Create shared Environments for your organization's shared developer credentials, like API keys, database credentials, service account tokens, and other infrastructure secrets. Organize your Environments by access boundary for each project, not credential type, so that each Environment reflects a separate context. If your team works with development, staging, and production environments for a project, create a corresponding 1Password Environment for each. For example, `Website Production`, `iOS App Beta`, or `Payment Services Production`. Developers can switch between targets by changing an Environment ID rather than managing separate sets of credentials. ### Shared vaults Create [shared vaults](https://support.1password.com/create-share-vaults-teams/) for the other credentials your developers need access to. Organize vaults by a shared context like team or project. Follow the [principle of least privilege](https://csrc.nist.gov/glossary/term/least_privilege) in deciding who has access to each shared vault. ### Groups You can create [custom groups](https://support.1password.com/custom-groups/) to manage access to shared vaults. Using groups to assign access makes onboarding and offboarding simpler and makes sure permissions stay consistent as your team evolves. ### Service accounts Create [1Password Service Accounts](/service-accounts) for your team's automated workflows, including CI/CD pipelines, deployment scripts, scheduled jobs, and other processes that need to access secrets without a human present. Each service account token is scoped to specific vaults and Environments with defined permissions. Follow the [principle of least privilege](https://csrc.nist.gov/glossary/term/least_privilege) when you create service accounts: give each service account access only to the vaults and Environments it needs, with the minimum permissions required. Create one service account per purpose, so you can easily revoke a token if needed, and for a better audit trail. For example, create separate service accounts for your CI/CD pipeline, your production deployment, your staging environment, and any other distinct use case. > [!TIP] > > By default, only owners and administrators can create service accounts. If you want to allow other groups to create service accounts, [sign in](https://start.1password.com/signin) on 1Password.com and navigate to **Developer** > **Permissions** > **Service Account**. Review your organization's service accounts periodically. Are any scoped too broadly? Are any still active for inactive projects? You can list and manage service accounts on 1Password.com under **Developer** > **Service accounts**. And you can generate reports about service accounts by creating a [usage report](https://support.1password.com/reports/#create-a-usage-report-for-a-team-member-service-account-or-vault). > [card] [Business security practices](https://support.1password.com/business-security-practices/) > > Best practices for securing your 1Password Business account across settings, access, integrations, and team lifecycle. ## Step 6: Roll out developer tools Now that you have your policies and shared resources set up, you're ready to get your engineering team using 1Password developer tools. Here are some tips to help you get started: ### Share the developer quickstart Share the [developer quickstart](/get-started/developer-quickstart) to help your engineering team set up 1Password's main developer tools. Make sure to add the quickstart to your organization's onboarding documentation to help new hires get started from day one. > [card] [Developer quickstart](/get-started/developer-quickstart) > > Install the 1Password desktop app, CLI, SSH agent, and learn how to securely load secrets from Environments. ### Require signed commits Adjust your GitHub or GitLab repository rules to require signed commits, then help them [configure Git commit signing with 1Password](/ssh/git-commit-signing). > [card] [GitHub](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-signed-commits) > > Learn how to require signed commits in GitHub. > [card] [GitLab](https://docs.gitlab.com/user/project/repository/push_rules/#require-signed-commits) > > Learn how to require signed commits in GitLab. ### Secure plaintext credentials Encourage your team to audit their local machines for secrets that can be migrated to 1Password, so they can remove plaintext secrets from their code. Common places to look include: * `.env` files in project directories. * Shell profiles like `.bashrc` or `.zshrc`. * Config files like `~/.aws/credentials` or `~/.ssh/config`. * SSH private keys in the `~/.ssh` directory. * Hardcoded values in scripts and source code. Then have them follow the guide to [securing developer credentials](/get-started/secure-developer-secrets) to load these secrets securely from 1Password instead. > [!TIP] > > If you turn on the [local disk scanning](#local-disk-scanning) policy, your team can use [Developer Watchtower](/watchtower) to help find plaintext developer secrets on their devices and import them into 1Password. > > If your developers use VS Code, [1Password for VS Code](/vscode) is also a convenient way to quickly detect secrets and secure them in 1Password. ### Promote Developer Watchtower After your team sets up 1Password for SSH, encourage developers to turn on [Developer Watchtower](/watchtower) to audit their machines for SSH key security issues, like keys that are stored in plaintext or use outdated cryptography. ## Next steps Choose what you want to do next: > [card] [Manage your organization](/get-started/manage-organization) > > Automate managing users, groups, vaults, and permissions with 1Password CLI or SDKs and our library of prewritten scripts and integrations. > [card] [Get data and analytics](/get-started/get-data-and-analytics) > > Generate account activity reports, send event data to your security and analytics tools, and trigger account access remediation. > [card] [Example scripts](/cli/scripts) > > Try example scripts for automating administrative tasks. > [card] [Set up Credential Broker](/brokered-access) > > Give your team's CI/CD and other automated workflows short-lived access to secrets without stored tokens (public preview). # Build integrations with 1Password Source: https://www.1password.dev/get-started/build-integrations Build integrations, apps, and scripts with 1Password CLI, SDKs for Go, JavaScript, and Python, or a self-hosted Connect REST API. You can build integrations, applications, and scripts that programmatically interact with 1Password using two primary interfaces: [1Password CLI](/cli/get-started) and [1Password SDKs](/sdks). Both tools allow you to access and manage items, vaults, users, and secrets in your 1Password account. You can also deploy a self-hosted [Connect server](/connect) to access your items. ## Choose your interface ### 1Password CLI [1Password CLI](/cli) is a command-line tool that you can call from scripts, build tools, or any process that can run shell commands. 1Password CLI is the best fit when you want to: * Write shell scripts that access or manage your information in 1Password. * Access 1Password interactively from the terminal with biometric authentication. * Access 1Password from CI/CD pipelines or infrastructure-as-code workflows using automated authentication with service accounts. * Explore or test before committing to an SDK integration. ### 1Password SDKs [1Password SDKs](/sdks) provide native libraries for Go, JavaScript, and Python that let you interact with 1Password directly in your application code. 1Password SDKs are the best fit when you want to: * Build an application that needs to manage items, vaults, groups, or secrets at runtime. * Embed 1Password in an integration that other people will use, with convenient authentication through their 1Password desktop app. * Build a Go, JavaScript, or Python integration with the type safety, error handling, and conventions of your preferred language. ### Connect server [1Password Connect](/connect) allows you to deploy a private REST API in your own infrastructure that provides access to your 1Password items. After the initial fetch, secrets are served locally, reducing latency and dependency on external API availability. Connect has its own [Go](https://github.com/1Password/connect-sdk-go), [JavaScript](https://github.com/1Password/connect-sdk-js), and [Python](https://github.com/1Password/connect-sdk-python) SDKs that allow you to get vaults and manage items. ## Choose your authentication method ### 1Password desktop app Authenticate with prompts from the [1Password desktop app](https://1password.com/downloads/), so you can approve requests with Touch ID, Windows Hello, Linux system authentication, or your 1Password account password. **Best for:** Integrations that run locally, where a human is present to approve requests. Use the 1Password app to authenticate when you want minimal setup, human-in-the-loop approval, user-specific auditing, access to your full account including personal vaults, and the ability to authenticate with biometrics. **Works with:** [1Password CLI](/cli/app-integration), [1Password SDKs](/sdks/concepts#1password-desktop-app) ### Service accounts [Service accounts](/service-accounts) allow you to authenticate using a token scoped to specific [vaults](https://support.1password.com/1password-glossary/#vault) or [Environments](/environments) in your 1Password account, with no user interaction required. You can also control which actions a service account can perform in the vaults it can access. **Best for:** Integrations that run without a human present and following the [principle of least privilege](https://csrc.nist.gov/glossary/term/least_privilege) in your project. Use service accounts for automated access, shared building, headless authentication, or when you want to authenticate with a credential that isn't tied to an individual user. 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. **Works with:** [1Password CLI](/service-accounts/use-with-1password-cli), [1Password SDKs](/sdks/concepts#1password-service-account) ### Connect server token If you deploy a Connect server, you can use your Connect server token and host to authenticate 1Password CLI and certain pre-built integrations, like the [1Password Connect Ansible collection](/connect/ansible-collection). **Best for:** When you want to interact with your 1Password Connect deployment using other tools and integrations. **Works with:** [1Password CLI](/connect/cli), integrations that support Connect ## Compatibility | Authentication method | 1Password CLI | 1Password SDKs | Connect SDKs | | - | - | - | - | | **Desktop app** | Yes | Yes | No | | **Service account** | Yes | Yes | No | | **Connect server token** | Yes | No | Yes | ## Start building After you choose an interface and authentication method, learn how to get started with your preferred workflow: > [card] [Get started with 1Password CLI](/cli/get-started) > > Install the CLI and authenticate with the desktop app, a service account, or Connect server. > [card] [Get started with 1Password SDKs](/sdks) > > Install an SDK and authenticate with the desktop app or a service account. > [card] [Create a service account](/service-accounts/get-started) > > Set up token-based authentication for automated workflows. > [card] [Deploy a Connect server](/connect/get-started) > > Host a private REST API for secret access in your own infrastructure. ## Examples > [card] [1Password CLI scripts](/cli/scripts) > > Example shell scripts that use the CLI in real workflows. > [card] [1Password SDK tutorials](/sdks/tutorials) > > Step-by-step guides for building with the Go, JavaScript, and Python SDKs. # 1Password developer quickstart Source: https://www.1password.dev/get-started/developer-quickstart Install the 1Password app and CLI, create an Environment, and run your app with secrets from 1Password instead of plaintext .env files. About 10 minutes. ## Before you begin You can authenticate 1Password developer tools in two ways: * **Local development:** Use the 1Password desktop app for fast setup and human-in-the-loop approval with biometrics. * **Automation and production:** Use service accounts for automated workflows with least privilege access. This guide focuses on local development. For CI/CD, containers, and production workflows, see [Secure your deployments](/get-started/secure-deployment). > [!TIP] > > **Prefer to let your AI coding agent do the setup?** If you use Claude Code, Codex, or Cursor on Mac or Linux, install the 1Password app, then paste this into your agent: > > ```text wrap theme={null} > Fetch and follow the instructions at https://www.1password.dev/agent-setup/prompt.md to set up 1Password developer tools for me. > ``` > > The agent sets up 1Password developer tools and checks that everything works. If a required setting in the app is turned off, the agent tells you where to find it. Windows and AI chats in a web browser aren't supported yet. ## Step 1: Install the 1Password app If you haven't already, [sign up for a 1Password account](https://1password.com/pricing/password-manager). Then install 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux). After you install the app: 1. Open the 1Password app and select your account or collection at the top of the sidebar. 2. Navigate to **Settings** > **Security**. 3. Turn on the setting to unlock the app using [Touch ID](https://support.1password.com/touch-id-mac/), [Windows Hello](https://support.1password.com/windows-hello/), or [Linux system authentication](https://support.1password.com/system-authentication-linux/). This allows you to authenticate most developer tools with your fingerprint. ## Step 2: Install 1Password CLI 1Password CLI (`op`) lets you access secrets and manage your account from your terminal and scripts. It's the fastest way to start experimenting with 1Password developer tools. To install [1Password CLI](/cli), use one of the following package managers, or [download the latest release](https://app-updates.agilebits.com/product_history/CLI2). > [tab] homebrew > > ```shell theme={null} > brew install 1password-cli > ``` > [tab] winget > > ```shell theme={null} > winget install 1password-cli > ``` > [!TIP] > > See the [full CLI installation guide](/cli/get-started) for requirements and additional Windows, Linux, and manual installation options. Then turn on the app integration to sign in with the accounts you've added to the app and authenticate commands using your fingerprint. 1. Open the 1Password app and select your account or collection at the top of the sidebar. 2. Navigate to **Settings** > [**Developer**](onepassword://settings/developers). 3. Select **Integrate with 1Password CLI**. Enter any 1Password CLI command to trigger the authentication prompt to sign in. For example, `op vault list` lists all the vaults in the authenticated account. ```shell theme={null} op vault list ``` ## Step 3: Create an Environment [Environments](/environments) are like vaults for your developer credentials. You can manage your project's secrets together in an Environment, then securely load each set of secrets directly from 1Password when you need them. Start by creating an Environment for a specific project or development context, like `iOS App Staging`. 1. In the 1Password app, select **Developer** in the sidebar, then select **Environments**. 2. Select **New environment**, enter a name, and select **Save**. 3. Open the Environment, then select **Import .env file** to import project secrets from an existing environment file or **New secret** to add secrets manually. After you create the Environment, you can select **Manage environment** > **Manage access** to share it with other people on your team. ## Step 4: Load your first secret You can access the project secrets stored in an Environment directly from 1Password using a locally mounted `.env` file or 1Password CLI. > [tab] Local .env file (Mac, Linux) > > A [locally mounted `.env` file](/environments/local-env-file) lets you access your Environment from tools that expect an environment file on disk. The contents of this file aren't tracked by Git or stored on disk, and are only available at the moment you access it. > > 1. In the 1Password app, go to **Developer** > **Environments** and open the Environment you created [in step 3](#step-3-create-an-environment). > 2. Under "Connect to", select the **Connect** button next to "Local .env file". > 3. Select **Choose file path** and choose the path on your device where you want to create your local `.env` file, then select **Mount .env file**. > > To confirm you can access your secrets, open your terminal and navigate to the directory where your local `.env` file is saved. Then run the following command with the name of your file. > > ```shell theme={null} > cat .env > ``` > > ![An authorization prompt is shown when you try to access a mounted \`.env\` file through your local terminal.](https://mintcdn.com/ab-634991b8/P8nNS8jHoY1I7R9r/static/img/environments-local-env-auth.png?fit=max\&auto=format\&n=P8nNS8jHoY1I7R9r\&q=85\&s=f0c41a08c8aa25779c162c775424569b) > [tab] 1Password CLI (all platforms) > > Use [`op run`](/cli/reference/commands/run) with the `--environment` flag to pass the secrets stored in an Environment to an application or script. 1Password CLI runs the command in a subprocess with your secrets available as environment variables only for the duration of the process. > > 1. In the 1Password app, go to **Developer** > **Environments** and open the Environment you created [in step 3](#step-3-create-an-environment). > 2. Select **Manage environment** > **Copy environment ID**. > 3. Run `op run --environment` with the Environment's ID, followed by `--` and the command you want to run. For example, to start an app: > ```shell theme={null} > op run --environment -- npm start > ``` > [!TIP] > > You can also [read project secrets from Environments in your code](/environments/read-environment-variables#sdks) using 1Password SDKs. ## Next steps You're set up. Pick what you're building next: > [card] [Set up SSH and Git](/ssh/get-started) > > Store SSH keys in 1Password and approve Git pushes and commit signing with your fingerprint. > [card] [Deploy with secrets](/get-started/secure-deployment) > > Load secrets into CI/CD, containers, and production apps. > [card] [Give your AI agent secrets](/get-started/secure-ai-access) > > Give coding agents project secrets without plaintext .env files on disk. > [card] [Build an integration](/get-started/build-integrations) > > Use the SDKs and APIs to work with 1Password from your code. # Get data and analytics for your 1Password account Source: https://www.1password.dev/get-started/get-data-and-analytics Generate 1Password account activity reports, stream audit and sign-in events to your SIEM with the Events API, and automate access remediation. Knowing how your team uses 1Password — who's signing in from where, what items are being accessed, and when admin settings change — is essential for security investigations, compliance reviews, and day-to-day account management. 1Password gives administrators several ways to access this activity data, from logs and reports available on 1Password.com to APIs that send events to your security and analytics tools or take action on user accounts. ## Choose your workflow Use the table below to decide which tools best suit your use case: | | [Audit log and reports](#audit-log-and-reports) | [1Password Events API](#1password-events-api) | [1Password Users API](#1password-users-api) | | - | - | - | - | | **Best for** | Reviewing activity and exporting reports on 1Password.com | Sending 1Password activity to a SIEM or analytics platform | Letting a SOAR or security automation platform act on user accounts | | **What you get** | Audit log, sign-in attempts, user adoption, device, team, usage, and overview reports | Audit events, item usage events, and sign-in attempts | List users, get user details, suspend users, and reactivate users | | **When to use it** | You want quick access to account information and CSV exports without building an integration | You want centralized dashboards, alerts, correlation, or longer-term retention in your own tooling | You want an approved integration to take user access remediation actions in 1Password | | **Setup** | Just sign in to your 1Password account — no integration required | Create an Events Reporting integration and issue a bearer token | Create an OAuth application and generate client credentials | ## Audit log and reports Gain visibility into the last 12 months of activities directly in your team's 1Password Business account without needing to set up an integration. ### Use the audit log You can access the audit log from the [audit log](https://start.1password.com/audit-log) section in your 1Password account. [Use the audit log](https://support.1password.com/activity-log/) to: * Search and filter sign-in attempts, item usage, and admin actions. * Track actions across users, groups, vaults, devices, service accounts, reports, and more to see who did what and when. * Export the filtered results as a CSV for auditors or further analysis. ### Create reports Generate reports from the [Reports](https://start.1password.com/reports) section in your 1Password account. You can [create reports](https://support.1password.com/reports/) to help you: * Monitor security issues in your account, like data breaches involving team members or company email addresses and plaintext developer secrets found on your team's local disks. * See active users, item access patterns, and sign-in attempts across your account. * Get detailed usage information for individual team members, service accounts, and vaults, including which items were accessed and when. * Navigate compliance reviews, access audits, and offboarding checks. > [card] [Use the audit log](https://support.1password.com/activity-log/) > > Search activity in your 1Password Business account and export results as CSV. > [card] [Create reports](https://support.1password.com/reports/) > > Generate reports for users, service accounts, vault activity, item usage, developer secrets discovery, and more. ## 1Password Events API Use the [1Password Events API](/events-api) to retrieve activity from your 1Password Business account and send it to your security and analytics tools, so it can be reviewed and correlated alongside the rest of your environment. The Events API includes detailed information about the following types of account activity: * **[Audit events](/events-api/audit-events)** for actions performed by team members involving vaults, groups, users, permissions, SSO configuration, service accounts, and more. * **[Item usage](/events-api/item-usage-actions)** in shared vaults, like when and where items are viewed, copied, filled, revealed, exported, shared, or edited. * **[Sign-in attempts](/events-api/reference/sign-in-attempt)** for successful and failed sign-ins, including details about the client app, IP address, geolocation, and the reason for any failures (such as bad credentials, failed MFA, or firewall blocks). It's easy to connect your 1Password account to your security information event management (SIEM) platform using a [pre-built connector](https://support.1password.com/events-reporting/), like the [Splunk](https://support.1password.com/events-reporting-splunk/) or [Elastic](https://support.1password.com/events-reporting-elastic/) integrations. Or build your own custom connector using the [Events API reference](/events-api/reference). > [!NOTE] > > The Events API can access the last 120 days of account activity. For events older than 120 days, you can [use the audit log](#use-the-audit-log) in your 1Password account. > [card] [Get started with the Events API](/events-api/get-started) > > Set up an Events Reporting integration in your 1Password Business account. > [card] [Pre-built SIEM connectors](https://support.1password.com/events-reporting/) > > See which platforms have built-in 1Password integrations. > [card] [Audit events catalog](/events-api/audit-events) > > Every audit action and object type the API can return, organized by category. > [card] [Item usage actions](/events-api/item-usage-actions) > > What each item usage action means and which client triggered it. > [card] [Events API reference](/events-api/reference) > > Endpoint details for audit events, item usage, and sign-in attempts. ## 1Password Users API Use the [1Password Users API](/users-api) to create an integration between your 1Password Business account and your preferred security automation platform. Then take actions on user accounts in response to events reporting data or SIEM-detected events, such as automatically suspending a user directly in 1Password when suspicious sign-in events are flagged. With the Users API, you can: * **[List users](/users-api/list-users)** in your account, optionally filtered to active or suspended users, to build inventories or pick targets for action. * **[Get a user](/users-api/get-user)** by ID to retrieve their display name, email, and current state (active or suspended). * **[Suspend a user](/users-api/suspend-user)** to remove their 1Password account access during offboarding or incident response. * **[Reactivate a user](/users-api/reactivate-user)** after the issue is resolved or onboarding is completed. It's easy to connect your 1Password account to your security automation platforms using a [pre-built partner integration](https://support.1password.com/security-automation/). Or build a custom integration using the [Users API reference](/users-api/reference). The Users API uses the [OAuth 2.0 client credentials flow](/users-api/authorization) with [scoped permissions](/users-api/authorization#scopes), so each integration only has the access it needs. Access tokens are short-lived and can be [revoked](/users-api/revoke-access-token) at any time. > [card] [Get started with the Users API](/users-api/get-started) > > Create an OAuth application and make your first request. > [card] [Pre-built partner integrations](https://support.1password.com/security-automation/) > > Security automation platforms that already work with the Users API. > [card] [Users API conventions](/users-api/conventions) > > Endpoint paths, request headers, pagination, rate limits, and errors. > [card] [Users API reference](/users-api/reference) > > Endpoint details for OAuth tokens and user actions. # Programmatically manage your 1Password organization Source: https://www.1password.dev/get-started/manage-organization Provision users, organize groups, and control vault access in 1Password Business with the CLI, SDKs, and Users API. 1Password offers three tools to help you automate administrative tasks: [1Password CLI](#1password-cli), [1Password SDKs](#1password-sdks), and the [1Password Users API](#1password-users-api). ## Choose your workflow Use the following table to decide which tool best suits your use case: | | [1Password CLI](#1password-cli) | [1Password SDKs](#1password-sdks) | [1Password Users API](#1password-users-api) | | - | - | - | - | | **Best for** | Shell scripts, CI/CD pipelines, and infrastructure-as-code workflows | Integrating directly into applications or services built in Go, JavaScript, or Python | Connecting your 1Password account to a security automation platform for incident response and access remediation | | **User management** | Provision, confirm, suspend, reactivate, edit, delete, list, and get users | Not yet directly supported | List, get, suspend, and reactivate users | | **Group management** | Create, edit, delete, get, and list groups; add and remove members; manage groups' access in vaults | Get groups and manage groups' access in vaults | Not supported | | **Vault management** | Create, edit, delete, get, and list vaults | Create, edit, delete, get, and list vaults | Not supported | | **Vault permissions** | Grant and revoke user and group access to vaults | Grant and revoke group access to vaults | Not supported | | **Item management** | Create, get, edit, delete, list, move, and share items | Create, get, edit, delete, list, and share items | Not supported | ## 1Password CLI [1Password CLI](/cli) lets you manage your 1Password account from the command line. You can call 1Password CLI commands from shell scripts, CI/CD pipelines, or any process that can run shell commands. Use the CLI when you want to: * Write shell scripts that automate repetitive tasks, like onboarding a batch of users or rotating group memberships. * Run one-off administrative tasks from the terminal, like provisioning a new user or creating a vault. * Run targeted operations on individual user accounts or generate reports about users from the terminal. * Automate user and group provisioning as part of your infrastructure workflows. For example, to provision a new user and add them to a group: ```shell theme={null} op user provision --name "Wendy Appleseed" --email wendy.appleseed@agilebits.com op group user grant --group Engineering --user wendy.appleseed@agilebits.com ``` To create a vault and grant a group access to view the items in it: ```shell theme={null} op vault create "New Project" op vault group grant --vault "New Project" --group Engineering --permissions view_items ``` > [card] [Get started with 1Password CLI](/cli/get-started) > > Install the CLI and sign in to your account. > [card] [CLI command reference](/cli/reference) > > Full reference for all CLI commands and flags. ### Example scripts > [card] [Item management](https://github.com/1Password/solutions/tree/main/1password/item-management) > > Bulk create, read, update, or delete items and related automation examples built on `op item`. > [card] [Scripted provisioning](https://github.com/1Password/solutions/tree/main/1password/scripted-provisioning) > > Invite, suspend, reactivate, or delete users from a CSV using the CLI provisioning workflow. > [card] [Reporting](https://github.com/1Password/solutions/tree/main/1password/reporting) > > Generate CSV reports of vault access, permissions, and contents using CLI scripts. > [card] [User management](https://github.com/1Password/solutions/tree/main/1password/user-management) > > Identify users who have not signed in for a chosen number of days for follow-up or bulk actions. ## 1Password SDKs [1Password SDKs](/sdks) provide native libraries for Go, JavaScript, and Python that let you manage 1Password programmatically from your application code. Use the SDKs when you want to: * Build custom admin tooling or internal dashboards that manage groups, vaults, and items. * Embed operations like group provisioning into existing applications and workflows. * Automate group, vault, and item management as part of a larger programmatic workflow, with native error handling in Go, JavaScript, or Python. > [card] [Get started with 1Password SDKs](/sdks) > > Install an SDK and authenticate with the desktop app or a service account. > [card] [Supported functionality](/sdks/functionality) > > See what's currently supported and what's in development. ### Example projects > [card] [Inventory tracker web app](https://github.com/1Password/solutions/tree/main/1password/onepassword_sdks/demo-inventory-tracker-webapp) > > Node.js sample that stores inventory in 1Password items and runs with `op run` and Docker Compose. > [card] [Okta user onboarding script](https://github.com/1Password/solutions/tree/main/1password/onepassword_sdks/demo-share-okta-user-script) > > Python utility that creates an Okta user, saves credentials in 1Password, and generates a secure item share link. > [card] [Encrypted vault backup app](https://github.com/1Password/solutions/tree/main/1password/onepassword_sdks/demo-vault-backup-webapp) > > Web app to back up and restore vaults with encryption, using the JS SDK and CLI for vault operations the SDK does not cover. > [card] [Vault migration web app](https://github.com/1Password/solutions/tree/main/1password/onepassword_sdks/demo-vault-migration-webapp) > > Self-hosted tool to migrate vaults between accounts with batch SDK operations, progress streaming, and downloadable logs. ## 1Password Users API Use the [1Password Users API](/users-api) to suspend, reactivate, or look up users programmatically through a server-to-server OAuth integration. The API allows you to connect your 1Password account to a security automation platform, so events flagged by your security tools can trigger user access remediation actions in 1Password. Use the Users API when you want to: * Connect your 1Password account to a security automation platform using a [pre-built partner integration](https://support.1password.com/security-automation/) or a custom integration. * Automatically suspend a user in 1Password in response to events from your SIEM or other detection tools. * Reactivate a user after an incident is resolved. * Programmatically list users or look up a single user's state to drive other workflows in your security tooling. For example, after [requesting an access token](/users-api/request-access-token), you can suspend a user in response to a security event: ```shell theme={null} curl --request POST \ --url "https://api.1password.com/v1/accounts//users/:suspend" \ --header "Authorization: Bearer " \ --header "User-Agent: /" ``` Or list all currently suspended users in the account: ```shell theme={null} curl --request GET \ --url "https://api.1password.com/v1/accounts//users?filter=user.isSuspended()" \ --header "Authorization: Bearer " \ --header "User-Agent: /" ``` > [card] [Get started with the Users API](/users-api/get-started) > > Create an OAuth application and make your first request. > [card] [Users API reference](/users-api/reference) > > Endpoint details for OAuth tokens and user actions. ## Authentication options 1Password CLI and SDKs support authentication through the [1Password desktop app](#1password-desktop-app) or a [service account](#1password-service-account). The Users API authenticates through [OAuth 2.0 client credentials](#oauth-2-0-authorization). ### 1Password desktop app Authenticate the CLI or an SDK locally in the same way you unlock your 1Password desktop app, like with biometrics or your 1Password account password. Best for interactive use where a human must be present to approve requests. > [!TIP] > > Use the 1Password desktop app when managing users' and groups' permissions in vaults. Service accounts can only manage access to vaults created by the service account. ### 1Password service account Authenticate the CLI or an SDK using a [service account](/service-accounts) token scoped to specific vaults, with no user interaction required. Best for automated workflows like CI/CD pipelines, scheduled scripts, or any process that runs without a human present. 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. ### OAuth 2.0 authorization Authenticate Users API requests using an [OAuth 2.0 client credentials flow](/users-api/authorization) with [scoped permissions](/users-api/authorization#scopes), so each integration only has the access it needs. Access tokens are short-lived and can be [revoked](/users-api/revoke-access-token) at any time. Best for server-to-server integrations between your 1Password account and an external system, like a security automation platform. # 1Password partner quickstart Source: https://www.1password.dev/get-started/partner-quickstart Integrate 1Password as a partner: billing with the Partnership API, user lifecycle with the Users API, and the Save in 1Password button for your website. 1Password partners are third-party organizations who integrate 1Password into their products or services to manage things like account billing, user lifecycle automation, and website autofill integration. > [!TIP] > > Learn how to join the [1Password Partner Program](https://1password.com/partners). ## Choose your path Start with the use case that matches your needs: > [card] [Billing integration](#billing-integration) > > Provision and manage billing for individual and family accounts. > [card] [User automation](#user-automation) > > Automate access control and user lifecycle for enterprise accounts. > [card] [Web experience](#web-experience) > > Let users save sign-in details and improve autofill on your site. ## Billing integration Use the [1Password Partnership API](/partnership-api/reference/) to manage partner billing accounts for individual and family plans. > [!TIP] > > Integrating 1Password account billing with third-party products and services is only available to registered partners. To request access, visit the [1Password Partner Program](https://1password.com/partners) or [contact the Partnerships team](mailto:partners@1password.com). Typical flow: 1. Authenticate using your partner-issued bearer token. 2. Create a billing account for a customer. 3. Generate a partner billing link using the activation token. 4. Manage the customer's account lifecycle (retrieve the account status, update the billing end date, or delete the account). > [card] [Partnership API reference](/partnership-api/reference) > > Endpoints, request formats, and billing link details. ## User automation Use the [1Password Users API](/users-api/) to automate access control and user lifecycle management for enterprise accounts as part of SOC or SIEM workflows. Typical flow: 1. Create an OAuth application in 1Password. 2. Request an access token using client credentials. 3. Call user endpoints (list, suspend, reactivate). > [card] [Get started with the 1Password Users API](/users-api/get-started) > [card] [Users API reference](/users-api/reference) ## Web experience ### Save in 1Password button Use the [Save in 1Password button](/web/add-1password-button-website) to allow visitors to your website to save sign-in details, credit cards, crypto wallets, or API keys (if you register as a partner) to their 1Password account in one step. 1. Install the [`@1password/save-button`](https://www.npmjs.com/package/@1password/save-button) package and import it in your page. 2. Build a **save request** with the fields your item type needs. 3. Render the custom element with the required attributes so 1Password can offer to save when appropriate. > [card] [Add the Save in 1Password button](/web/add-1password-button-website) > > Install the package, build save requests, and wire the button on your site. ### Design webpages that work well with 1Password Good form structure and semantics help the 1Password browser extension fill, save, and update passwords reliably. Follow [web best practices](/web/compatible-website-design): logical forms, correct `autocomplete` values, clear password-change flows, and optional `data-1p-ignore` where a field should be ignored. > [card] [Design your website for 1Password](/web/compatible-website-design) > > Forms, password rules, passkeys, and patterns that improve filling and saving. ## Next steps Explore these guides when you are ready to go deeper on a specific integration path: > [card] [Partnership API reference](/partnership-api/reference) > > Full billing API details, environments, and customer link formats. > [card] [Users API overview](/users-api/) > > Requirements, preview status, and links to authorization and endpoints. > [card] [Save in 1Password button](/web/add-1password-button-website) > > NPM package, save requests, and embedding the button. > [card] [Compatible website design](/web/compatible-website-design) > > Make sign-in and account flows work smoothly with 1Password in the browser. # Secure secrets for AI agents and tools Source: https://www.1password.dev/get-started/secure-ai-access Use 1Password to secure the API keys that power your AI tools and provide credentials to AI agents, with nothing exposed in plaintext, mcp.json, or LLM context. AI tools and agents are increasingly being used for tasks that require credentials like passwords, API tokens, and one-time password codes to complete. When you supply these credentials in plaintext, like by pasting a secret directly into an agentic browser when prompted to sign in, your secrets can leak into the LLM context. Storing API tokens for AI services in plaintext creates another risk. Hardcoded tokens in `.env` files, `mcp.json` files, and config files can be committed to source control or accidentally shared, allowing anyone who finds them to access your accounts. 1Password gives you secure ways to provide secrets to AI tools and agents. Store your credentials in 1Password, then load them into your AI workflows without exposing them in plaintext or allowing agents to directly handle your secrets. > [card] [The security principles guiding 1Password's approach to AI](https://1password.com/blog/security-principles-guiding-1passwords-approach-to-ai) > > How 1Password applies ideas like secrets staying secret, deterministic authorization, auditability, and least privilege when building and integrating AI. ## Secure AI API keys If you use AI services like OpenAI, Anthropic, or Google in your applications or scripts, you may have plaintext API keys stored in environment variables, `.env` files, or shell profiles. [1Password Environments](/environments) allow you to manage your API keys and other project secrets together in 1Password, then securely load them into your code when you need them. To get started: 1. [Create an Environment](/environments) in 1Password and add the API keys and other secrets your AI workflow needs. If you have an existing `.env` file for your project, you can import it. 2. [Create a locally mounted `.env` file](/environments/local-env-file) for the Environment. The contents of this file aren't tracked by Git or stored on disk, and are only available at the moment you access it. 3. [Verify you can access your secrets](/environments/local-env-file#verify-with-your-terminal) and make sure they work with your tools. After you set up the Environment, remove any plaintext API keys stored in your local `.env` files or shell profiles (`~/.zshrc`, `~/.bashrc`). > [!TIP] > > Local `.env` files are currently only supported in 1Password for Mac and Linux. You can also [programmatically read project secrets](/environments/read-environment-variables) from Environments on any platform using the latest beta version of the CLI or SDKs. ### Add validation for AI-assisted coding If you use AI coding agents in tools like Cursor, GitHub Copilot, Claude Code, or Windsurf, you can use [1Password hooks](/environments/agent-hook-validate) to validate that your locally mounted `.env` files are properly configured before the agent executes shell commands. If any required `.env` files are missing or invalid, the hook prevents the agent from executing and the agent provides instructions for how to fix the issue. In [Cursor](/environments/cursor-plugin), the hook is bundled in a plugin that installs the validation hook, an Environments agent skill, and MCP server configuration together. > [card] [Create and manage Environments](/environments) > > Store your AI API keys in an Environment. > [card] [Access secrets through local .env files](/environments/local-env-file) > > Sync an Environment to a local `.env` file. > [card] [Install the validation hook](/environments/agent-hook-validate) > > Validate locally mounted `.env` files before your agent runs shell commands. ## Secure MCP server config files MCP server configurations (like `mcp.json`) often include API tokens and other credentials as environment variables. Yours might look something like this: ``` { "mcpServers": { "unleash": { "command": "npx", "args": ["-y", "@unleash/mcp@latest", "--log-level", "error"], "env": { "UNLEASH_BASE_URL": "https://unleash_your-instance.com", "UNLEASH_PAT": "unleash_your-secret-token" } } } } ``` Instead of exposing your secrets in plaintext, you can store them in 1Password, then use an [Environment](/environments) to securely load the secrets as environment variables at runtime. To get started: 1. In 1Password, [create an Environment](/environments) and add the secrets your MCP server needs. 2. Open the Environment you just created and select **Manage environment** > **Copy environment ID**. 3. Update your MCP config file to use `op` as the command, with `run --environment` in `args` wrapping your original MCP server command. Remove any hardcoded secrets from the `env` block: ``` { "mcpServers": { "unleash": { "command": "op", "args": [ "run", "--environment", "", "--", "npx", "-y", "@unleash/mcp@latest", "--log-level", "error" ] } } } ``` When your MCP host starts the server, it runs 1Password CLI, which authenticates with 1Password, resolves the secrets from your Environment, and injects them into the process before handing off to `npx`. The MCP server receives the real secret values without your secrets ever being stored in your config file. With this approach, there's no need to re-declare your secrets in the env block. Because `op run` injects the secrets directly into the process environment, they're already available to the MCP server. If you need to pass additional non-secret configuration values alongside your command, you can still use the `env` block for those. > [!NOTE] > > Some MCP hosts (like Claude Desktop on Mac) launch as GUI apps and may not inherit your shell's `$PATH`. If `op` can't be found, use its full path as the command value instead. For example, `/usr/local/bin/op` or `/opt/homebrew/bin/op`. You can find the path by running `which op` in your terminal. You can also load your API tokens from 1Password at runtime using `op run` and [secret references](/cli/secret-references). ## Use the 1Password Environments MCP Server The [1Password Environments MCP Server](/environments/mcp-server) lets MCP clients like [Codex](https://help.openai.com/en/articles/11096431-openai-codex-cli-getting-started), [Cursor](https://cursor.com/home), and [Kiro](https://kiro.dev/) create and manage your [1Password Environments](/environments) directly, with a secure 1Password authorization prompt required for every action. The MCP server doesn't read or return secrets to the AI agent. Your secrets stay in 1Password and are only accessed by authorized processes, so your MCP client can act on your secrets without ever seeing them. You can use the MCP server from your client to create Environments, list secret names, handle local `.env` files within authenticated workflows, and manage secrets within your Environments. > [card] [Set up the 1Password Environments MCP Server](/environments/mcp-server) > > Connect your MCP client to 1Password to securely create and manage Environments. > [card] [Install the 1Password Developer Tools plugin for Claude Code](/environments/claude-plugin) > > Add MCP configuration and the Environments agent skill to Claude Code. > [card] [Install the 1Password Developer Tools plugin for Cursor](/environments/cursor-plugin) > > Add MCP configuration, `.env` file validation, and the Environments agent skill to Cursor. ## Keep secrets out of agent context with 1Password and NVIDIA OpenShell (beta) [1Password for NVIDIA OpenShell](/environments/nvidia-openshell) (beta) lets a coding agent use the credentials it needs without those credentials entering the agent's context. You connect a [1Password Environment](/environments) to an OpenShell gateway, then attach it to the sandbox where the agent runs. Inside the sandbox, the agent only ever works with placeholders. When it sends a request to a host you've approved, the gateway replaces the placeholders with the real secrets outside the sandbox and forwards the request. Requests to any other host don't receive the credential. You choose how long OpenShell keeps custody of the secrets. After that window expires, the sandbox keeps running but the agent no longer gets access. > [card] [Set up 1Password for NVIDIA OpenShell](/environments/nvidia-openshell) > > Connect an Environment to an OpenShell gateway and give sandboxed agents scoped, time-limited access to your secrets. ## Let your personal agent sign in with 1Password for Agents [1Password for Agents](https://support.1password.com/1password-for-agents/) lets your personal agent sign in to websites, so you don't have to share your passwords with the agent. When the agent needs to sign in, 1Password shows you which agent is asking and suggests a login for the website. After you approve the request, 1Password fills your username, password, and one-time password directly into the sign-in form in the agent's browser. > [card] [Get started with 1Password for Agents](https://support.1password.com/1password-for-agents/) > > Connect 1Password to a supported agent and approve sign-in requests. ## Authenticate AI command-line tools with biometrics You can set up [1Password Shell Plugins](/cli/shell-plugins) to authenticate AI command-line tools like [OpenAI CLI](/cli/shell-plugins/openai) or [Claude Code CLI](/cli/shell-plugins/claude-code) using the 1Password desktop app, eliminating the need to store plaintext API keys in your shell profile or environment. When you use a shell plugin, you authenticate the underlying CLI in the same way you unlock the 1Password desktop app, like with Touch ID, Apple Watch, or a Linux system authentication option, which enables convenient human-in-the-loop approval. Shell plugins let you [configure different default credentials in different directories](/cli/shell-plugins/environments), so you can automatically switch between secrets for different projects without needing to take any manual action. ## Next steps > [card] [Build integrations](/get-started/build-integrations) > > Use the SDKs and APIs to build integrations and scripts that work with your 1Password account. ## Get help To get help, join the discussion in our [Developer community](https://www.1password.community/category/discuss/discussions/developers) or join our [Developer Slack workspace](https://developer.1password.com/joinslack). # Secure CI/CD and deployments with 1Password Source: https://www.1password.dev/get-started/secure-deployment Use 1Password to load secrets into CI/CD pipelines, containers, and production apps at runtime — no plaintext credentials in your configs. Hardcoded secrets in CI/CD pipelines, container images, infrastructure configs, and production environments are a leading cause of credential exposure at scale. For example, if a secret is hardcoded in a `.github/workflows` or `Jenkinsfile`, anyone with access to the repository can see it. A single leaked token can compromise your entire deployment chain, and historically rotating exposed secrets required extensive code and configuration updates. 1Password developer tools eliminate secret sprawl across your deployment infrastructure and make rotating secrets simple. Store your credentials in 1Password, then securely load them into your CI/CD pipelines, containers, and production applications at runtime without exposing anything in plaintext in your source control or configuration files. Rotate your secrets by updating them in 1Password. > [!TIP] > > **Not sure where to start?** Use the [configuration tables](#choose-your-configuration) to find the best tool and authentication method for your specific use case. ## Environments You can use [1Password Environments](/environments) to store and manage the complete set of secrets for each stage of your deployment infrastructure (for example staging, production, or per-application) then load them all at once at runtime. Because Environments map directly to how applications consume secrets from the environment, they fit naturally into any deployment workflow that uses environment variables or `.env` files. You can use Environments across your entire deployment infrastructure. For example: * **CI/CD pipelines**: Use 1Password CLI to [load the secrets stored in Environments](/environments/read-environment-variables#cli) into any CI/CD platform that supports shell commands, so your pipeline runs with the right set of secrets for each deployment stage without storing anything in plaintext. * **Docker containers and Compose**: Use 1Password SDKs to [fetch secrets from an Environment](/environments/read-environment-variables#sdks) within your container's application code, keeping credentials out of your Dockerfile and image layers, or use `op run --environment` to [load an Environment directly into a Docker Compose process](/environments/read-environment-variables#cli). * **Kubernetes**: For application containers, use 1Password SDKs to [fetch secrets from an Environment](/environments/read-environment-variables#sdks) in your code, or use 1Password CLI in an [init container](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/) to load secrets before your main container starts. * **Server-side applications**: Use 1Password SDKs to [read secrets from an Environment in your application](/environments/read-environment-variables#sdks), with native language integration in Go, JavaScript, or Python. * **AWS deployments**: [Sync secrets from an Environment directly to AWS Secrets Manager](/environments/aws-secrets-manager), centralizing management in 1Password while using native AWS integrations at runtime. > [card] [Get started with Environments](/environments) > > Create and manage Environments. > [card] [Programmatically read Environments](/environments/read-environment-variables) > > Load secrets from Environments with 1Password CLI or SDKs. > [card] [Sync secrets to AWS Secrets Manager](/environments/aws-secrets-manager) > > Centralize secrets management and simplify your AWS Secrets Manager workflow. > [!NOTE] > > You can also replace hardcoded secrets in your deployment configs using [secret references](/cli/secret-references). ## Pre-built integrations 1Password provides pre-built integrations for the most popular CI/CD platforms, container orchestration tools, and Infrastructure as Code tools. Each integration uses [secret references](/cli/secret-references) to securely load secrets from 1Password into your pipelines and workflows. Secret references are URIs that point to the names or IDs of the specific vault, item, section, and field where an individual secret is stored in your 1Password account. ``` op:////[section-name/] ``` When a pipeline step runs, the integration resolves each reference and makes the actual secrets available as environment variables or step outputs. Sensitive values are automatically masked in build logs. ### GitHub Actions The [Load Secrets from 1Password GitHub Action](https://github.com/marketplace/actions/load-secrets-from-1password) adds a step to your workflow that resolves secret references and exposes them as environment variables or step outputs. To get started: 1. [Create a service account](/service-accounts/get-started) with access to the vaults your pipeline needs. 2. Store the service account token as a [GitHub repository secret](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets) (for example, `OP_SERVICE_ACCOUNT_TOKEN`). 3. Add the `1password/load-secrets-action/configure` step to set the token. 4. Add the `1password/load-secrets-action` step to set your environment variables to secret references. > [card] [GitHub Actions integration](/ci-cd/github-actions) > > Full setup guide with examples for service accounts and Connect server. ### CircleCI The [1Password Secrets orb](https://circleci.com/developer/orbs/orb/onepassword/secrets) provides two commands for loading secrets: `exec` (resolves secrets on demand with automatic masking) and `export` (makes secrets available to subsequent steps). To get started: 1. [Create a service account](/service-accounts/get-started) and set `OP_SERVICE_ACCOUNT_TOKEN` in your [CircleCI project settings.](https://circleci.com/docs/guides/about-circleci/introduction-to-the-circleci-web-app/#project-settings) 2. Add the `onepassword/secrets` orb to your [`config.yml`.](https://circleci.com/docs/guides/getting-started/config-intro/) 3. Install 1Password CLI using the [`1password/install-cli` command](/ci-cd/circle-ci#commands). 4. Use [`1password/exec`](/ci-cd/circle-ci#load-secrets-with-the-exec-command) or [`1password/export`](/ci-cd/circle-ci#load-secrets-with-the-export-command) to load secrets in your pipeline steps. > [card] [CircleCI integration](/ci-cd/circle-ci) > > Full setup guide with examples for service accounts and Connect server. ### Jenkins The [1Password Secrets plugin for Jenkins](https://plugins.jenkins.io/onepassword-secrets/) loads secrets into pipeline steps using the `withSecrets` function. Configuration can be set globally, per folder, or per job, with more specific levels overriding broader ones. To get started: 1. [Install the 1Password Secrets plugin for Jenkins](/ci-cd/jenkins#install-plugin). 2. [Install 1Password CLI](/ci-cd/jenkins#step-2-install-1password-cli) on the machine running your Jenkins pipelines. 3. [Configure the plugin](/ci-cd/jenkins#step-3-configure-the-1password-secrets-plugin-for-jenkins) with your service account token or Connect server credentials. 4. [Use the `withSecrets` function in your Jenkinsfile](/ci-cd/jenkins#use-with-a-jenkinsfile) to access secrets by reference. > [card] [Jenkins integration](/ci-cd/jenkins) > > Full setup guide with Declarative and Scripted Jenkinsfile examples. ### Kubernetes Use the [Kubernetes Operator](/k8s/operator) to sync 1Password items to native Kubernetes Secrets, the [Kubernetes Secrets Injector](/k8s/injector) to inject secrets directly into pods at runtime (avoiding the need to store them as Kubernetes Secret resources), or [`op inject`](/cli/secrets-config-files) to inject secret references in manifests when you deploy. > [card] [Kubernetes integrations](/k8s/integrations) > > Kubernetes Operator, Secrets Injector, and Helm chart integrations. ### Terraform, Pulumi, and Ansible 1Password integrates with popular Infrastructure as Code (IaC) tools so you can reference and manage secrets as part of your provisioning workflow without committing plaintext credentials to version control or hardcoding them in HCL or YAML. * **Terraform**: The [1Password Terraform provider](/terraform) lets you reference 1Password items as data sources or create and update items as managed resources. * **Pulumi**: The [1Password Pulumi provider](/pulumi) gives you programmatic access to 1Password items in TypeScript, Python, or Go. * **Pulumi ESC**: The Pulumi ESC integration lets you dynamically import secrets from 1Password into [Pulumi ESC environment definitions](https://www.pulumi.com/docs/esc/providers/1password-secrets/) for centralized configuration. * **Ansible**: The [1Password Ansible collection](/connect/ansible-collection) lets you interact with your 1Password Connect deployment from playbooks. It supports managing 1Password vaults and items through create, read, update, and delete operations. > [card] [Terraform provider](/terraform) > > Reference, create, or update 1Password items from Terraform. > [card] [Pulumi provider](/pulumi) > > Access vault items programmatically from Pulumi. > [card] [Ansible collection](/connect/ansible-collection) > > Manage 1Password vaults and items from playbooks with Connect. ## Choose your configuration Use the tables below to find the best tools and authentication method for your deployment use case. Every scenario includes a recommended [tool](#tool-options) and [authentication method](#authentication-options). ### Tool options * [1Password Environments](#environments): Best for managing project secrets in 1Password and eliminating plaintext secrets in code. * [Platform-specific integrations](/integrations): Load secrets using secret references into Ansible, AWS Secrets Manager, CircleCI, ECS Fargate, GitHub Actions, Jenkins, Kubernetes, Pulumi, and Terraform. * [Secret references](/cli/secret-references): Secure URIs that point to where a secret is stored in 1Password. * [1Password CLI](/cli/get-started): Best for quick testing, shell scripts, CI/CD pipelines, Infrastructure as Code, build tools and task runners. Use `op run --environment` to [load secrets from Environments](/environments/read-environment-variables#cli). * [1Password SDKs](/sdks): Best for native integrations with Go, Python, or JavaScript applications. Environments require the [latest SDK beta](/environments/read-environment-variables#sdks). * [1Password Connect Server](/connect/get-started): Deploy a private REST API within your own infrastructure. After the initial fetch, secrets are cached locally for subsequent requests, reducing latency and dependency on external API availability. ### Authentication options All deployment workflows require non-interactive authentication. 1Password offers two options depending on your infrastructure needs. * [1Password Service Accounts](/service-accounts/get-started) **(recommended)**: Authenticate using a token scoped to least privilege access in specific vaults or Environments, with no user interaction required. 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. * [Connect server token](/connect/get-started): Authenticate with your Connect server host and token. ### Scenarios #### CI/CD pipelines | Use case | Recommended tool | Authentication method | Why this approach | | - | - | - | - | | **GitHub Actions** | [GitHub integration](/ci-cd/github-actions) + [secret references](/cli/secret-references) | [Service account](/service-accounts/get-started) | The Load Secrets from 1Password GitHub Action loads referenced secrets and makes them available as environment variables or in the action's output. Secrets are automatically masked in logs. | | **CircleCI** | [CircleCI integration](/ci-cd/circle-ci) + [secret references](/cli/secret-references) | [Service account](/service-accounts/get-started) | The 1Password Secrets orb loads referenced secrets on demand using `exec` or makes them available as environment variables for subsequent steps. The `exec` command automatically masks secrets. | | **Jenkins** | [Jenkins integration](/ci-cd/jenkins) + [secret references](/cli/secret-references) | [Service account](/service-accounts/get-started) | The 1Password Secrets plugin for Jenkins uses the `withSecrets` function to load referenced secrets as environment variables. Supports global, folder, and job-level configuration scopes. | | **Other CI/CD platforms** (must support shell commands) | [CLI](/cli/get-started) + [Environments](/environments) | [Service account](/service-accounts/get-started) | Use Environments to pass project secrets into CI/CD pipelines that support shell commands. This allows you to organize and switch between secrets by development context. Service accounts provide automated authentication and can be scoped to only the Environments or vaults your pipeline needs access to for least privilege access. | #### Containers and orchestration | Use case | Recommended tool | Authentication method | Why this approach | | - | - | - | - | | **Docker containers** | [SDKs](/sdks) + [Environments](/environments) | [Service account](/service-accounts/get-started) | Use a 1Password SDK to read secrets from an Environment in your application, keeping credentials out of your Dockerfile, image layers, and `docker-compose.yml`. | | **Docker Compose** | [CLI/SDKs](/environments/read-environment-variables) + [Environments](/environments) | [Service account](/service-accounts/get-started) | Use 1Password SDKs to fetch secrets from an Environment within your container’s application code, keeping credentials out of your Dockerfile and image layers, or use 1Password CLI to load an Environment directly into a Docker Compose process. | | **Kubernetes** | [Kubernetes Operator](/k8s/operator) or [Secrets Injector](/k8s/injector) | [Service account](/service-accounts/get-started) | The 1Password Kubernetes Operator syncs 1Password items to native Kubernetes Secrets, while the Secrets Injector injects them directly into pods. | #### Infrastructure as Code | Use case | Recommended tool | Authentication method | Why this approach | | - | - | - | - | | **Terraform** | [Terraform provider](/terraform) + [secret references](/cli/secret-references) | [Service account](/service-accounts/get-started) | The 1Password Terraform provider lets you reference, create, or update 1Password items as part of your infrastructure provisioning. | | **Pulumi** | [Pulumi provider](/pulumi) + [secret references](/cli/secret-references) | [Service account](/service-accounts/get-started) | The 1Password Pulumi provider allows you to access and manage items in your 1Password vaults. | | **Pulumi ESC** | [Pulumi ESC integration](https://www.pulumi.com/docs/esc/providers/1password-secrets/) + [secret references](/cli/secret-references) | [Service account](/service-accounts/get-started) | The 1password-secrets provider allows you to dynamically import secrets from 1Password into your Pulumi ESC environment. | | **Ansible** | [Ansible collection](/connect/ansible-collection) + [secret references](/cli/secret-references) | [Connect server](/connect/get-started) | If you use a self-deployed Connect server, the 1Password Ansible collection lets you create, read, update, and delete vault items and vaults from playbooks. | | **Other IaC tools** (must support shell commands) | [CLI](/environments/read-environment-variables#cli) + [Environments](/environments) | [Service account](/service-accounts/get-started) | Pass sets of secrets from Environments using 1Password CLI. Environments allow you to easily manage and share project secrets from 1Password. Switch to secrets for a different development context by pointing to a different Environment ID. | #### Production applications | Use case | Recommended tool | Authentication method | Why this approach | | - | - | - | - | | **Server-side applications** (Go, JavaScript, Python) | [SDKs](/sdks) + [Environments](/environments) | [Service account](/service-accounts/get-started) | 1Password SDKs provide native language integration with proper error handling and type safety. Environments are best for managing and switching between sets of project secrets for different development contexts. Service accounts are best for headless authentication. | | **Self-hosted infrastructure** | [Connect SDK](/connect) + [secret references](/cli/secret-references) | [Connect server](/connect/get-started) | 1Password Connect server hosts a private REST API in your own infrastructure, enabling unlimited re-requests and reducing dependency on external API availability. | | **AWS ECS Fargate** | [ECS Fargate integration](/connect/aws-ecs-fargate) + [secret references](/cli/secret-references) | [Connect server](/connect/get-started) | The 1Password ECS Fargate integration uses a sidecar container running 1Password Connect to inject secrets into your task definitions at runtime. | | **AWS deployments** | [Environments](/environments) + [AWS Secrets Manager sync](/environments/aws-secrets-manager) | [Service account](/service-accounts/get-started) | Sync secrets from 1Password Environments directly to AWS Secrets Manager, centralizing management in 1Password and simplifying your AWS workflow. | ## Next steps Choose what you want to do next: > [card] [Secure AI access](/get-started/secure-ai-access) > > Give AI agents and tools credentials without exposing them in prompts, LLM context, or config files. > [card] [Build integrations](/get-started/build-integrations) > > Build integrations and scripts that can securely interact with your 1Password account. ## Get help To get help, join the discussion in our [Developer community](https://www.1password.community/category/discuss/discussions/developers) or join our [Developer Slack workspace](https://developer.1password.com/joinslack). # Secure local development with 1Password Source: https://www.1password.dev/get-started/secure-developer-secrets Store secrets in 1Password and load them into your terminal, IDE, and local projects, without exposing them in plaintext. Hardcoded plaintext secrets in source code, config files, environment files, and shell profiles are one of the most common causes of credential leaks. 1Password developer tools make it easy to access your secrets where you need them without exposing them in plaintext. Store your credentials in 1Password, then securely load them in your terminal, IDE, app, CI/CD pipelines, or anywhere else in your code. Before you start, install the 1Password app and [1Password CLI](/cli/get-started). [Video on how 1Password keeps developer secrets off disk.](https://www.youtube.com/embed/hUY1cTktGKg) > [!TIP] > > **Want to get started quickly?** [Create an Environment](/environments#requirements) for a set of project secrets, then [create a local `.env` file](/environments/local-env-file#mount-your-env-file) to access them directly from 1Password where you need them. Or use the [configuration tables](#choose-your-configuration) to find the best tool and authentication method for your specific use case. ## Environments ![An authorization prompt is shown when you try to access a mounted \`.env\` file through your local terminal.](https://mintcdn.com/ab-634991b8/P8nNS8jHoY1I7R9r/static/img/environments-local-env-auth.png?fit=max\&auto=format\&n=P8nNS8jHoY1I7R9r\&q=85\&s=f0c41a08c8aa25779c162c775424569b) [1Password Environments](/environments) function like a vault for your developer secrets. You can organize your secrets in 1Password Environments for each project or development context, then securely access them when you need them without exposing anything in plaintext. Switching between different sets of secrets for different contexts is as simple as pointing to a different Environment ID. You can use Environments to load sets of secrets into any context where you typically load secrets from the environment. For example: * **Local development**: Use 1Password CLI to [pass the secrets stored in an Environment](/environments/read-environment-variables#cli) to applications or scripts at runtime, or create a [locally mounted `.env` file](/environments/local-env-file) for tools that expect an environment file on disk. * **AI-assisted coding**: Keep plaintext secrets out of an LLM's context using a [locally mounted `.env` file](/environments/local-env-file) that your IDE can read without storing the plaintext contents on your device. Use [1Password hooks](/environments/agent-hook-validate) to validate your setup before the agent executes shell commands. * **Containerized apps**: Use 1Password SDKs to [retrieve Environment secrets](/environments/read-environment-variables#sdks) directly in your application container's code, or use 1Password CLI to [load secrets](/environments/read-environment-variables#cli) into an init container or sidecar at runtime. * **CI/CD pipelines**: Use 1Password CLI to [load the right set of secrets](/environments/read-environment-variables#cli) into your pipeline for the current development stage by pointing to the Environment your pipeline needs. Authenticate with a service account for automated, least privilege access. Environments are a great choice for securing your developer secrets when you have environment files that currently use plaintext secrets. You can import your existing `.env` files directly into 1Password, and you can share your Environments with your team members for quick and secure collaboration. > [card] [Get started](/environments) > > Create and manage Environments. > [card] [Access secrets through local .env files](/environments/local-env-file) > > Sync an Environment to a local .env file. > [card] [Programmatically read Environments](/environments/read-environment-variables) > > Fetch secrets from Environments with 1Password CLI or SDKs. > [card] [Sync secrets to AWS Secrets Manager](/environments/aws-secrets-manager) > > Centralize secrets management and simplify your AWS Secrets Manager workflow. > [card] [Find .env files with plaintext secrets](/watchtower) > > Use Developer Watchtower to scan your local disk for `.env` files with plaintext secrets, then import them into Environments. > [!NOTE] > > You can also replace hardcoded secrets in your code using [secret references](/cli/secret-references). ## Shell plugins With our open source [shell plugin ecosystem](/cli/shell-plugins), you can use 1Password to bring secure biometric authentication to all your command-line tools. When you configure a shell plugin for a CLI, you authenticate the CLI in the same way you unlock the 1Password desktop app, like with Touch ID, Apple Watch, or Linux system authentication. Shell plugins make authenticating all the CLI tools you use secure and easy, without ever needing to enter your credentials manually in your terminal. For example: * **Cloud provider CLIs**: Authenticate [`aws`](/cli/shell-plugins/aws) and other cloud provider CLIs with 1Password instead of storing access keys in `~/.aws/credentials` or shell profiles. * **Version control**: Use the [GitHub](/cli/shell-plugins/github) or [GitLab](/cli/shell-plugins/gitlab) shell plugins to authenticate `gh` or `glab` without storing plaintext tokens in your environment. * **Local development tools**: Authenticate package managers and development CLIs like [Homebrew](/cli/shell-plugins/homebrew) without storing credentials in config files. Shell plugins allow you to configure different credentials in different project directories, so you can [seamlessly switch between different contexts](/cli/shell-plugins/environments) without needing to take the time to sign out and in again. Get started with one of our most popular shell plugins: [GitHub](/cli/shell-plugins/github/) [AWS](/cli/shell-plugins/aws/) [Homebrew](/cli/shell-plugins/homebrew/) [GitLab](/cli/shell-plugins/gitlab/) [OpenAI](/cli/shell-plugins/openai/) [postgresql](/cli/shell-plugins/postgresql/) [Terraform](/cli/shell-plugins/terraform/) [DigitalOcean](/cli/shell-plugins/digitalocean/) [Heroku](/cli/shell-plugins/heroku/) [ngrok](/cli/shell-plugins/ngrok/) [CircleCI](/cli/shell-plugins/circleci/) [Vault](/cli/shell-plugins/hashicorp-vault/) ## Choose your configuration Use the tables below to find the best tools and authentication method for your specific use case. Every scenario includes a recommended [tool](#tool-options) and [authentication method](#authentication-options). ### Tool options * [1Password Environments](#environments): Best for managing project secrets in 1Password and eliminating plaintext secrets in code. * [1Password CLI](/cli/get-started): Best for quick testing, shell scripts, CI/CD pipelines, Infrastructure as Code, build tools and task runners. Use `op run --environment` to [load secrets from Environments](/environments/read-environment-variables#cli). * [1Password SDKs](/sdks): Best for native integrations with Go, Python, or JavaScript applications. Environments require the [latest SDK beta](/environments/read-environment-variables#sdks). * [1Password Shell Plugins](#shell-plugins): Best for securing command-line tools and adding convenient biometric authentication to any CLI. * [1Password Connect server](/connect): Securely access secrets in your company’s apps and cloud infrastructure using a private REST API. ### Authentication options * [1Password desktop app](https://1password.com/downloads/): Authenticate locally in the same way you unlock your 1Password desktop app, like with biometrics or your 1Password account password. Requires minimal setup with no token management and enables human-in-the-loop approval for sensitive workflows. * [1Password Service Accounts](/service-accounts/get-started): Authenticate using a token scoped to specific vaults or Environments, with no user interaction required. Best for headless servers, automated workflows, and 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. * [Connect server token](/connect/get-started): Authenticate with your Connect server host and token. ### Scenarios #### Local development | Use case | Recommended tool | Authentication method | Why this approach | | - | - | - | - | | **Local development** on your machine | [Environments](/environments) + [CLI/SDK](/environments/read-environment-variables) or [local `.env` file](/environments/local-env-file) | [Desktop app](https://1password.com/downloads/) | Use 1Password CLI or SDKs to load your project secrets from an Environment directly into your application at runtime, or use a locally mounted `.env` file if your app expects an environment file. Authenticate with the 1Password desktop app for quick setup with no token management required. | | **AI-assisted coding** | [Environments](/environments) + [Local `.env` file](/environments/local-env-file) | [Desktop app](https://1password.com/downloads/) | Use locally mounted `.env` files to provide secrets to your IDE without storing them on disk, keeping them out of LLM context. Then use [1Password hooks](/environments/agent-hook-validate) to validate your setup before the agent executes commands. | | **Build tools and task runners** | [Environments](/environments) + [CLI](/environments/read-environment-variables#cli) | [Desktop app](https://1password.com/downloads/) or [Service account](/service-accounts) | 1Password CLI integrates easily with build tools like `make`, `gradle`, or `npm` scripts. Use the 1Password desktop app for interactive developer builds, or service accounts for shared builds. | | **Replacing hardcoded secrets** in existing config files or scripts | [Environments](/environments) + [CLI](/environments/read-environment-variables#cli) | [Desktop app](https://1password.com/downloads/) or [Service account](/service-accounts) | Template your config file with environment variables instead of plaintext secrets, then use 1Password CLI to load the secrets from an Environment at runtime. Authenticate with the 1Password desktop app for personal scripts. Use service accounts for CI/CD, shared builds, or automated access. | | Securing **third-party CLI tools** | [Shell plugins](/cli/shell-plugins) | [Desktop app](https://1password.com/downloads/) | Shell plugins bring the biometric unlock options available in the 1Password desktop app to dozens of command-line tools, so there are no tokens to manage and credentials are never stored in shell profiles or config files. | | **Using a CLI tool with multiple accounts or environments** | [Shell plugins](/cli/shell-plugins) | [Desktop app](https://1password.com/downloads/) | Shell plugins allow you to seamlessly switch between different credentials for different accounts and development contexts. | #### Production environments | Use case | Recommended tool | Authentication method | Why this approach | | - | - | - | - | | **CI/CD pipelines** (GitHub Actions, GitLab CI, etc.) | [Environments + CLI](/environments/read-environment-variables) or [CI/CD integrations](/ci-cd) | [Service account](/service-accounts) | Use Environments to pass project secrets into CI/CD pipelines that support shell commands. This allows you to organize and switch between secrets by development context. Use CI/CD integrations to load secrets into your pipeline using secret references. Service accounts provide non-interactive authentication for automated workflows and can be scoped to only the Environments or vaults your pipeline needs. | | **Application runtime or server-side applications** | [Environments](/environments) + [SDKs](/environments/read-environment-variables#sdks) | [Service account](/service-accounts) | 1Password SDKs offer native language integration with better error handling and type safety. Service accounts enable secure, automated access without user interaction and headless server authentication. | | **Docker containers and Kubernetes** | [Environments](/environments) + [SDK or CLI](/environments/read-environment-variables) | [Service account](/service-accounts) | Service accounts work well in containerized environments. Choose 1Password SDKs for application containers, or choose 1Password CLI for init containers or sidecars. | | **Infrastructure as Code** | [Environments](/environments) + [CLI](/environments/read-environment-variables#cli) or [Terraform](/terraform)/[Pulumi](/pulumi) integrations | [Service account](/service-accounts) | 1Password CLI can be easily invoked from IaC tools. Service accounts enable automated infrastructure provisioning. | #### Secrets management | Use case | Recommended tool | Authentication method | Why this approach | | - | - | - | - | | **Secrets rotation** | [Environments](/environments) + [CLI/SDK](/environments/read-environment-variables) | [Service account](/service-accounts) | When you update an Environment, the change is automatically reflected in your code at runtime. Use a service account for automated or scheduled rotation workflows. | | **Accessing secrets in company apps and cloud infrastructure** | [CLI](/connect/cli) or [Connect SDK](/connect) | [Connect server](/connect) | Connect server hosts a private REST API in your own infrastructure, enabling unlimited re-requests after the initial fetch and reducing dependency on the availability of the 1Password API. | ## Next steps Choose what you want to do next: > [card] [Secure your deployments](/get-started/secure-deployment) > > Securely load secrets into CI/CD, containers, and production apps at runtime with least-privilege access. > [card] [Secure AI access](/get-started/secure-ai-access) > > Provide credentials to AI agents and tools without exposing them in prompts, LLM context, or config files. ## Get help To get help, join the discussion in our [Developer community](https://www.1password.community/category/discuss/discussions/developers) or join our [Developer Slack workspace](https://developer.1password.com/joinslack). # Secure SSH and Git workflows with 1Password Source: https://www.1password.dev/get-started/secure-ssh-git-workflows Use 1Password to manage SSH keys, authenticate Git and SSH connections, sign commits, and forward SSH requests without exposing your private keys. [Video walkthrough that covers creating an SSH key, turning on the 1Password SSH Agent, authenticating to GitHub with Touch ID, and signing Git commits.](https://www.youtube.com/embed/X3-TNJTJBWE) Plaintext SSH keys on disk, scattered `~/.ssh` directories, and unsigned Git commits are common sources of credential leaks and supply chain risk. A single private key left in `~/.ssh/id_rsa`, copied to a second machine, or forgotten on an old laptop is enough to compromise every host and repository it unlocks. And without commit signing, anyone with push rights can author Git commits that appear to be from you. 1Password eliminates these risks by keeping your SSH keys encrypted and off disk, and by enabling you to sign Git commits without needing a GPG key. Before you start, install the [1Password app](https://1password.com/downloads/) and turn on the [SSH agent](/ssh/get-started). With 1Password for SSH and Git, you can: * [Manage your SSH keys](#manage-your-ssh-keys) so you can easily generate, import, and store all your SSH keys, and share your public keys with the services, platforms, and people who need them. * [Authenticate SSH and Git connections](#authenticate-ssh-and-git-connections) for your terminal and GUI clients in the same way you unlock your 1Password desktop app, like with Touch ID, Apple Watch, or Linux system authentication. * [Sign Git commits and tags](#sign-git-commits-with-ssh) with the SSH keys you've stored in 1Password so others can verify your changes are authentic. * [Use multiple Git identities on the same machine](#use-multiple-git-identities-on-the-same-machine) for authenticating and signing Git commits over SSH without switching keys in and out of your agent. * [Forward SSH requests](#forward-ssh-requests) and authenticate Git and SSH commands from remote workstations, cloud development environments, and in WSL through the 1Password SSH Agent running on your local machine. * [Customize SSH agent behavior](#customize-ssh-agent-behavior) to help manage multiple SSH keys so you can make sure the right SSH key is matched to each SSH host. > [!TIP] > > **Not sure where to start?** To get started quickly, [generate or import an SSH key](/ssh/manage-keys) in 1Password, [turn on the SSH agent](/ssh/get-started), then start using 1Password to authenticate your SSH and Git connections. ## Manage your SSH keys Streamline your SSH key management by keeping your public keys, fingerprints, and private keys in 1Password to access anytime you need to use them. 1Password ensures your private keys are secured with end-to-end encryption and are never written to disk. * **Generate new SSH keys**: Use the apps or 1Password CLI to quickly [generate new SSH keys](/ssh/manage-keys#generate-an-ssh-key) and save them in 1Password, including the public keys, fingerprints, and private keys. Keys saved in 1Password are automatically available to the [1Password SSH Agent](/ssh/agent) for authenticating SSH requests. * **Import existing keys**: Secure your existing SSH keys by [importing them into 1Password](/ssh/manage-keys#import-an-ssh-key), then remove any local copies on your disk. You can also use [1Password Developer Watchtower](/watchtower) to check the `~/.ssh` folder on your local disk for SSH keys you can import. * **Share public keys**: Use 1Password to [autofill public keys](/ssh/public-key-autofill) in your Git or cloud provider accounts. You can also copy or download the public keys and fingerprints from your SSH Key items to [share them](/ssh/manage-keys#share-a-public-key) with the services and people who need them. > [!NOTE] > > 1Password supports [Ed25519 and RSA keys](/ssh/manage-keys#supported-ssh-key-types) (2048, 3072, and 4096-bit) in PKCS#1, PKCS#8, and OpenSSH formats. > [card] [Manage your SSH keys](/ssh/manage-keys) > > Secure your SSH keys in 1Password to access anytime you need them. > [card] [Autofill public keys](/ssh/public-key-autofill) > > Use the browser extension to fill your public keys in your Git or cloud platforms. > [card] [Developer Watchtower](/watchtower) > > Check for SSH private keys stored on your local disk and remediate any security issues. ## Authenticate SSH and Git connections The [1Password SSH Agent](/ssh/agent) runs in the background to handle authentication on behalf of your SSH and Git clients, replacing the standard OpenSSH agent. Instead of loading your private keys into an in-memory agent that any process can use, the [1Password SSH Agent security model](/ssh/agent/security) makes sure your encrypted private keys never leave 1Password and are never used without your consent. Any [eligible SSH Key item](/ssh/agent#eligible-keys) in your Personal, Private, or Employee vault is automatically available to the agent once it's turned on. To use it with your SSH and Git clients: 1. [Turn on the 1Password SSH Agent](/ssh/get-started#step-3-turn-on-the-1password-ssh-agent) in the desktop app. 2. [Configure your SSH or Git client](/ssh/get-started#step-4-configure-your-ssh-or-git-client) to use the agent for authentication. 3. Run an `ssh` or `git` command as usual and [authorize the request](/ssh/agent/authorization/) when 1Password prompts you. After approving a request, you can continue using the same SSH key for that application without being prompted again until 1Password locks or quits. You can also [adjust your authorization settings](/ssh/agent/authorization/#adjust-your-authorization-settings) to prompt more or less frequently. > [card] [Get started with 1Password for SSH](/ssh/get-started) > > Set up the SSH agent so you can authenticate your SSH requests from 1Password. > [card] [SSH client compatibility](/ssh/agent/compatibility) > > Check which SSH, Git, and SFTP clients are compatible with the 1Password SSH Agent. > [card] [About the 1Password SSH Agent](/ssh/agent) > > Learn more about configuration options for the SSH agent and how to make your keys available to use with the agent. > [card] [About 1Password SSH Agent security](/ssh/agent/security) > > Learn more about the SSH agent authorization model and how 1Password differs from OpenSSH. ## Sign Git commits with SSH Git 2.34 and later supports signing Git commits and tags with SSH keys. Save your signing keys in 1Password to use with Git hosts like GitHub, GitLab, and Bitbucket, which can verify SSH-signed commits. * [Configure Git commit signing with SSH globally](/ssh/git-commit-signing#step-1-configure-git-commit-signing-with-ssh) from the 1Password desktop app. * [Configure multiple commit signing setups](/ssh/git-commit-signing#configure-multiple-commit-signing-setups) by adding the `includeIf` directive to your `~/.gitconfig` file to scope configurations to specific directories. * [Set up commit signing for a specific repository](/ssh/git-commit-signing#configure-commit-signing-in-a-single-repository) by copying the commit signing snippet for your SSH key, then pasting it in the repository’s `/.git/config` file. * Set up SSH forwarding to sign commits in [cloud development environments](/ssh/agent/forwarding#set-up-git-commit-signing) and [remote workstations](/ssh/agent/forwarding#set-up-git-commit-signing-2). * Use the 1Password Windows Subsystem for Linux (WSL) integration to [sign Git commits from WSL](/ssh/integrations/wsl#sign-git-commits-with-ssh). > [card] [Sign Git commits with SSH](/ssh/git-commit-signing) > > Configure commit signing globally or per-repository and verify signatures. > [card] [Sign commits in remote environments](/ssh/agent/forwarding#git-commit-signing-cde) > > Use SSH agent forwarding to sign commits in a cloud development environment or remote workstation. > [card] [Sign commits in WSL](/ssh/integrations/wsl#sign-git-commits-with-ssh) > > Configure commit signing in WSL using the 1Password SSH Agent running on your Windows host. ## Use multiple Git identities on the same machine If you use multiple Git identities on the same machine — for example, separate accounts for work and personal projects — you can configure SSH host aliases for each identity. This tells your SSH clients which key to use when authenticating, and lets you configure each directory to sign commits with the matching key. 1. [Download the SSH public keys from 1Password](/ssh/manage-keys#share-a-public-key) that you use to authenticate each Git account and save them in your `~/.ssh/` directory. 2. [Define SSH host aliases (`Host`) for each Git identity in your `~/.ssh/config` file](/ssh/agent/advanced#use-multiple-github-accounts) and use the `IdentityFile` directive to point to the public key you downloaded for each alias, then update the Git remote URL for each Git repository to use the new host alias. 3. Configure commit signing for your different Git identities by [using the `includeIf` directive in your `~/.gitconfig` file](/ssh/git-commit-signing#configure-multiple-commit-signing-setups) so each directory uses the matching public signing key. > [!TIP] > > **Set your Git username and email per repository**: If your Git identities use a different [`user.name` and `user.email`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-username), you can set them from the root level of each repository using `git config user.name "Your Name"` and `git config user.email your@email.com`. > [card] [Download your public keys](/ssh/manage-keys#share-a-public-key) > > Download the public keys from your SSH Key items in 1Password. > [card] [Configure SSH host aliases](/ssh/agent/advanced#use-multiple-github-accounts) > > Define SSH host aliases for each Git identity so the correct SSH keys are used to authenticate your SSH requests. ## Forward SSH requests 1Password can help improve your experience when working in remote environments where you need to make SSH requests, like running Git commands and signing commits. Configure your remote host to allow SSH requests to be forwarded to the [1Password SSH Agent](/ssh/agent) on your local machine, then authorize those requests with biometrics without your private keys ever leaving the local 1Password process. * **CDEs and remote workstations**: Use [SSH agent forwarding with 1Password](/ssh/agent/forwarding) on a Mac or Linux machine to forward your local agent to a [CDE host](/ssh/agent/forwarding#cde) or a [remote workstation](/ssh/agent/forwarding#remote-workstation). Use [SSH agent forwarding more securely](/ssh/agent/forwarding#security) by scoping the `ForwardAgent yes` directive only to a specific host or domain you trust. * **Windows Subsystem for Linux (WSL)**: Use the [WSL integration](/ssh/integrations/wsl) to authenticate SSH and Git commands and [sign commits](/ssh/integrations/wsl#sign-git-commits-with-ssh) from inside WSL using the 1Password SSH Agent running on your Windows host. This integration works with both WSL 1 and WSL 2. > [card] [Remote environments](/ssh/agent/forwarding) > > Authenticate SSH and Git requests from within CDEs and remote workstations. > [card] [SSH agent forwarding security](/ssh/agent/forwarding#ssh-agent-forwarding-security) > > Best practices for scoping SSH agent forwarding to trusted hosts. > [card] [Forward SSH requests from WSL](/ssh/integrations/wsl) > > Forward SSH and Git requests from WSL to the 1Password SSH Agent on your Windows host. ## Customize SSH agent behavior When you attempt to authenticate with a server over SSH, the agent works with your SSH clients to offer your public keys one by one until the server acknowledges one that works. By default, every eligible SSH key in your Personal, Private, or Employee vault is made available to the 1Password SSH Agent. OpenSSH servers are configured to have a six-key limit for authentication attempts, which means you could run into authentication failures if you manage more than six SSH keys. To mitigate this issue, you can configure SSH agent behavior so your [SSH keys are matched to specific hosts](#match-ssh-keys-with-specific-hosts) and to [control which keys the agent offers to servers and in what order](#control-the-order-of-keys-offered-to-servers). ### Match SSH keys with specific hosts To avoid authentication failures and [make sure the correct key is matched to a specific SSH host](/ssh/agent/advanced#match-key-with-host), you can: * **Create SSH Bookmarks in 1Password**: [SSH Bookmarks](/ssh/bookmarks) are host URLs you can add to your SSH Key items in 1Password that let you connect to SSH hosts directly from 1Password, without manually entering commands in the terminal. You can create a bookmark using the Bookmark option in the [SSH agent activity log](/ssh/bookmarks#from-the-activity-log), or by [adding a custom field](/ssh/bookmarks#in-an-ssh-key-item) to an SSH Key item in 1Password. You can also generate an [SSH Bookmarks config file](/ssh/bookmarks#ssh-bookmarks-config-file) (`~/.ssh/1Password/config`) that 1Password automatically manages, which can prevent you from running into the six-key server limit. * **Configure your SSH config file**: [Download the public key](/ssh/manage-keys#share-a-public-key) from your SSH item in 1Password and save it in your `~/.ssh` directory. Then [manually edit your `~/.ssh/config` file](/ssh/agent/advanced#match-key-with-host) to add a `Host` block that sets `IdentityFile` to the path of your public key. This lets your SSH clients know which key to use when connecting to SSH servers. > [card] [SSH Bookmarks](/ssh/bookmarks) > > Bookmark hosts in your SSH Key items and launch SSH connections directly from 1Password. > [card] [Avoid the six-key limit](/ssh/agent/advanced#ssh-server-six-key-limit) > > Match keys to specific hosts with `IdentityFile` or the agent config file. ### Control the order of keys offered to servers You can use the [1Password SSH Agent config file](/ssh/agent/config) to give you fine-grained control over which keys the agent offers and in what order. With the agent config file, you can: * **Use SSH keys from shared or custom vaults**: Choose specific keys, vaults, or accounts to make available to the agent. * **Avoid the [six-key server limit](/ssh/agent/advanced#ssh-server-six-key-limit)**: Specify the order the agent uses to offer your keys to SSH servers, to prevent running into the six-key authentication limit on most servers. * **Keep different configurations per machine**: Customize how you use the SSH agent on each device. For example, you can configure the agent config file on your work laptop to only surface work keys. You can use the agent config file alongside your SSH client config file (`~/.ssh/config`) and with SSH Bookmarks. > [card] [Create an SSH agent config file](/ssh/agent/config) > > Control which keys the agent offers and in what order. ## Next steps Choose what you want to do next: > [card] [Secure local development](/get-started/secure-developer-secrets) > > Access credentials in your terminal, IDE, and local projects without exposing your secrets in plaintext. > [card] [Secure your deployments](/get-started/secure-deployment) > > Securely load secrets into CI/CD, containers, and production apps at runtime with least-privilege access. ## Get help To get help, join the discussion in our [Developer community](https://www.1password.community/category/discuss/discussions/developers) or join our [Developer Slack workspace](https://developer.1password.com/joinslack). # 1Password integrations Source: https://www.1password.dev/integrations Use integrations to securely access secrets from 1Password in your development workflows. To sign in to third-party command-line tools like `aws`, `gh`, or `claude` with your fingerprint, see [shell plugins](/cli/shell-plugins). ### AI agents Give AI agents and coding tools access to secrets without exposing them, with the Environments MCP server, the Claude Code and Cursor plugins, agent hooks, NVIDIA OpenShell, and 1Password for Agents. [Learn more](/security-for-ai) ### Ansible Interact with your 1Password Connect deployment from Ansible playbooks. Create, read, update, and delete 1Password vaults and items. [Learn more](/connect/ansible-collection/) ### AWS ECS Fargate Use 1Password Connect with AWS Fargate, so you can leverage Amazon Elastic Container Service (ECS) to run containers without the need to manage clusters. [Learn more](/connect/aws-ecs-fargate/) ### CI/CD integrations Securely access secrets in your CI/CD pipelines with CircleCI, GitHub Actions, and Jenkins. [Learn more](/ci-cd/) ### CircleCI Load secrets from 1Password into your CircleCI jobs with the 1Password orb. [Learn more](/ci-cd/circle-ci/) ### Credential Broker (public preview) Give GitHub Actions and other OIDC workflows short-lived access to secrets, without storing a service account token. [Learn more](/brokered-access) ### GitHub Actions Load secrets from 1Password into your GitHub Actions workflows with a service account or Connect server. [Learn more](/ci-cd/github-actions/) ### Jenkins Load secrets from 1Password into your Jenkins pipelines with the 1Password Secrets plugin. [Learn more](/ci-cd/jenkins/) ### Kubernetes integrations Integrate 1Password with Kubernetes Secrets Injector, Kubernetes Operator, or Helm charts. [Learn more](/k8s/integrations/) ### Postman Securely load API keys and other secrets stored in 1Password into Postman without exposing any secrets in plaintext. [Learn more](https://go.pstmn.io/1password) ### Pulumi Use the 1Password provider for Pulumi to access and manage items in your 1Password vaults. [Learn more](/pulumi/) ### Pulumi ESC Dynamically import Secrets from 1Password into your Environment. The provider will return a map of names to Secrets. [Learn more](https://www.pulumi.com/docs/esc/providers/1password-secrets/) ### Terraform Reference, create, or update items in your vaults with a Connect server or service account. [Learn more](/terraform/) ### VS Code Integrate your VS Code development workflow with 1Password. [Learn more](/vscode/) # 1Password Helm charts Source: https://www.1password.dev/k8s/helm Helm is a tool that helps you manage Kubernetes applications through specification files called Helm charts. Helm charts define a Kubernetes application and make it easy to share, install, and upgrade. Refer to [Helm](https://helm.sh) to learn more. The 1Password Helm charts allow you to use Helm to deploy a [Secrets Automation workflow](/secrets-automation/). 1Password offers two Helm charts: * The [1Password Connect and Kubernetes Operator Helm chart](https://github.com/1Password/connect-helm-charts/blob/main/charts/connect) runs a Connect server by itself or alongside the Kubernetes Operator. * The [1Password Secrets Injector Helm chart](https://github.com/1Password/connect-helm-charts/blob/main/charts/secrets-injector) runs the Kubernetes Secrets Injector, which works with both service accounts and Connect servers. See the following comparison table to learn which Helm chart is right for the environment you want to run. | Environment | Connect and Operator | Secrets Injector | | - | - | - | | Connect server (without the Kubernetes Operator) | Yes | No | | Connect server and the Kubernetes Operator | Yes | No | | Kubernetes Injector | No | Yes | ### Requirements Make sure you complete the requirements for the Helm chart you intend to use before continuing. > [tab] Connect Kubernetes Operator > > Before you use the 1Password Connect and Operator Helm chart, make sure you: > >
    >
  • [Sign up for 1Password](https://1password.com/pricing/password-manager).
  • >
  • Have a Kubernetes deployment. You can also use [minikube](https://minikube.sigs.k8s.io/docs/start/) to test locally.
  • >
  • Install [kubectl.](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
  • >
  • Install [Helm.](https://helm.sh)
  • >
  • Create a Secrets Automation workflow as a [Connect server](/connect/get-started/#step-1).
  • >
> [tab] Kubernetes Secrets Injector > > Before you use the 1Password Kubernetes Secrets Injector Helm chart, make sure you: > >
    >
  • [Sign up for 1Password](https://1password.com/pricing/password-manager).
  • >
  • Have a Kubernetes deployment. You can also use [minikube](https://minikube.sigs.k8s.io/docs/start/) to test locally.
  • >
  • Install [kubectl.](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
  • >
  • Install [Helm.](https://helm.sh)
  • >
  • Create a Secrets Automation workflow as a [Connect server](/connect/get-started/#step-1) or a [service account](/service-accounts/get-started/).
  • >
### Deployment The deployment process for the 1Password Helm charts depends on multiple factors, including: * The type of secrets automation workflow. * Whether you want to use the Kubernetes Operator, the Kubernetes Injector, or neither. > [tab] Connect Kubernetes Operator > > There are multiple ways to use the Helm chart for 1Password Connect and the Kubernetes Operator. Select one to get started: > > 1. [Deploy a Connect server.](/connect/get-started/?deploy=kubernetes#step-2-deploy-1password-connect-server) > 2. [Deploy a Connect server and the Kubernetes Operator.](/k8s/operator/?requirements=deploy-with-helm\&deployment=helm#deployment) > 3. [Deploy the Kubernetes Operator.](/k8s/operator/?requirements=deploy-with-helm\&deployment=helm#deployment) > [tab] Kubernetes Secrets Injector > > There are two ways to use the 1Password Connect and Operator Helm chart. Select one to get started: > > 1. [Deploy the Kubernetes Secrets Injector for a Connect server.](/k8s/injector/?workflow-type=connect#deployment) > 2. [Deploy the Kubernetes Secrets Injector for a service account.](/k8s/injector/?workflow-type=service-account#deployment) ### Configuration See the [Helm chart configuration values reference](/k8s/helm/) documentation. # Helm chart configuration Source: https://www.1password.dev/k8s/helm-config This page documents the configuration options for the 1Password Helm charts: * [Connect and Operator Helm chart](#connect-and-operator-helm-chart) * [Secrets Injector Helm chart](#secrets-injector-helm-chart) ## Connect and Operator Helm chart The 1Password Connect and Operator Helm chart allows you to use Helm to deploy [Connect](/connect/get-started/), the [Kubernetes Operator](/k8s/operator/), or both. You can override configuration values in a chart with the `helm install` command using either the `--values` flag or the `--set` flag. You can also force a string value with the `--set-string` flag. For example, the following code block shows how to use the `--set` flag to set the `connect.applicationName` configuration value: ```shell theme={null} helm install --set connect.applicationName=connect connect 1password/connect ``` Refer to the [official `helm install` documentation](https://helm.sh/docs/helm/helm_install/) for more information. > [!NOTE] > > By default, installing a 1Password Helm chart also installs the `OnePasswordItem` database operations for CRD (Custom Resource Definition). > > If you don't want to install the `OnePasswordItem` custom resource definitions (CRD), run `helm install` with the [`--skip-crds` flag.](https://helm.sh/docs/chart_best_practices/custom_resource_definitions/#method-1-let-helm-do-it-for-you) ### Configuration options The following table documents the available configuration options for the 1Password Connect and Operator Helm chart. > [!TIP] > > If you have a large configuration value, use `--set-file` to read the single large value from the file (instead of `--values` or `--set`). > > For example: > > ``` > $ helm install -f myvalues.yaml injector 1password/secrets-injector > ``` | Key | Type | Default | Description | | - | - | - | - | | `connect.create` | boolean | `true` | Denotes whether to deploy the 1Password Connect server. Set this value to `false` and `operator.create` to `true` to only deploy the Kubernetes Operator. See [Deploy without Connect](/k8s/operator?deployment-type=helm#helm-step-2). | | `connect.replicas` | integer | `1` | The number of replicas to run the 1Password Connect deployment. | | `connect.applicationName` | string | `"onepassword-connect"` | The name of 1Password Connect application. | | `connect.host` | string | `"onepassword-connect"` | The name of 1Password Connect host. | | `connect.api.imageRepository` | string | `"1password/connect-api` | The 1Password Connect API repository. | | `connect.api.name` | string | `"connect-api"` | The name of the 1Password Connect API container. | | `connect.api.resources` | object | `{}` | The resources requests/limits for the 1Password Connect API pod. | | `connect.api.httpPort` | integer | `8080` | The port the Connect API is served on when not using TLS. | | `connect.api.httpsPort` | integer | `8443` | The port the Connect API is served on when using TLS. | | `connect.api.logLevel` | string | `info` | The log level of the Connect API container. Valid options are `trace`, `debug`, `info`, `warn`, and `error`. | | `connect.credentials` | jsonString | | The contents of the `1password-credentials.json` file for Connect. You can set it by adding `--set-file connect.credentials=` to your `helm install` command. | | `connect.credentials_base64` | string | | The base64-encoded contents of the `1password-credentials.json` file for Connect. You can use this instead of `connect.credentials` if supplying raw JSON to `connect.credentials` lead to issues. | | `connect.credentialsKey` | string | `"1password-credentials.json"` | The key for the 1Password Connect credentials (stored in the credentials secret). The credentials must be encoded as a base64 string. | | `connect.credentialsName` | string | `"op-credentials"` | The name of Kubernetes Secret containing the 1Password Connect credentials. | | `connect.dataVolume.name` | string | `"shared-data"` | The name of the shared [volume](https://kubernetes.io/docs/concepts/storage/volumes/) used between 1Password Connect containers. | | `connect.dataVolume.type` | string | `"emptyDir"` | The type of shared [volume](https://kubernetes.io/docs/concepts/storage/volumes/) used between 1Password Connect containers. | | `connect.dataVolume.values` | object | `{}` | Describes the fields and values for the configuration of the shared [volume](https://kubernetes.io/docs/concepts/storage/volumes/) for 1Password Connect. | | `connect.imagePullPolicy` | string | `"IfNotPresent"` | The 1Password Connect API image pull policy. | | `connect.ingress.annotations` | object | `{}` | The 1Password Connect [ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) annotations. | | `connect.ingress.enabled` | bool | `false` | Whether to enable 1Password Connect [ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) traffic. | | `connect.ingress.extraPaths` | list | `[]` | Additional [ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) paths. | | `connect.ingress.hosts[0].host` | string | `"chart-example.local"` | The 1Password Connect [ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) hostname. | | `connect.ingress.hosts[0].paths` | list | `[]` | The 1Password Connect [ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) path. | | `connect.ingress.ingressClassName` | string | `""` | Optionally use `ingressClassName` instead of a deprecated annotation. | | `connect.ingress.labels` | object | `{}` | [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) labels for 1Password Connect. | | `connect.ingress.pathType` | string | `"Prefix"` | Ingress [PathType.](https://kubernetes.io/docs/concepts/services-networking/ingress/#path-types) | | `connect.ingress.tls` | list | `[]` | [Ingress TLS.](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls) | | `connect.nodeSelector` | object | `{}` | The [Node selector](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector) stanza for the Connect pod. | | `connect.probes.readiness` | boolean | `true` | Denotes whether the 1Password Connect API readiness probe operates and ensures the pod is ready before serving traffic. | | `connect.probes.liveness` | boolean | `true` | Denotes whether Kubernetes continually checks the 1Password Connect API for liveness and restarts if the pod becomes unresponsive. | | `connect.annotations` | object | `{}` | Additional [annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) to add to the Connect API deployment resource. | | `connect.labels` | object | `{}` | Additional [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) to add to the Connect API deployment resource. | | `connect.podAnnotations` | object | `{}` | Additional [annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) to be added to the Connect API pods. | | `connect.podLabels` | object | `{}` | Additional [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) to be added to the Connect API pods. | | `connect.serviceType` | string | `NodePort` | The type of Service resource to create for the Connect API and Connect Sync services. | | `connect.serviceAnnotations` | object | `{}` | Additional [annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) to be added to the service. | | `connect.sync.imageRepository` | string | `"1password/connect-sync"` | The 1Password Connect Sync repository. | | `connect.sync.name` | string | `"connect-sync"` | The name of the 1Password Connect Sync container. | | `connect.sync.resources` | object | `{}` | The resources requests/limits for the 1Password Connect Sync pod. | | `connect.sync.httpPort` | integer | `8081` | The port serving the health of the Connect Sync container. | | `connect.sync.logLevel` | string | `info` | The log level of the Connect Sync container. Valid options are `trace`, `debug`, `info`, `warn`, and `error`. | | `connect.tls.enabled` | boolean | `false` | Denotes whether the Connect API is secured with TLS. | | `connect.tls.secret` | string | `"op-connect-tls"` | The name of the secret containing the TLS key (`tls.key`) and certificate (`tls.crt`). | | `connect.tolerations` | list | `[]` | A list of tolerations to be added to the Connect API pods. | | `connect.version` | string | `{{.Chart.AppVersion}}` | The 1Password Connect version to pull. | | `operator.autoRestart` | boolean | `false` | Denotes whether the Kubernetes Operator automatically restarts deployments based on associated updated secrets. See [Automatic redeployment](/k8s/operator#enable-auto-redeployment). | | `operator.create` | boolean | `false` | Denotes whether to deploy the Kubernetes Operator. You can set this to `false` to only deploy Connect. | | `operator.imagePullPolicy` | string | `"IfNotPresent"` | The Kubernetes Operator image pull policy. | | `operator.imageRepository` | string | `"1password/onepassword-operator"` | The Kubernetes Operator repository. | | `operator.nodeSelector` | object | `{}` | [Node selector](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector) stanza for the Kubernetes Operator pod. | | `operator.annotations` | object | `{}` | Additional [annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) to add to the Kubernetes Operator deployment resource. | | `operator.labels` | object | `{}` | Additional [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) to be added to the Operator deployment resource. | | `operator.logLevel` | string | `info` | The log level of the Kubernetes Operator container. Valid options are: `debug`, `info`, and `error`. | | `operator.podAnnotations` | object | `{}` | Additional [annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) to add to the Kubernetes Operator pods. | | `operator.podLabels` | object | `{}` | Additional [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) to add to the Kubernetes Operator pods. | | `operator.pollingInterval` | integer | `600` | The interval at which the Kubernetes Operator polls for secrets updates. | | `operator.clusterRole.create` | boolean | `{{.Values.operator.create}}` | Denotes whether to create a cluster role for the Kubernetes Operator. | | `operator.clusterRole.name` | string | `"onepassword-connect-operator"` | The name of the Kubernetes Operator [Cluster Role.](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) | | `operator.clusterRoleBinding.create` | boolean | `{{.Values.operator.create}}` | Denotes whether to create a [ClusterRole binding](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) for the Kubernetes Operator Service Account. | | `operator.roleBinding.create` | boolean | `{{.Values.operator.create}}` | Denotes whether to create a role binding for each Namespace for the Kubernetes Operator Service Account. | | `operator.roleBinding.name` | string | `"onepassword-connect-operator"` | The name of the Kubernetes Operator Role Binding. | | `operator.serviceAccount.annotations` | object | `{}` | The [annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) for the 1Password Connect Service Account. | | `operator.serviceAccount.create` | boolean | `{{.Values.operator.create}}` | Denotes whether to create a [Service Account](/service-accounts/get-started/) for the Kubernetes Operator. | | `operator.serviceAccount.name` | string | `"onepassword-connect-operator"` | The name of the Kubernetes Operator. | | `operator.tolerations` | list | `[]` | A list of tolerations to add to the Kubernetes Operator pods. | | `operator.version` | string | `"1.8.0"` | The Kubernetes Operator version to pull. It defaults to the latest version. | | `operator.token.key` | string | `"token"` | The key for the 1Password Connect token (stored in the 1Password token secret). | | `operator.token.name` | string | `"onepassword-token"` | The name of Kubernetes Secret containing the 1Password Connect API token. | | `operator.token.value` | string | `"onepassword-token"` | An API token generated for 1Password Connect to be used by the Kubernetes Operator. | | `operator.watchNamespace` | list | `[]` | A list of namespaces for the Kubernetes Operator to watch and manage. Use the empty list to watch all namespaces. | | `operator.resources` | object | `{}` | The resources requests/limits for the Kubernetes Operator pod. | ## Secrets Injector Helm chart The 1Password Secrets Injector Helm chart allows you to use Helm to deploy the [Kubernetes Secrets Injector](/k8s/injector/). You can override configuration values in a chart with the `helm install` command using either the `--values` flag or the `--set` flag. You can also force a string value with the `--set-string` flag. For example, the following code block shows how to use the `--set` flag to set the `injector.applicationName` configuration value: ```shell theme={null} helm install --set injector.applicationName=injector injector 1password/secrets-injector ``` Refer to the [official `helm install` documentation](https://helm.sh/docs/helm/helm_install/) for more information. ### Configuration options The following table documents the available configuration options for the Secrets Injector Helm chart. > [!TIP] > > If you have a large configuration value, use `--set-file` to read the single large value from the file (instead of `--values` or `--set`). > > For example: > > ``` > $ helm install -f myvalues.yaml injector 1password/secrets-injector > ``` | Key | Type | Default | Description | | - | - | - | - | | `injector.applicationName` | string | `"secrets-injector"` | The name of 1Password Kubernetes Secrets Injector Application. | | `injector.imagePullPolicy` | string | `"IfNotPresent"` | The 1Password Secrets Injector Docker image policy. `"IfNotPresent"` means the image is pulled only if it is not already present locally. | | `injector.imageRepository` | string | `"1password/kubernetes-secrets-injector"` | The 1Password Secrets Injector docker image repository. | | `injector.port` | string | `443` | The port the Secrets Injector exposes. | | `injector.targetPort` | integer | `8443` | The port the Secrets Injector API sends requests to the pod. | | `injector.version` | string | `{{.Chart.AppVersion}}` | The 1Password Secrets Injector version to pull. | # Kubernetes Injector Source: https://www.1password.dev/k8s/injector The 1Password Kubernetes Secrets Injector implements a mutating webhook that allows you to inject 1Password secrets using a [service account](/service-accounts/) or a [Connect server](/connect/) to authenticate to 1Password. Unlike the 1Password [Kubernetes Operator](/k8s/operator/), the Secrets Injector doesn't create a Kubernetes Secret when assigning secrets to your resource. See [Kubernetes integrations](/k8s/integrations/) to compare the Kubernetes Operator and the Kubernetes Injector. > [!TIP] > > Learn how to use the Kubernetes Secrets Injector with a 1Password Service Account. > > [Using 1Password Service Accounts with Kubernetes Secrets Injector](https://www.youtube.com/embed/WS1CAooBqog) ## Requirements Before using the Kubernetes Injector, make sure you: * [Sign up for 1Password](https://1password.com/pricing/password-manager). * Have a Kubernetes deployment. You can also use [minikube](https://minikube.sigs.k8s.io/docs/start/) to test locally. * Create either a [service account](/service-accounts/get-started/) or a [Connect server](/connect/get-started/#step-1) to authenticate to 1Password. ## Limitations There are some limitations and nuances to consider about the Kubernetes Injector. For example: * The Kubernetes Injector requires deployment specifications to use the `command` field. * Secrets aren't available to all a container's sessions by default. ### The `command` field The Kubernetes Secrets Injector works by changing the `command` value on initialization. As a result, the pod you want to inject secrets into must have a `command` value defined in its [deployment specification](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) file (as shown in the following code block). See the `command` field in the code block below. In this example, a 1Password Service Account injects secrets into the application run by `npm` `start`. ```yaml deployment-specification.yaml theme={null} spec: containers: - name: app-example1 image: my-image ports: - containerPort: 5000 command: ["npm"] args: ["start"] env: - name: OP_SERVICE_ACCOUNT_TOKEN valueFrom: secretKeyRef: name: op-service-account key: token - name: DB_USERNAME value: op://my-vault/my-item/sql/username - name: DB_PASSWORD value: op://my-vault/my-item/sql/password ``` If the deployments you're using aren't designed to have a command field specified in the deployment, then the 1Password [Kubernetes Operator](/k8s/operator/) might be a better fit for your use case. ### Session availability Injected secrets are available only in the current pod's session. You can only access the secrets for the command listed in the container specification. To access it in any other session, for example, using `kubectl`, it's necessary to prepend `op run --` to the command. In the [service account example deployment specification](#usage-examples), the app-example1 container will have injected the `DB_USERNAME` and `DB_PASSWORD` values in the session executed by the command `npm start`. Another way to have secrets available in all sessions for a container is by using the [Kubernetes Operator](/k8s/operator/). ## Deployment Use the following instructions to configure and deploy the Kubernetes Injector with your service account or Connect server and Kubernetes deployment. > [accordion] Notes about strings and variables used in these code examples. > > Some strings used throughout the code examples on this page are variable and arbitrary. Other strings have specific meanings within the context of 1Password. > > The following strings used in the code examples on this page have very specific and hard-coded meanings within the context of 1Password: > > * `OP_CONNECT_HOST` > * `OP_CONNECT_TOKEN` > * `OP_SERVICE_ACCOUNT_TOKEN` > > The following strings used in the code examples on this page have are variables and don't have specific meanings within the context of 1Password: > > * `DB_PASSWORD` > * `DB_USERNAME` ### Step 1: Enable secrets injection Use kubectl to enable secrets injection by adding the `secrets-injection=enabled` label to your namespace (`NAMESPACE`) . The Kubernetes Injector uses the `default` namespace unless you specify a custom namespace. ```shell theme={null} kubectl label namespace NAMESPACE secrets-injection=enabled ``` ### Step 2: Deploy the injector Use the `kubectl apply` command to the deployment specification files. When you use manual deployment, you must apply each deployment specification file separately. In the following example, `INJECTOR.yaml` is the name of the Kubernetes Injector deployment specification file and `CONNECT.yaml` is the name of the Connect deployment specification file. ```shell theme={null} kubectl apply -f INJECTOR.yaml kubectl apply -f CONNECT.yaml ``` To undeploy, use `kubectl delete`. ```shell theme={null} kubectl delete -f INJECTOR.yaml kubectl delete -f CONNECT.yaml ``` The commands in this example only deploy the Kubernetes Injector and Connect. They don't handle additional configuration you might need, like [permissions](https://kubernetes.io/docs/tasks/administer-cluster/securing-a-cluster/), [namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/), and [custom resource definitions (CRD).](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) > [!TIP] > > You can deploy and configure the Kubernetes Injector in one command if you use the [1Password Secrets Injector Helm chart](/k8s/helm/). > [!NOTE] > > The Kubernetes Injector creates the necessary [TLS certificate](https://en.wikipedia.org/wiki/Public_key_certificate) for the webhook when it's deployed ([`deployment.yaml`](https://github.com/1Password/kubernetes-secrets-injector/blob/main/deploy/deployment.yaml)). If you remove the Kubernetes Injector from the cluster, it automatically deletes the TLS certificate. ### Step 3: Annotate your deployment specification Annotate your [Kubernetes deployment specification](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) with `operator.1password.io/inject:` followed by a comma-separated list of the containers you want to mutate and inject secrets into. 1. Edit your deployment specification file and add the following annotation: ```yaml deployment-specification.yaml theme={null} annotations: operator.1password.io/inject: "app-example1, app-example2" ``` ### Step 4: Configure the resource environment Add an environment variable to your pod or [Kubernetes deployment specification](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) with a value referencing your 1Password item using a [secret reference](/cli/secret-reference-syntax/). 1. Edit your deployment specification file and add an environment variable containing the path to the 1Password item. Make sure to replace `VAULT` , `ITEM`, `SECTION`, and `FIELD` with the correct values. ```yaml deployment-specification.yaml theme={null} env: - name: DB_USERNAME value: op://VAULT/ITEM[/SECTION]/FIELD ``` The value should look something like the text in the following code block: ```yaml deployment-specification.yaml theme={null} env: - name: DB_USERNAME value: op://my-vault/sql/username ``` ### Step 5: Add your 1Password credentials to your deployment #### Step 5.1: Create a Kubernetes Secret with your authentication token To authenticate to 1Password, you'll need to create a [Kubernetes Secret](https://kubernetes.io/docs/concepts/configuration/secret/) that contains your service account or Connect server token. > [tab] Service account > > You can pass your service account token to Kubernetes using the `kubectl create secret` command: > > > [!NOTE] > > > > Your service account token is generated automatically during the service account creation process. If you lose the token, you must [create a new service account](/service-accounts/get-started/). > > ```shell theme={null} > kubectl create secret generic op-service-account --from-literal=token=YOUR_SERVICE_ACCOUNT_TOKEN > ``` > > This creates a generic Secret named `op-service-account` with a key named `token` that contains your service account token. > [tab] Connect > > You can pass your Connect server access token token to Kubernetes using the `kubectl create secret` command: > > ```shell theme={null} > kubectl create secret generic connect-token --from-literal=token=YOUR_CONNECT_TOKEN > ``` > > This creates a generic Secret named `connect-token` with a key named `token` that contains your Connect server access token. #### Step 5.2: Add the Secret to your Kubernetes deployment specification file You can reference the Secret you created for your service account or Connect server token in your [Kubernetes deployment specification file](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) using an environment variable. Kubernetes will automatically inject the authentication token into your pod or deployment when it starts. > [tab] Service account > > Add an environment variable named `OP_SERVICE_ACCOUNT_TOKEN` to your deployment specification file, and set the `valueFrom` to reference the Kubernetes Secret you created in the previous step. > > If you used a custom Secret or key name, make sure to update the example to use the appropriate name and key. > > ```yaml deployment-specification.yaml theme={null} > spec: > containers: > - name: app-example1 > image: my-image > ports: > - containerPort: 5000 > command: ["npm"] > args: ["start"] > env: > - name: OP_SERVICE_ACCOUNT_TOKEN > valueFrom: > secretKeyRef: > name: op-service-account > key: token > ``` > [tab] Connect > > 1. Add an environment variable named `OP_CONNECT_HOST` to your deployment specification file for your Connect server host. Set the `value` to the URL where your Connect server is deployed. > 2. Add an environment variable named `OP_CONNECT_TOKEN`, and set the `valueFrom` to reference the Kubernetes Secret you created in the previous step. If you used a custom Secret or key name, make sure to update the example to use the appropriate name and key. > > ```yaml deployment-specification.yaml theme={null} > spec: > containers: > - name: app-example1 > image: my-image > ports: > - containerPort: 5000 > command: ["npm"] > args: ["start"] > env: > - name: OP_CONNECT_HOST > value: http://onepassword-connect:8080 > - name: OP_CONNECT_TOKEN > valueFrom: > secretKeyRef: > name: connect-token > key: token > ``` > [!WARNING] > > If you configure the Kubernetes Injector to authenticate with both a service account and a Connect server, the Connect server will take precedence. ## Usage examples The following Kubernetes deployment specification files show what your deployment file should look like. > [tab] Service account > > The following code block contains an example of a Kubernetes deployment specification YAML file setup to inject secrets using a 1Password Service Account. In this example, the Kubernetes Injector injects secrets into `APP_1`, but not `APP_2`. > > ```yaml deployment-specification.yaml theme={null} > apiVersion: apps/v1 > kind: Deployment > metadata: > name: app-example > spec: > selector: > matchLabels: > app: app-example > template: > metadata: > annotations: > operator.1password.io/inject: APP_1 > labels: > app: app-example > spec: > containers: > - name: APP_1 > image: my-image > ports: > - containerPort: 5000 > command: ["npm"] > args: ["start"] > env: > - name: OP_SERVICE_ACCOUNT_TOKEN > valueFrom: > secretKeyRef: > name: op-service-account > key: token > - name: DB_USERNAME > value: op://my-vault/my-item/sql/username > - name: DB_PASSWORD > value: op://my-vault/my-item/sql/password > - name: APP_2 > image: my-image > ports: > - containerPort: 5000 > command: ["npm"] > args: ["start"] > env: > - name: DB_USERNAME > value: op://my-vault/my-item/sql/username > - name: DB_PASSWORD > value: op://my-vault/my-item/sql/password > ``` > [tab] Connect > > The following code block contains an example of a Kubernetes deployment specification YAML file setup to inject secrets using a 1Password Connect Server. In this example, the Kubernetes Injector injects secrets into `APP_1`, but not `APP_2`. > > ```yaml deployment-specification.yaml theme={null} > apiVersion: apps/v1 > kind: Deployment > metadata: > name: app-example > spec: > selector: > matchLabels: > app: app-example > template: > metadata: > annotations: > operator.1password.io/inject: APP_1 > labels: > app: app-example > spec: > containers: > - name: APP_1 > image: my-image > ports: > - containerPort: 5000 > command: ["npm"] > args: ["start"] > env: > - name: OP_CONNECT_HOST > value: http://onepassword-connect:8080 > - name: OP_CONNECT_TOKEN > valueFrom: > secretKeyRef: > name: connect-token > key: token-value > - name: DB_USERNAME > value: op://my-vault/my-item/sql/username > - name: DB_PASSWORD > value: op://my-vault/my-item/sql/password > - name: APP_2 > image: my-image > ports: > - containerPort: 5000 > command: ["npm"] > args: ["start"] > env: > - name: DB_USERNAME > value: op://my-vault/my-item/sql/username > - name: DB_PASSWORD > value: op://my-vault/my-item/sql/password > ``` # Kubernetes integrations Source: https://www.1password.dev/k8s/integrations You can use Kubernetes integrations to deploy a [1Password Connect Server](/connect/) or a [1Password Service Account](/service-accounts/) to a Kubernetes cluster. 1Password offers multiple Kubernetes integrations, including the [Kubernetes Secrets Injector](#kubernetes-injector), the [Kubernetes Operator](#kubernetes-operator), and [Helm charts](#1password-helm-charts) (which support both the Kubernetes Injector and the Kubernetes Operator). The best integration option depends on your unique environment. > [card] [Securing secrets across your full deployment stack?](/get-started/secure-deployment) > > The [secure deployment guide](/get-started/secure-deployment) covers how 1Password works across CI/CD pipelines, containers, and production applications. ## Comparison Both the Kubernetes Injector and the Kubernetes Operator work by allowing you to inject secrets from 1Password into a Kubernetes environment. However, they vary slightly based on your intended use case and their requirements. The 1Password Helm charts allow you to more easily deploy a Connect server, the Kubernetes Operator, or the Kubernetes Injector. Refer to the following table to learn the differences between the integrations. | **Feature** | [**Kubernetes Injector**](#kubernetes-injector) | [**Kubernetes Operator**](#kubernetes-operator) | | - | - | - | | Supports service accounts | Yes | Yes | | Supports Connect servers | Yes | Yes | | Allows for granular selection of secrets | Yes | No | | Uses Kubernetes Secrets | No | Yes | | Injects 1Password items directly into Kubernetes pods | Yes | No | | Works with multiple credentials simultaneously | Yes | No | | Supports automatic redeployment when 1Password items change | No | Yes | | Requires a Connect token to deploy | No | Yes | ### Kubernetes Injector The 1Password Kubernetes Secrets Injector implements a mutating webhook that allows you to inject 1Password secrets as environment variables into a Kubernetes pod or deployment. You can use the Kubernetes Injector with [Connect servers](/connect/) or [service accounts](/service-accounts/). Get started with the Kubernetes Injector ### Kubernetes Operator The 1Password Connect Kubernetes Operator integrates [Kubernetes Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) with 1Password with one or more Connect servers or service accounts. It allows you to: * Create Kubernetes Secrets from 1Password items and load them into Kubernetes deployments. * Automatically restart deployments when 1Password items update. Get started with the Kubernetes Operator ### 1Password Helm charts [Helm](https://helm.sh/) is a tool that helps you manage Kubernetes applications through specification files called Helm charts. Helm charts define a Kubernetes application and make it easy to share, install, and upgrade. The official 1Password Helm charts allow you to create a Secrets Automation workflow deployment using a predefined specification. Get started 1Password Helm charts # Kubernetes Operator Source: https://www.1password.dev/k8s/operator The 1Password Connect Kubernetes Operator integrates [Kubernetes Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) with 1Password with one or more Connect servers. It allows you to: * Create Kubernetes Secrets from 1Password items and load them into Kubernetes deployments. * Automatically restart deployments when 1Password items update. [Using 1Password Connect with Kubernetes Operator](https://www.youtube.com/embed/kxbfCsJARHM) ## Requirements Before using the Kubernetes Operator, make sure you finish the requirement steps. The requirements vary slightly depending on how you plan to deploy the Kubernetes Operator. > [tab] Deploy with Helm > > Before you can deploy the Kubernetes Operator with the 1Password Connect and Operator Helm chart, you must: > >
    >
  • [Sign up for 1Password](https://1password.com/pricing/password-manager).
  • >
  • Install [1Password CLI](/cli/get-started/).
  • >
  • Have a Kubernetes deployment. You can also use [minikube](https://minikube.sigs.k8s.io/docs/start/) to test locally.
  • >
  • Install [Helm.](https://helm.sh/)
  • >
  • Create a Secrets Automation workflow as a [Connect server](/connect/get-started/#step-1). You need the Connect server's `1password-credentials.json` file.
  • >
> [tab] Deploy manually with Connect > > Before you can deploy the Kubernetes Operator with a Kubernetes deployment specification file, you must: > >
    >
  • [Sign up for 1Password](https://1password.com/pricing/password-manager).
  • >
  • Install [1Password CLI](/cli/get-started/).
  • >
  • Have a Kubernetes deployment. You can also use [minikube](https://minikube.sigs.k8s.io/docs/start/) to test locally.
  • >
  • Create a Secrets Automation workflow as a [Connect server](/connect/get-started/#step-1). You need the Connect server's `1password-credentials.json` file.
  • >
> [tab] Deploy manually with a service account > > Before you can deploy the Kubernetes Operator with a service account, you must: > >
    >
  • [Sign up for 1Password](https://1password.com/pricing/password-manager).
  • >
  • Have a Kubernetes deployment. You can also use [minikube](https://minikube.sigs.k8s.io/docs/start/) to test locally.
  • >
## Limitations The Kubernetes Operator supports Connect servers and service accounts. Additionally, the Operator doesn't allow you to select secrets granularly or use multiple credentials simultaneously. For a complete comparison of features and functionality, see [Kubernetes integrations](/k8s/integrations/). ## Deployment There are two ways to deploy the Kubernetes Operator: 1. Using the 1Password Connect and Operator Helm chart. 2. Manually using a Kubernetes deployment specification file. > [!WARNING] > > The recommended way to deploy the Kubernetes Operator is with Helm. Deploying manually is a much more involved and complicated process. > [tab] Deploy with Helm > > The following instructions cover deploying the Kubernetes Operator using the [1Password Connect and Operator Helm chart](/k8s/helm/). > > You can use the 1Password Connect and Operator Helm chart to deploy the Kubernetes alongside Connect or without Connect. > > ### Step 1. Add the 1Password Helm chart repository > > The following command adds the [1Password Helm chart repository](https://github.com/1Password/connect-helm-charts) to your local instance of Helm. This allows you to download and install all charts from 1Password's GitHub repository. > > ```shell theme={null} > helm repo add 1password https://1password.github.io/connect-helm-charts/ > ``` > > ### Step 2. Install the Kubernetes Operator using Helm > > You can use the 1Password Connect and Operator Helm chart to deploy the Kubernetes Operator with Connect or without Connect. > > In most cases, it makes sense to deploy the Kubernetes Operator alongside Connect because it simplifies the setup and communication between Connect and the Operator. However, it might make more sense to deploy only the Kubernetes Operator if you already have a Connect deployment in production. > > > [tab] With Connect > > > > To install the Kubernetes Operator with Connect, use the following command. It deploys the Kubernetes Operator with a 1Password Connect server using the `1password-credentials.json` file. > > > > ```shell theme={null} > > helm install connect 1password/connect --set-file connect.credentials=1password-credentials.json --set operator.create=true --set operator.token.value=OP_CONNECT_TOKEN > > ``` > > > > If you don't already have a Connect token, use the following command instead. Make sure to replace `SERVER` and `VAULT` with the correct values. > > > > ```shell theme={null} > > helm install connect 1password/connect --set-file connect.credentials=1password-credentials.json --set operator.create=true --set operator.token.value=$(op connect token create --server SERVER --vault VAULT) > > ``` > > > [tab] Without Connect > > > > To install the Kubernetes Operator without Connect, set `operator.create` to `true` and `connect.create` to `false`. > > > > ```shell theme={null} > > helm install connect 1password/connect --set operator.create=true --set operator.token.value= --set connect.create=false > > ``` > > > > If you don't already have a Connect token, use the following command instead. Make sure to replace `SERVER` and `VAULT` with the correct values. > > > > ```shell theme={null} > > helm install connect 1password/connect --set operator.create=true --set operator.token.value=$(op connect token create --server SERVER --vault VAULT) --set connect.create=false > > ``` > > > [tab] With a service account > > > > To install the Kubernetes Operator with a service account, set `operator.create` to `true`, `connect.create` to `false`, and `operator.authMethod` to `service-account`. > > > > ```shell theme={null} > > helm install connect 1password/connect --set operator.create=true --set connect.create=false --set operator.authMethod=service-account --set operator.serviceAccountToken.value= > > ``` > [tab] Deploy manually with Connect > > The following instructions cover deploying the Kubernetes Operator manually, using a [Kubernetes deployment specification.](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) > > 1. [Create a deployment specification.](#manual-step-1) > 2. [Create a Kubernetes Secret from the Connect server credentials.](#manual-step-2) > 3. [Add the `MANAGE_CONNECT` environment variable.](#manual-step-3) > 4. [Create a Kubernetes Secret for the Connect server token.](#manual-step-4) > 5. [Deploy the Kubernetes Operator.](#manual-step-5) > > ### Step 1: Create a deployment specification > > 1. Create a [Kubernetes deployment specification](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) YAML file. You can use the example [`manager.yaml`](https://github.com/1Password/onepassword-operator/blob/main/config/manager/manager.yaml) file from the Kubernetes Operator repository on GitHub. > > You can also update an existing Kubernetes deployment specification to include the `1password/onepassword-operator` container image and options. > > ### Step 2: Create a Kubernetes Secret from the Connect server credentials > > 1. Encode the `1password-credentials.json` file you generated when you created your Connect server and name it `FILE_NAME`. > > ```shell theme={null} > cat 1password-credentials.json | base64 | \ tr '/+' '_-' | tr -d '=' | tr -d '\n' > FILE_NAME > ``` > > 2. Use `kubectl` to create a Kubernetes Secret from the encoded `FILE_NAME` file. > > ```shell theme={null} > kubectl create secret generic op-credentials --from-file=FILE_NAME > ``` > > ### Step 3: Add the `MANAGE_CONNECT` environment variable > > 1. Add the `MANAGE_CONNECT` environment variable to the Kubernetes Operator container (`onepassword-connect-operator`) in the deployment specification file and set it to `true`. > > The `MANAGE_CONNECT` environment variable tells the Kubernetes Operator to automatically deploy a default configuration of the 1Password Connect server to the current namespace. > > ```yaml deployment-specification.yaml theme={null} > - name: MANAGE_CONNECT > value: "true" > ``` > > ### Step 4: Create a Kubernetes Secret for the Connect server token > > Create a Kubernetes Secret for your Connect server token. Replace `OP_CONNECT_TOKEN` with the Connect token string or an environment variable that contains the Connect token string. > > ```shell theme={null} > kubectl create secret generic onepassword-token --from-literal=token="OP_CONNECT_TOKEN" > ``` > > > [!TIP] > > > > If you don't already have a Connect server token for the Kubernetes Operator, you can use the following command to create a token and save it as a Kubernetes Secret. > > > > ```shell theme={null} > > kubectl create secret generic onepassword-token --from-literal=token=$(op connect token create op-k8s-operator --server SERVER --vault VAULT) > > ``` > > > > Make sure to replace `SERVER` with the name (or ID) of the Connect server and `VAULT` with the name (or ID) of the vault. > > ### Step 5: Deploy the Kubernetes Operator and Connect server > > Finally, manually deploy the Kubernetes Operator by running `make deploy`. > > > [!WARNING] > > > > You must clone the [Kubernetes Operator repository](https://github.com/1Password/onepassword-operator) before you can manually deploy the Kubernetes Operator. > > 1. Clone the [Kubernetes Operator repository.](https://github.com/1Password/onepassword-operator) > > 2. Run `make deploy`. > > > [!TIP] > > > > Run the following command to check if the CRDs installed correctly: > > > > ```shell theme={null} > > kubectl get crd onepassworditems.onepassword.com > > ``` > [tab] Deploy manually with a service account > > To deploy the Kubernetes Operator with a service account, first [create a service account](/service-accounts/get-started/#create-a-service-account). Then follow these steps: > > ### 1. Create a Kubernetes secret for the service account > > 1. Set the `OP_SERVICE_ACCOUNT_TOKEN` environment variable to the service account token you created in step 1. This token will be used by the Operator to access 1Password items. > 2. Create a Kubernetes secret: > > ```shell theme={null} > kubectl create secret generic onepassword-service-account-token --from-literal=token="$OP_SERVICE_ACCOUNT_TOKEN" > ``` > > ### 2. Deploy the Operator > > To use the Operator with a service account, you need to set the `OP_SERVICE_ACCOUNT_TOKEN` environment variable in the `/config/manager/manager.yaml` file and remove the environment variables `OP_CONNECT_TOKEN` and `OP_CONNECT_HOST`. > > To configure the 1Password Kubernetes Operator, the following environment variables can be set in the Operator YAML file: > > * `OP_SERVICE_ACCOUNT_TOKEN` (required): Specifies a service account token within Kubernetes to access the 1Password items. > * `WATCH_NAMESPACE`: A comma-separated list of namespaces to watch for changes. The default is `watch all namespaces`. > * `POLLING_INTERVAL`: The number of seconds the 1Password Kubernetes Operator will wait before checking for updates from 1Password. The default is `600`. > * `AUTO_RESTART`: If set to true, the Operator will restart any deployment using a secret from 1Password. This can be overwritten by a namespace, deployment, or individual secret. The default is `false`. > > After you've set the environment variables, run the following command to deploy the Operator: > > ```shell theme={null} > make deploy > ``` > > You can view a sample YAML file [in the onepassword-operator repository on GitHub.](https://github.com/1Password/onepassword-operator/blob/main/config/manager/manager.yaml) ## Usage examples Use the following usage examples to help you get started: * [Create a Kubernetes Secret from a 1Password item](#kubernetes-secret-from-item) * [Deploy with a single Kubernetes Secret](#deploy-single) * [Ignore updates for a Kubernetes Secret](#ignore-updates) * [Enable automatic redeployment](#enable-auto-redeployment) * [Per Kubernetes Operator](#per-kubernetes-operator) * [Per namespace](#per-namespace) * [Per Kubernetes deployment](#per-kubernetes-deployment) * [Per OnePasswordItem](#per-onepassworditem) ### Create a Kubernetes Secret from a 1Password item With the Kubernetes Operator deployed, you can create [Kubernetes Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) from 1Password items by creating a YAML file and then using `kubectl` to deploy it to your Kubernetes cluster. The YAML file tells the Kubernetes Operator to create a Kubernetes Secret from a `OnePasswordItem` (a 1Password item) and specifies the item name and the path of the item. 1. Create a YAML file (`1password-item.yaml`) for the 1Password item using the following template. Replace `SECRET_NAME`, `VAULT`, and `ITEM` with the correct values for your 1Password item. * Replace `SECRET_NAME` with the name to use to create the Kubernetes Secret. * Replace `VAULT` with the name or ID of the vault. * Replace `ITEM` with the ID or title of the 1Password item. ```yaml 1password-item.yaml theme={null} apiVersion: onepassword.com/v1 kind: OnePasswordItem metadata: name: SECRET_NAME spec: itemPath: "vaults/VAULT/items/ITEM" ``` 2. Use `kubectl` to deploy the `1password-item.yaml` file. ```shell theme={null} kubectl apply -f 1password-item.yaml ``` ```shell theme={null} kubectl get secret 1password-item.yaml ``` > [!WARNING] > > If you delete the 1Password item you created, the Kubernetes Operator automatically deletes the corresponding Kubernetes Secret. #### Deploy with a single Kubernetes Secret You can also create a single Kubernetes Secret for a Kubernetes deployment by adding specific metadata to the deployment specification file and then applying it. 1. Add the following annotations to the deployment specification file: ```yaml deployment-specification.yaml theme={null} apiVersion: apps/v1 kind: Deployment metadata: name: deployment-example annotations: operator.1password.io/item-path: "vaults/VAULT/items/ITEM" operator.1password.io/item-name: "SECRET_NAME" ``` Replace `VAULT`, `ITEM`, and `SECRET_NAME`, with the correct values for your 1Password item. * Replace `VAULT` with the name or ID of the vault. * Replace `ITEM` with the ID or title of the 1Password item. * Replace `SECRET_NAME` with the name to use to create the Kubernetes Secret. 2. Apply the YAML file. This creates a Kubernetes Secret named `SECRET_NAME` with the content from the 1Password item specified in the `operator.1password.io/item-path`. ```shell theme={null} kubectl apply -f deployment-specification.yaml ``` ### Ignore updates for a Kubernetes Secret The Kubernetes Operator automatically keeps Kubernetes Secrets in sync with the corresponding 1Password items. If a 1Password Item linked to a Kubernetes Secret changes within the `POLLING_INTERVAL`, the associated Kubernetes Secret automatically updates. You can prevent a specific Kubernetes Secret from updating by adding the annotation `operator.1password.io:ignore-secret` to the item stored in 1Password. While this annotation is in place, the Kubernetes Secret won't update when the associated 1Password item updates. ### Enable automatic redeployment The Kubernetes Operator supports automatic redeployment, which automatically restarts Kubernetes deployments when it detects that a 1Password item linked to a Kubernetes Secret has been updated. When enabled, the Kubernetes Operator restarts Kubernetes deployments that meet the following criteria each time the Connect server polls for updates: * Its scope is configured to automatically restart. * It's using a Kubernetes Secret linked to a 1Password item that's been updated. You can configure automatic redeployment for different scopes: * [Per Kubernetes Operator](#per-kubernetes-operator) * [Per namespace](#per-namespace) * [Per Kubernetes deployment](#per-kubernetes-deployment) * [Per OnePasswordItem](#per-onepassworditem) When you configure automatic deployment in a scope (such as per namespace), the configuration applies to all downstream scopes unless you explicitly specify a different configuration for the scope. #### Per Kubernetes Operator You can configure automatic redeployment per Kubernetes Operator, which includes all Kubernetes deployments within the namespaces watched by the Kubernetes Operator instance. The Kubernetes Operator automatic redeployment setting is controlled by the `AUTO_RESTART` environment variable. By default, it's set to `false`. To enable automatic redeployment, set it to `true`. #### Per namespace You can configure automatic redeployment per namespace, which includes all Kubernetes deployments within the namespace. * To turn on automatic redeployment for all Kubernetes deployments within a namespace, set the `operator.1password.io/auto-restart` annotation to `true`. * To turn off automatic redeployment for all Kubernetes deployments within a namespace, set the `operator.1password.io/auto-restart` annotation to `false`. Each namespace uses the Kubernetes Operator setting for automatic redeployment if you don't set the `operator.1password.io/auto-restart` annotation value. The following code block shows an example namespace configuration with automatic redeployment enabled for all Kubernetes deployments within the namespace. ```yaml deployment-specification.yaml highlight={6} theme={null} apiVersion: v1 kind: Namespace metadata: name: "example-namespace" annotations: operator.1password.io/auto-restart: "true" ``` #### Per Kubernetes deployment You can configure automatic redeployment per individual Kubernetes deployment: * To turn on automatic redeployment for a specific Kubernetes deployment, set the `operator.1password.io/auto-restart` annotation to `true`. * To turn off automatic redeployment for a specific Kubernetes deployment, set the `operator.1password.io/auto-restart` annotation to `false`. Each Kubernetes deployment uses the namespace setting for automatic redeployment if you don't set the `operator.1password.io/auto-restart` annotation value. The following code block shows an example deployment configuration with automatic redeployment enabled. ```yaml deployment-specification.yaml highlight={6} theme={null} apiVersion: v1 kind: Deployment metadata: name: "example-deployment" annotations: operator.1password.io/auto-restart: "true" ``` #### Per OnePasswordItem You can configure automatic redeployment for a specific 1Password item (`OnePasswordItem`) custom resource: * To turn on automatic redeployment for a specific 1Password item custom resource, set the `operator.1password.io/auto-restart` annotation value to `true`. * To turn off automatic redeployment for a specific 1Password item custom resource, set the `operator.1password.io/auto-restart` annotation value to `false`. Each 1Password item (`OnePasswordItem`) uses the Kubernetes deployment setting for automatic redeployment if you don't set the `operator.1password.io/auto-restart` annotation value. The following code block shows an example of a 1Password item configuration with automatic redeployment enabled. ```yaml deployment-specification.yaml highlight={6} theme={null} apiVersion: onepassword.com/v1 kind: OnePasswordItem metadata: name: example annotations: operator.1password.io/auto-restart: "true" ``` ## Behavior The 1Password Kubernetes Connect Operator follows the Kubernetes Operator pattern. It uses Controllers, which provide a reconcile function that synchronizes resources until it reaches the desired cluster state. Visit the Kubernetes documentation to learn more about the [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) and [Controllers.](https://kubernetes.io/docs/concepts/architecture/controller/) The information in this section documents some of the behavior of the Kubernetes Operator in specific scenarios. * [Deployment deletion](#deployment-deletion) * [Fields storing files](#fields-storing-files) * [Whitespace characters](#whitespace-characters) ### Deployment deletion Deleting the Deployment you've created deletes the Kubernetes Secret deployment if all the following are true: 1. The deployment has the `operator.1password.io/item-path` and `operator.1password.io/item-name` annotations. 2. No other deployments are using the secret. ### Fields storing files If a 1Password item field stores a file, the corresponding Kubernetes Secret uses the file's contents as the value. If a single 1Password item has a field storing a file and a field storing another type of data, the Kubernetes Operator prefers the non-file field and ignores the field containing a file. ### Whitespace characters Titles and field names that include whitespace characters (or any other characters invalid for DNS subdomain names) result in the Kubernetes Operator changing the titles (or fields) in the following manner when creating Kubernetes Secrets: * Remove invalid characters before the first alphanumeric character. * Remove invalid characters after the last alphanumeric character. * Replace whitespace characters between words with a dash (`-`). * Convert letters to lowercase. ## Configuration The following section describes the Kubernetes Operator (`1password/onepassword-operator`) container configuration options and their default values. The [example Kubernetes deployment specification file](https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure/#define-container-environment-variables-using-secret-data) shows these configuration values in context. ### Environment variables | **Environment variable** | **Description** | **Required** | **Default value** | | - | - | - | - | | `OP_CONNECT_HOST` | The hostname of the Connect server within Kubernetes. | Yes | `http://onepassword-connect:8080` | | `WATCH_NAMESPACE` | A comma-separated list of namespaces to watch for changes. By default, it watches all namespaces. | No | default (watch all namespaces) | | `POLLING_INTERVAL` | The number of seconds the Kubernetes Operator should wait before checking for updates from the Connect server. | No | `600` | | `MANAGE_CONNECT` | Whether or not the Kubernetes Operator should deploy with the Connect server in the current namespace with the default configuration. | No | `false` | | `AUTO_RESTART` | Whether or not the Kubernetes Operator should redeploy when it detects a secret change from the Connect server. You can overwrite this value by namespace, deployment, or individual secret. | No | `false` | | `OP_CONNECT_TOKEN` | A reference to the Kubernetes Secret that contains your Connect server token. | Yes | [secretKeyRef](https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure/#define-container-environment-variables-using-secret-data) | ### Command arguments | **Argument** | **Description** | **Default value** | | - | - | - | | `--zap-log-level` | Specify the logging level of detail for the Kubernetes Operator. The available options are `debug`, `info`, and `error`. | `debug` | # Open source at 1Password Source: https://www.1password.dev/open-source Browse 1Password's open source SDKs, shell plugins, CI/CD and infrastructure integrations, AI agent tools, and libraries, and learn how to contribute. We build many of our developer tools in the open. Use them in your projects, report issues, and send pull requests. Everything below lives on [GitHub](https://github.com/1Password). > [card] [Contribute a shell plugin](/cli/shell-plugins/contribute) > > Add biometric sign-in for a CLI you use. Our most active place for community contributions. > [card] [1Password for Open Source](https://github.com/1Password/for-open-source) > > Maintain an open source project? Apply for a free 1Password team account. > [card] [Share your project](https://github.com/1Password/developer-community-projects) > > Built something with 1Password? Add it to the community projects directory. ## Developer tools | Project | What it does | | - | - | | [shell-plugins](https://github.com/1Password/shell-plugins) | Biometric authentication for third-party CLIs like AWS, GitHub, and Stripe. | | [op-vscode](https://github.com/1Password/op-vscode) | 1Password for VS Code: find plaintext secrets and replace them with secret references. | | [op-js](https://github.com/1Password/op-js) | A JavaScript library powered by 1Password CLI. | ## SDKs | Project | What it does | | - | - | | [onepassword-sdk-go](https://github.com/1Password/onepassword-sdk-go) | The official Go SDK for 1Password. | | [onepassword-sdk-js](https://github.com/1Password/onepassword-sdk-js) | The official JavaScript SDK for 1Password. | | [onepassword-sdk-python](https://github.com/1Password/onepassword-sdk-python) | The official Python SDK for 1Password. | | [connect-sdk-go](https://github.com/1Password/connect-sdk-go) | Go SDK for 1Password Connect. | | [connect-sdk-js](https://github.com/1Password/connect-sdk-js) | Node SDK for 1Password Connect. | | [connect-sdk-python](https://github.com/1Password/connect-sdk-python) | Python SDK for 1Password Connect. | ## CI/CD and infrastructure | Project | What it does | | - | - | | [load-secrets-action](https://github.com/1Password/load-secrets-action) | Load secrets from 1Password into GitHub Actions jobs. | | [install-cli-action](https://github.com/1Password/install-cli-action) | Install 1Password CLI in GitHub Actions jobs. | | [secrets-orb](https://github.com/1Password/secrets-orb) | Load secrets from 1Password in CircleCI. | | [terraform-provider-onepassword](https://github.com/1Password/terraform-provider-onepassword) | Reference, create, and update 1Password items from Terraform. | | [pulumi-onepassword](https://github.com/1Password/pulumi-onepassword) | Pulumi provider for 1Password. | | [onepassword-operator](https://github.com/1Password/onepassword-operator) | Sync 1Password items to Kubernetes Secrets and restart deployments when they change. | | [kubernetes-secrets-injector](https://github.com/1Password/kubernetes-secrets-injector) | A mutating webhook that injects 1Password secrets as environment variables into Kubernetes pods. | | [connect-helm-charts](https://github.com/1Password/connect-helm-charts) | Official Helm charts for 1Password Connect and the Kubernetes Operator. | | [ansible-onepasswordconnect-collection](https://github.com/1Password/ansible-onepasswordconnect-collection) | Ansible modules for 1Password Connect. | | [vault-plugin-secrets-onepassword](https://github.com/1Password/vault-plugin-secrets-onepassword) | A HashiCorp Vault plugin for 1Password Connect. | ## AI agents | Project | What it does | | - | - | | [agent-hooks](https://github.com/1Password/agent-hooks) | A collection of hooks for AI agents, including validation for locally mounted .env files. | | [1password-claude-plugin](https://github.com/1Password/1password-claude-plugin) | 1Password Developer Environments as a Claude desktop extension (MCPB) for macOS. | | [cursor-plugin](https://github.com/1Password/cursor-plugin) | The official 1Password plugin for Cursor: .env validation hooks, an agent skill, and MCP configuration. | | [1password-codex-plugin](https://github.com/1Password/1password-codex-plugin) | A Codex plugin for the 1Password Developer Environments MCP server. | | [1password-kiro-plugin](https://github.com/1Password/1password-kiro-plugin) | A Kiro plugin for the 1Password Developer Environments MCP server. | | [agent-identity-specs](https://github.com/1Password/agent-identity-specs) | The Internet-Draft for 1Password's local delegated agent identity architecture. | | [SCAM](https://github.com/1Password/SCAM) | An open benchmark that tests AI agents' security awareness during realistic workplace tasks. | ## Events API and provisioning | Project | What it does | | - | - | | [events-api-elastic](https://github.com/1Password/events-api-elastic) | Send 1Password events to Elastic. | | [events-api-splunk](https://github.com/1Password/events-api-splunk) | Send 1Password events to Splunk. | | [events-api-generic](https://github.com/1Password/events-api-generic) | Example scripts for calling the Events API. | | [scim-examples](https://github.com/1Password/scim-examples) | Deployment examples for 1Password SCIM Bridge. | ## Libraries and security research | Project | What it does | | - | - | | [typeshare](https://github.com/1Password/typeshare) | Synchronize type definitions between Rust and other languages. | | [passkey-rs](https://github.com/1Password/passkey-rs) | A Rust framework for WebAuthn authenticators that support passkeys. | | [credential-exchange](https://github.com/1Password/credential-exchange) | Rust libraries for the Credential Exchange specifications. | | [arboard](https://github.com/1Password/arboard) | A cross-platform clipboard library for Rust. | | [electron-hardener](https://github.com/1Password/electron-hardener) | A Rust library that makes Electron apps more secure. | | [srp](https://github.com/1Password/srp) | Go functions for the Secure Remote Password protocol. | | [spg](https://github.com/1Password/spg) | 1Password's strong password generator as a Go package. | | [password-manager-resources](https://github.com/1Password/password-manager-resources) | Password rules and quirks for websites, shared across password managers. | ## Get help * Ask questions in the [Developer Slack](/joinslack). * Report bugs and request features with GitHub issues on each project. * Report security vulnerabilities privately, following the security policy in each repository. Don't open public issues for them. * See the [developer community](/community) for events, the newsletter, and more. # 1Password Partnership API reference Source: https://www.1password.dev/partnership-api/reference As a 1Password partner, use the Partnership API to create, look up, change the end date of, and delete the billing accounts you provide to your customers. It works with 1Password individual and family accounts, not team or business accounts. > [card] [Try the API in your browser](/partnership-api/reference/get-billing-account) > > Paste your token, pick the test server, and send a real request from the docs. No code needed. > [!NOTE] > > To work with the 1Password Partnership API in another tool, download the API specification file: [1password-partnership-api.yml](https://i.1password.com/media/1password-partnership-api/partnership-api.yml). ## Prerequisites Before you can use the API to integrate with our partner billing service, you'll need to register as a 1Password partner. Registered partners are granted access to bearer tokens to authorize requests to the API billing servers. To learn more about our partnership opportunities, visit the [1Password Partner Program website](https://1password.com/partnerships) or [contact the 1Password Partnerships team](mailto:partners@1password.com). If you're not a partner, reach out to your Customer Success Manager or the [1Password Sales team](https://1password.com/contact-us). ## Try it in the docs Every endpoint has a **Try it** panel. Paste your bearer token and send a real request from your browser. **1. Use your test token** The Partnership team gives you separate tokens for the test and production environments. Use your test token while you explore. See [Authorization](#authorization). **2. Start with a read-only call** Open [Get billing account information](/partnership-api/reference/get-billing-account). It reads an account without changing it. **3. Pick the test server and paste your token** Select **Try it**, choose the test server (billing.b5test.eu), and paste your token in the **Authorization** field. **4. Send it, then copy the code** Select **Send** to see the live response. The example panel turns the same request into cURL, Python, JavaScript, Go, and more. > [!WARNING] > > Create, update, and delete calls change real billing accounts. Only send them to production when you mean to. ## Information about the API The 1Password Partnership API is a REST-style API that follows the [OpenAPI 3.0 specifications.](https://spec.openapis.org/oas/v3.0.3) All communication between clients and servers is over HTTPS. You can use your preferred programming language and tools for testing and implementing the Partnership API. This reference uses [curl](https://curl.se/) on the command line to demonstrate example requests. You can replace the values in any request with your own to receive information about your customers' billing accounts. ### Request methods You can use the following standard HTTP methods to make requests to the Partnership API: * [POST](/partnership-api/reference/create-billing-account): Create a third-party billing account for a customer through the partner billing service. * [GET](/partnership-api/reference/get-billing-account): Get details about a customer's billing account. * [DELETE](/partnership-api/reference/delete-billing-account): Delete a customer's third-party billing account from the partner billing service. * [PATCH](/partnership-api/reference/update-billing-account-end-date): Update the date and time a customer's billing account is scheduled be removed from the partner billing service. Batch requests are not supported. ### Servers There are two billing servers partners can use to work with the 1Password Partnership API that provide the base URLs of the API endpoints: * **Test server** (`https://billing.b5test.eu`): Use the test server URL as the base for all requests in the test environment. You can provision and deprovision test partner billing accounts for all domains from the test server: **b5test.com**, **b5test.ca**, and **b5test.eu.** * **Production server** (`https://billing.1password.com`): Use the production server URL as the base for all requests in the production environment. You can provision and deprovision partner billing accounts for all domains from the production server: **1password.com**, **1password.ca**, and **1password.eu**. ### Endpoints Each request to the API starts with the base URL of the server environment you want to work with (test or production), followed by the path (`api/v1/partners/account`). Path parameters, indicated with curly braces (`{}`), are required where defined. For example: ```text Structure of an API endpoint theme={null} //{parameters} ``` Replace the `base_URL` and `\{parameters}` placeholders with the server environment you're using and any path parameters specified for the request. The `path` is the same for all requests. ```text Example API endpoint without a path parameter theme={null} https://billing.b5test.eu/api/v1/partners/accounts ``` ```text Example API endpoint with a path parameter theme={null} https://billing.1password.com/api/v1/partners/accounts/4266474b-6385-56d4-7b75-648096593064 ``` ### Authorization When you register with the [1Password Partner Program](https://1password.com/partnerships), the Partnership team will provide you with bearer tokens you'll need to authorize your calls to the Partnership API. You'll receive separate tokens to use with [the test and production environments](#servers). Make sure to use the token that has been authorized for the environment you're working in. If you're a partner and need a new bearer token, [contact the 1Password Partnerships team](mailto:partners@1password.com). If you're not a partner, reach out to your Customer Success Manager or the [1Password Sales team](https://1password.com/contact-us) and let them know you need a new bearer token. ### Request headers Requests to the Partnership API use three types of headers: * **`Authorization`**: Each GET, POST, DELETE, and PATCH request to the Partnership API must be authorized with a [bearer token](#authorization). * **`Content-Type`**: Each POST and PATCH request requires a header to indicate the media (MIME) type of the request body. * **`Accept`**: Each GET, POST, and PATCH request to the Partnership API should include an accept header to indicate what kind of response the client can accept from the server. All data is sent and received as JSON, so make sure to specify that in the headers. ``` Authorization: Bearer YOUR_BEARER_TOKEN Content-type: application/json Accept: application/json ``` If you're a partner and need a new bearer token, [contact the 1Password Partnerships team](mailto:partners@1password.com). If you're not a partner, reach out to your Customer Success Manager or the [1Password Sales team](https://1password.com/contact-us) and let them know you need a new bearer token. ### Request bodies Request bodies (also called request payloads) contain the JSON-formatted data clients send to create (POST) or update (PATCH) resources on the servers. A request body consists of an object that may include one or more of the following fields, as indicated: * **The unique identifier (UID) for the customer's billing account.** The UID is supplied by the partner. It can be up to 200 characters long with any combination of alphanumeric characters (`A-Z`, `a-z`, `0-9`), hyphens (`-`), and periods/dots (`.`) . * **The 1Password account type.** Options are individual (`I`) or family (`F`). Team and business accounts aren't supported. * **The domain the customer can use for their new or existing 1Password account.** For the test server, options are: `b5test.com`, `b5test.ca`, or `b5test.eu`. For the production server, options are: `1password.com`, `1password.ca`, or `1password.eu`. * **The date and time the customer's billing account is scheduled to be removed.** The date cannot be in the past. Format the date, time, and optional timezone in the [ISO 8601 standard.](https://www.iso.org/iso-8601-date-and-time-format.html) GET and DELETE calls don't contain request bodies. ### Activation tokens Activation tokens are used to provision customers to third-party billing by linking 1Password accounts to partner billing accounts. Make a [POST call](/partnership-api/reference/create-billing-account) to the Partnership API to create a new partner billing account for a customer and generate their unique activation token. Append the token returned in the [POST response](/partnership-api/reference/create-billing-account) to a 1Password partnership redemption link to [create the customer's partner billing link](#create-a-link-for-customers). Then provide the customer with their link. The link will direct the customer to a promotional page where they'll be instructed to create a new 1Password account or sign in to an existing one. The billing for the customer's 1Password account will then be linked to their partner billing account. #### Create a link for customers To create a partner billing link for a customer, adjust the 1Password partnership redemption link (`https://start.[1password_domain]/partnership/redeem`) to use the desired 1Password domain. Then append a query string with the required parameters for the account type and the activation token. You can also include an optional [language parameter](#language-code-parameters). ```text Structure of a partner billing link for a 1Password account theme={null} https://start.[1password_domain]/partnership/redeem?t={account_type}&c={activation_token}&l={language_code} ``` | Placeholder | Values | Required | | - | - | - | | `[1password_domain]` | Possible values are `1password.com`, `1password.ca`, or `1password.eu`. | Yes | | `\{account_type}` | Possible values are `individual` or `family`. | Yes | | `\{activation_token}` | The value of the token returned in the [POST response](/partnership-api/reference/create-billing-account). For example: `4266474b-6385-56d4-7b75-648096593064`. | Yes | | `\{language_code}` | Optional [language code](#language-code-parameters) values are `en`, `de`, `es`, `fr`, `it`, `ja`, `ko`, `nl`, `pt-BR`, `ru`, `zh-Hans`, or `zh-Hant`. | No | Replace the placeholders for the 1Password domain and the parameters with the appropriate values. For example: ```text Example partner billing link for an individual account on 1Password.eu with an optional language parameter theme={null} https://start.1password.eu/partnership/redeem?t=individual&c=4266474b-6385-56d4-7b75-648096593064&l=de ``` ```text Example partner billing link for a family account on 1Password.com with an optional language parameter theme={null} https://start.1password.com/partnership/redeem?t=family&c=4266474b-6385-56d4-7b75-648096593064&l=en ``` If you're not sure which link(s) you need to create, [contact the 1Password Partnerships team](mailto:partners@1password.com) for help. > [!WARNING] > > For customers with existing 1Password accounts, partner billing links will only work if their 1Password account type and domain are the same as the ones specified in the [POST request](/partnership-api/reference/create-billing-account). > > Customers can [contact 1Password Support](https://support.1password.com/contact/) if they need help to change their existing [account type](https://support.1password.com/change-account-type/) or [region](https://support.1password.com/regions/#change-your-region). #### Alternate partner billing link options > [accordion] Learn more about alternate link options. > > The Partnership API also supports some alternate options for partner billing links. Depending on the details of your partnership, you might prefer to create links for: > > * [A new 1Password account only](#create-a-link-for-a-new-1password-account-only) > * [An existing 1Password account only](#create-a-link-for-an-existing-1password-account-only) > > If you provide a customer with one of these links, they'll only be able to use it to link their partner billing account to either a new account or an existing account, respectively. > > You can also create one link of each type and provide your customers with both so they can choose the option they need. However, creating a [single link](#create-a-link-for-customers) that allows for both options may be a better solution. > > ##### Create a link for a new 1Password account only > > To create a partner billing link for a customer to use with a new 1Password account only, adjust the 1Password sign-up link (`https://start.[1password_domain]/sign-up/[account_type]`) to use the desired 1Password domain and account type. Then append a query string with the required activation token parameter. You can also include an optional [language parameter](#language-code-parameters). For example: > > ```text Structure of a partner billing link for a new 1Password account theme={null} > https://start.[1password_domain]/sign-up/[account_type]?c={activation_token}&l={language_code} > ``` > > Replace the [placeholders](#placeholder-reference) for the 1Password domain, account type, and the parameters with the appropriate values. For example: > > ```text Example partner billing link for a new individual account on 1Password.eu with an optional language parameter theme={null} > https://start.1password.eu/sign-up/individual?c=4266474b-6385-56d4-7b75-648096593064&l=de > ``` > > ```text Example partner billing link for a new family account on 1Password.com with an optional language parameter theme={null} > https://start.1password.com/sign-up/family?c=4266474b-6385-56d4-7b75-648096593064&l=en > ``` > > ##### Create a link for an existing 1Password account only > > To create a partner billing link for a customer to use with an existing 1Password account only, adjust the 1Password account sign-in link (`https://my.[1password_domain]/partnership/link`) to use the desired 1Password domain. Then append a query string with the required activation token parameter. You can also include an optional [language parameter](#language-code-parameters). For example: > > ```text Structure of a partner billing link for an existing 1Password account theme={null} > https://my.[1password_domain]/partnership/link?c={activation_token}&l={language_code} > ``` > > Replace the [placeholders](#placeholder-reference) for the 1Password domain and the parameters with the appropriate values. For example: > > ```text Example partner billing link for an existing account on 1Password.com with an optional language parameter theme={null} > https://my.1password.com/partnership/link?c=4266474b-6385-56d4-7b75-648096593064&l=en > ``` > > This link doesn't include an account type because it directs the customer to sign in to the 1Password account they already have. > > ##### Placeholder reference > > | Placeholder | Values | Required | > | - | - | - | > | `[1password_domain]` | Possible values are `1password.com`, `1password.ca`, or `1password.eu`. | Yes | > | `[account_type]` | The account type is only used with links to [create a new 1Password account](#create-a-link-for-a-new-1password-account-only). Possible values are `individual` or `family`. | Yes For new accounts only | > | `\{activation_token}` | The value of the token returned in the [POST response](/partnership-api/reference/create-billing-account). For example: `4266474b-6385-56d4-7b75-648096593064`. | Yes | > | `\{language_code}` | Optional [language code](#language-code-parameters) values are `en`, `de`, `es`, `fr`, `it`, `ja`, `ko`, `nl`, `pt-BR`, `ru`, `zh-Hans`, or `zh-Hant`. | No | #### Language code parameters > [accordion] Learn more about optional language code parameters. > > Language codes are an optional parameter that can be added to a [partner billing link](#create-a-link-for-customers) to take the customer to the appropriate landing page for that language. Customers will be directed to the default landing page (English) if no language parameter is included. > > The following language codes can be used with the language parameter: > > | Language | Code | > | - | - | > | English | `en` | > | Deutsch | `de` | > | Español | `es` | > | Français | `fr` | > | Italiano | `it` | > | 日本語 | `ja` | > > | Language | Code | > | - | - | > | 한국어 | `ko` | > | Nederlands | `nl` | > | Português | `pt-BR` | > | Русский | `ru` | > | 简体中文 | `zh-Hans` | > | 繁體中文 | `zh-Hant` | ## Endpoint reference Each endpoint has its own reference page with parameters, example requests and responses, error codes, and a **Try it** panel: * [Create a billing account](/partnership-api/reference/create-billing-account) * [Get billing account information](/partnership-api/reference/get-billing-account) * [Delete a billing account](/partnership-api/reference/delete-billing-account) * [Update a billing account end date](/partnership-api/reference/update-billing-account-end-date) # Create billing account Source: https://www.1password.dev/partnership-api/reference/create-billing-account /openapi/partnership_api.yaml post /api/v1/partners/accounts Begins provisioning process for a new partner associated 1Password account. # Delete billing account Source: https://www.1password.dev/partnership-api/reference/delete-billing-account /openapi/partnership_api.yaml delete /api/v1/partners/accounts/{customer_account_uid} Removes an account from the partnership domain. # Get billing account Source: https://www.1password.dev/partnership-api/reference/get-billing-account /openapi/partnership_api.yaml get /api/v1/partners/accounts/{customer_account_uid} Returns an account based on an UID. # Update billing account end date Source: https://www.1password.dev/partnership-api/reference/update-billing-account-end-date /openapi/partnership_api.yaml patch /api/v1/partners/accounts/{customer_account_uid} Updates the ends_at attribute of an account based on an UID. # Postman Source: https://www.1password.dev/postman # Use the 1Password provider for Pulumi Source: https://www.1password.dev/pulumi You can use the [1Password provider for Pulumi](https://www.pulumi.com/registry/packages/onepassword/) to access and manage items in your 1Password vaults. ## Requirements The provider can be configured to authenticate with a service account, a Connect server, or with your 1Password account details. > [tab] Service account > > [1Password Service Accounts](/service-accounts/) allow you to restrict the provider's access to specific vaults in your 1Password account, so you can follow the principle of least privilege in your project. > > To use a service account with the 1Password provider for Pulumi, you'll need: > > * [1Password subscription](https://1password.com/pricing/password-manager) > * [1Password CLI](/cli/get-started) > * [1Password service account](/service-accounts/get-started) > [tab] Connect server > > [1Password Connect Servers](/connect/) are a good authentication option when you need unlimited requests and use self-hosted infrastructure. > > Connect servers allow you to restrict the provider's access to specific vaults in your 1Password account, so you can follow the principle of least privilege in your project. > > To use a Connect server with the 1Password provider for Pulumi, you'll need: > > * [1Password subscription](https://1password.com/pricing/password-manager) > * [1Password Connect server](/connect/get-started/#step-1) > [tab] Account details > > When you configure the provider with your 1Password account details, the provider can access any vault in your account, and you can use Touch ID, Windows Hello, or another system authentication option with the provider. > > To use your account details with the 1Password provider for Pulumi, you'll need: > > * [1Password subscription](https://1password.com/pricing/password-manager) > * [1Password CLI](/cli/get-started) > * [1Password desktop app\*](https://1password.com/downloads/) > * [1Password app integration\*](/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration) > > \* To authenticate with Touch ID, Windows Hello, or another system authentication option. ## Step 1: Install the 1Password provider for Pulumi ### With a package manager > [tab] Node.js > > To use the provider with JavaScript or TypeScript in Node.js, install using either `npm` or `yarn`: > > npm install @1password/pulumi-onepassword > > yarn add @1password/pulumi-onepassword > [tab] Python > > To use the provider with Python, install using `pip`: > > ```shell theme={null} > pip install pulumi_onepassword > ``` > [tab] Go > > To use the provider with Go, use `go get` to download the latest version: > > ```shell theme={null} > go get github.com/1Password/pulumi-onepassword/sdk/go/... > ``` ### With the provider binary To install the 1Password provider binary, use the [`pulumi plugin`](https://www.pulumi.com/docs/cli/commands/pulumi_plugin/) command: ```shell theme={null} pulumi plugin install resource onepassword --server github://api.github.com/1Password/pulumi-onepassword ``` ## Step 2: Configure the provider with your credentials You can provide your 1Password credentials to Pulumi in the environment or in your Pulumi configuration. Your Pulumi configuration is a good option if you want to store your credentials alongside your Pulumi stack for multi-user access. > [tab] Service account > > 1. [Create a service account](https://start.1password.com/developer-tools/infrastructure-secrets/serviceaccount/) or find the token for an existing service account. Make sure the service account has access to the appropriate vaults and adequate permissions in those vaults. > > 2. Provide the token to Pulumi using either an environment variable or your Pulumi configuration. > > #### Environment variable > > export OP\_SERVICE\_ACCOUNT\_TOKEN=\\\ > > set -x OP\_SERVICE\_ACCOUNT\_TOKEN=\ > > \$Env:OP\_SERVICE\_ACCOUNT\_TOKEN=\ > > #### Pulumi configuration > > ```shell theme={null} > pulumi config set pulumi-onepassword:service_account_token --secret > #code-result > Value: > ``` > > Make sure to pass `--secret` when setting sensitive data. > > 3. Install [1Password CLI](/cli/get-started) in your PATH. If you install the CLI outside of your PATH, specify the path to your 1Password CLI binary using either an environment variable or your Pulumi configuration. > > #### Environment variable > > export OP\_CLI\_PATH=\\\ > > set -x OP\_CLI\_PATH=\ > > \$Env:OP\_CLI\_PATH=\ > > #### Pulumi configuration > > ```shell theme={null} > pulumi config set pulumi-onepassword:op_cli_path --secret > #code-result > Value: > ``` > [tab] Connect server > > 1. [Create a Connect server](/connect/get-started/#step-1) or find the host URL and token for an existing Connect server. > 2. Provide the host URL and token to Pulumi using either environment variables or your Pulumi configuration. > > #### Environment variables > > > [tab] Bash, Zsh, sh > > > > **Host URL** > > > > ```shell theme={null} > > export OP_CONNECT_HOST= > > ``` > > > > **Token** > > > > ```shell theme={null} > > export OP_CONNECT_TOKEN= > > ``` > > > [tab] fish > > > > **Host URL** > > > > ```shell theme={null} > > set -x OP_CONNECT_HOST= > > ``` > > > > **Token** > > > > ```shell theme={null} > > set -x OP_CONNECT_TOKEN= > > ``` > > > [tab] PowerShell > > > > **Host URL** > > > > ```shell theme={null} > > $Env:OP_CONNECT_HOST= > > ``` > > > > **Token** > > > > ```shell theme={null} > > $Env:OP_CONNECT_TOKEN= > > ``` > > #### Pulumi configuration > > **Host URL** > > ```shell theme={null} > pulumi config set pulumi-onepassword:url --secret > #code-result > Value: > ``` > > **Token** > > ```shell theme={null} > pulumi config set pulumi-onepassword:token --secret > #code-result > Value: > ``` > > Make sure to pass `--secret` when setting sensitive data. > [tab] Account details > > 1. Find the [sign-in address](https://support.1password.com/1password-glossary/#sign-in-address) or [unique identifier](/cli/reference/#unique-identifiers-ids) for your 1Password account. > > 2. Provide your account sign-in address or identifier to Pulumi using an environment variable or your Pulumi configuration. > > #### Environment variable > > > [tab] Bash, Zsh, sh > > > > ```shell theme={null} > > export OP_ACCOUNT= > > ``` > > > [tab] fish > > > > ```shell theme={null} > > set -x OP_ACCOUNT= > > ``` > > > [tab] PowerShell > > > > ```powershell theme={null} > > $Env:OP_ACCOUNT= > > ``` > > #### Pulumi configuration > > ```shell theme={null} > pulumi config set pulumi-onepassword:account --secret > #code-result > Value: > ``` > > Make sure to pass `--secret` when setting sensitive data. > > 3. Install [1Password CLI](/cli/get-started) in your PATH. If you install the CLI outside of your PATH, specify the path to your 1Password CLI binary using either an environment variable or your Pulumi configuration. > > #### Environment variable > > > [tab] Bash, Zsh, sh > > > > ```shell theme={null} > > export OP_CLI_PATH= > > ``` > > > [tab] fish > > > > ```shell theme={null} > > set -x OP_CLI_PATH= > > ``` > > > [tab] PowerShell > > > > ```powershell theme={null} > > $Env:OP_CLI_PATH= > > ``` > > #### Pulumi configuration > > ```shell theme={null} > pulumi config set pulumi-onepassword:op_cli_path --secret > #code-result > Value: > ``` > > 4. To use Touch ID, Windows Hello, or another system authentication option with the provider, [turn on the 1Password CLI app integration](/cli/get-started#step-2-turn-on-the-1password-desktop-app-integration). ## Step 3: Use the provider See [Pulumi's documentation](https://www.pulumi.com/registry/packages/onepassword/) to learn how to access and manage your items using the 1Password provider. ## Reference You can use either [Pulumi configuration keys](https://www.pulumi.com/docs/concepts/config/) or environment variables to provide your 1Password credentials to Pulumi. | Configuration key | Environment variable | Description | Authentication method | | - | - | - | - | | `pulumi-onepassword:service_account_token` | `OP_SERVICE_ACCOUNT_TOKEN` | The string value of your [1Password Service Account](/service-accounts/get-started) token. | Service account | | `pulumi-onepassword:url` | `OP_CONNECT_HOST` | The URL where your [1Password Connect Server](/connect/) can be found. For example: `http://localhost:8080`. | Connect server | | `pulumi-onepassword:token` | `OP_CONNECT_TOKEN` | The string value of your [Connect server token](/connect/concepts#connect-server-access-token). | Connect server | | `pulumi-onepassword:account` | `OP_ACCOUNT` | A 1Password account [sign-in address](https://support.1password.com/1password-glossary/#sign-in-address) or [unique identifier](/cli/reference/#unique-identifiers-ids). | Account details | | `pulumi-onepassword:op_cli_path` | `OP_CLI_PATH` | The [path to your 1Password CLI binary](/cli/config-directories). Only required if 1Password CLI binary is located outside of your PATH. |
  • Service account
  • Account details
| # Pulumi ESC Source: https://www.1password.dev/pulumi-esc # 1Password SaaS Manager API Source: https://www.1password.dev/saas-manager-api Use the SaaS Manager REST API to read and manage your applications, people, teams, contracts, devices, workflows, and audit log from your own code. > [card] [Try the API in your browser](/saas-manager-api/reference/people/list-people) > > Paste your token, pick your region, and send a real request from the docs. No code needed. The conventions below apply to every endpoint. Endpoints are grouped by area in the sidebar. ## Regions and base URL SaaS Manager is hosted in multiple regions. Choose a base URL for your tenant's region from the Servers dropdown: * `https://app.trelica.com` (United States) * `https://eu.trelica.com` (Europe) Endpoint URLs throughout this reference use whichever server you select. ## Authentication Every request must send an Authorization header carrying an OAuth 2.0 access token, prefixed with `Bearer`: ``` Authorization: Bearer ``` Obtain a token using either the Client Credentials flow (machine-to-machine) or the Authorization Code flow (acting on behalf of a user). The scopes granted to your token determine which endpoints you may call. Learn more in [scopes](#scopes). Access tokens expire. When a token is missing, invalid, or expired, you'll receive `401 Unauthorized`. Inspect the `WWW-Authenticate` response header for detail. For example: ``` Bearer error="invalid_token", error_description="The token expired at '12/23/2020 10:27:15'" ``` If you used the Authorization Code flow with the `offline_access` scope, use your refresh token to obtain a new access token. A `403 Forbidden` means the token is valid but lacks the scope required by the endpoint. ## Try it in the docs Every endpoint has a **Try it** panel. Paste an access token, pick your region, and send a real request from your browser. **1. Get an access token** Use the Client Credentials flow to get a token with a read scope like `People.Read`. See [Authentication](#authentication) and [Scopes](#scopes). **2. Start with a read-only call** Open [List people](/saas-manager-api/reference/people/list-people). It reads people in your organization without changing anything. **3. Pick your region and paste your token** Select **Try it**, choose United States or Europe to match your account, then paste your token in the **Authorization** field. **4. Send it, then copy the code** Select **Send** to see the live response. The example panel turns the same request into cURL, Python, JavaScript, Go, and more. ## Dates and times Dates and times are sent and returned in [RFC 3339 format.](https://tools.ietf.org/html/rfc3339) For example, `2020-12-25` (midnight) or `2020-12-25T10:50:00Z`. Field names ending in `Dtm` carry a meaningful time component, while field names ending in `Date` are date-only. ## Optional fields and null Responses omit fields that have no value, so you'll see the field absent rather than returned as `null`. When creating or replacing a resource with `PUT`, any field you omit is cleared. With `PATCH`, omitting a field leaves it unchanged, whereas sending it as `null` clears it. ## Pagination List endpoints are paginated and return up to 100 results by default. You can request up to 1000 with the limit query parameter, though you may receive fewer than requested. Request the next page with the `after` query parameter, passing the opaque cursor token that SaaS Manager supplies. The response's next field (and the `link` response header, `rel="next"`) contains the full URL for the next page: ```json theme={null} { "next": "https://app.trelica.com/api/people/v1?after=&limit=100", "results": [ { /* ... */ } ] } ``` Keep requesting pages until no further results are returned. User data returned over SCIM uses the SCIM `startIndex/count` pagination scheme instead. ## Filtering Many list endpoints accept a URL-encoded `filter` query parameter based on the [SCIM filtering specification.](https://tools.ietf.org/html/rfc7644#section-3.4.2.2) A filter is one or more expressions (an attribute name, operator, or optional value) combined with `and`, `or`, `not`, and grouped with parentheses. Attribute names match the JSON returned and may use dot notation for nested attributes (for example, `createdBy.email`). For an attribute that is an array of objects, put a sub-expression in brackets so the item matches when any element satisfies it. For example, `teams[name eq "Developers"]` or `teams[id eq "5f8d0a1b2c3d4e5f60718293"]`. Values can be double-quoted strings, integers, double-quoted RFC 3339 dates, or booleans. Some list endpoints also accept a free-text q parameter that searches the resource's displayable fields. Soft-deleted entities are excluded by default. You can include them with a filter that references `deleted` (for example, `filter=deleted eq true`). | Operator | Meaning | Behavior | | - | - | - | | `eq` | equal | Attribute value is identical to the operator value | | `ne` | not equal | Attribute value differs from the operator value | | `co` | contains | Attribute value contains the operator value text | | `sw` | starts with | Attribute value starts with the operator value text | | `ew` | ends with | Attribute value ends with the operator value text | | `pr` | present | Attribute has a non-empty / non-null value | | `gt` | greater than | Attribute value is greater than the operator value | | `ge` | greater than or equal | Attribute value is greater than or equal to the operator value | | `lt` | less than | Attribute value is less than the operator value | | `le` | less than or equal | Attribute value is less than or equal to the operator value | For `gt`/`ge`/`lt`/`le`, strings compare lexicographically, dates chronologically, and numbers numerically. Each list endpoint documents the fields you can filter on. For example: | Filter | Result | | - | - | | `firstName sw "Jan"` | People whose first name starts with "Jan" | | `teams[name eq "Developers"]` | People in the team called Developers | | `not (leavingDate pr)` | People with no leaving date | | `lastModifiedDtm ge "2021-06-01"` | Records modified on or after 1 June 2021 | ## Errors A `400 Bad Request` indicates a problem with your request. The body is a problem-details object where`errors` maps each offending field to its messages, with `title`, `status`, a `type` URL, and an `extensions.traceId` for correlation: ```json theme={null} { "errors": { "leavingDate": [ "Error converting value \"2020-40-40\" ..." ] }, "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "extensions": { "traceId": "00-91e4405b...-00" } } ``` If you see `500 Internal Server Error`, contact [saasmanager@1password.com](mailto:saasmanager@1password.com) with details of the request so we can investigate. ## Scopes Scopes define what an API app may do. Following the principle of least privilege, grant only the scopes you need. Each endpoint documents the scope(s) it requires. | Scope | Description | | - | - | | `Apps.Read` | Read-only access to applications | | `Apps.Users.Read` | Read-only access to application accounts | | `Apps.Write` | Write access to applications | | `Assets.Read` | Read-only access to devices | | `Assets.Write` | Write access to devices | | `AuditLog.Read` | Read-only access to the audit log | | `Contracts.Read` | Read-only access to contracts | | `Contracts.Write` | Write access to contracts | | `People.Read` | Read-only access to people and teams | | `People.Write` | Write access to people and teams | | `Users.Read` | Read-only access to users with access to SaaS Manager | | `Users.Write` | Write access to users with access to SaaS Manager | | `Workflows.Read` | Read-only access to workflow definitions | | `Workflows.Runs.Read` | Read-only access to workflow runs | | `Workflows.Runs.Execute` | Execute workflow run actions | | `Workflows.Runs.ReadSecrets` | Read workflow run secrets | | `offline_access` | Issue a refresh token alongside the access token (Authorization Code flow) | ## API reference Every endpoint has its own reference page with parameters, example requests and responses, and a **Try it** panel. Start with [List people](/saas-manager-api/reference/people/list-people), [List teams](/saas-manager-api/reference/teams/list-teams), or [List workflow runs](/saas-manager-api/reference/workflows/list-workflow-runs), or browse every endpoint in the sidebar. # Create an application Source: https://www.1password.dev/saas-manager-api/reference/applications/create-an-application /openapi/saas_manager_api.json post /api/apps/v1 Adds a managed application to your organization. Identify the underlying app with either `globalAppId` or `globalAppName` (exactly one is required). When supplying a name that does not match an app in the global catalog, supply `vendorName` and a new local vendor is created. Returns 409 if the application already exists. **Required scope:** `Apps.Write` (Write access to applications) # Get an application Source: https://www.1password.dev/saas-manager-api/reference/applications/get-an-application /openapi/saas_manager_api.json get /api/apps/v1/{appId} Fetches a single application (a managed SaaS app in your organization) by its ID. **Required scope:** `Apps.Read` (Read-only access to applications) # Get application categories Source: https://www.1password.dev/saas-manager-api/reference/applications/get-application-categories /openapi/saas_manager_api.json get /api/apps/v1/categories Returns the application category tags as a nested hierarchy. **Required scope:** `Apps.Read` (Read-only access to applications) # List application accounts Source: https://www.1password.dev/saas-manager-api/reference/applications/list-application-accounts /openapi/saas_manager_api.json get /api/apps/v1/{appId}/users Returns a paginated list of the accounts (users) on a given application. Follow the `next` link to page through large result sets. **Required scope:** `Apps.Users.Read` (Read-only access to application accounts) # List application custom fields Source: https://www.1password.dev/saas-manager-api/reference/applications/list-application-custom-fields /openapi/saas_manager_api.json get /api/apps/v1/customfields Returns the application custom fields defined for your organization. Use the field `lookupKey` values as the keys of the `customFields` object when creating or updating an application. **Required scope:** `Apps.Read` (Read-only access to applications) # List applications Source: https://www.1password.dev/saas-manager-api/reference/applications/list-applications /openapi/saas_manager_api.json get /api/apps/v1 Returns a paginated list of the applications in your organization. Use `filter` and `q` to narrow the results, and follow the `next` link (also provided in the `link` response header) to page through large result sets. **Required scope:** `Apps.Read` (Read-only access to applications) # Update selected details of an application Source: https://www.1password.dev/saas-manager-api/reference/applications/update-selected-details-of-an-application /openapi/saas_manager_api.json patch /api/apps/v1/{id} Partially updates an application: only the fields present in the request body are changed. Omitting a field leaves it untouched, whereas sending an explicit `null` clears it. At least one field must be supplied. **Required scope:** `Apps.Write` (Write access to applications) # List audit log events Source: https://www.1password.dev/saas-manager-api/reference/audit-log/list-audit-log-events /openapi/saas_manager_api.json get /api/audit/v1/logs Returns audit log events for your organization, oldest first. The audit log is a continuous, append-only stream. Pagination is cursor-based but differs from the rest of the SaaS Manager API: the response's `next` field (and the `link` response header, `rel="next"`) always returns a cursor URL — even on the last page — so you can keep following it to receive new events as they are written. Page until no further `results` are returned, then poll the same `next` URL periodically to pick up new events. Narrow results with `since`/`until` (a time window — by default the last 7 days), a SCIM-style `filter` (all operators except `[ ]`), or a free-text `q` query (matches the actor/target name, target email, and exactly matches event ID, event type, target ID and target type). Use `sortOrder=DESCENDING` to return newest events first. `limit` defaults to 100 (maximum 1000). # Authorize (Authorization Code flow) Source: https://www.1password.dev/saas-manager-api/reference/authentication/authorize-authorization-code-flow /openapi/saas_manager_api.json get /connect/authorize Redirects the user to the SaaS Manager consent screen. After the user consents, the browser is redirected back to `redirect_uri` with a `code` (and `state`) query parameter, which you then exchange for a token at `/connect/token`. This is a browser-redirect endpoint, not a JSON API call. # Request an access token Source: https://www.1password.dev/saas-manager-api/reference/authentication/request-an-access-token /openapi/saas_manager_api.json post /connect/token Exchanges client credentials (or an authorization code / refresh token) for an access token. The client ID and secret are sent via HTTP Basic authentication. The body is `application/x-www-form-urlencoded`. - **Client Credentials:** `grant_type=client_credentials` (optional `scope`). - **Authorization Code:** `grant_type=authorization_code` with `code` and `redirect_uri`. - **Refresh:** `grant_type=refresh_token` with `refresh_token` (requires the `offline_access` scope). # Create or update a contract Source: https://www.1password.dev/saas-manager-api/reference/contracts/create-or-update-a-contract /openapi/saas_manager_api.json put /api/contracts/v1 Creates a contract, or updates an existing one matched by its `id` or your own `externalId`. Either all line items carry an `externalId` or none do. Set the business owner with `businessOwnerEmail`. **Required scope:** `Contracts.Write` (Write access to contracts) # Delete a contract Source: https://www.1password.dev/saas-manager-api/reference/contracts/delete-a-contract /openapi/saas_manager_api.json delete /api/contracts/v1/{id} Deletes a contract by its SaaS Manager ID or by your own external ID. **Required scope:** `Contracts.Write` (Write access to contracts) # Get a contract Source: https://www.1password.dev/saas-manager-api/reference/contracts/get-a-contract /openapi/saas_manager_api.json get /api/contracts/v1/{id} Fetches a single contract by its SaaS Manager ID or by your own external ID. **Required scope:** `Contracts.Read` (Read-only access to contracts) # List contracts Source: https://www.1password.dev/saas-manager-api/reference/contracts/list-contracts /openapi/saas_manager_api.json get /api/contracts/v1 Returns a paginated list of the contracts in your organization. Use `filter` and `q` to narrow the results, and follow the `next` link (also provided in the `link` response header) to page through large result sets. **Required scope:** `Contracts.Read` (Read-only access to contracts) # Create or replace a device Source: https://www.1password.dev/saas-manager-api/reference/devices/create-or-replace-a-device /openapi/saas_manager_api.json put /api/assets/v1/{id} Creates a new device, or fully replaces an existing one when an ID is supplied (in the route or in the body). When creating, `hardwareVendor` and `modelName` are required. Assign the device to a person with `assignedToEmail` and to a location with `locationName` (a location is created if needed). `netPrice` is converted to your base currency. **Required scope:** `Assets.Write` (Write access to devices) # Delete a device Source: https://www.1password.dev/saas-manager-api/reference/devices/delete-a-device /openapi/saas_manager_api.json delete /api/assets/v1/{id} Deletes the device with the given SaaS Manager ID. **Required scope:** `Assets.Write` (Write access to devices) # Get a device Source: https://www.1password.dev/saas-manager-api/reference/devices/get-a-device /openapi/saas_manager_api.json get /api/assets/v1/{id} Fetches a single device by its SaaS Manager ID. **Required scope:** `Assets.Read` (Read-only access to devices) # List device custom fields Source: https://www.1password.dev/saas-manager-api/reference/devices/list-device-custom-fields /openapi/saas_manager_api.json get /api/assets/v1/customfields Returns the device custom fields defined for your organization. Use the field `lookupKey` values as the keys of the `customFields` object when creating or updating a device. **Required scope:** `Assets.Read` (Read-only access to devices) # List devices Source: https://www.1password.dev/saas-manager-api/reference/devices/list-devices /openapi/saas_manager_api.json get /api/assets/v1 Returns a paginated list of the devices in your organization. Use `filter` and `q` to narrow the results, and follow the `next` link (also provided in the `link` response header) to page through large result sets. **Required scope:** `Assets.Read` (Read-only access to devices) # Update selected details of a device Source: https://www.1password.dev/saas-manager-api/reference/devices/update-selected-details-of-a-device /openapi/saas_manager_api.json patch /api/assets/v1/{id} Partially updates a device: only the fields present in the request body are changed. Omitting a field leaves it untouched, whereas sending an explicit `null` clears it. At least one field must be supplied. **Required scope:** `Assets.Write` (Write access to devices) # Create or replace a person Source: https://www.1password.dev/saas-manager-api/reference/people/create-or-replace-a-person /openapi/saas_manager_api.json put /api/people/v1/{id} Creates a new person, or fully replaces an existing one when an ID is supplied (in the route or in the body). When creating, the email address must not already be in use. Set the line manager with lineManagerId or lineManagerEmail. Team membership is replaced wholesale: supply either teams (by ID or name) or teamIds (not both) — omitting both removes the person's manually-assigned teams. **Required scope:** `People.Write` (Write access to people and teams) # Get a person Source: https://www.1password.dev/saas-manager-api/reference/people/get-a-person /openapi/saas_manager_api.json get /api/people/v1/{id} Fetches a single person by their SaaS Manager ID (a UUID) or by email address. If an email address matches more than one person a 409 Conflict is returned. **Required scope:** `People.Read` (Read-only access to people and teams) # List a person's applications Source: https://www.1password.dev/saas-manager-api/reference/people/list-a-persons-applications /openapi/saas_manager_api.json get /api/people/v1/{id}/apps Returns a paginated list of the applications a person has an account on, identified by their SaaS Manager ID or email address. If an email address matches more than one person a 409 Conflict is returned. **Required scope:** `People.Read` (Read-only access to people and teams) # List people Source: https://www.1password.dev/saas-manager-api/reference/people/list-people /openapi/saas_manager_api.json get /api/people/v1 Returns a paginated list of the people in your organization. Use `filter` and `q` to narrow the results, and follow the `next` link (also provided in the `link` response header) to page through large result sets. **Required scope:** `People.Read` (Read-only access to people and teams) # Update selected details of a person Source: https://www.1password.dev/saas-manager-api/reference/people/update-selected-details-of-a-person /openapi/saas_manager_api.json patch /api/people/v1/{id} Partially updates a person: only the fields present in the request body are changed. Omitting a field leaves it untouched, whereas sending an explicit `null` clears it. At least one field must be supplied. **Required scope:** `People.Write` (Write access to people and teams) # Create a user Source: https://www.1password.dev/saas-manager-api/reference/scim/create-a-user /openapi/saas_manager_api.json post /api/scim/v2/Users Creates a user, following the SCIM 2.0 protocol (RFC 7644). `userName` is required and must belong to a domain verified for your organization; it must not already be in use (a duplicate returns 409). Server-controlled fields (`id`, `meta`) are ignored on the request and set by the service. Returns 201 with the created user and a `Location` header. **Required scope:** `Users.Write` (Write access to users with access to SaaS Manager) # Delete a user Source: https://www.1password.dev/saas-manager-api/reference/scim/delete-a-user /openapi/saas_manager_api.json delete /api/scim/v2/Users/{userId} Removes a user's SaaS Manager access, following the SCIM 2.0 protocol (RFC 7644). Returns 204 No Content on success. System-managed and EPM-managed users cannot be deleted (400). **Required scope:** `Users.Write` (Write access to users with access to SaaS Manager) # Get a user Source: https://www.1password.dev/saas-manager-api/reference/scim/get-a-user /openapi/saas_manager_api.json get /api/scim/v2/Users/{userId} Fetches a single user by SCIM resource ID, following the SCIM 2.0 protocol (RFC 7644). # Get the User resource type Source: https://www.1password.dev/saas-manager-api/reference/scim/get-the-user-resource-type /openapi/saas_manager_api.json get /api/scim/v2/ResourceTypes/User Returns the SCIM 2.0 "User" resource type definition (RFC 7643). # List resource types Source: https://www.1password.dev/saas-manager-api/reference/scim/list-resource-types /openapi/saas_manager_api.json get /api/scim/v2/ResourceTypes Returns the SCIM 2.0 resource types this provider exposes (RFC 7643), in a SCIM `ListResponse` envelope. SCIM clients read this during discovery. Per the SCIM standard, supplying a `filter` is not permitted. # List users Source: https://www.1password.dev/saas-manager-api/reference/scim/list-users /openapi/saas_manager_api.json get /api/scim/v2/Users Lists users with SaaS Manager access, following the SCIM 2.0 protocol (RFC 7644). Results are returned in a SCIM `ListResponse` envelope (`totalResults`, `itemsPerPage`, `startIndex`, `Resources`). Paging is SCIM-style — 1-based `startIndex` plus `count` (default and maximum 100) — not the cursor paging used elsewhere in the SaaS Manager API. An optional SCIM `filter` expression (e.g. `userName eq "john.doe@example.com"`) narrows the results. # Replace a user Source: https://www.1password.dev/saas-manager-api/reference/scim/replace-a-user /openapi/saas_manager_api.json put /api/scim/v2/Users/{userId} Replaces a user's attributes, following the SCIM 2.0 protocol (RFC 7644). Server-controlled fields (`id`, `meta`) are ignored on the request. EPM-managed and system-managed users, and users shared across multiple organizations, cannot be modified (403). **Required scope:** `Users.Write` (Write access to users with access to SaaS Manager) # Update a user Source: https://www.1password.dev/saas-manager-api/reference/scim/update-a-user /openapi/saas_manager_api.json patch /api/scim/v2/Users/{userId} Applies a SCIM PATCH operation set to a user, following the SCIM 2.0 protocol (RFC 7644). The request body must use the SCIM PatchOp schema (`urn:ietf:params:scim:api:messages:2.0:PatchOp`) and supply one or more `add`/`replace`/ `remove` operations, each with a `path`. `userName` is immutable. EPM-managed and system-managed users cannot be modified (403). **Required scope:** `Users.Write` (Write access to users with access to SaaS Manager) # Create or update a team Source: https://www.1password.dev/saas-manager-api/reference/teams/create-or-update-a-team /openapi/saas_manager_api.json put /api/people/v1/teams Creates a new team when no ID is supplied (returns 201 with the created team), or updates an existing team's name and/or parent when an ID is supplied (returns 200). A team cannot be moved beneath one of its own descendants. **Required scope:** `People.Write` (Write access to people and teams) # Delete a team Source: https://www.1password.dev/saas-manager-api/reference/teams/delete-a-team /openapi/saas_manager_api.json delete /api/people/v1/teams/{id} Deletes the team with the given ID, along with its descendants, and removes the corresponding memberships from people. Teams that are in use by integrations cannot be deleted. **Required scope:** `People.Write` (Write access to people and teams) # Get a team Source: https://www.1password.dev/saas-manager-api/reference/teams/get-a-team /openapi/saas_manager_api.json get /api/people/v1/teams/{id} Fetches a single team by ID, including its parent team ID (if any). **Required scope:** `People.Read` (Read-only access to people and teams) # Get the team hierarchy Source: https://www.1password.dev/saas-manager-api/reference/teams/get-the-team-hierarchy /openapi/saas_manager_api.json get /api/people/v1/teams/tree Returns all teams as a nested tree, starting from the root teams. **Required scope:** `People.Read` (Read-only access to people and teams) # List teams Source: https://www.1password.dev/saas-manager-api/reference/teams/list-teams /openapi/saas_manager_api.json get /api/people/v1/teams/list Returns all teams as a flat list; each entry carries its parent team ID (if any). **Required scope:** `People.Read` (Read-only access to people and teams) # Fire a signal Source: https://www.1password.dev/saas-manager-api/reference/workflows/fire-a-signal /openapi/saas_manager_api.json post /api/workflows/v1/{workflowId}/runs/{runId}/firedSignals/{activityId}/{signalName} Fires a named signal (for example an approval or rejection) on a workflow step that is currently waiting for input, allowing the run to continue. The valid signals for a waiting step — and the URL to call to fire each one — are listed under the step's `waiting.actions` in the run's response, so a client can simply `POST` to the supplied `href`. Returns `200` when the signal was fired and the run advanced. Returns `409` if the step is no longer waiting (for example it has already been signalled or has timed out), and `404` if the run or workflow cannot be found. **Required scope:** `Workflows.Runs.Execute` (Execute workflow run actions) # Get a workflow Source: https://www.1password.dev/saas-manager-api/reference/workflows/get-a-workflow /openapi/saas_manager_api.json get /api/workflows/v1/{workflowId} Returns the published workflow with the given ID, including its trigger and steps. The workflow is returned inside a one-item result page (empty if no workflow has that ID). **Required scope:** `Workflows.Read` (Read-only access to workflow definitions) # Get a workflow run Source: https://www.1password.dev/saas-manager-api/reference/workflows/get-a-workflow-run /openapi/saas_manager_api.json get /api/workflows/v1/{workflowId}/runs/{runId} Returns the run with the given ID for the workflow, including its context and step states, inside a one-item result page (empty if no run has that ID). The `variables` query parameter and the `Workflows.Runs.ReadSecrets` scope behave as for listing runs. **Required scope:** `Workflows.Runs.Read` (Read-only access to workflow runs) # List workflow runs Source: https://www.1password.dev/saas-manager-api/reference/workflows/list-workflow-runs /openapi/saas_manager_api.json get /api/workflows/v1/{workflowId}/runs Returns a paginated list of the runs (individual executions) of a workflow, including the run's context, current step states and any waiting actions. Use `filter` and `q` to narrow the results, and follow the `next` link to page through large result sets. **Variables:** workflow variable values are not returned by default. Pass the `variables` query parameter — a comma-separated list of variable IDs — to include those variables' values in each run's context. Reading the value of a **secret** (password) variable additionally requires the `Workflows.Runs.ReadSecrets` scope; requesting a secret variable without it returns `401`. **Required scope:** `Workflows.Runs.Read` (Read-only access to workflow runs) # List workflows Source: https://www.1password.dev/saas-manager-api/reference/workflows/list-workflows /openapi/saas_manager_api.json get /api/workflows/v1 Returns a paginated list of the published workflows in your organization, including each workflow's trigger and steps. Use `filter` and `q` to narrow the results, and follow the `next` link (also provided in the `link` response header) to page through large result sets. **Required scope:** `Workflows.Read` (Read-only access to workflow definitions) # 1Password SDKs Source: https://www.1password.dev/sdks Build integrations with 1Password SDKs for Go, JavaScript, and Python: load secrets into your code, read 1Password Environments, and manage items and vaults. 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](/sdks/load-secrets) or read [secrets](/sdks/environments/) from 1Password Environments. * **Automate item management**: Programmatically [manage items](/sdks/manage-items) in your 1Password account. * **Securely share items**: [Share items](/sdks/share-items) with anyone, whether or not they have a 1Password account. * **Manage vaults and access**: [Manage your team's vaults](/sdks/vaults) and the [permissions groups have](/sdks/vault-permissions) in them. * **Support biometric authorization**: Build local integrations that users authorize with prompts from the [1Password desktop app](/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](/sdks/concepts#1password-service-account) for least-privilege access and automated environments. See a full list of [supported functionality](/sdks/functionality). ## Supported languages [Golang](https://github.com/1Password/onepassword-sdk-go) [JavaScript](https://github.com/1Password/onepassword-sdk-js/) [Python](https://github.com/1Password/onepassword-sdk-python/) ## 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](/sdks/concepts#authentication) for 1Password SDKs: local authorization prompts from the [1Password desktop app](/sdks/concepts#1password-desktop-app) or automated authentication with a [1Password Service Account](/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. > [tab] 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 Developer Integrations, select **Integrate with 1Password SDKs**. > 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 1Password SDKs setting](/static/img/developer-integrations-sdks-light.png) > ![The Integrate with 1Password SDKs setting](/static/img/developer-integrations-sdks-dark.png) > [tab] 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](/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. > > > [tab] bash, sh, zsh > > > > ```shell theme={null} > > export OP_SERVICE_ACCOUNT_TOKEN= > > ``` > > > [tab] fish > > > > ```shell theme={null} > > set -x OP_SERVICE_ACCOUNT_TOKEN > > ``` > > > [tab] Powershell > > > > ```shell theme={null} > > $Env:OP_SERVICE_ACCOUNT_TOKEN = "" > > ``` ### Step 2: Install the SDK Install the SDK in your project. > [tab] Go > > ```go theme={null} > go get github.com/1password/onepassword-sdk-go > ``` > [tab] JavaScript > > ```shell theme={null} > npm install @1password/sdk > ``` > [tab] Python > > ```python theme={null} > pip install onepassword-sdk > ``` ### Step 3: Import the SDK Import the SDK into your project. > [tab] Go > > ```go theme={null} > import "github.com/1password/onepassword-sdk-go" > ``` > [tab] JavaScript > > #### CommonJS > > ```js theme={null} > const sdk = require("@1password/sdk"); > ``` > > #### ES Modules > > ```js theme={null} > import sdk from "@1password/sdk"; > ``` > [tab] Python > > ```py theme={null} > from onepassword import * > ``` ### 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. > [tab] 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 also use the account ID that [1Password CLI](/cli/get-started) returns with [`op account list --format json`](/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`. > > > [tab] 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 highlight={4} theme={null} > > // 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) > > } > > ``` > > > [tab] 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 highlight={4} theme={null} > > // 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", > > }); > > ``` > > > [tab] 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 highlight={7} theme={null} > > from onepassword import Client, DesktopAuth > > > > # 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", > > ) > > ``` > [tab] 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`. > > > [tab] Go > > > > ```go theme={null} > > // Gets your service account token from the OP_SERVICE_ACCOUNT_TOKEN environment variable. > > token := os.Getenv("OP_SERVICE_ACCOUNT_TOKEN") > > > > // Authenticates with your service account token and connects to 1Password. > > client, err := onepassword.NewClient(context.Background(), > > onepassword.WithServiceAccountToken(token), > > // TODO: Set the following to your own integration name and version. > > onepassword.WithIntegrationInfo("My 1Password Integration", "v1.0.0"), > > ) > > if err != nil { > > panic(err) > > } > > ``` > > > [tab] JavaScript > > > > ```js theme={null} > > // 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", > > }); > > ``` > > > [tab] Python > > > > ```python theme={null} > > import os > > > > from onepassword import Client > > > > # Get your service account token from the OP_SERVICE_ACCOUNT_TOKEN environment variable > > token = os.getenv("OP_SERVICE_ACCOUNT_TOKEN") > > > > # Create an authenticated client > > client = await Client.authenticate( > > auth=token, > > # Set to your own integration name and version > > integration_name="My 1Password Integration", > > integration_version="v1.0.0", > > ) > > ``` ### 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. > [tab] 1Password desktop app > > > [tab] Go > > > > ```go title="main.go" theme={null} > > package main > > > > import ( > > "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 theme={null} > > go run main.go > > #code-result > > Development > > Production > > Private > > ``` > > > [tab] JavaScript > > > > ```js title="example.js" theme={null} > > import sdk from "@1password/sdk"; > > > > 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 theme={null} > > node index.js > > #code-result > > Development > > Production > > Private > > ``` > > > [tab] Python > > > > ```python title="example.py" theme={null} > > import asyncio > > > > 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()) > > ``` > > > > ```shell theme={null} > > python3 example.py > > #code-result > > Development > > Production > > Private > > ``` > [tab] Service account > > In the following example, the service account is scoped to a vault titled `Development`. > > > [tab] Go > > > > ```go title="main.go" theme={null} > > package main > > > > import ( > > "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 theme={null} > > go run main.go > > #code-result > > Development > > ``` > > > [tab] JavaScript > > > > ```js title="index.js" theme={null} > > import sdk from "@1password/sdk"; > > > > 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 theme={null} > > node index.js > > #code-result > > Development > > ``` > > > [tab] Python > > > > ```python title="example.py" theme={null} > > import asyncio > > import os > > 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 theme={null} > > 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. ## Example integrations See examples of how our partners have used SDKs to build integrations with 1Password: ### Postman Securely load API keys and other secrets stored in 1Password into Postman without exposing any secrets in plaintext. [Learn more](https://go.pstmn.io/1password) ### Pulumi ESC Dynamically import secrets from 1Password into your environment. The provider will return a map of names to Secrets. [Learn more](https://www.pulumi.com/docs/esc/providers/1password-secrets/) ## 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 help To get help with 1Password SDKs, join our [Developer Slack workspace](/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: Integrate 1Password SDKs with AI agents Source: https://www.1password.dev/sdks/ai-agent > [!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. > > To learn how to securely provide credentials to AI agents and tools without exposing them to the model, see the [secure AI access workflow](/get-started/secure-ai-access) instead. > > 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](/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](/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](/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**. 5. 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**. 6. Select **Create Account**. 7. 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](/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. > [tab] Bash, Zsh, sh > > ```shell theme={null} > export OP_SERVICE_ACCOUNT_TOKEN= > ``` > [tab] fish > > ```shell theme={null} > set -x OP_SERVICE_ACCOUNT_TOKEN > ``` > [tab] PowerShell > > ```powershell theme={null} > $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 theme={null} import asyncio import os 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](/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](/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](/vscode/). Here's our example updated with secret references: ```python theme={null} import asyncio import os 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. > [!WARNING] > > AI agents can make mistakes. Make sure to double check the results of your prompts. ```python theme={null} import asyncio import os 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](/sdks/setup-tutorial) * [Load secrets using 1Password SDKs](/sdks/load-secrets) * [Manage items using 1Password SDKs](/sdks/manage-items) * [Workflow: Secure AI access](/get-started/secure-ai-access) * [Workflow: Build integrations with 1Password](/get-started/build-integrations) # 1Password SDK concepts Source: https://www.1password.dev/sdks/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.](/static/img/sdks/sdk-auth-prompt.png) ### 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](/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](/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](/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 secrets from your Environments](/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](/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](/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](/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](/sdks/concepts#unique-identifiers) of another item in the same vault. | | `SSHKey` | Must be a valid SSH private key – [a decrypted, PEM-encoded string](/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](/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](/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](/sdks/files/) file attachments saved in 1Password using the SDKs. ## Query parameters ### `otp` You can use the `otp` (or `totp`) [attribute query parameter](/cli/secret-reference-syntax#attribute-parameter) to retrieve one-time passwords with the [`Resolve` function](/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](/cli/secret-reference-syntax#attribute-parameter) to fetch a private SSH key in OpenSSH format using the [`Resolve` function](/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](/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](/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](/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](/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](/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](/sdks/vault-permissions#1password-teams-vault-permissions). # 1Password SDK local integration security Source: https://www.1password.dev/sdks/desktop-app-integrations 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](/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](/service-accounts/security). For information about 1Password security practices, visit the [1Password Security homepage](https://1password.com/security). [Video overview of how 1Password desktop app integrations work with SDKs.](https://www.youtube.com/embed/insGwC2GfrU) ## 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 Source: https://www.1password.dev/sdks/environments You can use [1Password SDKs](/sdks) to programmatically read the secrets stored in [1Password Environments](/environments) and use them in your applications. > [!WARNING] > > **Upcoming deprecation** > > The `get_variables()` function and the `GetVariablesResponse` and `EnvironmentVariable` types it returns will be deprecated on November 17, 2026, and removed on January 20, 2027. The new `list_secrets()` function will replace them. It takes an Environment name or ID and a `reveal` option, and returns a list of `EnvironmentSecret` objects directly, without a response wrapper. ## Requirements Before you begin, [follow the steps to get started](/sdks#get-started) with a 1Password SDK. The examples on this page assume you have an initialized `client` instance. For example: > [tab] Go > > ```go theme={null} > package main > > import ( > "context" > > "github.com/1password/onepassword-sdk-go" > ) > > func main() { > // TODO: Initialize client using your preferred authentication method (see Overview > Get started) > client, err := onepassword.NewClient(context.Background(), > ) > if err != nil { > panic(err) > } > > // Your code here > } > > ``` > [tab] JavaScript > > > [tab] ES Modules > > > > ```javascript theme={null} > > import sdk from "@1password/sdk"; > > > > async function main() { > > const client = await sdk.createClient({ > > // TODO: Initialize client using your preferred authentication method (see Overview > Get started) > > }); > > > > // Your code here > > } > > > > main().catch(console.error); > > > > ``` > > > [tab] CommonJS > > > > ```javascript theme={null} > > const sdk = require("@1password/sdk"); > > > > async function main() { > > const client = await sdk.createClient({ > > // TODO: Initialize client using your preferred authentication method (see Overview > Get started) > > }); > > > > // Your code here > > } > > > > main().catch(console.error); > > > > ``` > [tab] Python > > ```python theme={null} > import asyncio > > from onepassword import Client # Also import DesktopAuth for desktop app authentication. > > async def main(): > # TODO: Initialize client using your preferred authentication method (see Overview > Get started) > client = await Client.authenticate(...) > > # Your code here > > asyncio.run(main()) > > ``` ## Read secrets > [tab] Go > > To read the secrets stored in an Environment, use the [`GetVariables()`](https://github.com/1Password/onepassword-sdk-go/blob/main/environments.go#L15) method. Replace `` with the [Environment's ID](#appendix-get-an-environments-id). > > ```go theme={null} > res, err := client.Environments().GetVariables(context.Background(), "") > if err != nil { > panic(err) > } > for _, env := range res.Variables { > fmt.Printf("Secret %s: %s (hidden: %t)\n", env.Name, env.Value, env.Masked) > } > ``` > > The method returns a [`GetVariablesResponse`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L67) struct that contains a list of the secrets stored in the Environment. > > ```go theme={null} > // Response containing the full set of environment variables from an Environment. > type GetVariablesResponse struct { > // List of environment variables. > Variables []EnvironmentVariable `json:"variables"` > } > ``` > > Each secret in the response is an [`EnvironmentVariable`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L32) struct that contains the following: > > * **Name**: The secret's name (for example, `DB_HOST`). > * **Value**: The secret's value. > * **Masked**: A boolean that indicates whether the value is hidden by default in the 1Password app. > > ```go theme={null} > // 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"` > } > ``` > [tab] JavaScript > > To read the secrets stored in an Environment, use the [`getVariables()`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/environments.ts#L13) method. Replace `` with the [Environment's ID](#appendix-get-an-environments-id). > > ```js theme={null} > const res = await client.environments.getVariables(""); > for (const env of res.variables) { > console.log(`Secret ${env.name}: ${env.value} (hidden: ${env.masked})`); > } > ``` > > The method returns a [`GetVariablesResponse`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L68) object that contains a list of the secrets stored in the Environment. > > ```js theme={null} > /** Response containing the full set of environment variables from an Environment. */ > interface GetVariablesResponse { > /** List of environment variables. */ > variables: EnvironmentVariable[]; > } > ``` > > Each secret in the response is an [`EnvironmentVariable`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L29) object that contains the following: > > * **Name**: The secret's name (for example, `DB_HOST`). > * **Value**: The secret's value. > * **Masked**: A boolean that indicates whether the value is hidden by default in the 1Password app. > > ```js theme={null} > /** 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; > } > ``` > [tab] Python > > To read the secrets stored in an Environment, use the [`get_variables()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/environments.py#L16) method. Replace `ENVIRONMENT_ID` with the [Environment's ID](#appendix-get-an-environments-id). > > ```python theme={null} > environment_id = "your-environment-id" > > res = await client.environments.get_variables(environment_id) > for env in res.variables: > print(f"Secret {env.name}: {env.value} (hidden: {env.masked})") > ``` > > The method returns a [`GetVariablesResponse`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L162) object that contains a list of the secrets stored in the Environment. > > ```python theme={null} > class GetVariablesResponse(BaseModel): > """ > Response containing the full set of environment variables from an Environment. > """ > > variables: List[EnvironmentVariable] > """ > List of environment variables. > """ > ``` > > Each secret in the response is an [`EnvironmentVariable`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L91) object that contains the following: > > * **Name**: The secret's name (for example, `DB_HOST`). > * **Value**: The secret's value. > * **Masked**: A boolean that indicates whether the value is hidden by default in the 1Password app. > > ```python theme={null} > 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] > > Secrets in 1Password Environments 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 secret and select **Show value by default**. ## Appendix: Get an Environment's ID To read secrets 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 Source: https://www.1password.dev/sdks/files Use 1Password SDKs to read, save, and delete files in your 1Password account. You can store files in 1Password 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. ## Before you get started Before you begin, [follow the steps to get started](/sdks#get-started) with a 1Password SDK. The examples on this page assume you have an initialized `client` instance. For example: > [tab] Go > > ```go theme={null} > package main > > import ( > "context" > > "github.com/1password/onepassword-sdk-go" > ) > > func main() { > // TODO: Initialize client using your preferred authentication method (see Overview > Get started) > client, err := onepassword.NewClient(context.Background(), > ) > if err != nil { > panic(err) > } > > // Your code here > } > > ``` > [tab] JavaScript > > > [tab] ES Modules > > > > ```javascript theme={null} > > import sdk from "@1password/sdk"; > > > > async function main() { > > const client = await sdk.createClient({ > > // TODO: Initialize client using your preferred authentication method (see Overview > Get started) > > }); > > > > // Your code here > > } > > > > main().catch(console.error); > > > > ``` > > > [tab] CommonJS > > > > ```javascript theme={null} > > const sdk = require("@1password/sdk"); > > > > async function main() { > > const client = await sdk.createClient({ > > // TODO: Initialize client using your preferred authentication method (see Overview > Get started) > > }); > > > > // Your code here > > } > > > > main().catch(console.error); > > > > ``` > [tab] Python > > ```python theme={null} > import asyncio > > from onepassword import Client # Also import DesktopAuth for desktop app authentication. > > async def main(): > # TODO: Initialize client using your preferred authentication method (see Overview > Get started) > client = await Client.authenticate(...) > > # Your code here > > asyncio.run(main()) > > ``` > [!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. ## Read a file > [tab] 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](/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](/sdks/manage-items#get-an-item). > > > [tab] File field > > > > ```go theme={null} > > // Read the file field from an item > > retrievedFileContent, err := client.Items().Files().Read(context.Background(), item.VaultID, item.ID, item.Files[0].Attributes) > > if err != nil { > > panic(err) > > } > > ``` > > > [tab] Document file > > > > ```go theme={null} > > // Read the document item > > content, err := client.Items().Files().Read(context.Background(), replacedDocItem.VaultID, replacedDocItem.ID, *replacedDocItem.Document) > > if err != nil { > > panic(err) > > } > > ``` > [tab] 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](/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](/sdks/manage-items#get-an-item). > > > [tab] File field > > > > ```js theme={null} > > // Read the content of the file field on the Item > > let content = await client.items.files.read( > > item.vaultId, > > item.id, > > item.files[0].attributes, > > ); > > ``` > > > [tab] Document file > > > > ```js theme={null} > > // Read the content of the Document Item > > let content = await client.items.files.read( > > replacedDocumentItem.vaultId, > > replacedDocumentItem.id, > > replacedDocumentItem.document, > > ); > > ``` > [tab] 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](/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](/sdks/manage-items#get-an-item). > > > [tab] File field > > > > ```python theme={null} > > item = await client.items.get("your-vault-id", "your-item-id") > > > > # Read the content of the file field from an item > > content = await client.items.files.read( > > item.vault_id, item.id, item.files[0].attributes > > ) > > print(content.decode()) > > ``` > > > [tab] Document file > > > > ```python theme={null} > > item = await client.items.get("your-vault-id", "your-item-id") > > > > # Read the content of the Document item > > content = await client.items.files.read( > > item.vault_id, item.id, item.document > > ) > > print(content.decode()) > > ``` ## 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. | > [tab] Save files in a new item > > > [tab] Go > > > > You can add files to a new item when you [create the item](/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. > > > > ```go theme={null} > > fileContent, err := os.ReadFile("./example/service_account/file.txt") > > if err != nil { > > panic(err) > > } > > // Create the File Field item > > item, err := client.Items().Create(context.Background(), onepassword.ItemCreateParams{ > > Title: "Login with File Field created with SDK", > > Category: onepassword.ItemCategoryLogin, > > VaultID: vaultID, > > Sections: []onepassword.ItemSection{ > > { > > ID: sectionID, > > }, > > }, > > Files: []onepassword.FileCreateParams{ > > { > > Name: "file.txt", > > Content: fileContent, > > SectionID: sectionID, > > FieldID: "file_field", > > }, > > }, > > }) > > if err != nil { > > panic(err) > > } > > ``` > > > [tab] JavaScript > > > > You can add files to a new item when you [create the item](/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. > > > > ```js theme={null} > > // Create the file field item > > let item = await client.items.create({ > > title: "Login with File Field Item Created With JS SDK", > > category: sdk.ItemCategory.Login, > > vaultId: vaultId, > > fields: [ > > { > > id: "username", > > title: "username", > > fieldType: sdk.ItemFieldType.Text, > > value: "my username", > > }, > > { > > id: "password", > > title: "password", > > fieldType: sdk.ItemFieldType.Concealed, > > value: "my secret value", > > }, > > ], > > sections: [ > > { > > id: "custom section", > > title: "my section", > > }, > > ], > > files: [ > > { > > name: "file.txt", > > content: new Uint8Array(fs.readFileSync("file.txt")), > > sectionId: "custom section", > > fieldId: "file_field", > > }, > > ], > > }); > > ``` > > > [tab] Python > > > > You can add files to a new item when you [create the item](/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. > > > > ```python theme={null} > > from pathlib import Path > > > > from onepassword import ( > > FileCreateParams, > > ItemCategory, > > ItemCreateParams, > > ItemField, > > ItemFieldType, > > ItemSection, > > ) > > > > # Create an item with a file attached in a file field > > to_create = ItemCreateParams( > > title="FileField Item created with Python SDK", > > category=ItemCategory.LOGIN, > > vault_id="your-vault-id", > > fields=[ > > ItemField( > > id="username", > > title="username", > > field_type=ItemFieldType.TEXT, > > value="my-username", > > ), > > ItemField( > > id="password", > > title="password", > > field_type=ItemFieldType.CONCEALED, > > value="my-password", > > ), > > ], > > sections=[ > > ItemSection(id="", title=""), > > ], > > files=[ > > FileCreateParams( > > name="file.txt", > > content=Path("./example/file2.txt").read_bytes(), > > sectionId="", > > fieldId="file_field", > > ) > > ], > > ) > > > > created_item = await client.items.create(to_create) > > print(f'Created item with file attached "{created_item.title}" ({created_item.id})') > > ``` > [tab] Save a file in an existing item > > > [tab] 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. > > > > ```go theme={null} > > file2Content, err := os.ReadFile("./example/service_account/file2.txt") > > if err != nil { > > panic(err) > > } > > > > // Attach a file field to an item > > newItem, err := client.Items().Files().Attach(context.Background(), item, onepassword.FileCreateParams{ > > Name: "file2.txt", > > Content: file2Content, > > SectionID: sectionID, > > FieldID: "new_file_field", > > }) > > if err != nil { > > panic(err) > > } > > ``` > > > [tab] 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. > > > > ```js theme={null} > > // Attach a file field to the item > > let attachedItem = await client.items.files.attach(item, { > > name: "file2.txt", > > content: new Uint8Array(fs.readFileSync("file2.txt")), > > sectionId: "custom section", > > fieldId: "new_file_field", > > }); > > ``` > > > [tab] 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. > > > > ```python theme={null} > > from pathlib import Path > > > > from onepassword import FileCreateParams > > > > item = await client.items.get("your-vault-id", "your-item-id") > > > > # Attach a file field to the item > > attached_item = await client.items.files.attach( > > item, > > FileCreateParams( > > name="file2.txt", > > content=Path("./example/file2.txt").read_bytes(), > > sectionId="", > > fieldId="new_file_field", > > ), > > ) > > print(f'Attached "file2.txt" to item "{attached_item.title}".') > > ``` ### Remove a file > [tab] 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. > > ```go theme={null} > // Delete a file field from an item > updatedItemWithDeletedFile, err := client.Items().Files().Delete(context.Background(), newItem, newItem.Files[0].SectionID, newItem.Files[0].FieldID) > if err != nil { > panic(err) > } > ``` > [tab] 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. > > ```js theme={null} > // Delete a file field from an item > let deletedItem = await client.items.files.delete( > attachedItem, > attachedItem.files[1].sectionId, > attachedItem.files[1].fieldId, > ); > ``` > [tab] 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. > > ```python theme={null} > item = await client.items.get("your-vault-id", "your-item-id") > > # Delete a file field from an item > deleted_file_item = await client.items.files.delete( > item, > item.files[0].section_id, > item.files[0].field_id, > ) > print( > f"Deleted file '{item.files[0].attributes.name}' from item '{deleted_file_item.title}'." > ) > ``` ## Document operations ### Save a document > [tab] 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. > > ```go theme={null} > fileContent, err := os.ReadFile("./example/service_account/file.txt") > if err != nil { > panic(err) > } > // Create the document item > documentItem, err := client.Items().Create(context.Background(), onepassword.ItemCreateParams{ > Title: "Document Item Created With Go SDK", > Category: onepassword.ItemCategoryDocument, > VaultID: vaultID, > Document: &onepassword.DocumentCreateParams{ > Name: "file.txt", > Content: fileContent, > }, > }) > if err != nil { > panic(err) > } > ``` > [tab] 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. > > ```js theme={null} > // Create a Document Item > let item = await client.items.create({ > title: "Document Item Created With JS SDK", > category: sdk.ItemCategory.Document, > vaultId: vaultId, > document: { > name: "file.txt", > content: new Uint8Array(fs.readFileSync("file.txt")), > }, > }); > ``` > [tab] 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. > > ```python theme={null} > from pathlib import Path > > from onepassword import ( > DocumentCreateParams, > ItemCategory, > ItemCreateParams, > ItemSection, > ) > > vault_id = "your-vault-id" > > # Create a Document item > to_create = ItemCreateParams( > title="Document Item Created with Python SDK", > category=ItemCategory.DOCUMENT, > vault_id=vault_id, > sections=[ > ItemSection(id="", title=""), > ], > document=DocumentCreateParams( > name="file.txt", content=Path("./example/file2.txt").read_bytes() > ), > ) > created_item = await client.items.create(to_create) > print(f'Created Document item "{created_item.title}" ({created_item.id})') > ``` ### Replace a document > [tab] 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. > > ```go theme={null} > // Replace the document item > file2Content, err := os.ReadFile("./example/service_account/file2.txt") > if err != nil { > panic(err) > } > replacedDocItem, err := client.Items().Files().ReplaceDocument(context.Background(), documentItem, onepassword.DocumentCreateParams{ > Name: "file2.txt", > Content: file2Content, > }) > if err != nil { > panic(err) > } > ``` > [tab] 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. > > ```js theme={null} > // Replace the document in the Document Item > let replacedDocumentItem = await client.items.files.replaceDocument(item, { > name: "file2.txt", > content: new Uint8Array(fs.readFileSync("file2.txt")), > }); > ``` > [tab] 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. > > ```python theme={null} > from pathlib import Path > > from onepassword import DocumentCreateParams > > item = await client.items.get("your-vault-id", "your-item-id") > > # Replace the document in the Document item > replaced_item = await client.items.files.replace_document( > item, > DocumentCreateParams( > name="file2.txt", content=Path("./example/file2.txt").read_bytes() > ), > ) > print(f'Replaced document in item "{replaced_item.title}".') > ``` ## 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](/sdks/manage-items) * [Share items using 1Password SDKs](/sdks/share-items) * [List vaults and items using 1Password SDKs](/sdks/list-vaults-items) * [End-to-end setup guide](/sdks/setup-tutorial) * [Workflow: Build integrations with 1Password](/get-started/build-integrations) # Supported functionality Source: https://www.1password.dev/sdks/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](/sdks/load-secrets) * [x] [Retrieve items](/sdks/manage-items#get-an-item) * [x] [Create items](/sdks/manage-items#create-an-item) * [x] [Update items](/sdks/manage-items#update-an-item) * [x] [Delete items](/sdks/manage-items#delete-an-item) * [x] [Archive items](/sdks/manage-items#archive-an-item) * [x] [List items](/sdks/list-vaults-items#list-items) * [x] [Add & update tags on items](/sdks/manage-items#create-an-item) * [x] [Manage autofill websites and behavior](/sdks/manage-items#create-an-item) * [x] [Generate passwords](/sdks/manage-items#generate-a-password) * [x] [Share items](/sdks/share-items/) * [x] [Manage items in bulk](/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](/sdks/files) * [x] Menus * [ ] Passkeys Learn about [supported field types](/sdks/concepts#field-types). Query parameters: * [x] [`otp`](/sdks/concepts#otp) * [x] [`ssh-format`](/sdks/concepts#ssh-format) ### Vault management * [x] [Retrieve vaults](/sdks/vaults#get-a-vault-overview) * [x] [Create vaults](/sdks/vaults#create-a-vault) * [x] [Update vaults](/sdks/vaults#update-a-vault) * [x] [Delete vaults](/sdks/vaults#delete-a-vault) * [x] [List vaults](/sdks/list-vaults-items#list-vaults) * [x] [Manage group vault permissions](/sdks/vault-permissions) * [ ] Manage user vault permissions ### User & access management * [ ] Provision users * [ ] Retrieve users * [ ] List users * [ ] Suspend users * [x] [Retrieve groups](/sdks/groups/) * [ ] List groups * [ ] Create groups * [ ] Update group membership ### Environments management * [x] [Read 1Password Environments](/sdks/environments) ### Compliance & reporting * [ ] Watchtower insights * [ ] Travel mode * [ ] Events \ For now, use [1Password Events API](/events-api/) directly. ### Authentication * [x] [1Password Service Accounts](/service-accounts/get-started/) * [x] [User authentication](/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 Source: https://www.1password.dev/sdks/groups 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/). ## Before you get started Before you begin, [follow the steps to get started](/sdks#get-started) with a 1Password SDK. The examples on this page assume you have an initialized `client` instance. For example: > [tab] Go > > ```go theme={null} > package main > > import ( > "context" > > "github.com/1password/onepassword-sdk-go" > ) > > func main() { > // TODO: Initialize client using your preferred authentication method (see Overview > Get started) > client, err := onepassword.NewClient(context.Background(), > ) > if err != nil { > panic(err) > } > > // Your code here > } > > ``` > [tab] JavaScript > > > [tab] ES Modules > > > > ```javascript theme={null} > > import sdk from "@1password/sdk"; > > > > async function main() { > > const client = await sdk.createClient({ > > // TODO: Initialize client using your preferred authentication method (see Overview > Get started) > > }); > > > > // Your code here > > } > > > > main().catch(console.error); > > > > ``` > > > [tab] CommonJS > > > > ```javascript theme={null} > > const sdk = require("@1password/sdk"); > > > > async function main() { > > const client = await sdk.createClient({ > > // TODO: Initialize client using your preferred authentication method (see Overview > Get started) > > }); > > > > // Your code here > > } > > > > main().catch(console.error); > > > > ``` > [tab] Python > > ```python theme={null} > import asyncio > > from onepassword import Client # Also import DesktopAuth for desktop app authentication. > > async def main(): > # TODO: Initialize client using your preferred authentication method (see Overview > Get started) > client = await Client.authenticate(...) > > # Your code here > > asyncio.run(main()) > > ``` > [!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 > [tab] 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](/sdks/concepts#unique-identifiers). > > ```go theme={null} > // Get a group > group, err := client.Groups().Get(context.Background(), groupID, onepassword.GroupGetParams{}) > if err != nil { > panic(err) > } > fmt.Printf("Group details: %v\\n", group) > ``` > [tab] 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](/sdks/concepts#unique-identifiers). > > ```js theme={null} > // Get a group > const group = await client.groups.get(groupId, { vaultPermissions: false }); > console.log(JSON.stringify(group)); > ``` > [tab] Python > > To fetch a group, use the [`groups.get()`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/groups.py#L18) method. > > ```python theme={null} > from onepassword import GroupGetParams > > # Get a group > group = await client.groups.get("your-group-id", GroupGetParams(vaultPermissions=False)) > print(group) > ``` # Go Source: https://www.1password.dev/sdks/languages/golang # JavaScript Source: https://www.1password.dev/sdks/languages/javascript # Python Source: https://www.1password.dev/sdks/languages/python # List vaults and items using 1Password SDKs Source: https://www.1password.dev/sdks/list-vaults-items 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)](/sdks/concepts#unique-identifiers) for an item or vault. ## Before you get started Before you begin, [follow the steps to get started](/sdks#get-started) with a 1Password SDK. The examples on this page assume you have an initialized `client` instance. For example: > [tab] Go > > ```go theme={null} > package main > > import ( > "context" > > "github.com/1password/onepassword-sdk-go" > ) > > func main() { > // TODO: Initialize client using your preferred authentication method (see Overview > Get started) > client, err := onepassword.NewClient(context.Background(), > ) > if err != nil { > panic(err) > } > > // Your code here > } > > ``` > [tab] JavaScript > > > [tab] ES Modules > > > > ```javascript theme={null} > > import sdk from "@1password/sdk"; > > > > async function main() { > > const client = await sdk.createClient({ > > // TODO: Initialize client using your preferred authentication method (see Overview > Get started) > > }); > > > > // Your code here > > } > > > > main().catch(console.error); > > > > ``` > > > [tab] CommonJS > > > > ```javascript theme={null} > > const sdk = require("@1password/sdk"); > > > > async function main() { > > const client = await sdk.createClient({ > > // TODO: Initialize client using your preferred authentication method (see Overview > Get started) > > }); > > > > // Your code here > > } > > > > main().catch(console.error); > > > > ``` > [tab] Python > > ```python theme={null} > import asyncio > > from onepassword import Client # Also import DesktopAuth for desktop app authentication. > > async def main(): > # TODO: Initialize client using your preferred authentication method (see Overview > Get started) > client = await Client.authenticate(...) > > # Your code here > > asyncio.run(main()) > > ``` > [!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. ## List vaults > [tab] Go > > The [`Vaults().List()`](https://github.com/1Password/onepassword-sdk-go/blob/main/vaults.go#L66) method gets all vaults in an account. > > ```go theme={null} > // List vaults > vaults, err := client.Vaults().List(context.Background()) > if err != nil { > panic(err) > } > for _, vault := range vaults { > fmt.Println("VAULT ID: ", vault.ID, "VAULT NAME: ", vault.Title) > } > ``` > [tab] 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. > > ```js theme={null} > // List vaults > const vaults = await client.vaults.list({ decryptDetails: true }); > for await (const vault of vaults) { > console.log(JSON.stringify(vault, null, 2)); > } > ``` > [tab] 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. > > ```python theme={null} > # List vaults > vaults = await client.vaults.list() > for vault in vaults: > print(f"{vault.title} ({vault.id})") > ``` ## List items > [tab] 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). > > ```go theme={null} > overviews, err := client.Items().List(context.Background(), vaultID) > if err != nil { > panic(err) > } > for _, overview := range overviews { > fmt.Printf("%s %s\\n", overview.ID, overview.Title) > } > ``` > [tab] 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). > > ```js theme={null} > const overviews = await client.items.list(vaultId); > for (const overview of overviews) { > console.log(overview.id + " " + overview.title); > } > ``` > [tab] 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). > > ```python theme={null} > # List items > overviews = await client.items.list("your-vault-id") > for overview in overviews: > print(f"{overview.title} ({overview.id})") > ``` ### Filter listed items by state You can filter listed items by their [state](/sdks/concepts#item-states): `Active` or `Archived`. > [tab] 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: > > ```go theme={null} > archivedOverviews, err := client.Items().List(context.Background(), vaultID, > onepassword.NewItemListFilterTypeVariantByState( > &onepassword.ItemListFilterByStateInner{ > Active: false, > Archived: true, > }, > ), > ) > if err != nil { > panic(err) > } > for _, overview := range archivedOverviews { > fmt.Printf("%s %s\\n", overview.ID, overview.Title) > } > ``` > [tab] 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: > > ```js theme={null} > const archivedOverviews = await client.items.list(vaultId, { > type: "ByState", > content: { active: false, archived: true }, > }); > for (const overview of archivedOverviews) { > console.log(overview.id + " " + overview.title); > } > ``` > [tab] 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: > > ```python theme={null} > from onepassword import ItemListFilterByState, ItemListFilterByStateInner > > # List items using item filters > archived_overviews = await client.items.list( > "your-vault-id", > ItemListFilterByState( > content=ItemListFilterByStateInner(active=False, archived=True) > ), > ) > for overview in archived_overviews: > print(f"{overview.title} ({overview.id})") > ``` ## Learn more * [Secret reference syntax](/cli/secret-reference-syntax/) * [Load secrets using 1Password SDKs](/sdks/load-secrets/) * [Manage items using 1Password SDKs](/sdks/manage-items/) * [Share items using 1Password SDKs](/sdks/share-items/) * [Workflow: Build integrations with 1Password](/get-started/build-integrations) * [Workflow: Secure local development](/get-started/secure-developer-secrets) # Load secrets using 1Password SDKs Source: https://www.1password.dev/sdks/load-secrets You can use 1Password SDKs to securely load secrets into your code with [secret references](/cli/secret-reference-syntax/). You can retrieve secrets from [supported field types](/sdks/concepts#field-types). You can also retrieve one-time passwords using the [`otp` attribute parameter](/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 ``` ## Before you get started Before you begin, [follow the steps to get started](/sdks#get-started) with a 1Password SDK. The examples on this page assume you have an initialized `client` instance. For example: > [tab] Go > > ```go theme={null} > package main > > import ( > "context" > > "github.com/1password/onepassword-sdk-go" > ) > > func main() { > // TODO: Initialize client using your preferred authentication method (see Overview > Get started) > client, err := onepassword.NewClient(context.Background(), > ) > if err != nil { > panic(err) > } > > // Your code here > } > > ``` > [tab] JavaScript > > > [tab] ES Modules > > > > ```javascript theme={null} > > import sdk from "@1password/sdk"; > > > > async function main() { > > const client = await sdk.createClient({ > > // TODO: Initialize client using your preferred authentication method (see Overview > Get started) > > }); > > > > // Your code here > > } > > > > main().catch(console.error); > > > > ``` > > > [tab] CommonJS > > > > ```javascript theme={null} > > const sdk = require("@1password/sdk"); > > > > async function main() { > > const client = await sdk.createClient({ > > // TODO: Initialize client using your preferred authentication method (see Overview > Get started) > > }); > > > > // Your code here > > } > > > > main().catch(console.error); > > > > ``` > [tab] Python > > ```python theme={null} > import asyncio > > from onepassword import Client # Also import DesktopAuth for desktop app authentication. > > async def main(): > # TODO: Initialize client using your preferred authentication method (see Overview > Get started) > client = await Client.authenticate(...) > > # Your code here > > asyncio.run(main()) > > ``` > [!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. ## Load a secret from 1Password Replace the placeholder [secret reference](/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](/sdks/concepts#unique-identifiers) instead of the name in the secret reference. > [tab] 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. > > ```go theme={null} > // Retrieves a secret from 1Password. > // Takes a secret reference as input and returns the secret to which it points. > secret, err := client.Secrets().Resolve(context.Background(), fmt.Sprintf("op://%s/%s/%s", vaultID, itemID, fieldID)) > if err != nil { > panic(err) > } > fmt.Println(secret) > ``` > [tab] 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. > > ```js theme={null} > // Fetches a secret. > const secret = await client.secrets.resolve( > "op://" + item.vaultId + "/" + item.id + "/username", > ); > console.log(secret); > ``` > [tab] 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. > > ```python theme={null} > # Fetch a secret using a secret reference > value = await client.secrets.resolve( > f"op://vault-id/item-id/field-id" > ) > print(value) > ``` ## Retrieve multiple secrets > [tab] 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](/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. > > ```go theme={null} > // Retrieves multiple secrets from 1Password. > // Takes multiple secret references as input and returns the secret to which it points. > secret, _ := client.Secrets().ResolveAll( > context.Background(), > []string{ > fmt.Sprintf("op://%s/%s/%s", vaultID, itemID, fieldID), > fmt.Sprintf("op://%s/%s/%s", vaultID, itemID, fieldID2), > }, > ) > for _, s := range secret.IndividualResponses { > if s.Error != nil { > panic(string(s.Error.Type)) > } > fmt.Println(s.Content.Secret) > } > ``` > [tab] 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](/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. > > ```js theme={null} > try { > // Fetch all secrets > const secrets = await client.secrets.resolveAll([ > "op://7turaasywpymt3jecxoxk5roli/hdvxoumwprditdustkxv7d3dqy/username", > "op://7turaasywpymt3jecxoxk5roli/hdvxoumwprditdustkxv7d3dqy/password", > ]); > > for (const [_, response] of Object.entries(secrets.individualResponses)) { > if (response.error) { > console.error("Error resolving secret:", response.error); > continue; > } > > console.log(response.content.secret); > } > } catch (error) { > console.error("An unexpected error occurred:", error); > } > ``` > [tab] 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](/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 theme={null} > # Fetch multiple secrets using secret references > secrets = await client.secrets.resolve_all( > [ > f"op://vault-id/item-id/field-id", > f"op://vault-id/item-id/field-id2", > ] > ) > for secret in secrets.individual_responses.values(): > if secret.error is not None: > print(str(secret.error)) > else: > print(secret.content.secret) > ``` ## Validate a secret reference > [tab] 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](/cli/secret-reference-syntax/) is formatted correctly. > > ```go theme={null} > // Validate your secret reference > err := onepassword.Secrets.ValidateSecretReference(context.Background(), fmt.Sprintf("op://%s/%s/%s", vaultID, itemID, fieldID)) > if err != nil { > panic(err) > } > ``` > [tab] 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](/cli/secret-reference-syntax/) is formatted correctly. > > ```js theme={null} > // Validate a secret reference > try { > sdk.Secrets.validateSecretReference("op://vault/item/field"); > } catch (error) { > console.error(error); > } > ``` > [tab] 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](/cli/secret-reference-syntax/) is formatted correctly. > > ```python theme={null} > from onepassword import Secrets > > # Validate a secret reference > try: > Secrets.validate_secret_reference("op://vault-id/item-id/field-id") > except Exception as error: > print(error) > ``` If the secret reference is formatted incorrectly, the SDK will return an error that describes the syntax problem. Learn more about [secret references](/cli/secret-reference-syntax). ## Learn more * [Secret reference syntax](/cli/secret-reference-syntax/) * [Manage items using 1Password SDKs](/sdks/manage-items/) * [List vaults and items using 1Password SDKs](/sdks/list-vaults-items/) * [Share items using 1Password SDKs](/sdks/share-items/) * [Workflow: Build integrations with 1Password](/get-started/build-integrations) * [Workflow: Secure local development](/get-started/secure-developer-secrets) # Manage items using 1Password SDKs Source: https://www.1password.dev/sdks/manage-items You can use 1Password SDKs to read, write, and update secret values stored in your 1Password items. When managing items, you must use [unique identifiers (IDs)](/sdks/concepts#unique-identifiers) in place of vault, item, section, and field names. You can get IDs by [listing vaults and items](/sdks/list-vaults-items/). You can perform item management operations on [supported field types](/sdks/concepts#field-types). Some field types have [special constraints](#appendix-field-type-constraints). ## Before you get started Before you begin, [follow the steps to get started](/sdks#get-started) with a 1Password SDK. The examples on this page assume you have an initialized `client` instance, except for [password generation](#generate-a-password), which does not require a `client`. For example: > [tab] Go > > ```go theme={null} > package main > > import ( > "context" > > "github.com/1password/onepassword-sdk-go" > ) > > func main() { > // TODO: Initialize client using your preferred authentication method (see Overview > Get started) > client, err := onepassword.NewClient(context.Background(), > ) > if err != nil { > panic(err) > } > > // Your code here > } > > ``` > [tab] JavaScript > > > [tab] ES Modules > > > > ```javascript theme={null} > > import sdk from "@1password/sdk"; > > > > async function main() { > > const client = await sdk.createClient({ > > // TODO: Initialize client using your preferred authentication method (see Overview > Get started) > > }); > > > > // Your code here > > } > > > > main().catch(console.error); > > > > ``` > > > [tab] CommonJS > > > > ```javascript theme={null} > > const sdk = require("@1password/sdk"); > > > > async function main() { > > const client = await sdk.createClient({ > > // TODO: Initialize client using your preferred authentication method (see Overview > Get started) > > }); > > > > // Your code here > > } > > > > main().catch(console.error); > > > > ``` > [tab] Python > > ```python theme={null} > import asyncio > > from onepassword import Client # Also import DesktopAuth for desktop app authentication. > > async def main(): > # TODO: Initialize client using your preferred authentication method (see Overview > Get started) > client = await Client.authenticate(...) > > # Your code here > > asyncio.run(main()) > > ``` > [!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 an item > [tab] 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. > > ```go theme={null} > sectionID := "extraDetails" > itemParams := onepassword.ItemCreateParams{ > Title: "Login created with the SDK", > Category: onepassword.ItemCategoryLogin, > VaultID: vaultID, > Fields: []onepassword.ItemField{ > { > ID: "username", > Title: "username", > Value: "Wendy_Appleseed", > FieldType: onepassword.ItemFieldTypeText, > }, > { > ID: "password", > Title: "password", > Value: "my_weak_password123", > FieldType: onepassword.ItemFieldTypeConcealed, > }, > { > ID: "onetimepassword", > Title: "one-time password", > Value: "otpauth://totp/my-example-otp?secret=jncrjgbdjnrncbjsr&issuer=1Password", > SectionID: §ionID, > FieldType: onepassword.ItemFieldTypeTOTP, > }, > }, > Sections: []onepassword.ItemSection{ > { > ID: sectionID, > Title: "Extra Details", > }, > }, > Tags: []string{"test tag1", "test tag 2"}, > Websites: []onepassword.Website{ > { > URL: "1password.com", > AutofillBehavior: onepassword.AutofillBehaviorAnywhereOnWebsite, > Label: "my custom website", > }, > }, > } > > // Creates a new item based on the structure definition above > createdItem, err := client.Items().Create(context.Background(), itemParams) > if err != nil { > panic(err) > } > ``` > [tab] 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. > > ```js theme={null} > // Creates an item > let item = await client.items.create({ > title: "My Item", > category: sdk.ItemCategory.Login, > vaultId: vaultId, > fields: [ > { > id: "username", > title: "username", > fieldType: sdk.ItemFieldType.Text, > value: "my username", > }, > { > id: "password", > title: "password", > fieldType: sdk.ItemFieldType.Concealed, > value: "my secret value", > }, > { > id: "onetimepassword", > title: "one-time password", > sectionId: "custom section", > fieldType: sdk.ItemFieldType.Totp, > value: > "otpauth://totp/my-example-otp?secret=jncrjgbdjnrncbjsr&issuer=1Password", > }, > ], > sections: [ > { > id: "custom section", > title: "my section", > }, > ], > tags: ["test tag 1", "test tag 2"], > websites: [ > { > url: "example.com", > label: "url", > autofillBehavior: sdk.AutofillBehavior.AnywhereOnWebsite, > }, > ], > }); > ``` > [tab] 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. > > ```python theme={null} > from onepassword import ( > AutofillBehavior, > ItemCategory, > ItemCreateParams, > ItemField, > ItemFieldType, > ItemSection, > Website, > ) > > # Create an item > to_create = ItemCreateParams( > title="MyName", > category=ItemCategory.LOGIN, > vault_id="your-vault-id", > fields=[ > ItemField( > id="username", > title="username", > field_type=ItemFieldType.TEXT, > value="my-username", > ), > ItemField( > id="password", > title="password", > field_type=ItemFieldType.CONCEALED, > value="my-password", > ), > ItemField( > id="onetimepassword", > title="one-time-password", > field_type=ItemFieldType.TOTP, > section_id="totpsection", > value="otpauth://totp/my-example-otp?secret=jncrjgbdjnrncbjsr&issuer=1Password", > ), > ], > sections=[ > ItemSection(id="", title=""), > ItemSection(id="totpsection", title=""), > ], > tags=["test tag 1", "test tag 2"], > websites=[ > Website( > label="my custom website", > url="https://example.com", > autofill_behavior=AutofillBehavior.NEVER, > ) > ], > ) > created_item = await client.items.create(to_create) > print(f'Created item "{created_item.title}" ({created_item.id})') > ``` ### 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](/cli/item-fields#built-in-fields) ids. | | `Title` | The name of the field. | | `Field type` | The [type of field](/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](/sdks/files/). ## Get an item > [tab] 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): > > ```go theme={null} > // Retrieves the newly created item > login, err := client.Items().Get(context.Background(), createdItem.VaultID, createdItem.ID) > if err != nil { > panic(err) > } > ``` > [tab] 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): > > ```js theme={null} > let retrievedItem = await client.items.get(item.vaultId, item.id); > ``` > [tab] 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 an item and print its name and ID: > > ```python theme={null} > # Get an item > item = await client.items.get("your-vault-id", "your-item-id") > print(f'Retrieved item "{item.title}" ({item.id})') > ``` ## 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. > [tab] Go > > To retrieve and print a one-time password from the item [created in the first step](#create-an-item): > > ```go theme={null} > // Retrieve TOTP code from an item > for _, f := range login.Fields { > if f.FieldType == onepassword.ItemFieldTypeTOTP { > OTPFieldDetails := f.Details.OTP() > if OTPFieldDetails.ErrorMessage == nil { > fmt.Println(*OTPFieldDetails.Code) > } else { > panic(*OTPFieldDetails.ErrorMessage) > } > } > } > ``` > [tab] JavaScript > > To retrieve and print a one-time password from the item [created in the first step](#create-an-item): > > ```js theme={null} > // Get a one-time password code. > let element = item.fields.find((element) => { > return element.fieldType == sdk.ItemFieldType.Totp; > }); > > if (!element) { > console.error("no totp field found on item"); > } else { > switch (element.details.type) { > case "Otp": { > if (element.details.content.code) { > console.log(element.details.content.code); > } else { > console.error(element.details.content.errorMessage); > } > } > default: > } > } > ``` > [tab] Python > > ```python theme={null} > item = await client.items.get("your-vault-id", "your-item-id") > > # Get a one-time password code from an item > for f in item.fields: > if f.field_type == "Totp": > if f.details.content.error_message is not None: > print(f.details.content.error_message) > else: > print(f.details.content.code) > ``` ## Update an item > [tab] 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. > > ```go theme={null} > // Retrieves the newly created item > item, err := client.Items().Get(context.Background(), existingVaultID, existingItemID) > if err != nil { > panic(err) > } > > // Finds the field named "Details" and edits its value > for i := range item.Fields { > if item.Fields[i].Title == "Details" { > item.Fields[i].Value = "updated details" > } > } > item.Title = "New Title" > item.Websites = append(item.Websites, onepassword.Website{ > URL: "2password.com", > Label: "my second custom website", > AutofillBehavior: onepassword.AutofillBehaviorNever, > }) > > updatedItem, err := client.Items().Put(context.Background(), item) > if err != nil { > panic(err) > } > ``` > [tab] 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. > > ```js theme={null} > // Edit an item (change the password) > let newItem = { > ...retrievedItem, > fields: retrievedItem.fields.map((f) => { > if (f.title == "password") { > return { ...f, value: "my-new-password" }; > } else { > return f; > } > }), > }; > let updatedItem = await client.items.put(newItem); > ``` > [tab] 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. > > ```python theme={null} > from onepassword import AutofillBehavior, Website > > item = await client.items.get("your-vault-id", "your-item-id") > > # Update an item > item.fields[0].value = "new_value" > item.websites.append( > Website( > label="my custom website 2", > url="https://example2.com", > autofill_behavior=AutofillBehavior.NEVER, > ), > ) > updated_item = await client.items.put(item) > print(f"Updated item: {updated_item.title} ({updated_item.id})") > ``` ## Archive an item > [tab] 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. > > ```go theme={null} > // Archive a item from your vault. > err := client.Items().Archive(context.Background(), vaultID, itemID) > > if err != nil { > panic(err) > } > ``` > [tab] 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. > > ```js theme={null} > // Archive an item from your vault. > await client.items.archive(vaultId, itemId); > ``` > [tab] 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. > > ```python theme={null} > vault_id = "your-vault-id" > item_id = "your-item-id" > > # Archive an item > await client.items.archive(vault_id, item_id) > print(f"Item {item_id} successfully archived from vault {vault_id}.") > ``` ## Delete an item > [tab] 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. > > ```go theme={null} > // Delete a item from your vault. > err := client.Items().Delete(context.Background(), vaultID, itemID) > if err != nil { > panic(err) > } > ``` > [tab] 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. > > ```js theme={null} > // Delete an item from your vault. > await client.items.delete(item.vaultId, item.id); > ``` > [tab] 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. > > ```python theme={null} > vault_id = "your-vault-id" > item_id = "your-item-id" > > # Delete an item > await client.items.delete(vault_id, item_id) > print(f"Item {item_id} successfully deleted from vault {vault_id}.") > ``` ## Generate a password > [tab] 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#L1170), [`Random`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L1175), or [`Memorable`](https://github.com/1Password/onepassword-sdk-go/blob/main/types.go#L1158) password recipe struct, depending on the type of password you want to generate. > > > [tab] PIN > > > > Generates a PIN code. Pass a `PasswordRecipePinInner` struct with the following field: > > > > * `Length`: The number of digits in the generated code. > > > > ```go theme={null} > > pinPassword, err := onepassword.Secrets.GeneratePassword(context.Background(), onepassword.NewPasswordRecipeTypeVariantPin(&onepassword.PasswordRecipePinInner{Length: 10})) > > if err != nil { > > panic(err) > > } > > fmt.Println(pinPassword.Password) > > ``` > > > [tab] Random > > > > Generates a random password. Pass a `PasswordRecipeRandomInner` struct with the following fields: > > > > * `IncludeDigits`: Whether the password includes digits. > > * `IncludeSymbols`: Whether the password includes symbols. > > * `Length`: The length of the password. > > > > ```go theme={null} > > randomPassword, err := onepassword.Secrets.GeneratePassword(context.Background(), onepassword.NewPasswordRecipeTypeVariantRandom(&onepassword.PasswordRecipeRandomInner{ > > IncludeDigits: true, > > IncludeSymbols: true, > > Length: 10, > > })) > > if err != nil { > > panic(err) > > } > > fmt.Println(randomPassword.Password) > > ``` > > > [tab] Memorable > > > > Generates a memorable password. For example, `correct-horse-battery-staple`. Pass a `PasswordRecipeMemorableInner` struct with the following fields: > > > > * `SeparatorType`: The separator used between words. Options: `SeparatorTypeDigits`, `SeparatorTypeDigitsAndSymbols`, `SeparatorTypeSpaces`, `SeparatorTypeHyphens`, `SeparatorTypeUnderscores`, `SeparatorTypePeriods`, `SeparatorTypeCommas` > > * `WordListType`: Whether the memorable password is made up of full words or random syllables. Options: `WordListTypeFullWords`, `WordListTypeSyllables`, `WordListTypeThreeLetters` > > * `Capitalize`: Whether to capitalize one section of the generated password. > > * `WordCount`: The number of words included in the password. > > > > ```go theme={null} > > memorablePassword, err := onepassword.Secrets.GeneratePassword(context.Background(), onepassword.NewPasswordRecipeTypeVariantMemorable(&onepassword.PasswordRecipeMemorableInner{ > > SeparatorType: onepassword.SeparatorTypeCommas, > > WordListType: onepassword.WordListTypeFullWords, > > Capitalize: true, > > WordCount: 10, > > })) > > if err != nil { > > panic(err) > > } > > fmt.Println(memorablePassword.Password) > > ``` > [tab] 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#L677), [`Random`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L684), or [`Memorable`](https://github.com/1Password/onepassword-sdk-js/blob/main/client/src/types.ts#L664) password recipe object, depending on the type of password you want to generate. > > > [tab] PIN > > > > Generates a PIN code. Set `type` to `"Pin"` and pass a `parameters` object with the following property: > > > > * `length`: The number of digits in the generated code. > > > > ```js theme={null} > > try { > > let pinPassword = sdk.Secrets.generatePassword({ > > type: "Pin", > > parameters: { > > length: 8, > > }, > > }); > > console.log(pinPassword); > > } catch (error) { > > console.error(error); > > } > > ``` > > > [tab] Random > > > > Generates a random password. Set `type` to `"Random"` and pass a `parameters` object with the following properties: > > > > * `includeDigits`: Whether the password includes digits. > > * `includeSymbols`: Whether the password includes symbols. > > * `length`: The length of the password. > > > > ```js theme={null} > > try { > > let randomPassword = sdk.Secrets.generatePassword({ > > type: "Random", > > parameters: { > > includeDigits: true, > > includeSymbols: true, > > length: 8, > > }, > > }); > > console.log(randomPassword); > > } catch (error) { > > console.error(error); > > } > > ``` > > > [tab] Memorable > > > > Generates a memorable password. For example, `correct-horse-battery-staple`. Set `type` to `"Memorable"` and pass a `parameters` object with the following properties: > > > > * `separatorType`: The separator used between words. Options: `SeparatorType.Digits`, `SeparatorType.DigitsAndSymbols`, `SeparatorType.Spaces`, `SeparatorType.Hyphens`, `SeparatorType.Underscores`, `SeparatorType.Periods`, `SeparatorType.Commas` > > * `wordListType`: Whether the memorable password is made up of full words or random syllables. Options: `WordListType.FullWords`, `WordListType.Syllables`, `WordListType.ThreeLetters` > > * `capitalize`: Whether to capitalize one section of the generated password. > > * `wordCount`: The number of words included in the password. > > > > ```js theme={null} > > try { > > let memorablePassword = sdk.Secrets.generatePassword({ > > type: "Memorable", > > parameters: { > > separatorType: sdk.SeparatorType.Digits, > > capitalize: true, > > wordListType: sdk.WordListType.FullWords, > > wordCount: 8, > > }, > > }); > > console.log(memorablePassword); > > } catch (error) { > > console.error(error); > > } > > ``` > [tab] 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#L1469), [`Random`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L1480), or [`Memorable`](https://github.com/1Password/onepassword-sdk-python/blob/main/src/onepassword/types.py#L1444) password recipe object, depending on the type of password you want to generate. > > > [tab] PIN > > > > Generates a PIN code. Pass a `PasswordRecipePin` object whose `parameters` field is a `PasswordRecipePinInner` object with the following parameter: > > > > * `length`: The number of digits in the generated code. > > > > ```python theme={null} > > from onepassword import PasswordRecipePin, PasswordRecipePinInner, Secrets > > > > # Generate a PIN password > > pin_password = Secrets.generate_password( > > PasswordRecipePin(parameters=PasswordRecipePinInner(length=8)) > > ) > > print(pin_password) > > ``` > > > [tab] Random > > > > Generates a random password. Pass a `PasswordRecipeRandom` object whose `parameters` field is a `PasswordRecipeRandomInner` object with the following parameters: > > > > * `includeDigits`: Whether the password includes digits. > > * `includeSymbols`: Whether the password includes symbols. > > * `length`: The length of the password. > > > > ```python theme={null} > > from onepassword import ( > > PasswordRecipeRandom, > > PasswordRecipeRandomInner, > > Secrets, > > ) > > > > # Generate a random password > > random_password = Secrets.generate_password( > > PasswordRecipeRandom( > > parameters=PasswordRecipeRandomInner( > > length=10, > > includeDigits=False, > > includeSymbols=False, > > ) > > ), > > ) > > print(random_password) > > ``` > > > [tab] Memorable > > > > Generates a memorable password. For example, `correct-horse-battery-staple`. Pass a `PasswordRecipeMemorable` object whose `parameters` field is a `PasswordRecipeMemorableInner` object with the following parameters: > > > > * `separatorType`: The separator used between words. Options: `SeparatorType.DIGITS`, `SeparatorType.DIGITSANDSYMBOLS`, `SeparatorType.SPACES`, `SeparatorType.HYPHENS`, `SeparatorType.UNDERSCORES`, `SeparatorType.PERIODS`, `SeparatorType.COMMAS` > > * `wordListType`: Whether the memorable password is made up of full words or random syllables. Options: `WordListType.FULLWORDS`, `WordListType.SYLLABLES`, `WordListType.THREELETTERS` > > * `capitalize`: Whether to capitalize one section of the generated password. > > * `wordCount`: The number of words included in the password. > > > > ```python theme={null} > > from onepassword import ( > > PasswordRecipeMemorable, > > PasswordRecipeMemorableInner, > > Secrets, > > SeparatorType, > > WordListType, > > ) > > > > # Generate a memorable password > > memorable_password = Secrets.generate_password( > > PasswordRecipeMemorable( > > parameters=PasswordRecipeMemorableInner( > > separatorType=SeparatorType.UNDERSCORES, > > wordListType=WordListType.SYLLABLES, > > capitalize=False, > > wordCount=3, > > ) > > ), > > ) > > print(memorable_password) > > ``` ## Manage items in bulk ### Create items > [tab] 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](/sdks/concepts#unique-identifiers) for the vault where you want to create the items. > > ```go theme={null} > sectionID := "extraDetails" > var itemsToCreate []onepassword.ItemCreateParams > for i := 1; i <= 3; i++ { > itemsToCreate = append(itemsToCreate, onepassword.ItemCreateParams{ > Title: fmt.Sprintf("Login %d created with the SDK", i), > Category: onepassword.ItemCategoryLogin, > VaultID: vaultID, > Fields: []onepassword.ItemField{ > { > ID: "username", > Title: "username", > Value: "Wendy_Appleseed", > FieldType: onepassword.ItemFieldTypeText, > }, > { > ID: "password", > Title: "password", > Value: "my_weak_password123", > FieldType: onepassword.ItemFieldTypeConcealed, > }, > { > ID: "onetimepassword", > Title: "one-time password", > Value: "otpauth://totp/my-example-otp?secret=jncrjgbdjnrncbjsr&issuer=1Password", > SectionID: §ionID, > FieldType: onepassword.ItemFieldTypeTOTP, > }, > }, > Sections: []onepassword.ItemSection{ > { > ID: sectionID, > Title: "Extra Details", > }, > }, > Tags: []string{"test tag1", "test tag 2"}, > Websites: []onepassword.Website{ > { > URL: "1password.com", > AutofillBehavior: onepassword.AutofillBehaviorAnywhereOnWebsite, > Label: "my custom website", > }, > }, > }) > } > > // Create all items in the same vault in a single batch > batchCreateResponse, err := client.Items().CreateAll(context.Background(), vaultID, itemsToCreate) > if err != nil { > panic(err) > } > > var itemIDs []string > for _, res := range batchCreateResponse.IndividualResponses { > if res.Content != nil { > fmt.Printf("Created Item %q (%s)\\n", res.Content.Title, res.Content.ID) > itemIDs = append(itemIDs, res.Content.ID) > } else if res.Error != nil { > fmt.Printf("[Batch create] Something went wrong: %s\\n", res.Error) > } > } > ``` > [tab] 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](/sdks/concepts#unique-identifiers) for the vault where you want to create the items. > > ```js theme={null} > itemsToCreate = []; > for (let i = 1; i <= 3; i++) { > itemsToCreate.push({ > title: "My Login Item " + i, > category: sdk.ItemCategory.Login, > vaultId, > fields: [ > { > id: "username", > title: "username", > fieldType: sdk.ItemFieldType.Text, > value: "my username", > }, > { > id: "password", > title: "password", > fieldType: sdk.ItemFieldType.Concealed, > value: "my secret value", > }, > { > id: "onetimepassword", > title: "one-time password", > sectionId: "custom section", > fieldType: sdk.ItemFieldType.Totp, > value: > "otpauth://totp/my-example-otp?secret=jncrjgbdjnrncbjsr&issuer=1Password", > }, > ], > sections: [ > { > id: "custom section", > title: "my section", > }, > ], > tags: ["test tag 1", "test tag 2"], > websites: [ > { > url: "example.com", > label: "url", > autofillBehavior: sdk.AutofillBehavior.AnywhereOnWebsite, > }, > ], > }); > } > > const batchCreateResponse = await client.items.createAll( > vaultId, > itemsToCreate, > ); > > let itemIDs = []; > for (const res of batchCreateResponse.individualResponses) { > if (res.content) { > console.log( > "Created item", > res.content.title, > "(" + res.content.id + ")", > ); > itemIDs.push(res.content.id); > } else if (res.error) { > console.log( > "[Batch create] Something went wrong:", > res.error, > ); > } > } > ``` > [tab] 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](/sdks/concepts#unique-identifiers) for the vault where you want to create the items. > > ```python theme={null} > from onepassword import ( > AutofillBehavior, > ItemCategory, > ItemCreateParams, > ItemField, > ItemFieldType, > ItemSection, > Website, > ) > > vault_id = "your-vault-id" > > items_to_create = [] > for i in range(1, 4): > items_to_create.append( > ItemCreateParams( > title="My Login Item {}".format(i), > category=ItemCategory.LOGIN, > vault_id=vault_id, > fields=[ > ItemField( > id="username", > title="username", > field_type=ItemFieldType.TEXT, > value="my-username", > ), > ItemField( > id="password", > title="password", > field_type=ItemFieldType.CONCEALED, > value="my-password", > ), > ItemField( > id="onetimepassword", > title="one-time-password", > field_type=ItemFieldType.TOTP, > section_id="totpsection", > value="otpauth://totp/my-example-otp?secret=jncrjgbdjnrncbjsr&issuer=1Password", > ), > ], > sections=[ > ItemSection(id="", title=""), > ItemSection(id="totpsection", title=""), > ], > tags=["test tag 1", "test tag 2"], > websites=[ > Website( > label="my custom website", > url="https://example.com", > autofill_behavior=AutofillBehavior.NEVER, > ) > ], > ) > ) > > # Batch create all items in the same vault > batchCreateResponse = await client.items.create_all(vault_id, items_to_create) > > item_ids = [] > for res in batchCreateResponse.individual_responses: > if res.content is not None: > print('Created item "{}" ({})'.format(res.content.title, res.content.id)) > item_ids.append(res.content.id) > elif res.error is not None: > print("[Batch create] Something went wrong: {}".format(res.error)) > ``` ### Get items > [tab] 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](/sdks/concepts#unique-identifiers). > > To get the items you [created in the previous step](#create-items): > > ```go theme={null} > // Get multiple items form the same vault in a single batch > batchGetResponse, err := client.Items().GetAll(context.Background(), vaultID, itemIDs) > if err != nil { > panic(err) > } > for _, res := range batchGetResponse.IndividualResponses { > if res.Content != nil { > fmt.Printf("Obtained Item %q (%s)\\n", res.Content.Title, res.Content.ID) > } else if res.Error != nil { > fmt.Printf("[Batch get] Something went wrong: %s\\n", res.Error) > } > } > ``` > [tab] 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](/sdks/concepts#unique-identifiers). > > To get the items you [created in the previous step](#create-items): > > ```js theme={null} > const batchGetResponse = await client.items.getAll(vaultId, itemIDs); > for (const res of batchGetResponse.individualResponses) { > if (res.content) { > console.log( > "Obtained item", > res.content.title, > "(" + res.content.id + ")", > ); > } else if (res.error) { > console.log( > "[Batch get] Something went wrong:", > res.error, > ); > } > } > ``` > [tab] 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](/sdks/concepts#unique-identifiers). > > ```python theme={null} > vault_id = "your-vault-id" > item_ids = ["your-item-id-1", "your-item-id-2"] > > # Get multiple items from the same vault > batchGetReponse = await client.items.get_all(vault_id, item_ids) > for res in batchGetReponse.individual_responses: > if res.content is not None: > print('Obtained item "{}" ({})'.format(res.content.title, res.content.id)) > elif res.error is not None: > print("[Batch get] Something went wrong: {}".format(res.error)) > ``` ### Delete items > [tab] 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](/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): > > ```go theme={null} > // Delete multiple items from the same vault in a single batch > batchDeleteResponse, err := client.Items().DeleteAll(context.Background(), vaultID, itemIDs) > if err != nil { > panic(err) > } > for id, res := range batchDeleteResponse.IndividualResponses { > if res.Error != nil { > fmt.Printf("[Batch delete] Something went wrong: %s\\n", res.Error) > } else { > fmt.Printf("Deleted item %s\\n", id) > } > } > ``` > [tab] 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](/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): > > ```js theme={null} > const batchDeleteResponse = await client.items.deleteAll(vaultId, itemIDs); > for (const [id, res] of Object.entries( > batchDeleteResponse.individualResponses, > )) { > if (res.error) { > console.log( > "[Batch delete] Something went wrong:", > res.error, > ); > } else { > console.log("Deleted item", id); > } > } > ``` > [tab] 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](/sdks/concepts#unique-identifiers). Deleted items [remain available in Recently Deleted](https://support.1password.com/archive-delete-items/) for 30 days. > > ```python theme={null} > vault_id = "your-vault-id" > item_ids = ["your-item-id-1", "your-item-id-2"] > > # Delete multiple items from the same vault > batchDeleteResponse = await client.items.delete_all(vault_id, item_ids) > for id, res in batchDeleteResponse.individual_responses.items(): > if res.error is not None: > print("[Batch delete] Something went wrong: {}".format(res.error)) > else: > print("Deleted item {}".format(id)) > ``` ## Appendix: Field type constraints Some [supported field types](/sdks/concepts#field-types) have special requirements and constraints. Use these field definitions inside the `fields` list when creating or updating an item. ### 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. > [tab] Go > > ```go theme={null} > address := onepassword.NewItemFieldDetailsTypeVariantAddress(&onepassword.AddressFieldDetails{ > Street: "123 Main St", > City: "Anytown", > State: "CA", > Zip: "12345", > Country: "USA", > }) > addressField := onepassword.ItemField{ > ID: "address", > Title: "Address", > SectionID: §ionID, > FieldType: onepassword.ItemFieldTypeAddress, > Value: "", > Details: &address, > } > ``` > [tab] JavaScript > > ```js theme={null} > { > id: "address", > title: "Address", > sectionId: "custom section", > fieldType: sdk.ItemFieldType.Address, > value: "", > details: { > type: "Address", > content: { > street: "1234 Elm St", > city: "Springfield", > country: "USA", > zip: "12345", > state: "IL", > }, > }, > }, > ``` > [tab] Python > > ```python theme={null} > from onepassword import ( > AddressFieldDetails, > ItemField, > ItemFieldDetailsAddress, > ItemFieldType, > ) > > ItemField( > id="address", > title="Address", > sectionId="", > field_type=ItemFieldType.ADDRESS, > value="", > details=ItemFieldDetailsAddress( > content=AddressFieldDetails( > street="1234 Main St", > city="San Francisco", > state="CA", > zip="94111", > country="USA", > ), > ), > ), > ``` ### 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`. > [tab] Go > > ```go theme={null} > { > ID: "date", > Title: "Date", > SectionID: §ionID, > FieldType: onepassword.ItemFieldTypeDate, > Value: "1998-03-15", > }, > ``` > [tab] JavaScript > > ```js theme={null} > { > id: "date", > title: "Date", > sectionId: "custom section", > fieldType: sdk.ItemFieldType.Date, > value: "1998-03-15", > }, > ``` > [tab] Python > > ```python theme={null} > from onepassword import ItemField, ItemFieldType > > ItemField( > id="date", > title="Date", > section_id="", > field_type=ItemFieldType.DATE, > value="1998-03-15", > ), > ``` ### MonthYear For a `MonthYear` type item field, the value must be a string formatted as `MM/YYYY`. For example, `10/2000`. > [tab] Go > > ```go theme={null} > { > ID: "month_year", > Title: "Month Year", > SectionID: §ionID, > FieldType: onepassword.ItemFieldTypeMonthYear, > Value: "03/1998", > }, > ``` > [tab] JavaScript > > ```js theme={null} > { > id: "month_year", > title: "Month Year", > sectionId: "custom section", > fieldType: sdk.ItemFieldType.MonthYear, > value: "03/1998", > }, > ``` > [tab] Python > > ```python theme={null} > from onepassword import ItemField, ItemFieldType > > ItemField( > id="month_year", > title="Month Year", > section_id="", > field_type=ItemFieldType.MONTHYEAR, > value="03/1998", > ), > ``` ### Reference For a `Reference` type item field, the reference field's value must be the [unique identifier (ID)](/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`. > [tab] Go > > ```go theme={null} > { > ID: "reference", > Title: "Reference", > FieldType: onepassword.ItemFieldTypeReference, > SectionID: §ionID, > Value: "f43hnkatjllm5fsfsmgaqdhv7a", > }, > ``` > [tab] JavaScript > > ```js theme={null} > { > id: "reference", > title: "Reference", > sectionId: "custom section", > fieldType: sdk.ItemFieldType.Reference, > value: "f43hnkatjllm5fsfsmgaqdhv7a", > }, > ``` > [tab] Python > > ```python theme={null} > from onepassword import ItemField, ItemFieldType > > ItemField( > id="Reference", > title="Reference", > sectionId="", > field_type=ItemFieldType.REFERENCE, > value="f43hnkatjllm5fsfsmgaqdhv7a", > ), > ``` ### 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. > [tab] 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. > > ```go theme={null} > // Generate the RSA key pair > privateKey, err := rsa.GenerateKey(rand.Reader, 4096) > if err != nil { > panic(err) > } > privBytes, err := x509.MarshalPKCS8PrivateKey(privateKey) > if err != nil { > panic(err) > } > // Encode the data into PEM format > sshKeyPEMBytes := string(pem.EncodeToMemory(&pem.Block{ > Type: "PRIVATE KEY", > Bytes: privBytes, > })) > > vaultID := os.Getenv("OP_VAULT_ID") > > sectionID := "extraDetails" > itemParams := onepassword.ItemCreateParams{ > Title: "SSH Key Item Created With Go SDK", > Category: onepassword.ItemCategorySSHKey, > VaultID: vaultID, > Fields: []onepassword.ItemField{ > { > ID: "private_key", > Title: "private key", > Value: sshKeyPEMBytes, > FieldType: onepassword.ItemFieldTypeSSHKey, > SectionID: §ionID, > }, > }, > Sections: []onepassword.ItemSection{ > { > ID: sectionID, > Title: "Extra Details", > }, > }, > } > > // Creates a new item based on the structure definition above > createdItem, err := client.Items().Create(context.Background(), itemParams) > if err != nil { > panic(err) > } > > // Fetch all SSH key attributes > fmt.Println(createdItem.Fields[0].Value) > if sshAttributes := createdItem.Fields[0].Details.SSHKey(); sshAttributes != nil { > fmt.Println(createdItem.Fields[0].Details.SSHKey().PublicKey) > fmt.Println(createdItem.Fields[0].Details.SSHKey().Fingerprint) > fmt.Println(createdItem.Fields[0].Details.SSHKey().KeyType) > } > ``` > [tab] 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. > > ```js theme={null} > const privateKey = crypto.generateKeyPairSync("rsa", { > modulusLength: 4096, // 4096-bit key > privateKeyEncoding: { > type: "pkcs8", // PKCS#8 Private Key format > format: "pem", > }, > }); > // Create a SSH Key Item > let item = await client.items.create({ > title: "SSH Key Item Created With JS SDK", > category: sdk.ItemCategory.SshKey, > vaultId: vaultId, > fields: [ > { > id: "private_key", > title: "private key", > fieldType: sdk.ItemFieldType.SshKey, > value: privateKey.privateKey, > sectionId: "custom section", > }, > ], > sections: [ > { > id: "custom section", > title: "my section", > }, > ], > }); > console.log(item.fields[0].value); > console.log(item.fields[0].details.content.publicKey); > console.log(item.fields[0].details.content.fingerprint); > console.log(item.fields[0].details.content.keyType); > ``` > [tab] 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. > > ```python theme={null} > from cryptography.hazmat.primitives import serialization > from cryptography.hazmat.primitives.asymmetric import rsa > > from onepassword import ( > ItemCategory, > ItemCreateParams, > ItemField, > ItemFieldType, > ItemSection, > ) > > # Generate a 4096-bit RSA private key > private_key = rsa.generate_private_key( > public_exponent=65537, > key_size=4096, > ) > > # Serialize the private key in PKCS8 format (PEM) > ssh_key_pkcs8_pem = private_key.private_bytes( > encoding=serialization.Encoding.PEM, > format=serialization.PrivateFormat.PKCS8, > encryption_algorithm=serialization.NoEncryption(), > ) > > # Create an SSH Key item and add it to a vault > to_create = ItemCreateParams( > title="SSH Key Item Created With Python SDK", > category=ItemCategory.SSHKEY, > vault_id="your-vault-id", > fields=[ > ItemField( > id="private_key", > title="private key", > field_type=ItemFieldType.SSHKEY, > value=ssh_key_pkcs8_pem, > sectionId="", > ), > ], > sections=[ > ItemSection(id="", title=""), > ], > ) > created_item = await client.items.create(to_create) > > print(created_item.fields[0].value) > print(created_item.fields[0].details.content.public_key) > print(created_item.fields[0].details.content.fingerprint) > print(created_item.fields[0].details.content.key_type) > ``` ### 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`). > [tab] Go > > ```go theme={null} > { > ID: "onetimepassword", > Title: "One-Time Password URL", > SectionID: §ionID, > FieldType: onepassword.ItemFieldTypeTOTP, > Value: "otpauth://totp/my-example-otp?secret=jncrjgbdjnrncbjsr&issuer=1Password", > }, > ``` > [tab] JavaScript > > ```js theme={null} > { > id: "onetimepassword", > title: "One-Time Password URL", > sectionId: "custom section", > fieldType: sdk.ItemFieldType.Totp, > value: > "otpauth://totp/my-example-otp?secret=jncrjgbdjnrncbjsr&issuer=1Password", > }, > ``` > [tab] Python > > ```python theme={null} > from onepassword import ItemField, ItemFieldType > > ItemField( > id="onetimepassword", > title="one-time-password", > section_id="", > field_type=ItemFieldType.TOTP, > value="otpauth://totp/my-example-otp?secret=jncrjgbdjnrncbjsr&issuer=1Password", > ), > ``` ## 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](/service-accounts/get-started#create-a-service-account) with read and write permissions. ![1Password.com open to the details of a service account.](/static/img/sdk-service-account-permissions.png) ## Learn more * [Secret reference syntax](/cli/secret-reference-syntax/) * [Load secrets using 1Password SDKs](/sdks/load-secrets/) * [Manage files using 1Password SDKs](/sdks/files/) * [Share items using 1Password SDKs](/sdks/share-items/) * [List vaults and items using 1Password SDKs](/sdks/list-vaults-items/) * [Workflow: Build integrations with 1Password](/get-started/build-integrations) # Share items using 1Password SDKs Source: https://www.1password.dev/sdks/share-items 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. ## Before you get started Before you begin, [follow the steps to get started](/sdks#get-started) with a 1Password SDK. The examples on this page assume you have an initialized `client` instance. For example: > [tab] Go > > ```go theme={null} > package main > > import ( > "context" > > "github.com/1password/onepassword-sdk-go" > ) > > func main() { > // TODO: Initialize client using your preferred authentication method (see Overview > Get started) > client, err := onepassword.NewClient(context.Background(), > ) > if err != nil { > panic(err) > } > > // Your code here > } > > ``` > [tab] JavaScript > > > [tab] ES Modules > > > > ```javascript theme={null} > > import sdk from "@1password/sdk"; > > > > async function main() { > > const client = await sdk.createClient({ > > // TODO: Initialize client using your preferred authentication method (see Overview > Get started) > > }); > > > > // Your code here > > } > > > > main().catch(console.error); > > > > ``` > > > [tab] CommonJS > > > > ```javascript theme={null} > > const sdk = require("@1password/sdk"); > > > > async function main() { > > const client = await sdk.createClient({ > > // TODO: Initialize client using your preferred authentication method (see Overview > Get started) > > }); > > > > // Your code here > > } > > > > main().catch(console.error); > > > > ``` > [tab] Python > > ```python theme={null} > import asyncio > > from onepassword import Client # Also import DesktopAuth for desktop app authentication. > > async def main(): > # TODO: Initialize client using your preferred authentication method (see Overview > Get started) > client = await Client.authenticate(...) > > # Your code here > > asyncio.run(main()) > > ``` > [!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. > [!TIP] > > Make sure to add the `Share items` permission when creating a [service account token](/service-accounts/) to share items using the SDKs. ### Step 1: Retrieve the 1Password item you want to share > [tab] 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)](/sdks/concepts#unique-identifiers) for the item and the vault where the item is stored. > > ```go theme={null} > item, err := client.Items().Get(context.Background(), vaultID, itemID) > if err != nil { > panic(err) > } > ``` > [tab] 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)](/sdks/concepts#unique-identifiers) for the item and the vault where the item is stored. > > ```js theme={null} > let item = await client.items.get(vaultId, itemId); > console.log(item); > ``` > [tab] 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)](/sdks/concepts#unique-identifiers) for the item and the vault where the item is stored. > > ```python theme={null} > from onepassword import ItemShareDuration, ItemShareParams > > # Get an item to share > item = await client.items.get("your-vault-id", "your-item-id") > print(item) > ``` ### 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 > [tab] 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)](/sdks/concepts#unique-identifiers) for the item and the vault where the item is stored. > > ```go theme={null} > accountPolicy, err := client.Items().Shares().GetAccountPolicy(context.Background(), item.VaultID, item.ID) > if err != nil { > panic(err) > } > ``` > [tab] 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)](/sdks/concepts#unique-identifiers) for the item and the vault where the item is stored. > > ```js theme={null} > let policy = await client.items.shares.getAccountPolicy( > item.vaultId, > item.id, > ); > console.log(policy); > ``` > [tab] 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)](/sdks/concepts#unique-identifiers) for the item and the vault where the item is stored. > > ```python theme={null} > from onepassword import ItemShareDuration, ItemShareParams > > # Get your item sharing account policy > policy = await client.items.shares.get_account_policy(item.vault_id, item.id) > print(policy) > ``` ### 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. > [tab] 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. > > ```go theme={null} > recipients, err := client.Items().Shares().ValidateRecipients(context.Background(), accountPolicy, []string{"helloworld@agilebits.com"}) > if err != nil { > panic(err) > } > ``` > [tab] 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. > > ```js theme={null} > let valid_recipients = await client.items.shares.validateRecipients(policy, [ > "helloworld@agilebits.com", > ]); > > console.log(valid_recipients); > ``` > [tab] 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. > > ```python theme={null} > from onepassword import ItemShareDuration, ItemShareParams > > # Validate item share recipients > valid_recipients = await client.items.shares.validate_recipients( > policy, ["your-recipient-email-address"] > ) > > print(valid_recipients) > ``` ### 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). > [tab] 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. > > ```go theme={null} > shareLink, err := client.Items().Shares().Create(context.Background(), item, accountPolicy, onepassword.ItemShareParams{ > Recipients: recipients, > ExpireAfter: &accountPolicy.DefaultExpiry, > OneTimeOnly: false, > }) > if err != nil { > panic(err) > } > ``` > [tab] 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. > > ```js theme={null} > let share_link = await client.items.shares.create(item, policy, { > expireAfter: sdk.ItemShareDuration.OneHour, > oneTimeOnly: false, > recipients: valid_recipients, > }); > > console.log(share_link); > ``` > [tab] 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: > > * `expire_after`: 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. > * `one_time_only`: 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. > > ```python theme={null} > from onepassword import ItemShareDuration, ItemShareParams > > # Create a unique link to share the item > share_link = await client.items.shares.create( > item, > policy, > ItemShareParams( > recipients=valid_recipients, > expireAfter=ItemShareDuration.ONEHOUR, > oneTimeOnly=False, > ), > ) > > print(share_link) > ``` # 1Password SDK tutorials and examples Source: https://www.1password.dev/sdks/tutorials ## 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](/sdks/setup-tutorial) ### Integrate 1Password SDKs with AI agents Learn a workflow for integrating 1Password SDKs with AI agents. [Learn more](/sdks/ai-agent) ## 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](https://github.com/SimonBarendse/1password-sdks-rotation-demo/tree/main/message-service) ### Rotate an API key with AWS EventBridge Use 1Password SDKs with AWS EventBridge to automatically rotate secrets on a set schedule. [Learn more](https://github.com/SimonBarendse/1password-sdks-rotation-demo/tree/main/rotation-service) ### 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](https://github.com/1Password/solutions/tree/main/1password/onepassword_sdks/demo-inventory-tracker-webapp) ### 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](https://github.com/1Password/solutions/tree/main/1password/onepassword_sdks/demo-vault-migration-webapp) ### 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](https://github.com/1Password/solutions/tree/main/1password/onepassword_sdks/demo-share-script) ### 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](https://github.com/1Password/solutions/tree/main/1password/onepassword_sdks/demo-share-okta-user-script) # Use 1Password as a backend for a web app Source: https://www.1password.dev/sdks/tutorials/backend-web-app # Fetch an API key and authenticate to Twilio Source: https://www.1password.dev/sdks/tutorials/fetch-api-key-authenticate # Migrate data between 1Password tenants Source: https://www.1password.dev/sdks/tutorials/migrate-data-tenants # Securely onboard employees to Okta Source: https://www.1password.dev/sdks/tutorials/onboard-employees-okta # Rotate an API key with AWS EventBridge Source: https://www.1password.dev/sdks/tutorials/rotate-api-key-eventbridge # Securely share files and markdown Source: https://www.1password.dev/sdks/tutorials/share-files-markdown # Manage vault permissions using 1Password SDKs Source: https://www.1password.dev/sdks/vault-permissions 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](/sdks/concepts#1password-desktop-app) to manage vault permissions. Service accounts can only manage permissions for vaults created by the service account. > [!WARNING] > > 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. ## Before you get started Before you begin, [follow the steps to get started](/sdks#get-started) with a 1Password SDK. The examples on this page assume you have an initialized `client` instance. For example: > [tab] Go > > ```go theme={null} > package main > > import ( > "context" > > "github.com/1password/onepassword-sdk-go" > ) > > func main() { > // TODO: Initialize client using your preferred authentication method (see Overview > Get started) > client, err := onepassword.NewClient(context.Background(), > ) > if err != nil { > panic(err) > } > > // Your code here > } > > ``` > [tab] JavaScript > > > [tab] ES Modules > > > > ```javascript theme={null} > > import sdk from "@1password/sdk"; > > > > async function main() { > > const client = await sdk.createClient({ > > // TODO: Initialize client using your preferred authentication method (see Overview > Get started) > > }); > > > > // Your code here > > } > > > > main().catch(console.error); > > > > ``` > > > [tab] CommonJS > > > > ```javascript theme={null} > > const sdk = require("@1password/sdk"); > > > > async function main() { > > const client = await sdk.createClient({ > > // TODO: Initialize client using your preferred authentication method (see Overview > Get started) > > }); > > > > // Your code here > > } > > > > main().catch(console.error); > > > > ``` > [tab] Python > > ```python theme={null} > import asyncio > > from onepassword import Client # Also import DesktopAuth for desktop app authentication. > > async def main(): > # TODO: Initialize client using your preferred authentication method (see Overview > Get started) > client = await Client.authenticate(...) > > # Your code here > > asyncio.run(main()) > > ``` > [!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 > [tab] 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](/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](/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 (`|`). > > ```go theme={null} > // Grant group permissions to a vault. > groupAccess := onepassword.GroupAccess{ > GroupID: groupID, > Permissions: onepassword.ReadItems, > } > err := client.Vaults().GrantGroupPermissions(context.Background(), vaultID, []onepassword.GroupAccess{groupAccess}) > if err != nil { > panic(err) > } > fmt.Println("Granted group", groupID, "permissions to vault", vaultID) > ``` > [tab] 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](/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](/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 (`|`). > > ```js theme={null} > // Grant group permissions > await client.vaults.grantGroupPermissions(vaultId, [ > { groupId, permissions: sdk.READ_ITEMS }, > ]); > console.log( > "Granted READ_ITEMS permissions to group", > groupId, > "on vault", > vaultId, > ); > ``` > [tab] 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](/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](/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 (`|`). > > The following example grants a group permission to read items in a vault. > > ```python theme={null} > from onepassword import GroupAccess, READ_ITEMS > > vault_id = "your-vault-id" > group_id = "your-group-id" > > # Grant group permissions in a vault > await client.vaults.grant_group_permissions( > vault_id=vault_id, > group_permissions_list=[ > GroupAccess( > group_id=group_id, > permissions=READ_ITEMS, > ) > ], > ) > print(f"Granted group {group_id} permissions to vault {vault_id}") > ``` ## Update vault permissions > [!WARNING] > > Make sure to specify **all** the permissions the group should have in the vault. This method completely replaces all existing permissions. > [tab] 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](/sdks/concepts#unique-identifiers) of the vault. > * `GroupID`: The [unique identifier](/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 (`|`). > > ```go theme={null} > // Update group permissions for a vault > groupVaultAccess := onepassword.GroupVaultAccess{ > GroupID: groupID, > VaultID: vaultID, > Permissions: onepassword.ReadItems | onepassword.CreateItems | onepassword.UpdateItems, > } > err = client.Vaults().UpdateGroupPermissions(context.Background(), []onepassword.GroupVaultAccess{groupVaultAccess}) > if err != nil { > panic(err) > } > fmt.Println( > "Updated group", > groupID, > "permissions to vault", > vaultID, > ) > ``` > [tab] 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](/sdks/concepts#unique-identifiers) of the vault. > * `groupID`: The [unique identifier](/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 (`|`). > > ```js theme={null} > // Update group permissions > await client.vaults.updateGroupPermissions([ > { > vaultId, > groupId, > permissions: sdk.READ_ITEMS | sdk.CREATE_ITEMS | sdk.UPDATE_ITEMS, > }, > ]); > console.log( > "Updated group", > groupId, > "permissions to MANAGE_VAULT on vault", > vaultId, > ); > ``` > [tab] 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](/sdks/concepts#unique-identifiers) of the vault. > * `group_id`: The [unique identifier](/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 (`|`). > > The following example updates a group's permissions in a vault to give the group permission to read items, create items, and update items in the vault. > > The following example updates a group's permissions in a vault to give the group permission to read items, create items, and update items in the vault. > > ```python theme={null} > from onepassword import CREATE_ITEMS, GroupVaultAccess, READ_ITEMS, UPDATE_ITEMS > > vault_id = "your-vault-id" > group_id = "your-group-id" > > # Update group permissions in a vault > await client.vaults.update_group_permissions( > group_permissions_list=[ > GroupVaultAccess( > vault_id=vault_id, > group_id=group_id, > permissions= READ_ITEMS | CREATE_ITEMS | UPDATE_ITEMS, > ) > ], > ) > print(f"Updated group {group_id} permissions to vault {vault_id}") > ``` ## Revoke vault permissions > [tab] 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](/sdks/concepts#unique-identifiers) of the vault. > * `groupID`: The [unique identifier](/sdks/concepts#unique-identifiers) of the group whose permissions you want to revoke. > > ```go theme={null} > // Revoke group permissions from a vault. > err = client.Vaults().RevokeGroupPermissions(context.Background(), vaultID, groupID) > if err != nil { > panic(err) > } > fmt.Println("Revoked group permissions from vault", vaultID) > ``` > [tab] 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](/sdks/concepts#unique-identifiers) of the vault. > * `groupID`: The [unique identifier](/sdks/concepts#unique-identifiers) of the group whose permissions you want to revoke. > > ```js theme={null} > // Revoke group permissions > await client.vaults.revokeGroupPermissions(vaultId, groupId); > console.log( > "Revoked group", > groupId, > "permissions on vault", > vaultId, > ); > ``` > [tab] 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](/sdks/concepts#unique-identifiers) of the vault. > * `group_id`: The [unique identifier](/sdks/concepts#unique-identifiers) of the group whose permissions you want to revoke. > > ```python theme={null} > vault_id = "your-vault-id" > group_id = "your-group-id" > > # Revoke a group's permissions in a vault > await client.vaults.revoke_group_permissions( > vault_id=vault_id, > group_id=group_id, > ) > print(f"Revoked group {group_id}'s permissions in vault {vault_id}") > ``` ## 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 Source: https://www.1password.dev/sdks/vaults 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](/sdks/vault-permissions#appendix-vault-permissions). We recommend authenticating with the [1Password desktop app](/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. ## Before you get started Before you begin, [follow the steps to get started](/sdks#get-started) with a 1Password SDK. The examples on this page assume you have an initialized `client` instance. For example: > [tab] Go > > ```go theme={null} > package main > > import ( > "context" > > "github.com/1password/onepassword-sdk-go" > ) > > func main() { > // TODO: Initialize client using your preferred authentication method (see Overview > Get started) > client, err := onepassword.NewClient(context.Background(), > ) > if err != nil { > panic(err) > } > > // Your code here > } > > ``` > [tab] JavaScript > > > [tab] ES Modules > > > > ```javascript theme={null} > > import sdk from "@1password/sdk"; > > > > async function main() { > > const client = await sdk.createClient({ > > // TODO: Initialize client using your preferred authentication method (see Overview > Get started) > > }); > > > > // Your code here > > } > > > > main().catch(console.error); > > > > ``` > > > [tab] CommonJS > > > > ```javascript theme={null} > > const sdk = require("@1password/sdk"); > > > > async function main() { > > const client = await sdk.createClient({ > > // TODO: Initialize client using your preferred authentication method (see Overview > Get started) > > }); > > > > // Your code here > > } > > > > main().catch(console.error); > > > > ``` > [tab] Python > > ```python theme={null} > import asyncio > > from onepassword import Client # Also import DesktopAuth for desktop app authentication. > > async def main(): > # TODO: Initialize client using your preferred authentication method (see Overview > Get started) > client = await Client.authenticate(...) > > # Your code here > > asyncio.run(main()) > > ``` > [!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](/service-accounts/get-started#create-a-service-account) with this permission or authenticate using [the 1Password desktop app](/sdks/concepts#1password-desktop-app). > [tab] 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. > > ```go theme={null} > description := "This vault was created with the Go SDK." > // Create a vault with a description > createParams := onepassword.VaultCreateParams{ > Title: "Go SDK Vault", > Description: &description, > } > > createdVault, err := client.Vaults().Create(context.Background(), createParams) > if err != nil { > panic(err) > } > fmt.Printf("Created vault with description: %v\\n", createdVault) > ``` > [tab] 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. > > ```js theme={null} > // Create a vault > createdVault = await client.vaults.create({ > title: "JS SDK Vault", > description: "A vault created via the JS SDK", > }); > console.log( > "Created vault", > createdVault.title, > "(" + createdVault.id + ")", > ); > ``` > [tab] 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. > > ```python theme={null} > from onepassword import VaultCreateParams > > # Create a vault > vault_create_params = VaultCreateParams( > title="Python SDK Vault", > description="A description", > allow_admins_access=False, > ) > created_vault = await client.vaults.create(vault_create_params) > print(f"Created vault: {created_vault.id} - {created_vault.title}") > ``` ## Get a vault overview > [tab] Go > > Use the [`Vaults().GetOverview()`](https://github.com/1Password/onepassword-sdk-go/blob/main/vaults.go#L86) method with the [unique identifier (ID)](/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). > > ```go theme={null} > // Get vault overview > vaultOverview, err := client.Vaults().GetOverview(context.Background(), createdVault.ID) > if err != nil { > panic(err) > } > fmt.Printf("Vault overview: %v\\n", vaultOverview) > ``` > [tab] 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)](/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). > > ```js theme={null} > // Get vault overview > const vaultOverview = await client.vaults.getOverview(createdVault.id); > console.log(JSON.stringify(vaultOverview)); > ``` > [tab] 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)](/sdks/concepts#unique-identifiers) of a vault to retrieve high-level metadata about the vault. > > ```python theme={null} > # Get a vault overview > vault_overview = await client.vaults.get_overview("your-vault-id") > print(vault_overview) > ``` ## Get vault details > [tab] Go > > Use the [`Vaults().Get()`](https://github.com/1Password/onepassword-sdk-go/blob/main/vaults.go#L102) method with the [unique identifier (ID)](/sdks/concepts#unique-identifiers) of a vault to get details about the vault. > > The following example gets details for the vault you retrieved [in the previous step](#get-a-vault-overview). > > ```go theme={null} > // Get vault details > vault, err := client.Vaults().Get(context.Background(), vaultOverview.ID, onepassword.VaultGetParams{}) > if err != nil { > panic(err) > } > fmt.Printf("Vault details: %v\\n", vault) > ``` > [tab] 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)](/sdks/concepts#unique-identifiers) of a vault to get details about the vault. > > The following example gets details for the vault you created [in the first step](#create-a-vault). > > ```js theme={null} > // Get vault details > const vault = await client.vaults.get(createdVault.id, { accessors: false }); > console.log(JSON.stringify(vault)); > ``` > [tab] 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)](/sdks/concepts#unique-identifiers) of a vault to get details about the vault. For example, to get a vault's ID and name: > > ```python theme={null} > from onepassword import VaultGetParams > > # Get a vault > get_params = VaultGetParams( > accessors=True, > ) > > vault = await client.vaults.get("your-vault-id", get_params) > print(f"Retrieved vault: {vault.id} - {vault.title}") > ``` ## Update a vault > [tab] 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](/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). > > ```go theme={null} > // Update a vault > updateParams := onepassword.VaultUpdateParams{ > Title: nil, > Description: nil, > } > > name := "Go SDK Updated Vault" > description = "Updated description from Go SDK" > updateParams.Title = &name > updateParams.Description = &description > > // Update the vault > updatedVault, err := client.Vaults().Update(context.Background(), createdVault.ID, updateParams) > if err != nil { > panic(err) > } > fmt.Println("Updated Vault: ", updatedVault.Title) > ``` > [tab] 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](/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). > > ```js theme={null} > // Update vault > await client.vaults.update(createdVault.id, { > title: "JS SDK Vault Updated", > description: "An updated vault created via the SDK", > }); > console.log("Updated vault", createdVault.id); > ``` > [tab] 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](/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. > > ```python theme={null} > from onepassword import VaultUpdateParams > > vault_id = "your-vault-id" > > # Update a vault > update_params = VaultUpdateParams( > title="Python SDK Updated Name", > description="Updated description", > ) > > updated_vault = await client.vaults.update(vault_id, update_params) > print( > f'Updated vault "{updated_vault.title}" ({updated_vault.id}): ' > f'{updated_vault.description!r}' > ) > ``` ## Delete a vault > [tab] 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](/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). > > ```go theme={null} > // Delete vault > err = client.Vaults().Delete(context.Background(), createdVault.ID) > if err != nil { > panic(err) > } > fmt.Println("Deleted vault.") > ``` > [tab] 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](/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). > > ```js theme={null} > // Delete vault > await client.vaults.delete(createdVault.id); > console.log("Deleted vault", createdVault.id); > ``` > [tab] 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](/sdks/concepts#unique-identifiers) of the vault you want to delete. > > ```python theme={null} > vault_id = "your-vault-id" > > # Delete a vault > await client.vaults.delete(vault_id) > print(f"Vault {vault_id} successfully deleted.") > ``` > [!TIP] > > You can also [batch create, get, and delete items](/sdks/manage-items#manage-items-in-bulk) from a vault. ## Learn more * [Manage items in bulk](/sdks/manage-items#manage-items-in-bulk) * [Manage vault permissions](/sdks/vault-permissions) * [List vaults and items](/sdks/list-vaults-items) * [Workflow: Build integrations with 1Password](/get-started/build-integrations) * [Workflow: Programmatically manage your organization](/get-started/manage-organization) # 1Password Secrets Automation Source: https://www.1password.dev/secrets-automation Manage your secrets with a Secrets Automation workflow that allows you to securely access your 1Password items and vaults in your company's apps and cloud infrastructure. You can manage secrets with [1Password Service Accounts](#1password-service-accounts) or [1Password Connect servers](#1password-connect-servers). ## 1Password Service Accounts [Service accounts](/service-accounts/) allow you to automate secrets management in your applications and infrastructure without the need to deploy additional services. Service accounts work well for shared environments because they provide an authentication method for 1Password CLI that isn't associated with an individual. Get started with service accounts ## 1Password Connect Servers Alternatively, secure your infrastructure secrets with one or more self-hosted [Connect servers](/connect/). Connect servers allow for more control, scalability, and reduced dependency on the availability of the 1Password API. While 1Password Service Accounts are capped with strict [rate limits](/service-accounts/rate-limits), Connect servers cache your data in your infrastructure. This enables unlimited re-requests after the server fetches your secrets for the first time. 1Password also maintains several SDK libraries for the [Connect API](/connect/api-reference/) so you can integrate with your existing applications. Get started with Connect ## Comparison Review the following comparison table to learn about the different features and limitations of service accounts and Connect servers. | | Service accounts | Connect servers | | - | - | - | | [1Password CLI](/connect/cli/) | Yes | Yes | | REST API | No | Yes | | Self-hosted | No | Yes | | Infrastructure requirements | No | Yes | | Low overhead | Yes | No | | Low latency | No | Yes | | [Kubernetes integrations](/k8s/integrations/) | Yes | Yes | | [CI/CD integrations](/ci-cd/) | Yes | Yes | | Rate limits | Yes | No | | Request quotas | Yes | No | | Included with 1Password subscription | Yes | Yes | # Use 1Password with AI agents Source: https://www.1password.dev/security-for-ai Set up 1Password for coding agents on your machine, agents in a sandbox or pipeline, and personal agents that sign in to websites. AI agents need API keys, tokens, and passwords to get work done. 1Password gives them that access without the secret ever landing in a prompt, a config file, or plaintext on disk. ## Choose your setup > [card] [Coding agents on your machine](#coding-agents-on-your-machine) > > Claude Code, Cursor, Codex, Kiro, and other agents in your editor or terminal. > [card] [Agents in a sandbox or pipeline](#agents-in-a-sandbox-or-pipeline) > > Agents that run on their own, like in NVIDIA OpenShell or GitHub Actions. > [card] [Personal agents that sign in to websites](#personal-agents-that-sign-in-to-websites) > > Agents that browse for you and need to sign in to your accounts. ## Coding agents on your machine Store your project secrets in a [1Password Environment](/environments), then connect your agent to it. 1Password mounts the secrets as a local .env file, so nothing sits in plaintext on disk or in your MCP config and you can't commit a secret by accident. The agent can still read the secrets in that file. > [card] [Environments MCP server](/environments/mcp-server) > > Connect Claude Code, Codex, Cursor, Kiro, or any MCP client. Start here. > [card] [Claude Code plugin](/environments/claude-plugin) > > One install: MCP server plus the Environments agent skill. > [card] [Cursor plugin](/environments/cursor-plugin) > > One install: MCP server, agent skill, and the .env validation hook. Also useful: * [Mount a local .env file](/environments/local-env-file) so tools read secrets from 1Password instead of a plaintext file. * [Validate .env files with the agent hook](/environments/agent-hook-validate) before your agent runs shell commands. * [Secure MCP server config files](/get-started/secure-ai-access#secure-mcp-server-config-files) by replacing hardcoded tokens in `mcp.json`. * [Sign in to AI CLIs with your fingerprint](/cli/shell-plugins) using shell plugins for Claude Code, Codex, Gemini, GitHub Copilot, and more. ## Agents in a sandbox or pipeline When an agent runs on its own, give it only the access it needs, for only as long as it needs it. > [card] [NVIDIA OpenShell (beta)](/environments/nvidia-openshell) > > Time-limited access for sandboxed agents. The agent only ever sees placeholders. > [card] [Credential Broker (public preview)](/brokered-access) > > Agents in GitHub Actions or other OIDC workflows get secrets without a stored token. > [card] [Service accounts](/service-accounts/get-started) > > A scoped token for automated workflows that need specific vaults or Environments. Building your own agent? See [Integrate 1Password SDKs with AI agents](/sdks/ai-agent). ## Personal agents that sign in to websites [1Password for Agents](https://support.1password.com/1password-for-agents/) lets a personal agent sign in to websites for you. When the agent needs to sign in, 1Password shows you which agent is asking. After you approve, 1Password fills the username, password, and one-time password into the agent's browser. The agent never sees the credentials. > [card] [Get started with 1Password for Agents](https://support.1password.com/1password-for-agents/) > > Connect 1Password to a supported agent and approve sign-in requests. > [card] [Build an integration with Browserbase](https://docs.browserbase.com/integrations/1password/agentic-autofill) > > For partners: let agents running in Browserbase sign in to websites. ## Get help Join the discussion in our [Developer community](/community) or ask in [Developer Slack](/joinslack). # Browserbase Source: https://www.1password.dev/security-for-ai/browserbase # 1Password Service Accounts Source: https://www.1password.dev/service-accounts 1Password Service Accounts give scripts, CI/CD pipelines, and servers scoped access to secrets in 1Password, without a person signing in. 1Password Service Accounts help automate secrets management in your applications and infrastructure without the need to deploy additional services. Service accounts work well for shared environments because they provide an authentication method for [1Password CLI](/cli/) that isn't associated with an individual. You control which vaults and Environments are accessible and which actions the service account can perform. And you can see what items a service account accesses by creating a [usage report](https://support.1password.com/reports#create-a-usage-report-for-a-team-member-service-account-or-vault). You can create up to 100 service accounts. ## How service accounts compare 1Password gives you three ways to authenticate automated workflows, each with a different trade-off: | | Service accounts | Connect server | Credential Broker (public preview) | | - | - | - | - | | What it is | A token scoped to specific vaults or Environments | A self-hosted REST API you deploy in your own infrastructure | No token at all — access is verified per run using your CI/CD platform's OIDC identity | | Setup | Create a token, no infrastructure to run | Deploy and maintain a Connect server | An admin sets up a trust policy once; no secret to store | | Best for | Most CI/CD pipelines, scripts, and shared builds | High-volume or low-latency access, since requests are served from your own infrastructure after the first fetch | GitHub Actions or custom OIDC workflows where you'd rather not manage a token at all | | Limits | Subject to rate limits and request quotas | Requires infrastructure to run and maintain | Public preview; currently supports GitHub Actions and custom OIDC workflows | See the full [secrets automation comparison table](/secrets-automation/#comparison) for Connect, or [set up Credential Broker](/brokered-access) if you'd rather not manage tokens at all. ## Use cases You can use 1Password Service Accounts to accomplish a variety of tasks: Web services ### Provision web services with secrets Use a service account to provision an account with a secret stored in 1Password. If a web service needs access to a database (and the credentials for the database are in 1Password), you can use a service account to provision an account with the needed secret and allow the web service to access the secret during test runs. Test environments ### Create a test environment Use a service account in a test environment while using Connect in production. Using a service account for your test environment allows you to create a similar test environment while keeping secrets or access compartmentalized. You can use service accounts to automatically access secrets in the test environment without having to set up Connect. CI/CD pipelines ### Load secrets into CI/CD pipelines Use a service account to automatically access your secrets in continuous integration environments. If you've committed code and want to automatically run your CI/CD pipeline with credentials stored in a 1Password vault, you can use a service account to automatically access your secrets and use them for testing and deploying code while maintaining security without tying sensitive information to a personal user account. Infrastructure secrets ### Secure infrastructure secrets Use service accounts to make sure infrastructure secrets aren't tied to a personal user account. Secrets management ### Automate secrets management Use service accounts to automate scripts to manage secrets. Using a service account helps you implement the principal of least privilege and avoid the limitations of personal accounts (for example, SSO and MFA requirements). Development workflows ### Streamline development workflows Use service accounts to securely share and manage infrastructure secrets to streamline development workflows. ## Get started Learn how to get started and how to create, manage, and integrate with service accounts. Get started ## Next steps * [Create a service account](/service-accounts/get-started/#create-a-service-account) and scope it to the vaults or Environments it needs. * [Rotate a service account token](/service-accounts/manage-service-accounts/#rotate-token) on a schedule or after a potential exposure. * [Load secrets into CI/CD pipelines](/ci-cd/) with a service account instead of a personal account. * Compare service accounts with [Connect servers](/secrets-automation/#comparison) and [Credential Broker](/brokered-access). ## Get help To get help, join the discussion in our [Developer community](/community) or join our [Developer Slack](/joinslack) workspace. # Get started with 1Password Service Accounts Source: https://www.1password.dev/service-accounts/get-started Create a 1Password service account: a scoped token that gives scripts, CI/CD pipelines, and servers access to secrets without a person signing in. A service account is a token that gives scripts, CI/CD pipelines, and servers access to specific vaults and Environments, without a person signing in and without running any extra services. This page walks you through creating one and testing its token. Service accounts can: * Create, fetch, edit, delete, and share items. * Read secrets from [1Password Environments](/environments). * Create vaults. * Delete vaults. \ A service account can only delete a vault it created. See [service account security](/service-accounts/security/). * Retrieve information about users and groups. Each service account has a [service account token](/service-accounts/security#service-accounts-and-token-generation) that you can provide as an environment variable for authentication. You can choose which vaults and [Environments](/environments) the service account can access and its permissions in each vault. [Getting Started with 1Password Service Accounts](https://www.youtube.com/embed/E3HKeG9P8HA) > [accordion] Limitations > > Service accounts have the following limitations: > > * Service accounts have [rate limits and request quotes](/service-accounts/rate-limits/). > * You can't grant a service account access to 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, or your default [Shared](https://support.1password.com/1password-glossary/#shared-vault) vault. > * Service accounts can only be granted read access to Environments. > * Service accounts only work with 1Password CLI version 2.18.0 or later. See [Use service accounts with 1Password CLI](/service-accounts/use-with-1password-cli/). > * You can't use service accounts with the [Kubernetes Operator](/k8s/operator/) (only the [Kubernetes Secrets Injector](/k8s/injector/)). ## Requirements Before you can create and use service accounts, you'll need to: * [Sign up for 1Password.](https://1password.com/pricing/password-manager) * Have adequate account permissions to create service accounts. If you don't see the option to create service accounts, ask your administrator to [give you access to create and manage service accounts](/service-accounts/manage-service-accounts#manage-who-can-create-service-accounts). ## Create a service account You can create a service account on 1Password.com or with [1Password CLI](/cli/). Service account permissions, vault access, and Environment access are immutable. If you want to grant a service account access to additional vaults or Environments, change the permissions it has in the vaults it can access, or change its ability to create new vaults, you'll need to create a new service account with the appropriate permissions and access. > [tab] 1Password.com > > To create a service account on 1Password.com: > > 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. > 2. Open the [service account creation wizard](https://start.1password.com/developer-tools/infrastructure-secrets/serviceaccount/?source=dev-portal).\ > Or navigate to **Developer** > **Directory**, select **Other** under Infrastructure Secrets Management, then select **Create a Service Account**. > 3. Follow the onscreen instructions: > 1. Choose a name for the service account. > 2. Choose whether the service account can create vaults. > 3. Choose the vaults the service account can access.\ > You can't grant a service account access to your built-in Personal, Private, or Employee vault, or your default Shared vault. > 4. Select the settings icon next to each vault to choose the permissions the service account has in the vault. This can't be changed later. > 5. Choose which [1Password Environments](/environments) the service account can access. This can't be changed later. > 6. Select **Create Account** to create the service account. > 7. Select **Save in 1Password** to save the service account token in your 1Password account. In the next window, enter a name for the item and choose the vault where you want to save it. > > [!CAUTION] > > > > The service account creation wizard only shows the service account token once. **Save the token in 1Password** immediately to avoid losing it. Treat this token like a password, and don't store it in plaintext. > > You can find your new service account under "Service accounts" on the [**Developer**](https://start.1password.com/developer-tools/active) page. > [tab] 1Password CLI > > > [!NOTE] > > > > Use the [service account creation wizard](https://start.1password.com/developer-tools/infrastructure-secrets/serviceaccount/?source=dev-portal) on 1Password.com if you want to create a service account that can access 1Password Environments. > > To create a service account with 1Password CLI: > > 1. Make sure you have the latest version of [1Password CLI](/cli/get-started/) on your machine. > > 2. Create a new service account using the [`op service-account create` command](/cli/reference/management-commands/service-account#service-account-create): > > ```shell theme={null} > op service-account create --expires-in --vault , > ``` > > Available permissions: `read_items`, `write_items` (requires `read_items`), `share_items` (requires `read_items`) > > Include the `--can-create-vaults` flag to allow the service account to create new vaults. > > If the service account or vault name contains one or more spaces, enclose the name in quotation marks (for example, “My Service Account”). You don't need to enclose strings in quotation marks if they don't contain spaces (for example, myServerName). > > Service accounts can't be modified after they're created. If you need to make changes, revoke the service account and create a new one. > > 3. Save the service account token in your 1Password account. > > 4. If you want to start using the service account with 1Password CLI, [export the token to the `OP_SERVICE_ACCOUNT_TOKEN` environment variable](/service-accounts/use-with-1password-cli#get-started). > > For example, to create a service account named `My Service Account` that has read and write permissions in a vault named `Production`, can create new vaults, and expires in 24 hours: > > ```shell theme={null} > op service-account create "My Service Account" --can-create-vaults --expires-in 24h --vault Production:read_items,write_items > ``` > > > [!CAUTION] > > > > 1Password CLI only returns the service account token once. **Save the token in 1Password** immediately to avoid losing it. Treat this token like a password, and don't store it in plaintext. > [!WARNING] > > If your [sign-in address](https://support.1password.com/1password-glossary/#sign-in-address) changes, you'll need to [rotate your service account tokens](/service-accounts/manage-service-accounts#rotate-token). ## Test your token Save the token in 1Password, then test it with [1Password CLI](/cli/get-started) (version 2.18.0 or later): ```shell theme={null} export OP_SERVICE_ACCOUNT_TOKEN= op user get --me ``` If the output shows `Type: SERVICE_ACCOUNT`, the token works. For fish, PowerShell, and more examples, see [Use service accounts with 1Password CLI](/service-accounts/use-with-1password-cli/). ## Next steps Now use your service account where your code runs: * [Use a service account with 1Password CLI.](/service-accounts/use-with-1password-cli/) * [Manage a service account.](/service-accounts/manage-service-accounts/) * [Integrate a service account with a CI/CD pipeline.](/ci-cd/) * [Integrate a service account with Kubernetes.](/k8s/integrations/) > [!TIP] > > **Need help?** > > [Join our Developer Slack workspace](/joinslack) to ask questions and provide feedback. # Manage service accounts Source: https://www.1password.dev/service-accounts/manage-service-accounts Owners and administrators can manage all service accounts created by their team. Other team members with the [permission to create service accounts](#manage-who-can-create-service-accounts) can manage their own service accounts, but not service accounts created by other people. You can view and manage a service account from its overview page on 1Password.com. The service account overview page shows information about the service account, such as the vaults and [1Password Environments](/environments) it can access, vault permissions, and recent activity. To manage a service account, go to the service account overview: 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. Select **Service accounts** at the top of the page, then choose the service account you want to manage. ### Create a usage report for a service account To create a [usage report](https://support.1password.com/reports/#create-a-usage-report-for-a-team-member-service-account-or-vault) for a service account: 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. Select **Service accounts** at the top of the page, then choose a service account. 4. On the service account overview page, select **View Item Usage Report**. Usage reports for service accounts include information on the number of vaults and items a service account can access, an overview of vaults where a service account has accessed items, when those items were last accessed, and the action performed. ### Change a service account's name To change a service account's name: 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. Select **Service accounts** at the top of the page, then choose a service account. 4. Select **Edit Details**. 5. Type a new name, then select **Save**. ### Rotate a service account token Rotating a service account token generates a new token with the same permissions. You can also specify an expiration for the current token, so you have time to update to the new token without any interruption in service. Take note of any places where you may need to update a service account token before you rotate it. This helps you set a more reasonable expiration time. To rotate a service account token: 1. [Sign in](https://start.1password.com/sign-in/) to your account on 1Password.com. 2. Select [**Developer**](https://start.1password.com/developer-tools) in the sidebar. 3. Select **Service accounts** at the top of the page, then choose a service account. 4. Under the Token section, select **Rotate Token**. 5. Select a value for **Expire existing token** to set when the token will expire. \ For example, you can set the existing token to expire **now** (immediately), in **1 hour**, or in **3 days**. 6. Enter the service account name to confirm. 7. Select **Rotate Token**. 8. Select **Save in 1Password** to save the new token value in 1Password. > [!WARNING] > > If your [sign-in address](https://support.1password.com/1password-glossary/#sign-in-address) changes, make sure to rotate your service account tokens. Your tokens will redirect to the new sign-in address for 30 days. ### Revoke a service account token Revoking a service account token immediately removes its access to 1Password vaults. You might want to revoke a token if it becomes compromised or unnecessary. To revoke a service account token: 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. Select **Service accounts** at the top of the page, then choose a service account. 4. Under the Token section, select **Revoke Token**. 5. Enter the service account name to confirm, then select **Revoke Token**. ## Manage service account settings With 1Password Teams and 1Password Business, you can manage who on your team can create service accounts and which vaults the service accounts can access. ### Manage who can create service accounts By default, only [owners and administrators](https://support.1password.com/groups/) can create and manage service accounts in 1Password Teams and 1Password Business. To allow other groups to create service accounts, an owner or administrator can: 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. Select **Permissions** at the top of the Developer page, then select **Service Account**. 4. Select **Manage groups**, choose the groups you want to allow to create service accounts, then select **Update Groups**. Team members in the selected groups will be able to create service accounts. To manage which individual team members can create service accounts, change from the Groups tab to the People tab. Select **Manage People**, choose the team members you want to allow to create service accounts, then select **Update People**. Each team member with permission to create service accounts will only be able to manage their own service accounts, not service accounts created by other people. ### Manage which vaults team members can grant access to Team members can only grant service accounts access to a vault if they have the appropriate permissions in the vault: | Account type | Permission | | - | - | | 1Password Teams | `Allow Managing` | | 1Password Business | `Manage Vault` | You can manage team members' permissions in vaults [with 1Password CLI](/cli/grant-revoke-vault-permissions) or [on 1Password.com](https://support.1password.com/create-share-vaults-teams/#manage-permissions). ### Manage service account access to vaults Team administrators can control service account access to 1Password vaults by turning access to a vault off or on. A vault's service account access setting applies to all service accounts. If you turn off service account access in a vault, existing service accounts will lose access to that vault and new service accounts can't be granted access. After you create a service account, you can't add additional vaults or edit any vault permissions it has. To turn service account access on or off for a vault: 1. [Sign in](https://start.1password.com/signin) to your account on 1Password.com. 2. Choose the vault you want to change service account access to. 3. Select **Manage**. 4. Under Service Account Access, select the toggle to turn access on or off. ## Get help ### If you need to change a service account's permissions or access After you create a service account, you can't give it access to additional vaults or [1Password Environments](/environments), change its permissions in the vaults it can access, or change its ability to create new vaults. If you want to edit a service account's access or permissions, you'll need to create a new service account. You can [create a service account](/service-accounts/get-started#create-a-service-account) on 1Password.com or with 1Password CLI. # Postman Source: https://www.1password.dev/service-accounts/postman # Pulumi ESC Source: https://www.1password.dev/service-accounts/pulumi-esc # Service account rate limits Source: https://www.1password.dev/service-accounts/rate-limits 1Password Service Accounts have hourly limits and daily limits. [Hourly limits](#hourly-limits) control the number of read and write actions a service account can perform within a 60-minute window. [Daily limits](#daily-limits) determine the total number of requests that all service accounts within a 1Password account can make in a 24-hour window. Some 1Password CLI commands make more than one request. You can use [`op service-account ratelimit`](/cli/reference/management-commands/service-account#service-account-ratelimit) to get rate limit usage data for the service account currently set with the `OP_SERVICE_ACCOUNT_TOKEN` environment variable. To get information about a specific service account, specify a service account by its name or ID. ```bash theme={null} op service-account ratelimit #code-result TYPE ACTION LIMIT USED REMAINING RESET token write 1000 0 1000 N/A token read 10000 3 9997 59 minutes from now account read_write 50000 3 49997 23 hours from now ``` > [!TIP] > > Learn which 1Password CLI commands [make multiple requests](/service-accounts/use-with-1password-cli#commands-that-make-multiple-requests). ## Hourly limits Service account tokens have hourly limits applied to both read and write actions independently. The 60-minute time window begins after 1Password receives the first request. Your 1Password account type determines the hourly limits. | Account type | Action | Limit | Period | Scope | | - | - | - | - | - | | [1Password Business](https://support.1password.com/explore/business/) | Read | 10,000 | 1 hour | Per service account token | | | Write | 1,000 | 1 hour | Per service account token | | 1Password, [1Password Families](https://support.1password.com/explore/families/), and [1Password Teams](https://support.1password.com/explore/team-admin/) | Read | 1,000 | 1 hour | Per service account token | | | Write | 100 | 1 hour | Per service account token | If you exceed the hourly limit, you'll receive the following error: ```text theme={null} Error: [ERROR] (429) Too Many Requests: You've reached the maximum number of this type of requests this service account is allowed to make. Please retry in 59 minutes or try other requests. ``` > [!TIP] > > If you hit an hourly limit, you can: > > * Wait for the 60-minute window to reset. > * [Change your 1Password account type.](https://support.1password.com/change-account-type/) > * [Contact 1Password support.](https://support.1password.com/contact/) > * [Create a new service account.](/service-accounts/get-started/) \ > Hourly limits are scoped per service account token. ## Daily limits 1Password has daily limits in place that determine the total number of requests that all service accounts can make over a 24-hour period. Your 1Password account type determines the daily limit. | Account type | Action | Limit | Period | Scope | | - | - | - | - | - | | [1Password Business](https://support.1password.com/explore/business/) | Read/Write | 50,000 | 24 hours | Per 1Password account | | [1Password Teams](https://support.1password.com/explore/team-admin/) | Read/Write | 5,000 | 24 hours | Per 1Password account | | 1Password and [1Password Families](https://support.1password.com/explore/families/) | Read/Write | 1,000 | 24 hours | Per 1Password account | If you exceed the daily limit, you'll receive the following error: ```text theme={null} Error: [ERROR] (429) Too Many Requests: You've reached the maximum number of this type of requests this 1Password account is allowed to make. Please retry in 23 hours and 59 minutes or try other requests. ``` > [!TIP] > > If you hit a daily limit, you can: > > * Wait for the 24-hour window to reset. > * [Change your 1Password account type.](https://support.1password.com/change-account-type/) > * [Contact 1Password support.](https://support.1password.com/contact/) # 1Password Service Account security Source: https://www.1password.dev/service-accounts/security You can automate managing secrets in your apps and systems with [1Password Service Accounts](/service-accounts/). No need for extra services. Explore the sections on this page to learn more about service account security. For information about 1Password security practices, visit the [1Password Security homepage](https://1password.com/security). ## Access control When creating a service account, you choose the vaults it can access and its level of access. The service account only returns information from vaults it can access. You can also give service accounts permission to create and manage vaults. ## Service accounts and token generation A service account is a type of user account that's meant for programmatic access. Service accounts differ from regular 1Password accounts in that you don't need to provide an email or an [account password](https://support.1password.com/1password-glossary#1password-account-password). When a regular user account creates a master key, the user must provide an email, a [Secret Key](https://support.1password.com/1password-glossary#secret-key), and an account password. When a service account user creates a master key, 1Password generates all the input. | Element | Regular user | Service account | | - | - | - | | Secret Key | Generated | Generated | | Password | User provided | Generated | 1Password uses the Secret Key and the password as part of the [two-secret key derivation (2SKD)](#2skd) process to create the following: * [Account Unlock Key (AUK)](#auk) * [Secure Remote Password (SRP)](#srp) After deriving these two items, 1Password discards the password used to create them. Each user, whether a regular user or a service account user, has a [personal keyset](#personal-keyset) that 1Password generates when you create the user account. The AUK encrypts the personal keyset, and 1Password uses the personal keyset to encrypt and decrypt vaults. A service account token is an authentication string that represents an SRPx object that's serialized and Base64 URL encoded. The service account token allows a service account to authenticate with 1Password CLI. 1Password creates the service account token by serializing the Account Unlock Key (AUK), Secure Remote Password (SRP), and the personal keyset into a [JSON Web Token (JWT) ](https://jwt.io/), then Base64 encoding it. See the following examples of a service account token encoded and decoded. > [tab] Encoded > > Encoded service account token: > > ``` > ops_eyJlbWFpbCI6ImVqd2U2NHFtbHhocmlAMXBhc3N3b3Jkc2VydmljZWFjY291bnRzLmxjbCIsIm11ayI6eyJhbGciOiJBMjU2R0NNIiwiZXh0Ijp0cnVlLCJrIjoiTThWUGZJYzhWRWZUaGNNWExhS0NLRjhzTWg1Sk1ac1BBdHU5MmZRTmItbyIsImtleV9vcHMiOlsiZW5jcnlwdCIsImRlY3J5cHQiXSwia3R5Ijoib2N0Iiwia2lkIjoibXAifSwic2VjcmV0S2V5IjoiQTMtQzRaSk1OLVBRVFpUTC1IR0w4NC1HNjRNNy1LVlpSTi00WlZQNiIsInNycFgiOiI4NzBkNjdhOWU2MjY2MjVkOWUzNjg1MDc4MDRjOWMzMmU2NjFjNTdlN2U1NTg3NzgyOTFiZjI5ZDVhMjc5YWUxIiwic2lnbkluQWRkcmVzcyI6ImdvdGhhbS5iNWxvY2FsLmNvbTo0MDAwIiwidXNlckF1dGgiOnsibWV0aG9kIjoiU1JQZy00MDk2IiwiYWxnIjoiUEJFUzJnLUhTMjU2IiwiaXRlcmF0aW9ucyI6MTAwMDAwLCJzYWx0IjoiRk1SVVBpeXJONFhmXzhIb2g2WVJYUSJ9fQ > ``` > [tab] Decoded > > Decoded service account token: > > ```json theme={null} > { > "email": "ejwe64qmlxhri@1passwordserviceaccounts.lcl", > "muk": { > "alg": "A256GCM", > "ext": true, > "k": "M8VPfIc8VEfThcMXLaKCKF8sMh5JMZsPAtu92fQNb-o", > "key_ops": [ > "encrypt", > "decrypt" > ], > "kty": "oct", > "kid": "mp" > }, > "secretKey": "A3-C4ZJMN-PQTZTL-HGL84-G64M7-KVZRN-4ZVP6", > "srpX": "870d67a9e626625d9e368507804c9c32e661c57e7e558778291bf29d5a279ae1", > "signInAddress": "gotham.b5local.com:4000", > "userAuth": { > "method": "SRPg-4096", > "alg": "PBES2g-HS256", > "iterations": 100000, > "salt": "FMRUPiyrN4Xf_8Hoh6YRXQ" > }, > "throttleSecret": { > "seed": "ddc20da89d71ff640f36bb6c446c64d56a2123eb4e7bd9c89ce303075eea5780", > "uuid": "TP4Z5ZB7IJABDPGIVSUZLY4T5A" > }, > "deviceUuid": "ay5shynibdyqisjz3j63b7uygy" > } > ``` > [!NOTE] > > 1Password uses a unique string format to help code analyzers find accidental credential exposure. The format uses "`ops_`" as the token prefix. The steps to create the token happen on your device (client-side); nothing sensitive goes to 1Password's servers. It's up to you to save and protect the service account token. ### Token rotation and revocation You can rotate or revoke service account tokens. You might want to revoke or rotate a service account token if a service account token became compromised or you need to comply with a security policy that requires regular token rotation. * [Learn how to revoke a service account token.](/service-accounts/manage-service-accounts#revoke-token) * [Learn how to rotate a service account token.](/service-accounts/manage-service-accounts#rotate-token) ## Security model The 1Password Service Account security model has the following guarantees: * A service account can only read items from vaults it has READ access to. * A service account can only update, delete, and create items for vaults it has WRITE access to. * The creator of a service account can only grant the service account access to vaults that the creator has access to. * You can't grant a service account access to vaults that have service accounts turned off, even if the creator of the service account has permissions to manage the vault. * Disabling service accounts for a vault removes access to that vault from all pre-existing service accounts. * By default, account [owners](https://support.1password.com/1password-glossary#owner) and [administrators](https://support.1password.com/1password-glossary#administrator) can create service accounts. * All owners and administrators can view service account details and delete service accounts, but they can't view the generated service account token. * Owners and administrators can [give other team members access](/service-accounts/manage-service-accounts#manage-who-can-create-service-accounts) to create and manage their own service accounts. * Team members can only grant service accounts access to a vault if they have the `Manage Vault` permission for that vault. * A service account token associated with a deleted service account can't authenticate. * You can't add vault access to a generated service account after creation. * A service account can't create another service account. * A service account can't manage users. ## Terminology ### Account Unlock Key The Account Unlock Key (AUK) is a key derived from the [2SKD process](#2skd). It's used to decrypt a user's [personal keyset](#personal-keyset). It's derived from the user's account password and Secret Key. Previously known as the “Master Unlock Key”. ### Personal keyset Each user account (whether a regular user or a service account) has a personal keyset that consists of a public and private key pair that's used to encrypt and decrypt vaults. ### Secure Remote Password The Secure Remote Password (SRP) is a key derived from the [2SKD process](#2skd). It's used for the Secure Remote Password protocol, which is a method for both a client and a server to authenticate each other without either revealing any secrets. ### Service account token A service account token is an authentication string that grants a service account access to one or more 1Password vaults. You can use service account tokens to authenticate services and tools, such as the 1Password CLI. ### Two-secret key derivation Two-secret key derivation (2SKD) is a type of key derivation function that uses two user secrets (the Account password and Secret Key) to derive two independent keys (the [Account Unlock Key](#auk) and the [Secure Remote Password](#srp)). ## Responsible disclosure 1Password requests you practice responsible disclosure if you discover a vulnerability. If you find a vulnerability in 1Password, [submit a report on HackerOne.](https://hackerone.com/1password) # Use service accounts with 1Password SDKs Source: https://www.1password.dev/service-accounts/setup-tutorial 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**. ![](https://mintcdn.com/ab-634991b8/9g9fZmRyYnb5i5sQ/static/img/sdks/create-vault-light.png?fit=max\&auto=format\&n=9g9fZmRyYnb5i5sQ\&q=85\&s=917a5a3ec9ed5ac11f419818a05b5632) ### Step 2: Create a service account Next, create a [1Password Service Account](/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](/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`. ![](https://mintcdn.com/ab-634991b8/9g9fZmRyYnb5i5sQ/static/img/sdks/create-sa-1.png?fit=max\&auto=format\&n=9g9fZmRyYnb5i5sQ\&q=85\&s=1c87e7eac5fa0f973f8bdbd6cdf53a5b) 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**. ![](https://mintcdn.com/ab-634991b8/9g9fZmRyYnb5i5sQ/static/img/sdks/create-sa-2.png?fit=max\&auto=format\&n=9g9fZmRyYnb5i5sQ\&q=85\&s=7d268867a8492346777c3dc260684b80) 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. ![](https://mintcdn.com/ab-634991b8/9g9fZmRyYnb5i5sQ/static/img/sdks/create-sa-3a.png?fit=max\&auto=format\&n=9g9fZmRyYnb5i5sQ\&q=85\&s=524d9343fa93eed9bf26dd09db248609) ### 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. ![](https://mintcdn.com/ab-634991b8/Ul-COtb5ywadNlrP/static/img/sdks/sdk-create-item-light.png?fit=max\&auto=format\&n=Ul-COtb5ywadNlrP\&q=85\&s=8d0f9614bfe20676d9efad5b73dec323) ## 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 theme={null} mkdir Tutorial ``` 2. Change directories to the Tutorial folder, then check to make sure you have NodeJS version 18 or later installed: ```shell theme={null} 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 theme={null} 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. ```json highlight={6} theme={null} { "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 theme={null} 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 theme={null} touch index.js ``` 2. Copy and paste the following code into it: ``` import sdk from "@1password/sdk"; // 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 theme={null} 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: 1. Copy and paste the following into your terminal to export the token to the environment. Don't run the code yet. > [tab] Bash, Zsh, sh > > ```shell theme={null} > export OP_SERVICE_ACCOUNT_TOKEN= > ``` > [tab] fish > > ```shell theme={null} > set -x OP_SERVICE_ACCOUNT_TOKEN > ``` > [tab] PowerShell > > ```powershell theme={null} > $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. > [tab] Bash, Zsh, sh > > ```shell theme={null} > export OP_SERVICE_ACCOUNT_TOKEN= > ``` > [tab] fish > > ```shell theme={null} > set -x OP_SERVICE_ACCOUNT_TOKEN > ``` > [tab] PowerShell > > ```powershell theme={null} > $Env:OP_SERVICE_ACCOUNT_TOKEN = "" > ``` 6. Run the following command to confirm you successfully set the environment variable: > [tab] Bash, Zsh, sh > > ```shell theme={null} > echo $OP_SERVICE_ACCOUNT_TOKEN > ``` > [tab] fish > > ```shell theme={null} > echo $OP_SERVICE_ACCOUNT_TOKEN > ``` > [tab] PowerShell > > ```powershell theme={null} > $Env:OP_SERVICE_ACCOUNT_TOKEN > ``` Now try running the code again: ```shell theme={null} 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](/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. ![](https://mintcdn.com/ab-634991b8/9g9fZmRyYnb5i5sQ/static/img/sdks/api-reference-light.png?fit=max\&auto=format\&n=9g9fZmRyYnb5i5sQ\&q=85\&s=9044a488d5e210f3ae004c7b3341af38) > [!TIP] > > You can also get secret references with [1Password CLI](/cli/secret-reference-syntax/#with-1password-cli) and [1Password for VS Code](/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 highlight={12} theme={null} import sdk from "@1password/sdk"; // 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 theme={null} 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. > [!WARNING] > > 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 theme={null} console.log("The secret is: " + secret); ``` 2. Save and close the file, then run the code for a final time: ```shell theme={null} 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](/sdks/manage-items#update-an-item). ## Learn more * [Get started with service accounts](/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) * [Workflow: Secure your deployments](/get-started/secure-deployment) * [Workflow: Build integrations with 1Password](/get-started/build-integrations) # Use service accounts with 1Password CLI Source: https://www.1password.dev/service-accounts/use-with-1password-cli You can use 1Password Service Accounts with 1Password CLI to manage vaults and items. See [supported commands](#supported-commands). ## Requirements Before you use service accounts with 1Password CLI, you need to: * [Sign up for 1Password.](https://1password.com/pricing/password-manager) * Install [1Password CLI](/cli/get-started/). \ Service Accounts require 1Password CLI version 2.18.0 or later. * [Create a service account.](/service-accounts/get-started/#create-a-service-account) ## Get started To use a service account with 1Password CLI: 1. Set the `OP_SERVICE_ACCOUNT_TOKEN` environment variable to the service account token: > [tab] bash, sh, zsh > > ```shell theme={null} > export OP_SERVICE_ACCOUNT_TOKEN= > ``` > [tab] fish > > ```shell theme={null} > set -x OP_SERVICE_ACCOUNT_TOKEN > ``` > [tab] Powershell > > ```shell theme={null} > $Env:OP_SERVICE_ACCOUNT_TOKEN = "" > ``` 2. Run the following command to make sure the service account is configured: ```shell highlight={9} theme={null} op user get --me # code-result ID: Name: Email: State: ACTIVE Type: SERVICE_ACCOUNT Created: 2 minutes ago Updated: 2 minutes ago Last Authentication: now ``` > [!WARNING] > > If you have 1Password CLI configured to work with [1Password Connect](/connect/), the `OP_CONNECT_HOST` and `OP_CONNECT_TOKEN` environment variables take precedence over `OP_SERVICE_ACCOUNT_TOKEN`. > > Clear the Connect environment variables to configure a service account instead. ### Supported commands You can now run supported 1Password CLI commands authenticated as the service account: * [`op read`](/cli/reference/commands/read/) * [`op inject`](/cli/reference/commands/inject/) * [`op service-account ratelimit`](/cli/reference/management-commands/service-account/#service-account-ratelimit) - [`op run`](/cli/reference/commands/run/) - [`op vault create`](/cli/reference/management-commands/vault/#vault-create) To use the following commands, you must specify a vault with the `--vault` flag if the service account has access to more than one vault: * [`op item`](/cli/reference/management-commands/item/) - [`op document`](/cli/reference/management-commands/document/) The following commands are only supported for vaults created by the service account: * [`op vault delete`](/cli/reference/management-commands/vault/#vault-delete) * [`op vault group grant`](/cli/reference/management-commands/vault/#vault-group-grant) * [`op vault user grant`](/cli/reference/management-commands/vault/#vault-user-grant) - [`op vault group revoke`](/cli/reference/management-commands/vault/#vault-group-revoke) - [`op vault user revoke`](/cli/reference/management-commands/vault/#vault-user-revoke) > [accordion] Unsupported commands > > When using a service account, the following commands aren't supported: > > * [`op connect`](/cli/reference/management-commands/connect) > > * [`op group`](/cli/reference/management-commands/group/) > > * [`op user provision`](/cli/reference/management-commands/user/#user-provision) > > * [`op user confirm`](/cli/reference/management-commands/user/#user-confirm) > > * [`op user suspend`](/cli/reference/management-commands/user/#user-suspend) > > * [`op user delete`](/cli/reference/management-commands/user/#user-delete) > > * [`op user recovery`](/cli/reference/management-commands/user/#user-recovery) > > - [`op events-api`](/cli/reference/management-commands/events-api/) > - [`op vault edit`](/cli/reference/management-commands/vault/#vault-edit) > > Although service accounts support some user, group, and vault management commands, we recommend against using them because a full provisioning workflow isn't supported: > > * [`op user get`](/cli/reference/management-commands/user/#user-get) > > * [`op user list`](/cli/reference/management-commands/user/#user-list) > > - [`op group get`](/cli/reference/management-commands/group/#group-get) > - [`op group list`](/cli/reference/management-commands/group/#group-list) ### Commands that make multiple requests Service accounts have [hourly and daily limits](/service-accounts/rate-limits) on the total number of requests the service account can make. You can sometimes reduce the number of requests made by passing a vault or item's [unique identifier (ID)](/cli/reference/#unique-identifiers-ids) instead of its name. 1Password CLI commands make one request unless otherwise noted. The following commands make more than one request: | Command | Total requests | Notes | | - | - | - | | `op item list` | 1 + 1 per vault the service account has access to | To limit total requests to 3, list items in a specific vault using the `--vault` flag. Pass the vault's ID to further limit requests to 2. | | `op item get` | 3 reads | To reduce to 1 request, pass the item and vault IDs. | | `op item create` | 1 read and 1 write | To reduce to 1 request, pass the vault ID. | | `op item delete` | 5 reads and 1 write | To reduce the read requests by 1, pass the vault ID. | | `op item edit` | 5 reads and 1 write | To reduce the read requests by 1, pass the vault ID. | | `op read` | 3 reads | To reduce to 1 request, pass the item and vault IDs. | | `op vault delete` | 2 reads + 1 write | To reduce the read requests by 1, pass the vault ID. | | `op vault edit` | up to 3 writes | The number of requests may vary depending on how many changes are made with a single command. | | `op vault get` | 2 reads | To reduce the read requests by 1, pass the vault ID. | # 1Password for SSH & Git Source: https://www.1password.dev/ssh Store SSH keys in 1Password, authenticate Git and SSH with the 1Password SSH Agent, and sign Git commits, without private keys in plaintext on disk. Introducing 1Password for SSH & Git, the single source of truth for all your SSH keys. With 1Password, you can: * [Generate and import](/ssh/manage-keys/) your SSH keys. * [Autofill public keys](/ssh/public-key-autofill/) in your browser for Git and other cloud platforms. * Automatically configure [Git commit signing with SSH](/ssh/git-commit-signing/) from the 1Password app. * Use the [1Password SSH Agent](/ssh/agent/) to authenticate all your Git and SSH workflows. * [Authorize SSH requests](/ssh/agent/authorization/) with options like Touch ID and Windows Hello. * Monitor recent [SSH Agent activity](/ssh/manage-keys#track-ssh-agent-activity) from the 1Password app. ![A terminal with a git push command, overlaid with a 1Password authorization prompt to approve the request to use an SSH key.](/static/img/ssh/1password-ssh-git.png) The SSH agent works with your existing SSH clients and acts as their key provider. Use your keys in your SSH workflows, like when you work with Git to check code into source control, or when you log in to virtual machines. 1Password stores all your SSH keys behind secure end-to-end encryption, allowing you to access your keys when you need them without your SSH keys ever leaving 1Password. ## Quickstart ### [Get started](/ssh/get-started/) If you're setting up SSH in 1Password for the first time, [start here](/ssh/get-started/). [Video on securing SSH keys for admins and developers with 1Password.](https://www.youtube.com/embed/7LK3_rK_jOg) ## Guides ### [Manage SSH keys](/ssh/manage-keys/) Learn how to generate and import SSH keys, and how to copy or download your public key if you need to share it. ### [Autofill public keys](/ssh/public-key-autofill/) Learn how to use 1Password in your browser to fill your public keys on your favourite Git or cloud platforms. ### [Sign Git commits with SSH](/ssh/git-commit-signing/) Learn how to automatically configure Git commit signing with SSH through the 1Password app. ### [Authorize SSH requests](/ssh/agent/authorization/) Learn how to authorize SSH requests with the 1Password SSH Agent and adjust when 1Password asks you to approve requests. ### [Advanced use cases](/ssh/agent/advanced/) Learn how to configure the 1Password SSH Agent for specific hosts and how to avoid rate limits with OpenSSH servers. ### [1Password agent config file](/ssh/agent/config/) Learn how to create and customize an SSH agent config file if you need to use SSH keys from shared or custom vaults or have more fine-grained control over the behavior of the SSH agent. ## Reference documentation ### [SSH client compatibility](/ssh/agent/compatibility/) Learn which SSH and Git clients have been tested with the 1Password SSH Agent. ### [About 1Password SSH Agent security](/ssh/agent/security/) Learn about the authorization model for the 1Password SSH Agent, how it's different from the OpenSSH agent, and what's kept in local storage. # 1Password SSH Agent Source: https://www.1password.dev/ssh/agent The 1Password SSH Agent authenticates your Git and SSH clients with the SSH keys saved in 1Password. Your private keys never leave the 1Password app. The 1Password SSH Agent uses the SSH keys you have saved in 1Password to seamlessly integrate with your Git and SSH workflows. It authenticates your Git and SSH clients without those clients ever being able to read your private key. In fact, your private key never even leaves the 1Password app. The SSH agent works with the SSH keys stored in 1Password, but never without your consent. Only SSH clients you explicitly authorize will be able to use your SSH keys until 1Password locks. Learn how to [turn on the 1Password SSH Agent](/ssh/get-started/#step-3-turn-on-the-1password-ssh-agent) and [configure your SSH clients](/ssh/get-started/#step-4-configure-your-ssh-or-git-client). ## Requirements > [tab] Mac > > 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) > 2. [Install and sign in to 1Password for Mac.](https://1password.com/downloads/mac) > 3. [Install the 1Password browser extension](https://1password.com/downloads/browser-extension) (optional).\\ > > Required to autofill SSH keys in your browser. > [tab] Windows > > 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) > 2. [Install and sign in to 1Password for Windows.](https://1password.com/downloads/windows) > 3. [Install the 1Password browser extension](https://1password.com/downloads/browser-extension) (optional).\\ > > Required to autofill SSH keys in your browser. > [tab] Linux > > 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) > > 2. [Install and sign in to 1Password for Linux.](https://1password.com/downloads/linux) > > 3. [Install the 1Password browser extension](https://1password.com/downloads/browser-extension) (optional).\\ > > Required to autofill SSH keys in your browser. > > > [!WARNING] > > > > The 1Password SSH agent doesn't work with [Flatpak](https://flatpak.org/) or Snap Store installations of 1Password. To use the SSH agent, choose a different method to [install 1Password for Linux](https://support.1password.com/install-linux/). > [!TIP] > > For the best experience when using the 1Password SSH Agent, you can configure [Touch ID](https://support.1password.com/touch-id-mac/), [Apple Watch](https://support.1password.com/apple-watch-mac/), [Windows Hello](https://support.1password.com/windows-hello/), or [system authentication](https://support.1password.com/system-authentication-linux/) to unlock 1Password and authenticate SSH key requests. ## Configuration By default, the 1Password SSH Agent will make every [eligible key](/ssh/agent/#eligible-keys) in the 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 of your 1Password accounts available to offer to SSH servers. This configuration is automatically set up when you [turn on the SSH agent](/ssh/get-started/#step-3-turn-on-the-1password-ssh-agent). If you need to use the SSH agent with keys saved in shared or custom vaults, you can create and customize an [SSH agent config file](/ssh/agent/config/) (`~/.config/1Password/ssh/agent.toml`) to override the default agent configuration. If you have more than six SSH keys available in the agent, you can edit your SSH config file or use [SSH Bookmarks](/ssh/bookmarks/) to match your keys to specific hosts. This will help you avoid authentication failures with OpenSSH servers that limit the number of connection attempts. Learn more about the [SSH server six-key limit](/ssh/agent/advanced/#ssh-server-six-key-limit). You can also configure your authorization settings to determine when 1Password asks you to approve SSH requests and how long the agent remembers your key approvals. Learn how to [authorize SSH requests with 1Password](/ssh/agent/authorization/). ## Eligible keys For the 1Password SSH Agent to work with your SSH keys, your 1Password SSH key items must meet the following requirements. They must be: * [Generated](/ssh/manage-keys/#generate-an-ssh-key) or [imported](/ssh/manage-keys/#import-an-ssh-key) using the `SSH Key` item type (which supports [`Ed25519` or `RSA`](/ssh/manage-keys/#supported-ssh-key-types) key types). * Stored in the vaults [the SSH agent is configured to use](#configuration) in 1Password. By default, this is the [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 of any 1Password account you're signed in to. * Active items (not archived or deleted). Any key meeting these requirements will automatically be available in the SSH agent for authentication. You will still be required to explicitly [authorize any request](/ssh/agent/security/#authorization-model) an SSH client makes to use your keys. To see a list of all keys that the agent has available, [set the `SSH_AUTH_SOCK` environment variable](/ssh/get-started#step-4-configure-your-ssh-or-git-client) (Mac and Linux only) and run: ```shell theme={null} ssh-add -l ``` ## Learn more * [Autofill public keys](/ssh/public-key-autofill/) * [Manage SSH keys](/ssh/manage-keys/#generate-an-ssh-key) * [Sign Git commits](/ssh/git-commit-signing) * [Workflow: Secure your SSH & Git workflows](/get-started/secure-ssh-git-workflows) # Advanced use cases Source: https://www.1password.dev/ssh/agent/advanced Learn more about how to use the SSH agent for specific hosts, avoid authentication limits, and use multiple Git identities on the same machine. ## Gradual migration ### Mac & Linux If you don't want to use the 1Password SSH agent for all your hosts right away, you don't have to. The 1Password SSH agent can run alongside another SSH agent, like the OpenSSH agent. The SSH client config file (`~/.ssh/config`) allows you to provide different authentication details for different hosts. So, you can try the 1Password SSH agent with one or two hosts to start, then gradually migrate the rest when you're ready. Here are a few examples of what your `~/.ssh/config` file could look like: > [tab] Example 1 > > ```toml theme={null} > # A host that uses the 1Password agent > Host raspberry-pi > HostName 192.168.12.34 > User pi > IdentityAgent ~/.1password/agent.sock > > # A host that uses a local private key file that isn't saved in 1Password > Host ec2-server > HostName 54.123.45.67 > User ec2-user > IdentityFile ~/.ssh/ssh-key-not-on-1password.pem > ``` > [tab] Example 2 > > ```toml theme={null} > # By default, use the 1Password SSH agent for all hosts > Host * > IdentityAgent ~/.1password/agent.sock > > # A host that uses a local private key file that isn't saved in 1Password > Host ec2-server > HostName 54.123.45.67 > User ec2-user > IdentityFile ~/.ssh/ssh-key-not-on-1password.pem > IdentityAgent none > ``` > [tab] Example 3 > > ```toml theme={null} > # By default, use a local private key file that's not saved in 1Password > Host * > IdentityFile ~/.ssh/ssh-key-not-on-1password.pem > > # Use the 1Password agent on a single host instead of the local key file > Host raspberry-pi > HostName 192.168.12.34 > User pi > IdentityAgent ~/.1password/agent.sock > IdentityFile none > ``` ### Windows No changes to the SSH configuration need to be made on Windows. Windows doesn't have the same flexibility with the `~/.ssh/config` file as macOS and Linux, because Microsoft OpenSSH listens to a fixed pipe `(\\.\pipe\openssh-ssh-agent)`. If you want to use the 1Password SSH agent on Windows, it will authenticate for all hosts. ## SSH server six-key limit > [!TIP] > > Use [SSH bookmarks](/ssh/bookmarks/) to match your SSH hosts with SSH keys and avoid server key limitations. SSH agents work together with SSH clients by trying all public keys the agents manage, offering them one by one to SSH servers until the server acknowledges one that works. However, OpenSSH servers are configured by default to limit the amount of authentication attempts for an incoming SSH connection (`MaxAuthTries`) to six. If your SSH client offers the SSH server a seventh key, the server will refuse the connection and you'll see this error message in your SSH client: ```text theme={null} Too many authentication failures ``` Server administrators *can* increase the limit by setting `MaxAuthTries` in the [server's `/etc/ssh/sshd_config`](https://linux.die.net/man/5/sshd_config), but in many cases you can't (or don't want to) change this. Instead, you can specify which host should be matched to which SSH key. ### Match key with host To avoid the `Too many authentication failures` error, your SSH client needs to know which SSH public key should be used with which host. This can be configured in the SSH config file by setting `IdentityFile` in a `Host` block to the public key you want use with that host. You can configure [SSH Bookmarks](/ssh/bookmarks/) to automatically manage this for you. Alternatively, you can manually edit your SSH config file: 1. In your 1Password app, select the **Download** button on the "Public key" field of the SSH item. 2. In your `~/.ssh/config` file, add an entry for the host you're connecting to and set `IdentityFile` to the path of the **public key** you just downloaded. The private key can stay in 1Password. ```toml theme={null} Host github.com IdentityFile ~/.ssh/public-key-downloaded-from-1password.pub IdentitiesOnly yes ``` Now your SSH clients will know which key to use when connecting to SSH servers, so you won't run into these authentication limits. > [!WARNING] > > Some SSH clients don't support specifying public keys in `IdentityFile`. > See [SSH client compatibility](/ssh/agent/compatibility/). ### Create an SSH agent config file You can also create an optional [SSH agent config file](/ssh/agent/config/) (`~/.config/1Password/ssh/agent.toml`). The agent config file allows you to specify which keys the SSH agent can make available to SSH servers and the order it offers those keys to servers. You can use the SSH agent config file alongside your SSH client config file (`~/.ssh/config`) to help further avoid authentication limits. ## Use multiple GitHub accounts When you connect to remote Git repositories from your local machine, all connections that are authenticated over SSH use the same `git` user. If you want to use SSH with multiple Git identities on the same machine, such as a work and personal account, you'll need to: * Define SSH host aliases for the different Git identities in your SSH config file. * Configure which SSH keys are used to authenticate connections to the remote Git repositories. * Update the URLs for your Git remotes to use the new SSH host aliases. To get started, follow these steps: 1. In the 1Password app, locate the SSH Key item for one of your Git accounts. 2. Select the down arrow on the "public key" field and choose **Download**. ![Download your public key](https://mintcdn.com/ab-634991b8/2GuQWN9fVwUxVlhr/static/img/ssh/share-public-key.png?fit=max\&auto=format\&n=2GuQWN9fVwUxVlhr\&q=85\&s=fdda3e9bcb4b979c9b39c08ed9e6b1cb) 3. Save the public key to your `~/.ssh/` directory. 4. Repeat steps 1–3 for each SSH key you need to use. 5. On your local machine, edit your `~/.ssh/config` file to add SSH host sections for each Git identity. For example, to configure SSH hosts for your personal and work GitHub accounts, you would add the following to your SSH config file: ```text ~/.ssh/config theme={null} # Personal GitHub Host personalgit HostName github.com User git IdentityFile ~/.ssh/personal_git.pub IdentitiesOnly yes # Work GitHub Host workgit HostName github.com User git IdentityFile ~/.ssh/work_git.pub IdentitiesOnly yes ``` You can adjust the host (the alias name) and hostname, if needed, and you'll need to set `IdentityFile` to use the public key you saved in your `~/.ssh/` directory for that repository. 6. For each Git repository, change the `git` URL to use one of the new SSH host aliases instead of the default host URL, such as `git@github.com`. ```bash theme={null} git remote set-url origin :/.git ``` For example: ```bash theme={null} git remote set-url origin personalgit:1password/1password-teams-open-source.git ``` Now your SSH clients will know which SSH key to use for each Git identity. Learn more about how to [sign Git commits with SSH](/ssh/git-commit-signing/). ## Learn more * [Autofill public keys](/ssh/public-key-autofill/) * [Manage SSH keys](/ssh/manage-keys/#generate-an-ssh-key) * [Workflow: Secure your SSH & Git workflows](/get-started/secure-ssh-git-workflows) # Authorize SSH requests with 1Password Source: https://www.1password.dev/ssh/agent/authorization Learn how to authorize SSH requests with the 1Password SSH Agent and adjust when 1Password asks you to approve requests. When an SSH client makes a request through the [1Password SSH Agent](/ssh/agent/) to use one of your SSH keys, 1Password will ask for your consent before the agent can use the key. You can quickly and securely approve the request from the 1Password desktop app, and [adjust your authorization settings](#adjust-your-authorization-settings) to control when 1Password asks you for approval. Before you can authorize SSH requests, make sure you've [turned on the 1Password SSH Agent](/ssh/get-started/#step-3-turn-on-the-1password-ssh-agent) and [configured your SSH or Git client](/ssh/get-started/#step-4-configure-your-ssh-or-git-client) to use the agent for authentication. ## Approve an SSH request When you run an SSH or Git command, 1Password will ask you to allow your terminal or other SSH client to use your SSH key. The authorization prompt indicates which application is requesting permission to use which SSH key, and you'll always have the option to deny the request. You can approve the request using the authentication option indicated on the prompt (for example, Touch ID, Windows Hello, or your account password). The authorization method will vary depending on your device, operating system version, and 1Password settings. If 1Password is locked, you'll also be prompted to unlock the app so the SSH agent can access your private keys. ![Authorization prompt showing a Touch ID icon.](/static/img/ssh/auth-prompt-touch-id.png) ![Authorization prompt showing that the 1Password account password needs to be entered.](/static/img/ssh/auth-prompt-account-password.png) ![Authorization prompt showing a Windows Hello icon.](/static/img/ssh/auth-prompt-windows-hello.png) If the SSH key you're approving belongs to an account that uses [1Password Unlock with SSO](https://support.1password.com/sso-get-started/), you may be redirected to the sign-in page for your identity provider. You'll then need to sign in using the credentials for your provider account to authorize the request. After approving the request, you can continue using the same SSH key for that application without being prompted again until 1Password locks or quits. You can also [adjust your authorization settings](#adjust-your-authorization-settings) to prompt more or less frequently. [Learn more about the 1Password SSH Agent authorization model.](/ssh/agent/security/#authorization-model) ## Adjust your authorization settings There are several options you can choose from to determine what usage you're approving for each key and how long the agent remembers your SSH key approval. These options determine when the SSH agent will ask you to approve SSH requests. To adjust your authorization settings, open 1Password, then select your account or collection at the top of the sidebar and select **Settings** > [**Developer**](onepassword://settings/developers). In the advanced settings for the SSH agent, you can choose the options that best suit your needs. You can change your settings at any time. ### Choose when 1Password asks for approval Use the **Ask approval for each new** setting to choose what usage you're approving when you authorize an SSH request. ![SSH agent advanced settings showing the menu with the options for when 1Password will ask you to approve SSH requests.](https://mintcdn.com/ab-634991b8/sG98I5gpxsW5yq0Z/static/img/ssh/advanced-settings-ask-approval.png?fit=max\&auto=format\&n=sG98I5gpxsW5yq0Z\&q=85\&s=290224dfc18c2e8fd4167c4fbc375f1e) 1Password can ask you to approve an SSH request: * **For each new application** (default): You'll be asked to authorize SSH requests from each new application to use a specific SSH key. * **For each new application and terminal session**: Similar to the first option, you'll be asked to authorize SSH requests from each new application to use a specific SSH key. If the application is a terminal emulator or an IDE with a built-in terminal, you'll also be asked to authorize requests for each new terminal tab in that application. * **For each new request**: You'll be asked to authorize every new SSH request, even if it comes from an application or terminal session you've already approved. Each approval only authorizes a single request, so the agent doesn't remember your key approvals with this option. ### Choose how long 1Password remembers your approval Use the **Remember key approval** setting to choose how long 1Password will remember your key approval. > [!NOTE] > > The "Remember key approval" setting isn't available if you've configured 1Password to ask for approval for each new request. Because each approval only authorizes a single request, there's no key approval for the agent to remember. ![SSH agent advanced settings showing the menu with the options for how long 1Password remembers your key approval.](https://mintcdn.com/ab-634991b8/sG98I5gpxsW5yq0Z/static/img/ssh/advanced-settings-remember-approval.png?fit=max\&auto=format\&n=sG98I5gpxsW5yq0Z\&q=85\&s=5e99a986d73e711d71fc663f32870617) 1Password can remember your key approval: * **Until 1Password locks** (default): Every time 1Password locks, your key approvals are wiped from the agent's memory and you'll be asked to reauthorize any previously approved SSH clients to use your keys. For example, if you approve the terminal application to use your SSH key for GitHub, then 1Password locks, you'll need to reapprove any new requests from the terminal to use your GitHub SSH key when 1Password unlocks. [Learn how to change your 1Password lock settings.](https://support.1password.com/auto-lock/) * **Until 1Password quits**: Every time 1Password quits, your key approvals are wiped from the agent's memory. Any agent sessions and background processes will also end. To use the SSH agent to authorize any new requests to use your SSH keys, you'll need to reopen 1Password. * **For a set amount of time**: You can choose from 4, 12, or 24 hours. If you select one of these options, your key approvals will remain in the agent's memory for that duration, even when 1Password is locked. You won't need to reauthorize new requests from the same applications to use the same SSH keys you've already approved, but you'll be prompted to unlock 1Password so the SSH agent can access your private key. ### Approve a key for all applications Every authorization prompt for a client to use an SSH key includes the option to approve the use of that key for all applications. To turn on this option, select the checkbox to **Approve for all applications**. ![An authorization prompt from 1Password with the allow all option checked, showing that all applications can use the GitHub SSH key.](https://mintcdn.com/ab-634991b8/2GuQWN9fVwUxVlhr/static/img/ssh/auth-prompt-allow-all.png?fit=max\&auto=format\&n=2GuQWN9fVwUxVlhr\&q=85\&s=88b825036eeee9398662ca7b226167e6) This option can be selected for individual SSH keys. It temporarily authorizes all applications running in the current OS user account on your device to use that SSH key for the duration of the agent session (depending on [the options you've selected in the developer settings](#adjust-your-authorization-settings) in 1Password). You can use this option alongside your other settings. Learn more about the [authorization model for the SSH agent](/ssh/agent/security#authorization-model). ## Suppressing background requests It's very common for IDEs and Git GUI clients to periodically run `git fetch` in the background on currently open repositories. This feature is often enabled by default and may result in unexpected authorization prompts from 1Password, especially if you're unaware of an application's auto-fetch behavior. 1Password helps to suppress prompts if it detects that the app or window the request originated from is not in the foreground. The 1Password icon in your device's menu bar, taskbar, or system tray will display an indicator dot when a prompt has been suppressed. If you need to access the prompt, select the 1Password icon and select **SSH request waiting**. The authorization prompt will be brought to the foreground. ## Learn more * [About 1Password SSH Agent security](/ssh/agent/security/) * [SSH client compatibility](/ssh/agent/compatibility/) * [Use the 1Password SSH Agent with WSL](/ssh/integrations/wsl) * [Workflow: Secure your SSH & Git workflows](/get-started/secure-ssh-git-workflows) # SSH client compatibility Source: https://www.1password.dev/ssh/agent/compatibility The 1Password SSH agent has been tested for compatibility with a number of different clients that use SSH and Git. > [tab] Mac > > | Name | SSH Capability | Compatible with 1Password | > | - | - | - | > | **[Cyberduck](#cyberduck)** | SFTP | Yes | > | **[DataGrip](#datagrip)** | SSH tunneling | Yes | > | **[FileZilla](#filezilla)** | SFTP | Yes | > | **[Fork](#fork)** | Git | Yes | > | **[ForkLift](#forklift)** | SFTP | Yes | > | **[git CLI](#git-cli)** | Git | Yes | > | **[Gitfox](#gitfox)** | Git | Yes | > | **[GitHub Desktop](#github-desktop)** | Git | Yes | > | **[GitKraken](#gitkraken)** | Git | Yes | > | **GitUp** | Git | Yes | > | **[JetBrains IDEs](#jetbrains-ide)** | Git | Yes | > | **[Nova](#nova)** | Git | Yes | > | **[OpenSSH](#openssh)** | SSH, SFTP | Yes | > | **[Postico](#postico)** | SSH tunneling | No | > | **[Sequel Ace](#sequel-ace)** | SSH tunneling | No | > | **[Sourcetree](#sourcetree)** | Git | Yes | > | **[Sublime Merge](#sublime-merge)** | Git | Yes | > | **[TablePlus](#tableplus)** | SSH tunneling | Yes | > | **[Termius](#termius)** | SSH | No | > | **[Tower](#tower)** | Git | Yes | > | **[Transmit](#transmit)** | SFTP | Yes | > | **[Visual Studio Code](#vs-code)** | Git | Yes | > | **[Xcode](#xcode)** | Git | No | > [tab] Windows > > | Name | SSH Capability | Compatible with 1Password | > | - | - | - | > | **[Celestial Software](#celestial-software)** | SSH, SFTP | Yes | > | **[Cyberduck](#cyberduck)** | SFTP | Yes | > | **[FileZilla](#filezilla)** | SFTP | No | > | **[Fork](#fork)** | Git | Yes | > | **[Git for Windows](#git-for-windows)** | Git | Yes | > | **[GitHub Desktop](#github-desktop)** | Git | Yes | > | **[GitKraken](#gitkraken)** | Git | Yes | > | **[JetBrains IDEs](#jetbrains-ide)** | Git | Yes | > | **[Microsoft OpenSSH](#openssh)** | SSH, SFTP | Yes | > | **[Pageant](#pageant)** | SSH | No | > | **[PuTTY](#putty)** | SSH | No | > | **[Sourcetree](#sourcetree)** | Git | Yes | > | **[Sublime Merge](#sublime-merge)** | Git | Yes | > | **[Termius](#termius)** | SSH | No | > | **[Tower](#tower)** | Git | Yes | > | **[Visual Studio Code](#vs-code)** | Git | Yes | > [tab] Linux > > | Name | SSH Capability | Compatible with 1Password | > | - | - | - | > | **[DataGrip](#datagrip)** | SSH tunneling | Yes | > | **[git CLI](#git-cli)** | Git | Yes | > | **[GitKraken](#gitkraken)** | Git | Yes | > | **[JetBrains IDEs](#jetbrains-ide)** | Git | Yes | > | **[OpenSSH](#openssh)** | SSH, SFTP | Yes | > | **[Sublime Merge](#sublime-merge)** | Git | Yes | > | **[Termius](#termius)** | SSH | No | > | **[Visual Studio Code](#vs-code)** | Git | Yes | *** ## Working with SSH clients ### Agent configuration with `IdentityAgent` On Mac and Linux, most SSH and Git clients check your `~/.ssh/config` file for the `IdentityAgent` setting for the corresponding host. The clients then use the configured agent socket path to handle SSH authentication. This option gives you the most flexibility, like the ability to configure [multiple agents side by side](/ssh/agent/advanced/#gradual-migration). However, not every SSH client adheres to every value in the SSH config file. In the list below, you can see whether or not your SSH client supports configuration with `IdentityAgent`. ### Agent configuration with `SSH_AUTH_SOCK` On Mac and Linux, you can also configure the agent socket path using the `SSH_AUTH_SOCK` environment variable. There are more SSH clients that support `SSH_AUTH_SOCK` than `IdentityAgent`. For clients that support both, `IdentityAgent` usually takes precedence over `SSH_AUTH_SOCK`. Follow the steps for your operating system to configure `SSH_AUTH_SOCK` for your SSH client: > [tab] Mac > > #### Configure `SSH_AUTH_SOCK` for the terminal > > To configure `SSH_AUTH_SOCK` for the terminal, run: > > ``` > export SSH_AUTH_SOCK=~/Library/Group\ Containers/2BUA8C4S2C.com.1password/t/agent.sock > ``` > > Any command you run within that same shell will use the 1Password SSH agent. > > To pass `SSH_AUTH_SOCK` to a GUI application, you can use the `open` command to launch the application: > > ```shell theme={null} > export SSH_AUTH_SOCK=~/Library/Group\ Containers/2BUA8C4S2C.com.1password/t/agent.sock > open -a /Applications/.app > ``` > > #### Configure `SSH_AUTH_SOCK` globally for every client > > If you want to persist and automatically configure the `SSH_AUTH_SOCK` environment variable for every client without launching them from the terminal, run the following snippet to create a launch agent: > > ```shell theme={null} > mkdir -p ~/Library/LaunchAgents > cat << EOF > ~/Library/LaunchAgents/com.1password.SSH_AUTH_SOCK.plist > > > > > Label > com.1password.SSH_AUTH_SOCK > ProgramArguments > > /bin/sh > -c > /bin/ln -sf $HOME/Library/Group\ Containers/2BUA8C4S2C.com.1password/t/agent.sock \$SSH_AUTH_SOCK > > RunAtLoad > > > > EOF > launchctl load -w ~/Library/LaunchAgents/com.1password.SSH_AUTH_SOCK.plist > ``` > [tab] Linux > > #### Configure `SSH_AUTH_SOCK` for the terminal > > To configure `SSH_AUTH_SOCK` for the terminal, run: > > ``` > export SSH_AUTH_SOCK=~/.1password/agent.sock > ``` > > Any command you run within that same shell will use the 1Password SSH agent. > > #### Configure `SSH_AUTH_SOCK` globally for every client > > If you want to persist and automatically configure the `SSH_AUTH_SOCK` environment variable for every client without launching them from the terminal, run the following snippet to create a login script in `/etc/profile.d/`: > > ```shell theme={null} > echo "export SSH_AUTH_SOCK=~/.1password/agent.sock" | sudo tee /etc/profile.d/1password-ssh-auth-sock.sh > ``` > > If your system launches the GNOME keyring SSH agent automatically, you can disable that by running the following command: > > ```shell theme={null} > mkdir -p ~/.config/autostart \ > && cp /etc/xdg/autostart/gnome-keyring-ssh.desktop ~/.config/autostart/gnome-keyring-ssh.desktop \ > && echo "Hidden=true" >> ~/.config/autostart/gnome-keyring-ssh.desktop > ``` > > If you choose not to do this, the GNOME setting (`/run/user/1000/keyring/ssh`) may take precedence over the 1Password setting, depending on your operating system. ### Using Git autofetch Some Git clients are configured by default to periodically perform a `git fetch` in the background. This can result in authorization prompts popping up unexpectedly, so 1Password helps to suppress prompts if the application or window where the request came from isn't in the foreground. If a prompt has been suppressed, you'll see an indicator dot on the 1Password icon in your device's menu bar, taskbar, or system tray. To access the prompt, select the 1Password icon, then select **SSH request waiting**. The authorization prompt will be brought to the foreground, where you can approve or deny the request. If you'd rather not be prompted when your applications automatically fetch changes, even when the prompts are suppressed, you can turn off the autofetch settings in your Git client and instead only fetch or pull on demand. ![Turn on the settings in 1Password to make sure the agent keeps running](/static/img/ssh/suppressed-prompt-notification.png) ### Setting public keys as `IdentityFile` If an SSH client supports setting public keys as `IdentityFile`, you can use that to [match hosts to a specific key in 1Password](/ssh/agent/advanced/#match-key-with-host). In the list below, you can see if that's the case for your preferred SSH client. *** ## OpenSSH > [tab] Mac > > #### `ssh`, `sftp`, `scp` > >
  • > >
  • > >
  • > >
  • > >
  • > > #### `ssh-add` > >
  • > >
  • > >
  • > >
  • > >
  • > [tab] Windows > > #### `ssh`, `sftp`, `scp` > >
  • > >
  • > > #### `ssh-add` > >
  • > >
  • > >
  • > >
  • > >
  • > [tab] Linux > > #### `ssh`, `sftp`, `scp` > >
  • > >
  • > >
  • > >
  • > >
  • > > #### `ssh-add` > >
  • > >
  • > >
  • > >
  • > >
  • ## Celestial Software > [tab] Windows > >
  • > >
  • ## Cyberduck > [tab] Mac > >
  • > >
  • > >
  • > >
  • > [tab] Windows > >
  • > >
  • ## DataGrip > [tab] Mac > >
  • > >
  • > >
  • > >
  • > [tab] Linux > >
  • > >
  • > >
  • > >
  • ## FileZilla > [tab] Mac > >
  • > >
  • > >
  • > [tab] Windows > >
  • ## Fork > [tab] Mac > >
  • > >
  • > >
  • > >
  • > >
  • > [tab] Windows > >
  • > >
  • > >
  • > >
  • ## ForkLift > [tab] Mac > >
  • > >
  • > >
  • ## `git` CLI > [tab] Mac > >
  • > >
  • > >
  • > >
  • > [tab] Windows > > For Git compatibility on Windows, see [Git for Windows](#git-for-windows). > [tab] Linux > >
  • > >
  • > >
  • > >
  • ## Git for Windows > [tab] Windows > >
  • > >
  • > >
  • > >
  • > >
  • ## Gitfox > [tab] Mac > >
  • > >
  • > >
  • > >
  • ## GitHub Desktop > [tab] Mac > >
  • > >
  • > >
  • > >
  • > [tab] Windows > >
  • > >
  • > >
  • ## GitKraken > [tab] Mac > >
  • > >
  • > >
  • > >
  • > [tab] Windows > >
  • > >
  • > [tab] Linux > >
  • > >
  • > >
  • > >
  • ## JetBrains IDEs *IntelliJ IDEA, WebStorm, GoLand, CLion, PhpStorm, RubyMine, AppCode.* > [tab] Mac > >
  • > >
  • > >
  • > >
  • > >
  • > [tab] Windows > >
  • > >
  • > >
  • > [tab] Linux > >
  • > >
  • > >
  • > >
  • > >
  • ## Nova > [tab] Mac > >
  • > >
  • > >
  • > >
  • ## Pageant > [tab] Windows > >
  • > >
  • ## Postico > [tab] Mac > >
  • > >
  • ## PuTTY > [tab] Windows > >
  • ## Sequel Ace > [tab] Mac > >
  • > >
  • ## Sourcetree > [tab] Mac > >
  • > >
  • > >
  • > >
  • > [tab] Windows > >
  • > >
  • > >
  • > >
  • ## Sublime Merge > [tab] Mac > >
  • > >
  • > >
  • > >
  • > [tab] Windows > >
  • > >
  • > >
  • > [tab] Linux > >
  • > >
  • > >
  • > >
  • ## TablePlus > [tab] Mac > >
  • > >
  • > >
  • ## Termius > [tab] Mac > >
  • > [tab] Windows > >
  • > [tab] Linux > >
  • ## Tower > [tab] Mac > >
  • > >
  • > >
  • > >
  • > >
  • > [tab] Windows > >
  • > >
  • > >
  • > >
  • ## Transmit > [tab] Mac > >
  • > >
  • > >
  • > >
  • ## Visual Studio Code > [tab] Mac > >
  • > >
  • > >
  • > >
  • > [tab] Windows > >
  • > >
  • > >
  • > [tab] Linux > >
  • > >
  • > >
  • > >
  • ## Xcode > [tab] Mac > >
  • ## Learn more * [Autofill public keys](/ssh/public-key-autofill/) * [Manage SSH keys](/ssh/manage-keys/#generate-an-ssh-key) * [Sign Git commits](/ssh/git-commit-signing) * [Workflow: Secure your SSH & Git workflows](/get-started/secure-ssh-git-workflows) # SSH agent config file Source: https://www.1password.dev/ssh/agent/config The 1Password SSH Agent config file is a [TOML file](https://toml.io/en/) you can create that gives you more fine-grained control over the behavior of the SSH agent. With the agent config file, you can: * [Choose which keys are available to the SSH agent](#add-individual-keys) from any of your vaults and accounts, not just your Personal, Private, or Employee vault. * Specify the order the agent uses to offer your keys to SSH servers, to prevent running into the [six-key authentication limit](/ssh/agent/advanced/#ssh-server-six-key-limit) on most servers. * Create different agent configurations for each machine, to customize how you use the SSH agent on each device. The SSH agent config file (`~/.config/1Password/ssh/agent.toml`) is unique to 1Password. It's separate from the SSH *client* config file ([`~/.ssh/config`](https://linux.die.net/man/5/ssh_config)) and the SSH *server* config file ([`/etc/ssh/sshd_config`](https://linux.die.net/man/5/sshd_config)) and can be used alongside them. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux). 3. [Import or generate SSH keys in 1Password.](/ssh/manage-keys/) 4. [Set up the 1Password SSH Agent.](/ssh/get-started/#step-3-turn-on-the-1password-ssh-agent) ## About the SSH agent config file The SSH agent config file is an optional configuration file that allows you to override the [default behavior](#agent-configuration-options) of the 1Password SSH Agent on your Mac, Windows, or Linux machine. It doesn't alter your SSH agent settings or other SSH config files on your computer — only which keys the agent can access and in which order to make them available to servers. The agent config file is saved locally on your machine and isn't synced to the 1Password servers. If you use 1Password with multiple workstations, you can sync or share the agent config file using your own method (for example, using Git) the same way you do with other dotfiles. Or you can create separate agent config files for each machine. You can [remove the agent config file](#remove-the-ssh-agent-config-file) at any time to return to the default agent configuration. ### Agent configuration options If there's no agent config file on your machine, 1Password will use the default SSH agent configuration, which allows the agent to make any SSH key item in your default [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 available to offer to SSH servers. If you want to customize how the SSH agent is configured, you can [create the SSH agent config file](#create-the-ssh-agent-config-file) to override the default agent behavior, then [modify the file](#modify-the-ssh-agent-config-file) to specify which keys the SSH agent has access to and the order you want them offered to the server. ### File syntax and structure #### TOML syntax The SSH agent config file uses the [TOML file syntax](https://toml.io/en/v1.0.0) to identify which SSH keys the SSH agent can access and when it can access them. Each entry in the file requires an `[[ssh-keys]]` header and one or more key-value pairs to indicate the item, vault, and/or account name or ID for the SSH key item. For example: ```toml agent.toml theme={null} # Add my Git authentication key from my Work vault [[ssh-keys]] item = "Git Authentication Key" vault = "Work" # Add my Git signing key from my Work vault [[ssh-keys]] item = "Git Signing Key" vault = "Work" # Then add all keys from my Private vault [[ssh-keys]] vault = "Private" account = "Wendy Appleseed's Family" ``` > [accordion] TOML syntax rules > > The SSH agent config file adheres to the following TOML syntax rules: > > * **Case sensitivity:** TOML is case-sensitive, so all TOML elements (the header name and keys in key-value pairs) must be lowercase. Strings (1Password values enclosed in quotation marks) and comments are not case-sensitive. > > * **Encoding:** The TOML file must use valid [UTF-8 character encoding.](https://www.ietf.org/rfc/rfc3629.txt) > > * **Comments:** Use the hash (#) symbol to indicate the line is a comment. Comments are optional and are not case-sensitive. For example: > > ``` > # This line is a comment. > ``` > > * **Header name:** Indicates the start of a new section and must be lowercase and enclosed in double brackets to indicate an array of tables. Each header must use the same name `[[ssh-keys]]` header name to define it as part of the array. > > * **Key-value pairs:** Indicate which SSH key items are available to the SSH agent. Keys must be lowercase and can be one or more of `item`, `vault`, or `account`. Values are the strings containing the item, vault, or account name or ID from 1Password and must be enclosed in quotes. > > Key-value pairs are separated by an equal (=) sign and each pair must be on a new line. Unspecified values are invalid. For example: > > ``` > item = "My SSH key item name" > ``` > > * **Whitespace:** Leading and trailing whitespace of both `key` and `value` segments are ignored, so `key = "value"` is parsed the same as `key="value"`. > > #### Examples of good TOML file entries > > ```toml theme={null} > # My work GitHub SSH key > [[ssh-keys]] > item = "GitHub SSH key - Work" > ``` > > The example above meets all the syntax criteria. > > ```toml theme={null} > # My team's demo GitHub SSH key > [[ssh-keys]] > item="GitHub SSH key - Demo" > vault="Demo" > account="AgileBits" > ``` > > Whitespace is ignored for key-value pairs, so this example is also good. > > #### Examples of bad TOML file entries > > ```toml theme={null} > # My work GitHub SSH key > [[SSH-KEYS]] > ITEM = "GitHub SSH key - Work" > ``` > > The example above doesn't respect the case sensitivity for TOML elements — `[[ssh-keys]]` and `item` need to be lowercase. > > ```toml theme={null} > # My work GitHub SSH key > item = "github ssh key - work" > ``` > > In this example, the `"github ssh key - work"` value is good because 1Password values aren't case sensitive, but the entry is missing the required `[[ssh-keys]]` header. > > ```toml theme={null} > # My team's demo GitHub SSH key > [[ssh-keys]] > item = GitHub SSH key - Demo > vault = Demo > account = AgileBits > ``` > > In the example above, the values for `item`, `vault`, and `account` aren't enclosed in quotations. > > For more information about TOML, see the [full list of specifications.](https://toml.io/en/v1.0.0) #### File structure The SSH agent config file is made up of sections. A section is defined by the `[[ssh-keys]]` header followed by one or more key-value pairs for the intended SSH key or set of keys to be made available to the SSH agent. The order of the `[[ssh-keys]]` sections in the agent config file determine the order the agent offers your keys to SSH servers. This helps to minimize the number of authentication attempts the SSH agent makes so you don't run into the [six-key limit](/ssh/agent/advanced/#ssh-server-six-key-limit) (`MaxAuthTries`) that is the default for most SSH servers. Here's an example of an SSH agent configuration file with entries for two specific SSH keys: ```toml agent.toml highlight={3,9} theme={null} # My GitHub SSH key for my Work account [[ssh-keys]] item = "GitHub SSH key - Work" vault = "Private" account = "AgileBits" # Shared GitHub SSH key for the Demo account [[ssh-keys]] item = "GitHub SSH Key - Demo" vault = "Demo" account = "AgileBits" ``` With this configuration, if you try to SSH into a GitHub repository in your `Work` account, the SSH agent will offer your work SSH key to the server first because it's the first key entry in the file. If the key is a match, 1Password will ask you to [authorize the request](/ssh/agent/authorization/). If you try to SSH into a GitHub repository in your `Demo` account instead, the agent will still offer your work key to the server first, then your demo SSH key. With only two SSH keys in the file, it's unlikely that you'd be at risk of running into any server limits. However, if you have six or more SSH keys listed in your agent config file before the demo key, or if your agent config file includes multiple SSH keys for the same host, you can also modify the SSH client config file (`~/.ssh/config`) to [match your SSH keys to individual hosts](/ssh/agent/advanced#match-key-with-host) or specify [which SSH key each of your GitHub repositories uses](/ssh/agent/advanced#use-multiple-github-accounts). ## Create the SSH agent config file ### From the 1Password app You can use the 1Password desktop app to create the SSH agent config file for you. The file will include entries to allow the SSH agent to access all the keys in any of your Personal, Private, or Employee vaults, similar to the [default configuration](#agent-configuration-options) used by the agent when no agent config file exists. For example, if you're signed in to a 1Password account with a default Private vault, you'll see an entry like this added to the agent config file: ```toml theme={null} [[ssh-keys]] vault = "Private" ``` You can then choose to [modify the file](#modify-the-ssh-agent-config-file) to adjust which keys the agent offers to SSH servers in which order. To create the agent config file from 1Password: > [tab] Mac > > 1. Open and unlock [1Password for Mac](https://1password.com/downloads/mac) and select any SSH key you want to add to the agent config file.\ > If you don't have any SSH keys saved in 1Password yet, you can [generate a new key in 1Password](/ssh/manage-keys/#generate-an-ssh-key) or [import an existing key](/ssh/manage-keys/#import-an-ssh-key). > 2. Select > **Configure for SSH Agent**. > > This will automatically create the SSH agent config file and open it in your default editor. You can then [modify the config file](#modify-the-ssh-agent-config-file) to add the SSH key. > > ![Create the SSH agent config file from the app](/static/img/ssh/configure-for-ssh-agent.png) > > On macOS, 1Password will create the SSH agent config file in the following location: > > ```text theme={null} > ~/.config/1Password/ssh/agent.toml > ``` > > 1Password also supports the `XDG_CONFIG_HOME` environment variable, if you have it configured. > > After you create the file, you may need to lock and then unlock 1Password for the agent config file to be recognized. > [tab] Windows > > 1. Open and unlock [1Password for Windows](https://1password.com/downloads/windows) and select any SSH key you want to add to the agent config file.\ > If you don't have any SSH keys saved in 1Password yet, you can [generate a new key in 1Password](/ssh/manage-keys/#generate-an-ssh-key) or [import an existing key](/ssh/manage-keys/#import-an-ssh-key). > 2. Select > **Configure for SSH Agent**. > > This will automatically create the SSH agent config file and open it in your default editor. You can then [modify the config file](#modify-the-ssh-agent-config-file) to add the SSH key. > > ![Create the SSH agent config file from the app](/static/img/ssh/configure-for-ssh-agent.png) > > On Windows, 1Password will create the SSH agent config file in the following location: > > ```text theme={null} > %LOCALAPPDATA%/1Password/config/ssh/agent.toml > ``` > > After you create the file, you may need to lock and then unlock 1Password for the agent config file to be recognized. > [tab] Linux > > 1. Open and unlock [1Password for Linux](https://1password.com/downloads/linux) and select any SSH key you want to add to the agent config file.\ > If you don't have any SSH keys saved in 1Password yet, you can [generate a new key in 1Password](/ssh/manage-keys/#generate-an-ssh-key) or [import an existing key](/ssh/manage-keys/#import-an-ssh-key). > 2. Select > **Configure for SSH Agent**. > > This will automatically create the SSH agent config file and open it in your default editor. You can then [modify the config file](#modify-the-ssh-agent-config-file) to add the SSH key. > > ![Create the SSH agent config file from the app](/static/img/ssh/configure-for-ssh-agent.png) > > On Linux, 1Password will create the SSH agent config file in the following location: > > ```text theme={null} > ~/.config/1Password/ssh/agent.toml > ``` > > 1Password also supports the `XDG_CONFIG_HOME` environment variable, if you have it configured. > > After you create the file, you may need to lock and then unlock 1Password for the agent config file to be recognized. ### From the terminal You can also choose to create the SSH agent config file yourself from the terminal. The file won't include any entries for your SSH keys — including any keys in your default Personal, Private, or Employee vault(s) — until you add them. When you create the file at the specified path, 1Password will detect it and override the default agent behavior, even if the agent config file is empty. Make sure to [modify the agent config file](#modify-the-ssh-agent-config-file) after you create it, to add any SSH keys items you need from any of your vaults or accounts. You can create the SSH agent config file on your machine at the specified path: > [tab] Mac > > On macOS, 1Password will look for the SSH agent config file at: > > ```text theme={null} > ~/.config/1Password/ssh/agent.toml > ``` > > If you have the `XDG_CONFIG_HOME` environment variable configured, 1Password will check the following path first: > > ```text theme={null} > $XDG_CONFIG_HOME/1Password/ssh/agent.toml > ``` > [tab] Windows > > On Windows, 1Password will look for the SSH agent config file at: > > ```text theme={null} > %LOCALAPPDATA%/1Password/config/ssh/agent.toml > ``` > [tab] Linux > > On Linux, 1Password will look for the SSH agent config file at: > > ```text theme={null} > ~/.config/1Password/ssh/agent.toml > ``` > > If you have the `XDG_CONFIG_HOME` environment variable configured, 1Password will check the following path first: > > ```text theme={null} > $XDG_CONFIG_HOME/1Password/ssh/agent.toml > ``` ## Modify the SSH agent config file You can make your SSH keys available to the SSH agent by adding `[[ssh-keys]]` sections to the agent config file for any combination of individual keys, vaults, and accounts you have access to in 1Password, including shared and custom vaults. Your `[[ssh-keys]]` entries can be as specific or as broad in scope as you'd like, where you'll use at least one or more of the following key-value pairs to act like a series of queries on your SSH key items: * item: "The item name or ID" * vault: "The vault name or ID" * account: "The account name sign-in address or ID" These key-value pairs work like `WHERE`/`AND` clauses and operators, where the more data you include, the more specific your query becomes. If the SSH agent finds more than one key match per entry, the keys will be added in ascending order according to when the item was created (from the oldest to the most recent). To control the exact order, you can add additional `[[ssh-keys]]` sections to the agent config file. Before you modify the agent config file, make sure you're familiar with the [file syntax and structure](#file-syntax-and-structure), to ensure the SSH agent behaves as you expect it to. You don't need to restart the SSH agent each time you edit the agent config file. Your saved changes will be immediately available to the agent. ### Add individual keys You can add an `[[ssh-keys]]` section for an individual SSH key by including an `item` key-value pair in the entry. Include additional key-value pairs if you want to further specify which vault or account the SSH key is in. For example: ```toml agent.toml theme={null} # Add my Git authentication key from my Work vault [[ssh-keys]] item = "Git Authentication Key" # Then add my Git signing key from my Work vault [[ssh-keys]] item = "Git Signing Key" vault = "Work" account = "ACME, Inc." ``` ### Add all keys in a vault You can add an `[[ssh-keys]]` section for all the SSH keys in a vault by including the `vault` key-value pair in the entry. You can include an `account` key-value if you want to specify which 1Password account the key is in, but don't include an `item` key-value pair or only that item will be added. For example: ```toml agent.toml theme={null} # Add all keys from my Work vault [[ssh-keys]] vault = "Work" # Then add all keys from the Private vault in my family account [[ssh-keys]] vault = "Private" account = "Wendy Appleseed's Family" ``` If you add or remove SSH keys from the vault, access to the keys will be added to, or removed from, the SSH agent without needing to modify the agent config file later. ### Add all keys in an account You can add an `[[ssh-keys]]` section for all the SSH keys in a 1Password account by including the `account` key-value pair in the entry. Don't include the `item` or `vault` key-value pairs or you'll only add SSH keys for that item or vault. For example: ```toml agent.toml theme={null} # Add all keys from my family account [[ssh-keys]] account = "Wendy Appleseed's Family" # Then add all keys from my work account [[ssh-keys]] account = "ACME, Inc." ``` Instead of the account name, you can also use the [sign-in address](https://support.1password.com/1password-glossary/#sign-in-address) as the `account` value (sign-in addresses can include `https://` at the start, but it's not required). For example: ```toml agent.toml theme={null} # Add all keys from my family account [[ssh-keys]] account = "my.1password.com" # Then add all keys from my work account [[ssh-keys]] account = "https://acme.1password.com" ``` If you add or remove SSH keys from the account, access to the keys will be added to, or removed from, the SSH agent without needing to modify the agent config file later. ### Filter keys You can use the `[[ssh-keys]]` entries as filters in the agent config file to progressively add keys for the SSH agent to access in your preferred order. When you have multiple 1Password accounts, like a work account and a family account, you can progressively filter the `[[ssh-keys]]` entries down by 1Password account. If you have any specific items or vaults that you want the SSH agent to offer to servers first, you can include those as well. For example: ```toml agent.toml theme={null} # Add my Git signing key from my Work vault [[ssh-keys]] item = "Git Signing Key" vault = "Work" account = "ACME, Inc." # Then add all keys from the Private vault in my family account [[ssh-keys]] vault = "Private" account = "Wendy Appleseed's Family" # Then add all keys from the Private vault in my work account [[ssh-keys]] vault = "Private" account = "ACME, Inc." # Then add all remaining keys from any vault in my family account [[ssh-keys]] account = "Wendy Appleseed's Family" ``` ### Use IDs as values Using the name of an item, vault, or account in the agent config file makes it easier to identify what the entry is for. However, you might choose to use an ID in place of a name if: * **You don't want your item, vault, or account names stored in plaintext on disk.** [This metadata is encrypted](https://support.1password.com/1password-privacy/#data-saved-in-1password:~:text=Your%20metadata%20is%20private) by default in 1Password, but the agent config file on your device is unencrypted. * **You expect the name of an item, vault, or account to be updated periodically.** IDs are the most stable way to reference an item. An item's ID only changes if you move it to a different vault. An example entry with an item ID: ```toml agent.toml highlight={3} theme={null} # Add my signing key from my Private vault [[ssh-keys]] item = "hhaeohhhc7iksdbadbx5pxyb6m" ``` To find and copy an item ID, go to the [**Advanced** settings](onepassword://settings/advanced) in the 1Password app and turn on **Show debugging tools**. Find the item you want and select it, then select > **Copy UUID**. Then paste the UUID value in the config file entry. You can also [use 1Password CLI to find the IDs for your items, vaults, and accounts](/cli/reference/#unique-identifiers-ids). ## Remove the SSH agent config file If you no longer want to use the SSH agent configuration file, you can delete the file or move it to another location. The 1Password SSH Agent will then use the [default configuration](#agent-configuration-options) again. ## Get help To get help or provide feedback, use the `#ssh-agent-config` channel on the [1Password Developers Slack workspace](/joinslack). This channel is used as the primary means of communication about the agent config file and is where we'll post updates and help answer questions. ### Errors in the agent config file If there's an error in the agent config file, the SSH agent will stop running and will notify you of the error in the [Developer settings](onepassword://settings/developers) of the 1Password app. Make sure each entry [uses the correct syntax](#file-syntax-and-structure). If you don't see an error message in 1Password but you're seeing an authentication error in your SSH client or having trouble using the SSH agent, check the values from your key-value pairs. If you make any typos in an item, vault, or account name value, the SSH agent won't be able to make a key match. Entries without key matches are not considered errors and will be ignored. If you're not able to use a specific key with the SSH agent and it's in the agent config file with the correct syntax and values, you can also check that the SSH key hasn't been archived or deleted. Any archived or deleted SSH Key items will be ignored, even if you specify them by ID. To see the list of all keys the SSH agent can access, you can run the `ssh-add -l` command, with the `SSH_AUTH_SOCK` environment variable set to the agent socket path: > [tab] Mac > > ```sh theme={null} > SSH_AUTH_SOCK=~/Library/Group\ Containers/2BUA8C4S2C.com.1password/t/agent.sock ssh-add -l > ``` > [tab] Windows > > ```sh theme={null} > ssh-add -l > ``` > [tab] Linux > > ```sh theme={null} > SSH_AUTH_SOCK=~/.1password/agent.sock ssh-add -l > ``` ## Learn more * [Get started with 1Password for SSH & Git](/ssh/get-started/) * [Advanced use cases](/ssh/agent/advanced/) * [Manage SSH keys](/ssh/manage-keys#generate-an-ssh-key) * [SSH client compatibility](/ssh/agent/compatibility/) * [About 1Password SSH Agent security](/ssh/agent/security/) * [Workflow: Secure your SSH & Git workflows](/get-started/secure-ssh-git-workflows) # SSH agent forwarding with 1Password Source: https://www.1password.dev/ssh/agent/forwarding SSH agent forwarding lets you make SSH requests within a remote environment as if it were your local machine, like running Git commands and signing commits from a [cloud development environment](#cde) or [remote workstation](#remote-workstation). Instead of storing your private keys on the remote host, you can use SSH agent forwarding to forward your requests to your local 1Password SSH Agent. Then authorize the request with biometrics without your private keys ever leaving the local 1Password process. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. [Import or generate SSH keys in 1Password.](/ssh/manage-keys/) 4. [Set up the 1Password SSH Agent](/ssh/get-started/#step-3-turn-on-the-1password-ssh-agent) and make sure it's running on your local machine. > [!TIP] > > **If you use Windows** > > If you use a Windows computer, you can [set up the 1Password WSL integration](/ssh/integrations/wsl) to authenticate SSH requests in your WSL instance from your Windows host. ## About SSH agent forwarding When you enable agent forwarding for a remote host, every SSH request you make within the remote environment gets forwarded to the local 1Password process over the 1Password SSH Agent socket. You can authorize SSH requests locally using options you've set up in 1Password, like your fingerprint. Then your authorization gets forwarded back to the remote host without ever needing to provide your private key to the remote server. > [!WARNING] > > Make sure you only use SSH agent forwarding with trusted hosts. [Learn how to use SSH agent forwarding more securely.](#security) ## Set up SSH agent forwarding SSH agent forwarding is turned off in OpenSSH by default. You can choose to turn it on for a [single session](#for-a-single-session) or for a [specific host](#for-a-specific-host). ### For a single session To turn on agent forwarding for a single session only, use the `-A` flag with the `ssh` command: ```shell theme={null} ssh -A user@example.com ``` When you're connected to the remote host with agent forwarding turned on, the `SSH_AUTH_SOCK` environment variable on the remote host is automatically set. Data sent over this socket gets forwarded to the local 1Password socket. ```text theme={null} user@example.com:~$ echo $SSH_AUTH_SOCK #code-result /tmp/ssh-XXXXNpdlnL/agent.151 ``` To check if agent forwarding is working, run the following command view a list of the SSH keys forwarded from 1Password to the remote host: ```text theme={null} user@example.com:~$ ssh-add -l #code-result 256 SHA256:2zmxMpLy5MeIx18pBUkumptKkKinlghygOvV6URe8QI SSH Key from 1Password (ED25519) ``` If you see your SSH key listed, try to run an SSH request from within the remote server: ```text theme={null} user@example.com:~$ ssh -T git@github.com ``` The 1Password app on your local machine should prompt you to authorize the request. ### For a specific host If you want to set up SSH agent forwarding for a specific host all the time so you don't need to use the `-A` flag for each session, edit your `~/.ssh/config` file to include that host: ```text theme={null} Host example.com ForwardAgent yes ``` ## SSH agent forwarding security ### Security considerations When you authorize your local terminal, IDE, or other SSH client to use an SSH key in an agent forwarding session, any new connection made within the remote environment using the same key is also authorized. If someone else were to gain access to the remote environment as the same OS user, they'd be able to use the SSH key to authenticate connections from the remote host for the duration of the session. However, any other SSH keys available in the remote environment still require your approval before they can be used. Unlike the standard OpenSSH agent, where every key in the agent can be used in the remote environment without additional authorization, the 1Password SSH Agent requires your approval for each SSH key before it can be used. An attempt to use one of those keys from the remote environment triggers a 1Password authorization prompt that needs to be authenticated, making agent forwarding more secure with 1Password than with the OpenSSH agent. ### Use agent forwarding more securely We recommend the following: * Only use agent forwarding when you need it and in environments that you trust are secure. * Set up agent forwarding on a [per-command basis](#for-a-single-session) or configure your `~/.ssh/config` file to allow agent forwarding [only with specific hosts](#for-a-specific-host). **Do not turn on SSH agent forwarding for all hosts by default.** ```text ~/.ssh/config (bad 👎) theme={null} Host * ForwardAgent yes ``` We recommend that you always scope the `ForwardAgent yes` directive down to a specific host or domain you trust for agent forwarding. For example, to turn on agent forwarding for [Gitpod](https://www.gitpod.io/), add this to your `~/.ssh/config` file: ```text ~/.ssh/config (good 👍) theme={null} Host *.gitpod.io ForwardAgent yes ``` ## Use case: Cloud Development Environment If you use a local integrated development environment (IDE) to connect to a cloud development environment (CDE) and you want to pull, push, and sign remote Git commits, you can authenticate those commands through the local 1Password SSH Agent. For example, you might have an IDE desktop app on your local workstation that you use to authenticate into a cloud-based development environment. You want to use the the CDE workspace to access remote Git repositories and you need to be able to authenticate Git requests and sign commits. With SSH agent forwarding, you can authenticate SSH and Git commands from your CDE workspace in your IDE desktop app through the 1Password SSH Agent running on your local workstation. ### Set up SSH agent forwarding To set up SSH agent forwarding so you can authorize Git requests from your cloud development environment, [edit your SSH config file to add your CDE host](#for-a-specific-host). The remote development integration in your IDE should recognize this automatically. To check if agent forwarding is correctly set up, open a remote shell in your IDE then run the following command: ```shell theme={null} ssh-add -l #code-result 256 SHA256:2zmxMpLy5MeIx18pBUkumptKkKinlghygOvV6URe8QI SSH Key from 1Password (ED25519) ``` You should see a list of the SSH keys the agent can use for SSH requests. ### Use SSH for Git authentication If your CDE is set up to use HTTPS to authenticate with Git and you want to use SSH instead, run the following command to modify the remote Git configuration for the CDE: ```shell theme={null} git config --global url."ssh://git@".insteadOf "https://" ``` Alternatively, you can add the command to your cloud development initialization (cloud-init) script or dotfiles. The next time you make a Git request from your CDE, 1Password should prompt you to authorize the request. For example: ```shell theme={null} git fetch ``` If you only want to use SSH authentication going forward, you may want to revoke HTTPS write access to your repository. ### Set up Git commit signing Your local `.gitconfig` file isn't automatically forwarded to your cloud development environment, so you'll need to modify the Git configuration in your CDE to set up remote Git commit signing. 1. Configure Git to use SSH for commit signing: ```shell theme={null} git config --global gpg.format ssh ``` 2. Tell Git to always sign commits: ```shell theme={null} git config --global commit.gpgsign true ``` 3. Set the SSH key you want to use to sign commits: ```shell theme={null} git config --global user.signingkey ``` ### Authorization model When you run an SSH or Git request in your cloud development environment that requires authorization, 1Password will prompt you to approve SSH key usage for the IDE that's connected to your CDE. If you approve the request, the entire IDE will be authorized to use that key. Any process running on the cloud development environment under the same OS user will also be authorized, which is a [security consideration](#security) to keep in mind. ## Use case: Remote workstation If you have a remote workstation that you connect to over SSH, and you want to run SSH and Git requests from that workstation, you can authenticate those requests through the 1Password agents that runs on your local host. For example, you might have a desktop workstation at home that contains all your Git repositories. You want to work on the go, so you use your laptop to connect to your remote workstation over SSH so you can work in your Git repos. With SSH agent forwarding, you can authenticate SSH and Git commands from your remote workstation through the 1Password SSH Agent running on your local laptop. ### Set up SSH agent forwarding To set up SSH agent forwarding so you can authorize SSH and Git requests from your remote workstation, [edit the SSH config file](#for-a-specific-host) on your local host to allow agent forwarding with your remote workstation. To check if agent forwarding is correctly set up, connect to your remote workstation then run the following command: ```shell theme={null} ssh-add -l #code-result 256 SHA256:2zmxMpLy5MeIx18pBUkumptKkKinlghygOvV6URe8QI SSH Key from 1Password (ED25519) ``` You should see a list of the SSH keys the agent can use for SSH requests. ### Modify the `IdentityAgent` configuration on the remote workstation If your remote workstation also has the 1Password SSH Agent installed, you'll want to make sure that Git and SSH use the forwarded socket from your local host instead of the agent socket for the 1Password app installed on the remote workstation. The `IdentityAgent` takes precedence over the `SSH_AUTH_SOCK` environment variable, so you may want to modify the `~/.ssh/config` file for your remote workstation so the `IdentityAgent` setting is only applied if you're not in an SSH shell. ```text theme={null} Match host * exec "test -z $SSH_TTY" IdentityAgent "~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock" ``` Then any Git or SSH command executed from an SSH shell on the remote workstation will use the forwarded `SSH_AUTH_SOCK` for authentication and 1Password should prompt you to authorize SSH requests from your local host. This change won't affect how the 1Password SSH Agent runs when you use the workstation locally instead of accessing it remotely. The `IdentityAgent` setting will be applied as usual to use the SSH agent running on the workstation. ### Set up Git commit signing Your local `.gitconfig` file isn't automatically forwarded to your remote workstation, so the remote Git configuration will be used by default. If you've configured [Git commit signing with 1Password](/ssh/git-commit-signing) on the remote workstation using the same SSH key you use on your local host, you shouldn't need make any changes to your setup. If the `op-ssh-sign` signing program finds that both the `SSH_AUTH_SOCK` and the `SSH_TTY` environment variables are set, it will automatically adapt to use the forwarded socket from your local host instead of the 1Password socket from your remote workstation. ### Authorization model When you run an SSH or Git request from a remote shell or remotely connected IDE that requires authorization, 1Password will prompt you to approve SSH key usage for the terminal or IDE you use to connect to the remote workstation. If you approve the request, the entire app will be authorized to use this key. Any process running on the remote workstation under the same OS user will also be authorized, which is a [security consideration](#security) to keep in mind. ## Troubleshooting If you're having trouble using agent forwarding with the 1Password SSH Agent, there are a few things you should check. ### Check if the `SSH_AUTH_SOCK` environment variable is set Run `echo $SSH_AUTH_SOCK` in the terminal to make sure the environment variable is set on your server. ```text theme={null} user@example.com:~$ echo $SSH_AUTH_SOCK #code-result /tmp/ssh-XXXXNpdlnL/agent.151 ``` If the variable isn't set, SSH agent forwarding won't work. Make sure [the 1Password SSH Agent is turned on](/ssh/get-started#step-3-turn-on-the-1password-ssh-agent) and that you've [configured your SSH client to use the agent for authentication](/ssh/get-started#step-4-configure-your-ssh-or-git-client). ### Check if the SSH agent can access the correct SSH key Run `ssh-add -l` in the terminal to see a list of the SSH keys forwarded from 1Password to the remote host: ```text theme={null} user@example.com:~$ ssh-add -l #code-result 256 SHA256:2zmxMpLy5MeIx18pBUkumptKkKinlghygOvV6URe8QI SSH Key from 1Password (ED25519) ``` If you don't see your SSH key listed, make sure the key is [eligible to use with the 1Password SSH Agent](/ssh/agent/#eligible-keys) and that it's [saved in a vault the SSH agent is configured to use](/ssh/agent/#configuration). ### Check if agent forwarding is allowed on the server To use agent forwarding with a remote server, the `AllowAgentForwarding` option must be set to `Yes` in the [`sshd_config` file](https://man.openbsd.org/sshd_config) for the server. ## Learn more * [Autofill public keys](/ssh/public-key-autofill/) * [Manage SSH keys](/ssh/manage-keys/#generate-an-ssh-key) * [Sign Git commits](/ssh/git-commit-signing) * [Workflow: Secure your SSH & Git workflows](/get-started/secure-ssh-git-workflows) # About 1Password SSH Agent security Source: https://www.1password.dev/ssh/agent/security The 1Password SSH Agent allows you to securely authenticate all your Git and SSH commands from 1Password. Your private keys never leave 1Password, are never stored locally, and are never used without your consent. ## Differences with the OpenSSH agent The standard OpenSSH agent (`ssh-agent`) that comes preinstalled on most operating systems requires you to add keys to the agent (`ssh-add`) every time it launches. After you've added your SSH keys, any process can use any key that the OpenSSH agent is managing. It's then up to you to remove those keys when they're not needed anymore. The 1Password SSH Agent uses a different approach and asks for your consent before an SSH client or terminal session can use your key. Because of this, there's no concept of adding or removing keys like with the OpenSSH agent. When you [turn on the SSH agent](/ssh/get-started/#step-3-turn-on-the-1password-ssh-agent) from the 1Password preferences or settings, every [eligible key](/ssh/agent/#eligible-keys) saved in 1Password becomes available to use for SSH, but your private keys will never be used without your consent. ## Authorization model The authorization model for the 1Password SSH Agent is built on the idea that you should be able to control which processes are allowed to use which private keys. When an SSH client or terminal session on your system makes a request through the SSH agent to use one of your keys, 1Password will ask if you want to [approve the request](/ssh/agent/authorization/). The authorization prompt indicates which process is requesting permission to use which SSH key. After you approve the request, a session is established between the key and the process the SSH command was run from (a process can be a terminal window or tab, an IDE, or a GUI application, like a Git or SFTP client). ![An SSH authorization prompt asking to approve a request over a terminal window showing a git pull command.](https://mintcdn.com/ab-634991b8/2GuQWN9fVwUxVlhr/static/img/ssh/authorize-ssh-request.png?fit=max\&auto=format\&n=2GuQWN9fVwUxVlhr\&q=85\&s=ea9e839d63a7c04ac3c10b5ff574fc6e) Any subsequent SSH commands run in that process can use your key without further approval until 1Password locks or quits, or for the amount of time set in the [options you've configured](#authorization-options). For example, if you authorize a `git pull` command from the terminal for one of your SSH keys, 1Password won't prompt you to approve your following `git push` because the session is already approved. If you've configured 1Password to ask for approval for each new request, no session is established and you'll be asked to approve every request individually. When 1Password is locked, the SSH agent continues to run in the background and will prompt you if an SSH client tries to use one of your keys. If you've already authorized the client to use your key for a set amount of time (for example, four hours) instead of when 1Password locks, your approval will still be in the agent's memory and you'll only be prompted to unlock 1Password. The SSH agent doesn't keep your private keys in memory when 1Password is locked, only your authorization, so the app needs to be unlocked for the agent to access your private keys. ### Authorization options The authorization model for the 1Password SSH Agent allows for some flexibility, so you can set it up to best suit your needs at any given time. You'll always be asked to authorize the use of each private key, but you can adjust options like how long an SSH agent session lasts (how long the agent remembers your key approval). This could be until 1Password locks or quits, or until a set amount of time has passed. You can also choose what usage you're approving for each key, which determines when the SSH agent will ask you to approve requests. Usage options you can choose include: * **Per key, per application** (default): When you approve an SSH key request, you authorize a specific application (including all of its subprocesses) to use a specific SSH key. Your authorization grants access to the SSH key within that agent session, or until the application quits. * **Per key, per application, per terminal session**: When you approve an SSH key request, you authorize a specific application (including all of its subprocesses) to use a specific SSH key, but with an additional restrictions. If the application is a terminal emulator or an IDE with a built-in terminal, your authorization only applies to a specific tab. Each new terminal tab in that application requires separate approval to use that key. Your authorization grants access to the SSH key within that agent session, or until the application or terminal session quits. * **Per key, per request**: When you approve an SSH key request, you authorize only that single request. No agent session is established and the agent doesn't remember your key approval, so you'll be asked to approve every new SSH request, even from applications or terminal sessions you've previously approved. * **Per key, once for every process running on the user’s system**: You can see this option on a per-request basis for a specific SSH key by selecting the **Approve for all applications** checkbox on the authorization prompt. This temporarily authorizes all processes running under the current OS user to use that key for the duration of the agent session. Access is only restricted by file permissions on the agent socket or named pipe. This option doesn't affect your other settings. [Learn how to adjust the authorization settings for the 1Password SSH Agent.](/ssh/agent/authorization/#adjust-your-authorization-settings) ## Local storage When you turn on the SSH agent, the 1Password app will store an unencrypted copy of the **public keys** of all your [eligible SSH keys](/ssh/agent/#eligible-keys) on disk. Storing your public keys allows the SSH authorization prompt to be shown even when 1Password is locked. If you turn on "Display key names when authorizing connections" for the SSH agent, the 1Password app will also store an unencrypted copy of your SSH key **item titles** on disk. Displaying SSH key names is optional and this setting is turned off by default. This setting can be turned on or off in the 1Password app. If the setting is turned off, your SSH key names will not be stored. The authorization prompt will instead show a truncated public key fingerprint for identification. ## Learn more * [Authorize SSH requests with 1Password](/ssh/agent/authorization/) * [Autofill public keys](/ssh/public-key-autofill/) * [Manage SSH keys](/ssh/manage-keys/#generate-an-ssh-key) * [Sign Git commits](/ssh/git-commit-signing) * [Workflow: Secure your SSH & Git workflows](/get-started/secure-ssh-git-workflows) # Troubleshooting Source: https://www.1password.dev/ssh/agent/troubleshooting ## If you see "No accounts configured for use with 1Password CLI" or the SSH agent stops working on macOS 27 Golden Gate If you updated to macOS 27 Golden Gate and the 1Password SSH agent stopped responding to SSH or Git requests, macOS may be blocking your terminal from accessing data from the 1Password app. To allow access: 1. Open **System Settings** > **Privacy & Security** > **Files & Folders**. 2. Select the app you use to run commands, like Terminal, iTerm, or Ghostty. If you use a terminal built into an editor, like Visual Studio Code or Cursor, select the editor. 3. Turn on the setting that starts with "Data shared by 1Password". The rest of the name depends on which 1Password apps you've installed. 4. Quit and reopen your terminal, then try your command again. If you don't see the "Data shared by 1Password" setting, run a 1Password CLI or SSH command in that terminal and select **Allow** when macOS asks to access data from other apps. Then check again. If you use more than one terminal, turn on the setting for each one. ## Create an SSH agent diagnostics report If you're experiencing issues with how the SSH agent handles your SSH requests, you can send us an SSH diagnostics report so we can help resolve the problem. You must use a [beta](https://support.1password.com/betas/) or nightly release of the 1Password app to create an SSH diagnostics report. ### Step 1: Set up SSH diagnostics recording To start recording SSH diagnostics, navigate to the 1Password data directory: > [tab] Mac > > ```text theme={null} > ~/Library/Group Containers/2BUA8C4S2C.com.1password/Library/Application Support/1Password/Data > ``` > [tab] Windows > > ```text theme={null} > %LOCALAPPDATA%\1Password > ``` > [tab] Linux > > ```text theme={null} > ~/.config/1Password > ``` From this location, create a new subdirectory called `ssh-diagnostics`. SSH diagnostics recording is now enabled. ### Step 2: Run some SSH requests Run a few SSH requests using your preferred setup and tools to reproduce the issue you're having. Each SSH request you run will be logged as a pair of JSON files in the `ssh-diagnostics` directory. ### Step 3: Create a ZIP file of your `ssh-diagnostics` directory After you've recorded a few SSH requests that demonstrate the issue, create a ZIP file of your `ssh-diagnostics` directory. To stop recording, delete the `ssh-diagnostics` directory. ### Step 4: Remove personally identifiable information (PII) from the diagnostics files The files generated during the SSH diagnostics recording may contain PII, like your OS username, Git repo names, and SSH hosts. The 1Password app attempts to redact as much of this data as possible and you'll see things like ``, ``, and `` in the generated JSON files. However, there could still be some PII contained in your diagnostics files. Make sure to check for any information you don't want to include, like a company name that appears as part of a path, and redact it. Then recreate your ZIP file. ## Learn more * [Autofill public keys](/ssh/public-key-autofill/) * [Manage SSH keys](/ssh/manage-keys/#generate-an-ssh-key) * [Sign Git commits](/ssh/git-commit-signing) * [Workflow: Secure your SSH & Git workflows](/get-started/secure-ssh-git-workflows) # Manage SSH Bookmarks in 1Password (beta) Source: https://www.1password.dev/ssh/bookmarks SSH Bookmarks in 1Password allow you to: * Connect to SSH hosts directly from 1Password, without manually entering commands in the terminal. * Match your SSH keys to specific hosts to make sure the correct key is used for each connection. * Avoid [server key limitations](/ssh/agent/advanced#ssh-server-six-key-limit) when managing multiple SSH keys. You can add bookmarks from the [SSH Agent activity log](#from-the-activity-log) or by adding `ssh://` URLs to your SSH Key items. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux). 3. [Import or generate SSH keys in 1Password.](/ssh/manage-keys/) 4. [Set up the 1Password SSH Agent.](/ssh/get-started/#step-3-turn-on-the-1password-ssh-agent) ## Manage your SSH Bookmarks You can use and manage SSH Bookmarks for hosts that use keys [available to the 1Password SSH Agent](/ssh/agent/#eligible-keys). If you're signed in to [multiple accounts](https://support.1password.com/multiple-accounts/) in the 1Password desktop app, make sure to unlock the accounts where you've stored the keys for your SSH hosts. ### Create a bookmark Create bookmarks for your frequently used SSH hosts from the [SSH Agent activity log](#from-the-activity-log) or in an [SSH Key item](#in-an-ssh-key-item). #### From the activity log If you've recently used 1Password to authorize an `ssh` command run from the terminal (like `ssh user@hostname`), you can create a bookmark from the [SSH Agent activity log](/ssh/manage-keys#track-ssh-agent-activity). 1. Open and unlock the 1Password desktop app. 2. Select **Developer** in the sidebar. 3. Select **View SSH Agent**, then select the **Activity** tab. 4. Select **Bookmark** in the Actions column for an SSH host. ![The SSH Agent activity log in the SSH Agent page of the 1Password app.](https://mintcdn.com/ab-634991b8/dzX4i4DKMioaV1IG/static/img/ssh/ssh-activity-log-bookmark.png?fit=max\&auto=format\&n=dzX4i4DKMioaV1IG\&q=85\&s=26ac5477b4ce43a3bed7f5de179c765c) 1Password will add the SSH host URL to the associated SSH Key item, then add the bookmark to the Bookmarks section of the SSH Agent developer page. #### In an SSH Key item To create a bookmark manually, you can add the SSH host URL to an SSH Key item in 1Password. 1. Find the SSH Key item for the host you want to bookmark, then select **Edit**. 2. Add a [custom field](https://support.1password.com/custom-fields/#add-a-custom-field) with the SSH host URL (a field label isn't required). SSH host URLs must start with `ssh://` and can use the hostname or IP address of the SSH host. 3. Select **Save**. The bookmark will be added to the Bookmarks section of the SSH Agent developer page. If you've defined a `Host` block in your `~/.ssh/config` file with a custom alias (for example, `Host my-host-alias`), you can also bookmark the alias instead of the actual hostname or IP address. For example: * **Hostname**: `ssh://user@example.org`, `ssh://test-server.example.com` * **IP address**: `ssh://admin@192.0.2.255`, (IPv4), `ssh://user@2001:DB8:a8b0:5678::200c` (IPv6) * **Host alias**: `ssh://my-host-alias` ### Connect to a bookmarked host You can connect to your bookmarked SSH hosts from the Bookmarks section of the 1Password app. 1. Open and unlock the 1Password desktop app. 2. Select **Developer** in the sidebar. 3. Select **View SSH Agent**, then select the **Bookmarks** tab. 4. Select **Connect** on a bookmarked host. 1Password will launch the terminal, which initiates a connection to the SSH host. 5. [Authorize the connection](/ssh/agent/authorization/), if prompted. 1Password uses the [terminal application](#terminal-for-ssh-connections) set for SSH URLs to connect to the host. ### Edit a bookmark From the Bookmarks section of the SSH Agent developer page: 1. Select > **View SSH Key item** in the bookmark's Actions menu. 2. Select **Edit**, then update the host URL field. 3. Save your changes. Your saved changes will automatically update in your Bookmarks list. ![The SSH bookmarks tab in the SSH Agent page of the 1Password app.](https://mintcdn.com/ab-634991b8/dzX4i4DKMioaV1IG/static/img/ssh/ssh-bookmarks.png?fit=max\&auto=format\&n=dzX4i4DKMioaV1IG\&q=85\&s=b2adc51cca1939cdba5d6f2f8d1296c9) ### Remove a bookmark From the Bookmarks section of the SSH Agent page, select > **Remove bookmark** in the bookmark's Actions menu. You can also remove a bookmark by editing the SSH Key item. Remove the SSH host URL from the item, or delete the item if you no longer need the SSH key. Using either method removes an SSH Bookmark from your Bookmarks list, the SSH Key item, and the [1Password SSH configuration file](#ssh-bookmarks-config-file), if you turned on that feature. ## SSH Bookmarks config file 1Password can automatically manage an SSH config file (`~/.ssh/1Password/config`) that matches bookmarked SSH hosts with the corresponding SSH key. You can include this file in your main SSH config file (`~/.ssh/config`). This also prevents you from running into the [six-key server limit](/ssh/agent/advanced#ssh-server-six-key-limit). Note that generating SSH configuration files will store your unencrypted SSH host URLs and SSH public keys for your bookmarks on disk. Your private keys will remain safe in 1Password. ### Generate the 1Password config file This feature is turned off by default, so you'll need to turn on the setting in 1Password: 1. Open the 1Password desktop app and navigate to **Settings** > [**Developer**](onepassword://settings/developers). 2. Go to the Advanced section for the SSH Agent (you may need to select the section to expand it). 3. Select **Generate SSH config files with bookmarked hosts**. \ If you see a message that says "Managed by administrator", the setting is managed by your team's [app usage policy](https://support.1password.com/team-policies/#app-usage). Contact your team administrator to learn more. 1Password will generate a directory at `~/.ssh/1Password/` that includes: * `~/.ssh/1Password/config` file: An SSH configuration file that maps SSH hosts to their corresponding keys. * `*.pub` files: Individual public key files for each bookmarked host, named using the SSH key's public fingerprint. ### Use the configuration file To start using the 1Password configuration file, you'll need to include it in your main SSH config file. Add the following line to the top of your `~/.ssh/config` file: ```toml theme={null} Include ~/.ssh/1Password/config ``` Then save your changes to the file. 1Password manages changes to the `~/.ssh/1Password/config` file. Any time you create, edit, or remove an SSH Bookmark, 1Password automatically updates the configuration file. If you want to override any of the rules from the 1Password configuration file, you can do so by editing your SSH configuration file. Copy the relevant `Match Host` block from the 1Password-generated `~/.ssh/1Password/config` file into your `~/.ssh/config` file. Then edit the configuration values in the block to your preferred values. If you turn off the setting to generate configuration files, 1Password will remove the `~/.ssh/1Password` directory and all generated files. > [!WARNING] > > **Do not manually edit the 1Password-generated files** > > Manual edits made to the 1Password-generated files won't be saved. If you need to make changes, [edit your SSH Bookmarks](#edit-a-bookmark) in 1Password or make the changes in your main `~/.ssh/config` file. ## Terminal for SSH connections 1Password will use your system's default terminal application to launch SSH connections without additional setup, or you can choose your preferred terminal option in the settings. > [tab] Mac > > #### Choose a terminal option for SSH Bookmarks > > 1. Open the 1Password desktop app and navigate to **Settings** > [**Developer**](onepassword://settings/developers). > 2. Go to the Advanced section for the SSH Agent and locate the **Open SSH URLs with** setting. > 3. Select your preferred terminal application from the available options. > [tab] Windows > > #### Choose a terminal option for SSH Bookmarks > > 1. Open the 1Password desktop app and navigate to **Settings** > [**Developer**](onepassword://settings/developers). > 2. Go to the Advanced section for the SSH Agent and locate the **Open SSH URLs with** setting. > 3. Select the option you want 1Password to use to open SSH connections: Windows Terminal or a [custom terminal command](#set-custom-command-windows). > > #### Set a custom terminal command > > The custom terminal command option allows you to provide your own shell command to open `ssh://` URLs. > > Terminal commands are executed using the `cmd.exe /c start` process and can only contain simple command-line arguments. For more complex arguments that use environment variables or interpolation, you can create a script file and use the script's file path in your command. > > A basic command structure could include the terminal application, with any options and flags you want to use to specify the terminal's behavior, followed by the SSH command and [URL option(s)](#url-options-windows). > > For example, if you want 1Password to use the Windows Terminal to open an SSH URL in a maximized window with a vertical, split-pane, you could use a command like: > > ``` > wt.exe --maximized split-pane -V ssh %s > ``` > > If your terminal app isn't in your `PATH`, use the full path of the app in your command. For example: > > ``` > "C:\Program Files (x86)\My Terminal App\MyTerminalApp.exe" ssh %s > ``` > > For more complex arguments, you can create a custom script and use the full path of the script in your command. For example: > > ``` > "C:\Scripts\MyScript.ps1" %s > ``` > > > [!NOTE] > > > > For more examples of Windows command-line arguments, see [Microsoft's documentation.](https://learn.microsoft.com/en-us/windows/terminal/command-line-arguments?tabs=windows) > > ##### SSH URL options and variables > > You can use one or more of the following options in your command to reference all or part of the SSH URL in your bookmark: > > * `%s`: the full SSH URL in your bookmark (for example: `ssh://admin@example.com:9999`) > * `%u`: the user (`admin`) > * `%h`: the host (`example.com`) > * `%p`: the port (`9999`) > > If you want 1Password to use the full SSH URL syntax from your bookmark, use the `%s` option in your custom command: > > ``` > my-command %s > ``` > > If your SSH client doesn't support the SSH URL syntax, use the `%u` and `%h` options to pass the host and user variables separately when 1Password invokes your custom command: > > ``` > my-command --user %u --host %h --port %p > ``` > > The `--port %p` variable is optional. You don't need to include port information in your bookmark or custom command unless you need to use a port other than the default SSH port (`22`). > > If you don't want 1Password to replace an SSH URL option with a variable, add a backslash (`\`) before the option to escape it so it's treated as a literal string. For example: > > ``` > my-command \%s > ``` > [tab] Linux > > #### Choose a terminal option for SSH Bookmarks > > 1. Open the 1Password desktop app and navigate to **Settings** > [**Developer**](onepassword://settings/developers). > 2. Go to the Advanced section for the SSH Agent and locate the **Open SSH URLs with** setting. > 3. Select the option you want 1Password to use to open SSH connections: your preferred terminal application from the available options, a [custom terminal command](#set-custom-command-linux), or [xdg-open](#configure-xdg-open). > > If you want 1Password to handle your bookmarks separately from the rest of your system, you can choose your preferred terminal or a custom command in 1Password and configure `xdg-open` for your system. > > #### Set a custom terminal command > > The custom terminal command option allows you to provide your own shell command to open `ssh://` URLs. > > Terminal commands are executed using the `systemd-run` process and can only contain [simple command-line arguments.](https://linux.die.net/man/1/bash) For more complex arguments that use environment variables or interpolation, you can create a script file and use the script's file path in your command. > > A basic command structure could include the terminal application, with any options and flags you want to use to specify the terminal's behavior, followed by the SSH command and [URL option(s)](#url-options-linux). > > For example, if you want 1Password to use the WezTerm terminal app to open an SSH URL in a new `tmux` session on a remote server, you could use a custom command like: > > ``` > wezterm -e ssh %s tmux new -A > ``` > > If your terminal app isn't in your `PATH`, use the full path of the app in your command. For example: > > ``` > /home/my-apps/my-terminal-app ssh %s > ``` > > For more complex arguments, you can create a custom script and use the full path of the script in your command. For example: > > ``` > /home/user/scripts/my-custom-script.sh %s > ``` > > ##### SSH URL options and variables > > You can use one or more of the following options in your command to reference all or part of the SSH URL in your bookmark: > > * `%s`: the full SSH URL in your bookmark (for example: `ssh://admin@example.com:9999`) > * `%u`: the user (`admin`) > * `%h`: the host (`example.com`) > * `%p`: the port (`9999`) > > If you want 1Password to use the full SSH URL syntax from your bookmark, use the `%s` option in your custom command: > > ``` > my-command %s > ``` > > If your SSH client doesn't support the SSH URL syntax, use the `%u` and `%h` options to pass the host and user variables separately when 1Password invokes your custom command: > > ``` > my-command --user %u --host %h --port %p > ``` > > The `--port %p` variable is optional. You don't need to include port information in your bookmark or custom command unless you need to use a port other than the default SSH port (`22`). > > If you don't want 1Password to replace an SSH URL option with a variable, add a backslash (`\`) before the option to escape it so it's treated as a literal string. For example: > > ``` > my-command \%s > ``` > > #### Configure `xdg-open` > > You can use `xdg-open` to open `ssh://` URLs with the application that registers the `x-scheme-handler/ssh` MIME type. > > To customize how `xdg-open` launches `ssh://` URLs, you can create a `.desktop` file: > > 1. Create a file called `1password-ssh-handler.desktop` in `~/.local/share/applications` with the following content: > > ```file 1password-ssh-handler.desktop highlight={3} theme={null} > [Desktop Entry] > Name=1Password SSH Handler > Exec=gnome-terminal -- ssh %u > Terminal=false > Type=Application > MimeType=x-scheme-handler/ssh; > ``` > > You can edit the `Exec` command to use your preferred terminal. > > 2. Run the following command in your terminal to register the SSH handler: > > ```shell theme={null} > update-desktop-database ~/.local/share/applications > ``` ## Learn more * [Advanced use cases](/ssh/agent/advanced/) * [SSH agent config file](/ssh/agent/config/) * [Sign Git commits with SSH](/ssh/git-commit-signing/) * [Workflow: Secure your SSH & Git workflows](/get-started/secure-ssh-git-workflows) # Get started with 1Password for SSH Source: https://www.1password.dev/ssh/get-started Generate or import an SSH key in 1Password, turn on the 1Password SSH Agent, and authenticate Git and SSH connections with your fingerprint. You can use 1Password to generate an SSH key and autofill your public key to your favorite Git platform. Then, set up the 1Password SSH Agent and configure your SSH or Git client so you can use the SSH agent to authenticate your Git and SSH workflow. [Video walkthrough that covers creating an SSH key, turning on the 1Password SSH Agent, authenticating to GitHub with Touch ID, and signing Git commits.](https://www.youtube.com/embed/X3-TNJTJBWE) The following examples use GitHub to illustrate the SSH workflow from start to finish, but you can modify the steps to use with your favorite Git or cloud platform. ## Requirements > [tab] Mac > > 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) > 2. [Install and sign in to 1Password for Mac.](https://1password.com/downloads/mac) > 3. [Install the 1Password browser extension](https://1password.com/downloads/browser-extension) (optional).\\ > > Required to autofill SSH keys in your browser. > [tab] Windows > > 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) > 2. [Install and sign in to 1Password for Windows.](https://1password.com/downloads/windows) > 3. [Install the 1Password browser extension](https://1password.com/downloads/browser-extension) (optional).\\ > > Required to autofill SSH keys in your browser. > [tab] Linux > > 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) > > 2. [Install and sign in to 1Password for Linux.](https://1password.com/downloads/linux) > > 3. [Install the 1Password browser extension](https://1password.com/downloads/browser-extension) (optional).\\ > > Required to autofill SSH keys in your browser. > > > [!WARNING] > > > > The 1Password SSH agent doesn't work with [Flatpak](https://flatpak.org/) or Snap Store installations of 1Password. To use the SSH agent, choose a different method to [install 1Password for Linux](https://support.1password.com/install-linux/). > [!TIP] > > For the best experience when using the 1Password SSH Agent, you can configure [Touch ID](https://support.1password.com/touch-id-mac/), [Apple Watch](https://support.1password.com/apple-watch-mac/), [Windows Hello](https://support.1password.com/windows-hello/), or [system authentication](https://support.1password.com/system-authentication-linux/) to unlock 1Password and authenticate SSH key requests. ## Step 1: Generate an SSH key 1. Open and unlock the 1Password app, then navigate to your **Personal**, **Private**, or **Employee** vault. The name of this vault varies depending on your account type. 2. Select **New Item** > **SSH Key**. 3. Select **Add Private Key** > **Generate New Key**. 4. Select an SSH key type: [Ed25519 or RSA](/ssh/manage-keys/#supported-ssh-key-types), then select **Generate**. 5. When you're done, select **Save**. 1Password will generate your SSH key, which includes the private key, public key, and its fingerprint. ![Generating a new SSH Key item with the Ed25519 key type selected.](/static/img/ssh/github-generate-ssh-key.png) Learn more about [generating or importing SSH keys](/ssh/manage-keys/) and [which SSH keys you can use with the 1Password SSH Agent](/ssh/agent/#eligible-keys). ## Step 2: Upload your public key After you generate your SSH key, you can add the public key to your GitHub account. Visit the [GitHub SSH key settings page](https://github.com/settings/ssh/new) upload your public key using the 1Password browser extension or desktop app. > [tab] Browser extension > > 1. Select the **Title** or **Key** field on the GitHub settings page. If 1Password doesn't show a list of suggested items, select the 1Password icon in the field. > 2. Select the GitHub SSH key you just created. 1Password will automatically fill the public key and title in the corresponding fields. > 3. Select **Add SSH Key** on the settings page to save the key in your GitHub account. > > Your SSH key can now be used to authenticate with GitHub. > > For examples using other Git or cloud platforms, see [Autofill public keys](/ssh/public-key-autofill/). > > ![The GitHub SSH key settings page in a browser, with the Key field selected on the page and the GitHub SSH key item selected in the 1Password popup.](/static/img/ssh/add-public-key-github.png) > [tab] Desktop apps > > 1. Navigate to the GitHub SSH key you just created in 1Password and select it. > 2. Copy your public key from the item details, then paste it into the **Key** field on the GitHub settings page.\ > You can also use [Quick Access](https://support.1password.com/quick-access/) to find and copy your public key. > 3. Then select **Add SSH Key** on the settings page to save the key in your GitHub account. > > Your SSH key can now be used to authenticate with GitHub. > > For examples using other Git or cloud platforms, see [Autofill public keys](/ssh/public-key-autofill/). > > ![A GitHub SSH Key item selected in the 1Password desktop app, with the public key field selected and ready to copy.](/static/img/ssh/copy-public-key-github.png) ## Step 3: Turn on the 1Password SSH Agent The 1Password desktop app includes an SSH agent that, when turned on, runs in the background to handle authentication for your SSH clients. Follow these steps to turn on the SSH agent: > [tab] Mac > > 1. Open the 1Password app and select **1Password** > **Settings** from the menu bar, then select **Developer**. > 2. Select **Use the SSH Agent**, then choose whether you want to display SSH key names when you authorize connections. > 3. (Optional) [Adjust your authorization settings](/ssh/agent/authorization/#adjust-your-authorization-settings) for when and how often the SSH agent will ask you to approve SSH requests. > > ![The SSH agent developer settings in the 1Password desktop app, with both checkboxes selected and a badge at the top that shows the agent is running.](/static/img/ssh/turn-on-ssh-agent.png) > > If you previously turned off the SSH agent and would like to turn it back on, select the checkbox to **Use the SSH agent**. > > When you choose to display SSH key names when authorizing connections, it's easier for you to identify which key 1Password is requesting access to when authenticating a request from an SSH client. To display key names in authorization prompts, 1Password needs to [save the titles of your SSH Key items in local storage](/ssh/agent/security/#local-storage). To turn off this feature, deselect the checkbox to **Display key names when authorizing connections** in the Security section. > > To make sure the SSH agent keeps running, even when the 1Password app is closed: > > 1. Open the 1Password app and select **1Password** > **Settings** from the menu bar, then select **General**. > 2. Select the checkboxes to **Keep 1Password in the menu bar** and **Start at login**. > > ![The general settings page in the 1Password desktop app, with the checkboxes selected for the settings to keep the SSH agent running.](/static/img/ssh/keep-1password-running-mac.png) > [tab] Windows > > > [!WARNING] > > > > The 1Password SSH Agent only works with SSH clients that support [Microsoft OpenSSH.](https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_overview) For more information, see [SSH client compatibility](/ssh/agent/compatibility/). > > #### Check if the OpenSSH Authentication Agent service is installed and running > > Before you can turn on the SSH agent in 1Password, you'll need to check if the OpenSSH Authentication Agent service is installed: > > 1. Go to **Services** > **OpenSSH Authentication Agent** (press Win + R on your keyboard to open the Run window, type `services.msc` and press Enter or select **OK**). > 2. Look for the **OpenSSH Authentication Agent** in the list of services. > If you don't see the OpenSSH Authentication Agent in the list, skip ahead to the steps to [turn on the SSH agent in 1Password](/ssh/get-started/#turn-on-the-ssh-agent-in-1password). > If you do see the OpenSSH Authentication Agent in the list, continue with these steps to disable it from startup and make sure it's not running: > 3. Select **OpenSSH Authentication Agent** in the list of services and press Enter. > 4. In the "Startup type" menu, select **Disabled**. If the service status shows the agent is running, select **Stop**. > 5. Select **Apply** > **OK**. > > The 1Password SSH Agent can then take over and listen on the system-wide pipe at `\\.\pipe\openssh-ssh-agent`. > > #### Turn on the SSH agent in 1Password > > Follow these steps to turn on the SSH agent in 1Password: > > 1. Open the 1Password app, then select your account or collection at the top of the sidebar and select **Settings** > **Developer**. > 2. Select **Use the SSH Agent**, then choose whether or not you want to display SSH key names when you authorize connections. > 3. (Optional) [Adjust your authorization settings](/ssh/agent/authorization/#adjust-your-authorization-settings) for when and how often the SSH agent will ask you to approve SSH requests. > > ![The SSH agent developer settings in the 1Password desktop app, with both checkboxes selected and a badge at the top that shows the agent is running.](/static/img/ssh/turn-on-ssh-agent.png) > > If you previously turned off the SSH agent and would like to turn it back on, select the checkbox to **Use the SSH agent**. > > When you choose to display SSH key names when authorizing connections, it's easier for you to identify which key 1Password is requesting access to when authenticating a request from an SSH client. To display key names in authorization prompts, 1Password needs to [save the titles of your SSH Key items in local storage](/ssh/agent/security/#local-storage). To turn off this feature, deselect the checkbox to **Display key names when authorizing connections** in the Security section. > > To make sure the SSH agent keeps running, even when the 1Password app is closed: > > 1. Open 1Password, then select your account or collection at the top of the sidebar and select **Settings** > **General**. > 2. Select the checkbox to **Keep 1Password in the notification area**. > > ![The general settings page in the 1Password desktop app, with the checkboxes selected for the settings to keep the SSH agent running.](/static/img/ssh/keep-1password-running-mac.png) > [tab] Linux > > 1. Open the 1Password app, then select your account or collection at the top of the sidebar and select **Settings** > **Developer**. > 2. Select **Use the SSH Agent**, then choose whether or not you want to display SSH key names when you authorize connections. > 3. (Optional) [Adjust your authorization settings](/ssh/agent/authorization/#adjust-your-authorization-settings) for when and how often the SSH agent will ask you to approve SSH requests. > > ![The SSH agent developer settings in the 1Password desktop app, with both checkboxes selected and a badge at the top that shows the agent is running.](/static/img/ssh/turn-on-ssh-agent.png) > > If you previously turned off the SSH agent and would like to turn it back on, select the checkbox to **Use the SSH agent**. > > When you choose to display SSH key names when authorizing connections, it's easier for you to identify which key 1Password is requesting access to when authenticating a request from an SSH client. To display key names in authorization prompts, 1Password needs to [save the titles of your SSH Key items in local storage](/ssh/agent/security/#local-storage). To turn off this feature, deselect the checkbox to **Display key names when authorizing connections** in the Security section. > > To make sure the SSH agent keeps running, even when the 1Password app is closed: > > 1. Open 1Password, then select your account or collection at the top of the sidebar and select **Settings** > **General**. > 2. Select the checkbox to **Keep 1Password in the system tray**. > > ![The general settings page in the 1Password desktop app, with the checkboxes selected for the settings to keep the SSH agent running.](/static/img/ssh/keep-1password-running-mac.png) ## Step 4: Configure your SSH or Git client After you turn on the SSH agent in 1Password, you'll need to configure your SSH client to use the agent for authentication. > [tab] Mac > > Add the `IdentityAgent` snippet to your `~/.ssh/config` file: > > ```text theme={null} > Host * > IdentityAgent "~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock" > ``` > > If your `~/.ssh` folder or `config` file doesn't exist yet, create it first. > > You can also set the `SSH_AUTH_SOCK` environment variable in the shell where your SSH command runs: > > ```shell theme={null} > export SSH_AUTH_SOCK=~/Library/Group\ Containers/2BUA8C4S2C.com.1password/t/agent.sock > ``` > > For an agent path that's easier to type, you can optionally run the following command to create a symlink for `~/.1password/agent.sock`: > > ```shell theme={null} > mkdir -p ~/.1password && ln -s ~/Library/Group\ Containers/2BUA8C4S2C.com.1password/t/agent.sock ~/.1password/agent.sock > ``` > > Now your SSH clients will use the 1Password SSH Agent for all hosts. > > If you prefer to migrate to the 1Password SSH Agent gradually, you can configure your SSH clients to only use the SSH agent for one or more specific hosts, instead of all hosts. Learn more about [gradual migration](/ssh/agent/advanced/#gradual-migration). > > Some SSH clients don't support every configuration option that the `~/.ssh/config` file has to offer. Learn more about [SSH client compatibility](/ssh/agent/compatibility/). > > By default, OpenSSH servers are configured to limit the amount of authentication attempts for an incoming SSH connection. Learn more about how to avoid the [SSH server six-key limit](/ssh/agent/advanced/#ssh-server-six-key-limit). > [tab] Windows > > Additional configuration to use the SSH agent for authentication with your SSH clients isn't required. > > To use the SSH agent with Git, configure the [`core.sshCommand`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-coresshCommand) variable in your Git config to use Microsoft OpenSSH: > > ```text theme={null} > git config --global core.sshCommand "C:/Windows/System32/OpenSSH/ssh.exe" > ``` > > You can also manually edit your [`gitconfig` file](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup#:~:text=On%20Windows%20systems) to add the following: > > ```text theme={null} > [core] > sshCommand = C:/Windows/System32/OpenSSH/ssh.exe > ``` > > For the best Git experience with 1Password, install the latest version of [Git for Windows](https://gitforwindows.org/) (version `2.33` or later). > > If you're using Windows Subsystem for Linux (WSL), you can [use the 1Password SSH Agent with WSL](/ssh/integrations/wsl). > > By default, OpenSSH servers are configured to limit the amount of authentication attempts for an incoming SSH connection. Learn more about how to avoid the [SSH server six-key limit](/ssh/agent/advanced/#ssh-server-six-key-limit). > [tab] Linux > > Add the `IdentityAgent` snippet to your `~/.ssh/config` file: > > ```text theme={null} > Host * > IdentityAgent ~/.1password/agent.sock > ``` > > If your `~/.ssh` folder or `config` file doesn't exist yet, create it first. > > You can also set the `SSH_AUTH_SOCK` environment variable in the shell where your SSH command runs: > > ```shell theme={null} > export SSH_AUTH_SOCK=~/.1password/agent.sock > ``` > > Now your SSH clients will use the 1Password SSH Agent for all hosts. > > If you prefer to migrate to the 1Password SSH Agent gradually, you can configure your SSH clients to only use the SSH agent for one or more specific hosts, instead of all hosts. Learn more about [advanced use cases](/ssh/agent/advanced/#gradual-migration). > > Some SSH clients don't support every configuration option that the `~/.ssh/config` file has to offer. Learn more about [SSH client compatibility](/ssh/agent/compatibility/). > > By default, OpenSSH servers are configured to limit the amount of authentication attempts for an incoming SSH connection. Learn more about how to avoid the [SSH server six-key limit](/ssh/agent/advanced/#ssh-server-six-key-limit). ## Step 5: Run a command Now you're ready to start using the 1Password SSH Agent with GitHub. From your project directory, run: ```text theme={null} git pull ``` If you don't have a project available on GitHub where you can run `git pull` now, you can run this command instead to quickly test your GitHub SSH setup: ```text theme={null} ssh -T git@github.com ``` ## Step 6: Authorize the SSH request 1Password will ask you to allow your terminal or other SSH client to use your SSH key. You can approve this request using the authentication option indicated on the prompt (for example, Touch ID, Windows Hello, or your account password). If 1Password is locked, you'll also be prompted to unlock the app so the SSH agent can access your private keys. ![Authorization prompt showing a Touch ID icon.](/static/img/ssh/auth-prompt-touch-id.png) ![Authorization prompt showing that the 1Password account password needs to be entered.](/static/img/ssh/auth-prompt-account-password.png) ![Authorization prompt showing a Windows Hello icon.](/static/img/ssh/auth-prompt-windows-hello.png) After approving the request, you can continue using the same SSH key for that application without being prompted again until 1Password locks or quits. You can also adjust your authorization settings to prompt more or less frequently. To learn more about the authorization process and how to adjust when 1Password asks you to approve SSH requests, see [Authorize SSH requests with 1Password](/ssh/agent/authorization/). ## Learn more * [Authorize SSH requests with 1Password](/ssh/agent/authorization/) * [Manage SSH keys](/ssh/manage-keys/#generate-an-ssh-key) * [Autofill public keys](/ssh/public-key-autofill/) * [SSH client compatibility](/ssh/agent/compatibility/) * [Advanced use cases](/ssh/agent/advanced/) * [About 1Password SSH Agent security](/ssh/agent/security/) * [Use the 1Password SSH Agent with WSL](/ssh/integrations/wsl) * [Workflow: Secure your SSH & Git workflows](/get-started/secure-ssh-git-workflows) # Sign Git commits with SSH Source: https://www.1password.dev/ssh/git-commit-signing Set up Git to sign your commits with an SSH key stored in 1Password, and approve each signature with your fingerprint. Git version 2.34 and later supports signing commits and tags with SSH keys — no GPG key needed. This means you can use the [1Password SSH integration](/ssh/) to create new Git signing keys in seconds, and use them with your terminal apps and other [Git clients](/ssh/agent/compatibility/) without the private key ever leaving 1Password. You can also automatically configure Git commit signing with SSH in the 1Password app. When you sign your commits, they can be cryptographically verified using the SSH public keys associated with your [GitHub](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification), [GitLab](https://docs.gitlab.com/user/project/repository/signed_commits/ssh/#configure-git-to-sign-commits-with-your-ssh-key), or [Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/use-ssh-keys-to-sign-commits/) account. This ensures other people can verify that the changes were actually made by you. This is important because anyone with push rights to your repository can push new commits as any author, allowing them to impersonate others if commits aren't signed. [Learn how easy it is to use 1Password to sign your Git commits.](https://blog.1password.com/git-commit-signing/) ## Requirements Before you get started, you'll need to: 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux). 3. Update to Git 2.34.0 or later. 4. [Import or generate SSH keys in 1Password.](/ssh/manage-keys/) 5. [Set up the 1Password SSH Agent.](/ssh/get-started/#step-3-turn-on-the-1password-ssh-agent) ## Step 1: Configure Git commit signing with SSH To automatically configure Git commit signing with SSH globally: 1. Open the SSH key you want to use in your 1Password desktop app. 2. Select > **Configure Commit Signing**. 3. In the next window, select **Edit Automatically**. \ Or select **Copy Snippet**, then paste the snippet into your `~/.gitconfig` file manually. ![The Configure Git Commit Signing window showing options to edit your config file automatically or copy the configuration snippet manually.](/static/img/ssh/configure-git-commit-signing.png) You can also [configure SSH signing in a single repository](#configure-commit-signing-in-a-single-repository). 1Password will make the following changes to your Git config file: * Set `gpg.format` to `ssh`. * Set `user.signingkey` to the public key you chose to sign commits with. * Set `commit.gpgsign` to `true` so you don't need to include the `-S` flag with each commit. *(optional)* * Set `gpg.ssh.program` to the SSH signer binary provided by 1Password, so you don't have to set `SSH_AUTH_SOCK` yourself. *(optional)* > [!TIP] > > If you use WSL on a Windows machine, learn how to set up the [1Password WSL integration](/ssh/integrations/wsl) to authenticate SSH and Git commands and [sign your Git commits within WSL](/ssh/integrations/wsl#sign-git-commits-with-ssh). ## Step 2: Register your public key Now that you've configured SSH commit signing locally, you'll need to register your public key so that others can verify the authenticity of your commits. > [tab] GitHub > > To allow GitHub to verify your commits, visit the [GitHub SSH key settings](https://github.com/settings/ssh/new) to register your SSH key for commit signing. You can use the 1Password browser extension to automatically fill in the public key and key title. > > Make sure you set the "Key type" to `Signing key` to allow your SSH key to be used for signing commits. > > ![The GitHub form to add a new SSH key, with signing key selected.](/static/img/ssh/github-add-ssh-key.png) > [tab] GitLab > > To allow GitLab to verify your commits, visit the [GitLab SSH key settings](https://gitlab.com/-/user_settings/ssh_keys) to register your SSH key for commit signing. You can use the 1Password browser extension to automatically fill in the public key and key title. > > Make sure you set the "Usage type" to either `Authentication & Signing` or `Signing` to allow your SSH key to be used for signing commits. > > ![The GitLab form to add a new SSH key, with authentication and signing selected.](/static/img/ssh/gitlab-add-ssh-key.png) > [tab] Bitbucket > > To allow Bitbucket to verify your commits, visit the [Bitbucket SSH key settings](https://bitbucket.org/account/settings/ssh-keys/) to register your SSH key for commit signing. You can use the 1Password browser extension to automatically fill in the public key and key title. > > ![The Bitbucket form to add a new SSH key.](/static/img/ssh/bitbucket-add-ssh-key.png) > [tab] Locally > > To verify SSH signatures locally, you'll need to create an [allowed signers file](https://www.man7.org/linux/man-pages/man1/ssh-keygen.1.html#ALLOWED_SIGNERS) and configure Git to use it. > > You can choose to configure this globally, for example: > > ```shell theme={null} > touch ~/.ssh/allowed_signers > git config --global gpg.ssh.allowedSignersFile ~/.ssh/allowed_signers > ``` > > Or to tie it to a single repository, for example: > > ```shell theme={null} > touch .git/allowed_signers > git config --local gpg.ssh.allowedSignersFile .git/allowed_signers > ``` > > In the allowed signers file, add pairs of emails and public keys you'd like to trust: > > ```text allowed_signers theme={null} > wendy@appleseed.com ssh-ed25519 AAAAC3NzaC1IZDI1NTE5AAAAIFIUXAdv5sWOrfZFEPAW8liKjBW3sFxuaNITBWwtFKO > ``` > > You can share this file with others and could even consider checking it into Git, similar to a `CODEOWNERS` file. ## Step 3: Commit and push your code Now that you're all set up, you can commit some code: ``` git commit -m "Signing my first commit with SSH" ``` You'll be prompted to authorize your SSH key the same way you unlock the 1Password app (for example, with Touch ID or Windows Hello). ![A Mac terminal showing a git commit command, overlaid with a 1Password prompt asking to authorize the use of a commit signing key with Touch ID.](https://mintcdn.com/ab-634991b8/2GuQWN9fVwUxVlhr/static/img/ssh/git-sign.png?fit=max\&auto=format\&n=2GuQWN9fVwUxVlhr\&q=85\&s=63f86e8e340c83a4e1fedb36c48fdd8d) If you've chosen to use the same key to sign as you do to push and pull, you can now also push without requiring additional authorization: ``` git push ``` ## Step 4: Verify your commit signature > [tab] GitHub > > If you look at your commit history on GitHub, you should see the `Verified` badge show up on your SSH-signed commits. If you select it, you can see the SSH key used to sign it. > > ![A GitHub commit marked with the verified badge and showing the SSH public key used to sign.](/static/img/ssh/github-verified.png) > [tab] GitLab > > If you look at your commit history on GitLab, you should see the `Verified` badge show up on your SSH-signed commits. If you select it, you can see the SSH key used to sign it. > > ![A GitLab commit marked with the verified badge and showing the SSH public key used to sign.](/static/img/ssh/gitlab-verified.png) > [tab] Bitbucket > > If you look at your commit history on Bitbucket, you should see a verified checkmark show up on your SSH-signed commits. If you select it, you can see the SSH key used to sign it. > > ![A Bitbucket commit marked with the verified badge and showing the SSH public key used to sign.](/static/img/ssh/bitbucket-verified.png) > [tab] Locally > > To verify commits locally, run the following command: > > ```shell theme={null} > git log --show-signature > ``` ## Advanced configuration ### Configure commit signing in a single repository You can enable Git commit signing with SSH for specific repositories or directories instead of globally. To do this: 1. Open the SSH key you want to use in your 1Password desktop app. 2. Select > **Configure Commit Signing**. 3. In the next window, select **Copy Snippet**. 4. Paste the snippet in the repository's `/.git/config` file instead of the global `~/.gitconfig` file. ### Configure multiple commit signing setups If you want to configure multiple commit signing setups, you can use the `includeIf` directive in your `~/.gitconfig`. For example, to use an SSH commit signing setup with 1Password as your default configuration and a non-1Password GPG setup for the `/work/acme` subdirectory: ```toml ~/.gitconfig theme={null} [user] name = Wendy Appleseed email = wendy@appleseed.com signingkey = ssh-ed25519 AAAAC3NzaC1IZDI1NTE5AAAAIFIUXAdv5sWOrfZFEPAW8liKjBW3sFxuaNITBWwtFKO [commit] gpgsign = true [gpg] format = ssh [gpg "ssh"] program = /Applications/1Password.app/Contents/MacOS/op-ssh-sign [includeIf "gitdir:~/work/acme/"] path = ~/work/acme/.gitconfig ``` ```toml ~/work/acme/.gitconfig theme={null} [user] email = wendy.appleseed@acme.com signingkey = 6A40D13BBB936F443084E8C9292E4F983136B860 [gpg] format = openpgp ``` In this example, every repository under `~/work/acme` will use the GPG configuration, while the SSH configuration will be used everywhere else. ### Configure commit signing in remote environments You can [set up SSH agent forwarding](/ssh/agent/forwarding) to authenticate Git requests and sign commits in remote environments, like from a [cloud development environment](/ssh/agent/forwarding/#cde) or [remote workstation](/ssh/agent/forwarding/#remote-workstation). ## Get help ### If Git says that SSH is an unsupported format If you see the following error message, then your Git version may be outdated: ```text theme={null} error: unsupported value for gpg.format: ssh ``` Support for SSH commit signing was added to Git in version **2.34**. Run this command to check your Git version: ```shell theme={null} git --version ``` It's common for operating systems and Git GUI clients to ship with an outdated version of Git out of the box. To install a more up-to-date version, see the [Git install docs.](https://git-scm.com/downloads) In the case of Git GUI clients, check the app preferences to see if they allow you to change the Git binary to a more up-to-date version. ### If your commits fail after you change your Git configuration If you see one of the following error messages, it's likely related to your `user.signingkey` value. Make sure that's set to a valid SSH public key. ```text theme={null} fatal: failed to write commit object ``` ```text theme={null} could not deserialize public key ``` ```text theme={null} No such file or directory ``` If your `user.signingkey` is set correctly in your `~/.gitconfig` file, check the value at the repository level by running the following command from your repo's directory: ```shell theme={null} git config user.signingkey ``` Example of a correct output: ```text theme={null} ssh-ed25519 AAAAC3NzaC1IZDI1NTE5AAAAIFIUXAdv5sWOrfZFEPAW8liKjBW3sFxuaNITBWwtFKO ``` If the signing key is not the SSH public key you've configured in your `~/.gitconfig`, you may have a [local override](#local-git-overrides) in your repository. ### If you see errors related to the allowed signers file If you see the following error message, make sure you've properly configured your [allowed signers file](#step-2-register-your-public-key): ```text theme={null} error: gpg.ssh.allowedSignersFile needs to be configured and exist for ssh signature verification ``` This error should not block you from browsing your commit log - it just prevents you from locally verifying the commit authenticity. ### If your SSH-signed commit doesn't get verified by Git, GitHub, GitLab, and/or Bitbucket If you believe you've signed your commits through SSH but they're not showing up as verified, there are a few things that could be happening: #### Commit author email mismatch Commit signatures will only show up as verified if the registered public key matches the commit author email. Make sure it matches the email you've registered on [GitHub](https://github.com/settings/emails), [GitLab](https://gitlab.com/-/user_settings/profile), or [Bitbucket](https://id.atlassian.com/manage-profile/profile-and-visibility) in your allowed signers file. > [!NOTE] > > **Case-sensitive email addresses** > > If your signed commits are verified locally but aren't verified on GitLab.com or Bitbucket, check for any case mismatches in your email address. > > For example, if the email address in your GitLab or Bitbucket account is `wendy@appleseed.com` but your `~/.gitconfig` file uses `Wendy@appleseed.com`, your commits will show as unverified in those accounts. If you have the correct email in your `~/.gitconfig`, check that the settings have correctly propagated down to the repository level as well. To validate this, run the following command from your repo's directory: ```shell theme={null} git config user.email ``` If this is not the email you've configured in your `~/.gitconfig`, you may have a [local override](#local-git-overrides) in your repository. #### Misconfigured public key On GitHub, visit the [SSH key settings](https://github.com/settings/keys) and check that the key you've locally configured as `user.signingkey` shows up under "Signing keys". On GitLab, visit the [SSH key settings](https://gitlab.com/-/user_settings/ssh_keys) and check that the key you've locally configured as `user.signingkey` shows up under "Your SSH keys". On Bitbucket, visit the [SSH key settings](https://bitbucket.org/account/settings/ssh-keys/) and check that the key you've locally configured as `user.signingkey` shows up under "SSH keys". For a local allowed signers file, make sure your public key is present and matches your email. #### Unsupported Git client Most Git clients support SSH commit signing out of the box, but there are [a few exceptions](/ssh/agent/compatibility/). Even though you may have configured Git correctly, a Git client that doesn't support SSH commit signing will leave your commit unsigned. Make sure to also [check that you're on the latest version of your Git client](#git-error-ssh-unsupported-format). #### Local Git overrides Even though you may have configured your `~/.gitconfig` well, make sure to also check that the settings have correctly propagated down to the repository level. To validate this, run the following command from your repo's directory: ```shell theme={null} cat << EOF gpg.format: $(git config gpg.format) user.signingkey: $(git config user.signingkey) gpg.ssh.program: $(git config gpg.ssh.program) commit.gpgsign: $(git config commit.gpgsign) EOF ``` Example of a correct output: ```text theme={null} gpg.format: ssh user.signingkey: ssh-ed25519 AAAAC3NzaC1IZDI1NTE5AAAAIFIUXAdv5sWOrfZFEPAW8liKjBW3sFxuaNITBWwtFKO gpg.ssh.program: /Applications/1Password.app/Contents/MacOS/op-ssh-sign commit.gpgsign: true ``` If this output does not match up with what you've configured in your `~/.gitconfig`, unset the local values: ```shell theme={null} git config --local --unset gpg.format git config --local --unset user.signingkey git config --local --unset gpg.ssh.program git config --local --unset commit.gpgsign ``` If you still end up with the wrong value somewhere, you can check where it originates from using the `--show-origin` flag: ```shell theme={null} cat << EOF gpg.format: $(git config --show-origin gpg.format) user.signingkey: $(git config --show-origin user.signingkey) gpg.ssh.program: $(git config --show-origin gpg.ssh.program) commit.gpgsign: $(git config --show-origin commit.gpgsign) EOF ``` ## Learn more * [Manage SSH keys](/ssh/manage-keys/#generate-an-ssh-key) * [Autofill public keys](/ssh/public-key-autofill/) * [About 1Password SSH Agent security](/ssh/agent/security/) * [Workflow: Secure your SSH & Git workflows](/get-started/secure-ssh-git-workflows) # Use the 1Password SSH agent with WSL Source: https://www.1password.dev/ssh/integrations/wsl The 1Password Windows Subsystem for Linux (WSL) integration allows you to authenticate SSH and Git commands and sign your Git commits within WSL using the 1Password SSH agent running on your Windows host. The 1Password integration supports both WSL 1 and WSL 2. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. [Install and sign in to 1Password for Windows](https://1password.com/downloads/windows). 3. [Import or generate SSH keys in 1Password.](/ssh/manage-keys/) 4. [Set up the 1Password SSH agent](/ssh/get-started/) on your Windows host and make sure it's running. 5. [Install Windows Subsystem for Linux on Windows](https://learn.microsoft.com/windows/wsl/install) with your preferred Linux distribution. To use [SSH Git commit signing with the 1Password WSL integration](#sign-git-commits-with-ssh), you'll also need: * Git 2.34.0 or later. * A 64-bit version of Windows 10 or later. Arm-powered Windows devices aren't supported. ## How the integration works With WSL, you can [run Windows tools from the command line](https://learn.microsoft.com/windows/wsl/filesystems#run-windows-tools-from-linux), such as the Windows OpenSSH client (`ssh.exe`). The 1Password WSL integration leverages the [interoperability](https://learn.microsoft.com/windows/wsl/filesystems#interoperability-between-windows-and-linux-commands) built into WSL to forward SSH requests to the 1Password SSH agent on Windows. Instead of forwarding SSH *agent* requests, like with standard OpenSSH agent forwarding, you can effectively forward the entire SSH request from WSL to the `ssh.exe` process running on Windows. The `ssh.exe` process then uses the 1Password SSH agent on your Windows host to authenticate the request. This also means that any [changes to your SSH configuration](/ssh/agent/advanced) need to be made in your Windows `%USERPROFILE%/.ssh/config` file, rather than the file on your WSL instance. ## Forward an SSH request 1. Check if the 1Password SSH agent is running **on your Windows host** with the following command: ```powershell theme={null} ssh-add.exe -l #code-result 256 SHA256:2zmxMpLy5MeIx18pBUkumptKkKinlghygOvV6URe8QI Git Authentication Key (ED25519) ``` If the agent is running, a list with one or more SSH keys will be returned. These are the SSH keys you stored in 1Password that are available to use with the agent for SSH requests. 2. Check if WSL is forwarding SSH requests successfully by running the following command **in your WSL instance**: ```shell theme={null} ssh-add.exe -l #code-result 256 SHA256:2zmxMpLy5MeIx18pBUkumptKkKinlghygOvV6URe8QI Git Authentication Key (ED25519) ``` You should see the same list of SSH keys returned as you did when you ran the command on your Windows host. If you do, then WSL is forwarding your SSH requests to your Windows host.\ [Get help](#error-command-not-found) if you don't see your SSH key(s) listed when you run the `ssh-add.exe -l` command. 3. If you see your SSH key(s) listed in WSL, try to run an SSH request, replacing `ssh` with `ssh.exe` in your command. For example: ```shell theme={null} ssh.exe -T git@github.com ``` You should see a prompt from 1Password to authorize the SSH request: ![SSH authorization prompt for WSL.](/static/img/ssh/wsl-auth-prompt.png) You can now use the 1Password SSH agent to forward SSH requests between your Windows host and WSL instance. ## Configure Git to use `ssh.exe` To use the 1Password SSH agent to authenticate Git commands in WSL, you can configure Git to use `ssh.exe` as the `core.sshCommand`. To set this variable globally, run the following command in WSL: ```shell theme={null} git config --global core.sshCommand ssh.exe ``` ## Sign Git commits with SSH > [!NOTE] > > 1Password for Windows 8.11.18 and later uses a new [MSIX installer](https://support.1password.com/cs/1password-msix-installer/), which automatically [updates the app data path](#error-cannot-run). If you set up the SSH agent to authenticate Git commands in WSL prior to version 8.11.18, you'll need to follow the steps below to configure Git commit signing again. With Git configured to use `ssh.exe`, you can also use the integration to sign Git commits from WSL. To configure Git commit signing with SSH globally in WSL: 1. On your Windows host, open the 1Password app, then open the SSH key you want to use. 2. Select > **Configure Commit Signing**. 3. In the next window, select the checkbox to **Configure for Windows Subsystem for Linux (WSL)**, then select **Copy Snippet**. 4. In your WSL instance, paste the snippet into your `~/.gitconfig` file. ![The Configure Git Commit Signing window showing the checkbox to configure for WSL and the configuration snippet.](/static/img/ssh/configure-git-commit-signing-wsl.png) You can also [configure SSH signing in a single repository](/ssh/git-commit-signing#configure-commit-signing-in-a-single-repository). 1Password will make the following changes to your Git config file: * Set `gpg.format` to `ssh`. * Set `user.signingkey` to the public key you chose to sign commits with. * Set `commit.gpgsign` to `true` so you don't need to include the `-S` flag with each commit. *(optional)* * Set `gpg.ssh.program` to the SSH signer binary provided by 1Password. After you set up Git commit signing on WSL, you can use the same steps as your Windows host to test the configuration. [Register your public key](/ssh/git-commit-signing/#step-2-register-your-public-key), then [commit some code](/ssh/git-commit-signing/#step-3-commit-and-push-your-code) and [verify your commit is signed](/ssh/git-commit-signing#step-4-verify-your-commit-signature). ## Optional: Add an alias for SSH commands If you plan to use the 1Password SSH agent on your Windows host to authenticate SSH requests other than Git, you can optionally [create aliases in your Bash profile](https://linux.die.net/Bash-Beginners-Guide/sect_03_05.html) to use `ssh` and `ssh-add` on the command line in place of `ssh.exe` and `ssh-add.exe`. This isn't required, but it can be convenient to use the same SSH commands across all your platforms. In your `~/.bashrc` or `~/.bash_aliases` file, add the following aliases: ```shell theme={null} alias ssh='ssh.exe' alias ssh-add='ssh-add.exe' ``` ## Authorization model The 1Password SSH agent uses the same [authorization model](/ssh/agent/security#authorization-model) with the WSL integration as it does on other platforms. When you approve an SSH key request for a WSL session, only the current session is authorized to use that key. If you open a new WSL session or tab, you'll be prompted to approve the SSH request again. [Learn more about the 1Password SSH agent authorization model.](/ssh/agent/security#authorization-model) ## Troubleshooting ### Error: `command not found` If you see a `command not found` error when you run the `ssh-add.exe -l` command in WSL, OpenSSH may not be in your `PATH`. Try to run the command again using the full executable path: ```shell theme={null} /mnt/c/Windows/System32/OpenSSH/ssh-add.exe -l ``` If you still see an error, check if the [interoperability setting](https://learn.microsoft.com/windows/wsl/wsl-config#interop-settings) (`[interop]`)is turned on in your WSL config file. If it is, the entry will look like this: ```text theme={null} [interop] enabled = true ``` If you see `enabled = false` instead, set the `enabled` value to `true`. ### Error: `cannot run` 1Password for Windows 8.11.18 and later uses an [MSIX installer](https://support.1password.com/cs/1password-msix-installer/), which updates the app data path previously used by the EXE installer. If you configured the SSH agent to authenticate Git commands in WSL using an earlier version of the app, you may see the following error message: ``` fatal: cannot run /mnt/c/Users//AppData/Local/1Password/app/8/op-ssh-sign-wsl: No such file or directory ``` To fix the issue, you'll need to [reconfigure Git commit signing for WSL](#sign-git-commits-with-ssh). This will add the updated path to your `.gitconfig` file. ```text Deprecated path (8.11.16 and earlier) theme={null} /mnt/c/Users//AppData/Local/1Password/app/8/op-ssh-sign-wsl ``` ```text New path (8.11.18 and later) theme={null} /mnt/c/Users//AppData/Local/Microsoft/WindowsApps/op-ssh-sign-wsl.exe ``` ## Learn more * [Autofill public keys](/ssh/public-key-autofill/) * [Manage SSH keys](/ssh/manage-keys/#generate-an-ssh-key) * [Sign Git commits](/ssh/git-commit-signing) * [Workflow: Secure your SSH & Git workflows](/get-started/secure-ssh-git-workflows) # Manage SSH keys Source: https://www.1password.dev/ssh/manage-keys You can use 1Password to manage all your SSH keys. [Generate SSH Key items](#generate-an-ssh-key) – with public keys, fingerprints, and private keys – right in 1Password. And if you have existing SSH keys, you can [import them into 1Password](#import-an-ssh-key). You can also [export your SSH keys](#export-an-ssh-key) from 1Password at any time. > [!TIP] > > If you manage multiple SSH keys and you want to use them with the [1Password SSH Agent](/ssh/agent/), learn more about how to avoid the [SSH server six-key limit](/ssh/agent/advanced/#ssh-server-six-key-limit). ## Requirements Before you can use 1Password to manage your SSH keys, you'll need to: 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux). 3. (Optional) [Install 1Password CLI](/cli/get-started#step-1-install-1password-cli) `2.20.0` or later.\ Required to create SSH keys using 1Password CLI. ## Generate an SSH key Generate an SSH key in the 1Password desktop apps or with 1Password CLI to use anywhere you need one. > [tab] Desktop apps > > 1. Open and unlock the 1Password app, then navigate to your [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 in the sidebar. \\ > > If you've [configured the SSH agent](/ssh/agent#configuration) for any shared or custom vaults, you can generate your SSH key in one of those vaults instead. > 2. Select **New Item**, then select **SSH Key**. > 3. Select **Add Private Key** > **Generate a New Key**. > 4. Choose a [key type](#supported-ssh-key-types), then select **Generate**. > 5. You can edit the name of your key and make any other changes. When you're done, select **Save**. > > ![The 1Password save dialog for an SSH Key item with the option to generate an Ed25519 key type selected.](/static/img/ssh/github-generate-ssh-key.png) > [tab] 1Password CLI > > 1. Open the terminal and [sign in](/cli/get-started/#step-3-enter-any-command-to-sign-in) to your 1Password account. > > 2. To generate an SSH key, run: > > ```shell theme={null} > op item create --category ssh --title "My SSH Key" > ``` > > 1Password CLI will generate an [Ed25519](#ed25519) key by default. Learn how to [create an RSA key](/cli/ssh-keys/#generate-an-ssh-key) instead. > > 3. After you run the command, 1Password CLI will generate an SSH key and save it as a new item in 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, then will print the key to stdout with the private key redacted.\ > SSH keys are saved in your Personal, Private, or Employee vault by default. > > See the full [1Password CLI documentation](/cli/ssh-keys/) for more information about how to manage your SSH keys on the command line. ## Import an SSH key If you have an SSH key you want to save in 1Password, you can import it. 1. Open and unlock the 1Password desktop app, then navigate to your [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 in the sidebar. \ If you've [configured the SSH agent](/ssh/agent#configuration) for any shared or custom vaults, you can generate your SSH key in one of those vaults instead. 2. Select **New Item** > **SSH Key**. 3. Select **Add Private Key** > **Import a Key File**, then navigate to the location of the SSH key you want and select **Import**. You can also drag and drop your SSH key file directly into the new SSH item or paste it from your clipboard. 4. If your SSH key is encrypted with a passphrase, enter the passphrase and select **Decrypt**. You'll only need to enter the passphrase once. After you import the SSH key into 1Password, it'll be encrypted according to the [1Password security model](https://support.1password.com/1password-security/#encryption). 5. When you're done, select **Save**. ![A new SSH Key item with Import a Key File selected.](/static/img/ssh/github-generate-ssh-key.png) > [!TIP] > > **Is your passphrase saved in 1Password?** > > If the passphrase for your SSH key is already saved in 1Password, use [Quick Access](https://support.1password.com/quick-access/) to find and copy it without needing to switch context. > > ![Use Quick Access to find and copy the passphrase for your SSH key.](https://mintcdn.com/ab-634991b8/2GuQWN9fVwUxVlhr/static/img/ssh/copy-ssh-passphrase-quick-access.png?fit=max\&auto=format\&n=2GuQWN9fVwUxVlhr\&q=85\&s=c4e569e699e141911d31e562067a32a8) ### Key import errors If you see one of the error messages below when you import an SSH key in 1Password, check if there's an issue with the type of key, the file format, or the encryption: > [accordion] If you see a message that your SSH key isn't supported > > If you see a message that your SSH key isn't supported, make sure you're importing a [supported Ed25519 or RSA (2048, 3072, or 4096-bit) key](/ssh/manage-keys/#supported-ssh-key-types). Other key lengths and other key types, such as **DSA** or **ECDSA** keys, aren't supported. > > To check the key type and bit length, run the following command: > > ```shell theme={null} > ssh-keygen -l -f > ``` > > RSA keys also require a minimum public exponent of **65,537** to meet [NIST standards.](https://csrc.nist.gov/pubs/sp/800/78/5/final) RSA keys with a public exponent less than 65,537 aren't supported. > To check the size of the public exponent for your key, run the following command: > > ```shell theme={null} > openssl rsa -text -in | grep publicExponent > ``` > [accordion] If you see a message that your SSH key file couldn't be read > > If you see a message that your SSH key file couldn't be read, make sure the key file is in a supported format. 1Password supports **PKCS#1**, **PKCS#8**, and **OpenSSH** formats. Keys that use a different file format, such as PuTTYgen `.ppk`, aren't supported. > [accordion] If you see a message that your SSH key couldn't be decrypted > > If you see a message that your SSH key couldn't be decrypted, it could be that it's encrypted with an unsupported and outdated cipher such as **RC4**. You can re-encrypt your key file so that it uses a more modern algorithm and then try importing it again. To do this, run the following command: > > ```shell theme={null} > ssh-keygen -p -f path/to/your/key > ``` If you still can't import your SSH key, you can use 1Password to [generate a new SSH key](/ssh/manage-keys/#generate-an-ssh-key) using the latest standards. ## View available SSH keys In the 1Password desktop app, select **Developer** in the sidebar, then select **View SSH agent**. The **Available SSH Keys** list shows SSH keys you've saved in 1Password that are [available to use with the SSH agent](/ssh/agent/#eligible-keys). * Select **View details** to open an SSH Key item in 1Password. * Select **Show all SSH keys** to see a list of all the SSH keys you've saved in 1Password. * Select **New SSH Key** to [generate](https://1password.dev/ssh/manage-keys#generate-an-ssh-key) a new SSH key or [import](https://1password.dev/ssh/manage-keys#import-an-ssh-key) an existing key into 1Password. ![The list of available SSH keys in the 1Password app.](https://mintcdn.com/ab-634991b8/dzX4i4DKMioaV1IG/static/img/ssh/available-ssh-keys.png?fit=max\&auto=format\&n=dzX4i4DKMioaV1IG\&q=85\&s=96dc42193ba495035ce4f605b0ffdc17) If you use [multiple accounts](https://support.1password.com/multiple-accounts/) in the 1Password app, you may see "Key name unavailable" for an SSH key saved in a locked account. To show the key name, select **Unlock account** or turn on **Display key names when authorizing connections** in the [Developer](onepassword://settings/developers) settings. ## Track SSH Agent activity You can track SSH and Git activity authenticated with the 1Password SSH Agent, including the command, when it was run, requests made from apps running in the background, and the SSH key that was used. To see your 1Password SSH Agent activity log: 1. Open and unlock the 1Password desktop app. 2. Select **Developer** in the sidebar. 3. Select **View SSH Agent**, then select the **Activity** tab. ![The SSH Agent activity log in the SSH Agent page of the 1Password app.](https://mintcdn.com/ab-634991b8/dzX4i4DKMioaV1IG/static/img/ssh/ssh-activity-log-bookmark.png?fit=max\&auto=format\&n=dzX4i4DKMioaV1IG\&q=85\&s=26ac5477b4ce43a3bed7f5de179c765c) You'll see a table with your recent 1Password SSH Agent activity. Your activity log data is encrypted on your device. Older entries get purged regularly, and you can manually clear your activity log data at any time. If you don’t want to use activity logging, turn off **Record and display activity** in the [1Password Developer settings](onepassword://settings/developers). ## Export an SSH key You can export a private SSH key from 1Password at any time. 1. Open and unlock the 1Password desktop app. 2. Choose the SSH key you want to export, then select the private key field. 3. Choose the export format you need: **OpenSSH** or **PKCS#8**. If you imported a PKCS#1-formatted key into 1Password, you will also have the option to export that key in **PKCS#1** format. 4. Choose how you want to export your private key: * To encrypt your exported private key (OpenSSH format only), enter a passphrase, then select **Copy Encrypted Key** or **Download Encrypted Key**. * To export your private key in plaintext, leave the passphrase field empty (if there is one), then select **Copy Unencrypted Key** or **Download Unencrypted Key**. ![A GitHub SSH key item with the private key field highlighted to show the Export option.](/static/img/ssh/export-private-key.png) ![The export dialog for a private key with an empty passphrase field and copy and download buttons.](https://mintcdn.com/ab-634991b8/2GuQWN9fVwUxVlhr/static/img/ssh/choose-export-format.png?fit=max\&auto=format\&n=2GuQWN9fVwUxVlhr\&q=85\&s=715c023d6edbaf1f30f111bf0afb3a2b) > [!WARNING] > > **Keep your private keys safe** > > 1Password can't protect SSH keys that you store outside of your account. If you need to export a private key, we recommend you save it in a secure location. Don't store unencrypted private keys on disk. ## Share a public key 1Password will automatically generate the public key and fingerprint for each private key you create so you can share it with the services and people who need it. You can copy or download the public key of an SSH key in the right format every time, and you can use the fingerprint to compare and identify your keys across all your services. For platforms that let you provide public keys in the browser (often found in an SSH Key settings panel), you can use 1Password in your browser to [fill your public key](/ssh/public-key-autofill/). You can also copy your public key from the item view in 1Password and share it where needed, or use [Quick Access](https://support.1password.com/quick-access/) to find your public key even faster without needing to switch context. ![Copy or download your public key to share it with others.](/static/img/ssh/share-public-key.png) ## Supported SSH key types 1Password supports the following key types, formats, and encryption algorithms: * **Key types**: [Ed25519](#ed25519) and [RSA](#rsa) (2048, 3072, and 4096-bit) * **Formats**: PKCS#1, PKCS#8, and OpenSSH * **Encryption**: AES and 3DES (all supported key formats), and ChaCha20-Poly1305 (OpenSSH format only) ### Ed25519 Ed25519 is the fastest and most secure key type available today and is the option recommended by most Git and cloud platforms. Ed25519 is the default suggestion when you generate a new SSH key in 1Password and the key is automatically set to 256 bits. The Ed25519 key type was first introduced in 2014 with [OpenSSH 6.5.](https://www.openssh.com/releasenotes.html) If you need to connect to an older server that isn't using OpenSSH 6.5 or later, an Ed25519 key won't work. ### RSA RSA is one of the oldest key types available and is compatible with most servers, including older ones. Compared to Ed25519, RSA is considerably slower, particularly with decryption, and is only considered secure if it's 2048 bits or longer. 1Password supports 2048-bit, 3072-bit, and 4096-bit RSA keys. ## View SSH keys in 1Password 7 > [!WARNING] > > Starting in early 2027, 1Password 7 will be retired. If you continue to use 1Password 7 after this time, it'll no longer reflect any changes you make in your 1Password account. > > Learn how to [upgrade to 1Password 8](https://support.1password.com/upgrade/?mac) to avoid any disruptions to your 1Password experience. Generating, importing, and sharing SSH keys requires 1Password 8. Any SSH keys that you generate or import can be viewed and copied in the 1Password 7 apps on your other devices. Make sure you're using an [updated version](https://support.1password.com/update-1password/) of 1Password 7 to view or copy your public or private keys. ## Learn more * [SSH client compatibility](/ssh/agent/compatibility/) * [Autofill public keys](/ssh/public-key-autofill/) * [About 1Password SSH Agent security](/ssh/agent/security/) * [Workflow: Secure your SSH & Git workflows](/get-started/secure-ssh-git-workflows) # Autofill public keys Source: https://www.1password.dev/ssh/public-key-autofill To use the SSH keys you saved in 1Password to connect to your favorite Git or cloud platforms, you'll need to provide your public key to those services. [Use 1Password in your browser](https://support.1password.com/getting-started-browser/) to fill your public key on those sites, anywhere you see the 1Password icon. Or copy your public key from the SSH key item in 1Password and paste it into the public key area of the website. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux). 3. [Install the 1Password browser extension.](https://1password.com/downloads/browser-extension) 4. [Import or generate SSH keys in 1Password.](/ssh/manage-keys/) ## AWS CodeCommit Visit the **Security credentials** tab of your [IAM user](https://console.aws.amazon.com/iam/home#/users) to add a new key: ![AWS CodeCommit SSH key settings](https://mintcdn.com/ab-634991b8/2GuQWN9fVwUxVlhr/static/img/ssh/autofill-aws-codecommit.png?fit=max\&auto=format\&n=2GuQWN9fVwUxVlhr\&q=85\&s=6abce75251bc64e96b41b0df65f1b7a7) ## Azure DevOps Visit the **SSH public keys** page of your user settings to add a new key: ![Azure DevOps SSH key settings](https://mintcdn.com/ab-634991b8/MKy6sgNGqMk-yGDS/static/img/ssh/autofill-azure-devops.png?fit=max\&auto=format\&n=MKy6sgNGqMk-yGDS\&q=85\&s=5dd34808700d450cbabdfe2ccd5a9720) ## Bitbucket Visit the [Bitbucket SSH key settings](https://bitbucket.org/account/settings/ssh-keys/) to add a new key: ![Bitbucket SSH key settings](https://mintcdn.com/ab-634991b8/2GuQWN9fVwUxVlhr/static/img/ssh/autofill-bitbucket.png?fit=max\&auto=format\&n=2GuQWN9fVwUxVlhr\&q=85\&s=45082e2f81cbd73ad136e1d51c338610) It also works for [access keys.](https://support.atlassian.com/bitbucket-cloud/docs/add-access-keys/) ## DigitalOcean Visit your [account security settings](https://cloud.digitalocean.com/account/security) to add a new key: ![DigitalOcean SSH key settings](https://mintcdn.com/ab-634991b8/MKy6sgNGqMk-yGDS/static/img/ssh/autofill-digitalocean.png?fit=max\&auto=format\&n=MKy6sgNGqMk-yGDS\&q=85\&s=1ce6d4a76b9b22d314baf6047a93ca7c) ## GitHub Visit the [GitHub SSH key settings](https://github.com/settings/ssh/new) to add a new key: ![GitHub SSH key settings](https://mintcdn.com/ab-634991b8/2GuQWN9fVwUxVlhr/static/img/ssh/autofill-github.png?fit=max\&auto=format\&n=2GuQWN9fVwUxVlhr\&q=85\&s=b42f58a736bb2aa1ea08dc8a42876b5f) You can also autofill [deploy keys.](https://docs.github.com/en/developers/overview/managing-deploy-keys#deploy-keys) ## GitLab Visit the [GitLab SSH key settings](https://gitlab.com/-/user_settings/ssh_keys) to add a new key: ![GitLab SSH key settings](https://mintcdn.com/ab-634991b8/2GuQWN9fVwUxVlhr/static/img/ssh/autofill-gitlab.png?fit=max\&auto=format\&n=2GuQWN9fVwUxVlhr\&q=85\&s=4d7a36557038f45288b2fa9131bd7244) It also works for [deploy keys.](https://docs.gitlab.com/user/project/deploy_keys/) ## Gitpod Visit the [Gitpod SSH key settings](https://gitpod.io/keys) to add a new key: ![Gitpod SSH key settings](https://mintcdn.com/ab-634991b8/2GuQWN9fVwUxVlhr/static/img/ssh/autofill-gitpod.png?fit=max\&auto=format\&n=2GuQWN9fVwUxVlhr\&q=85\&s=6a0f2343738c44d16cb30c43e62b35d0) ## Google Compute Engine Visit the [Google Compute Engine metadata settings](https://console.cloud.google.com/compute/metadata?tab=sshkeys) to add a new key: ![Google Compute Engine metadata settings SSH keys](https://mintcdn.com/ab-634991b8/2GuQWN9fVwUxVlhr/static/img/ssh/autofill-gce.png?fit=max\&auto=format\&n=2GuQWN9fVwUxVlhr\&q=85\&s=4b3202d2170f3691545edb2e55c3dadd) ## IBM Cloud (VPC) Visit the [**SSH keys** section](https://cloud.ibm.com/vpc-ext/compute/sshKeys) in the VPC Infrastructure console to add a new key: ![IBM Cloud SSH Keys list (VPC)](https://mintcdn.com/ab-634991b8/2GuQWN9fVwUxVlhr/static/img/ssh/autofill-ibm-cloud-vpc.png?fit=max\&auto=format\&n=2GuQWN9fVwUxVlhr\&q=85\&s=984698f2419fddb586ada14226ab5f5f) ## IBM Cloud (Classic) Visit the [**SSH keys** section](https://cloud.ibm.com/gen1/infrastructure/ssh-keys) in the Classic Infrastructure console to add a new key: ![IBM Cloud SSH Keys list (Classic)](https://mintcdn.com/ab-634991b8/2GuQWN9fVwUxVlhr/static/img/ssh/autofill-ibm-cloud-classic.png?fit=max\&auto=format\&n=2GuQWN9fVwUxVlhr\&q=85\&s=7a29d2e8ee51930503ce89b4ac16f46f) ## JetBrains Space Visit the **Git Keys** tab in your Space profile settings to add a new key: ![JetBrains Space Git Keys settings](https://mintcdn.com/ab-634991b8/MKy6sgNGqMk-yGDS/static/img/ssh/autofill-jetbrains-space.png?fit=max\&auto=format\&n=MKy6sgNGqMk-yGDS\&q=85\&s=6aeb85c9be3304ccbd3141f7ab0c9a28) ## Linode Visit the [**SSH Keys** section in your profile](https://cloud.linode.com/profile/keys) to add a new key: ![SSH Keys section](https://mintcdn.com/ab-634991b8/2GuQWN9fVwUxVlhr/static/img/ssh/autofill-linode.png?fit=max\&auto=format\&n=2GuQWN9fVwUxVlhr\&q=85\&s=83714a96d2792dcb6cd402f3c6a92cf7) ## Microsoft Azure Visit the [**SSH keys** section in the Azure portal](https://portal.azure.com/#create/Microsoft.SshKey) to add a new key: ![Azure SSH key settings](https://mintcdn.com/ab-634991b8/2GuQWN9fVwUxVlhr/static/img/ssh/autofill-azure.png?fit=max\&auto=format\&n=2GuQWN9fVwUxVlhr\&q=85\&s=338702c7f5f01c8f198054c4440ec35b) ## Ngrok Visit the [**SSH Public Keys** section in the Ngrok dashboard](https://dashboard.ngrok.com/tunnels/ssh-keys/new) to add a new key: ![Ngrok SSH Public Keys section](https://mintcdn.com/ab-634991b8/2GuQWN9fVwUxVlhr/static/img/ssh/autofill-ngrok.png?fit=max\&auto=format\&n=2GuQWN9fVwUxVlhr\&q=85\&s=3e6eed99cbc4870dc23150ca85432688) ## Vultr Visit the [Vultr SSH key settings](https://my.vultr.com/settings/#settingssshkeys) to add a new key: ![Vultr SSH key settings](https://mintcdn.com/ab-634991b8/2GuQWN9fVwUxVlhr/static/img/ssh/autofill-vultr.png?fit=max\&auto=format\&n=2GuQWN9fVwUxVlhr\&q=85\&s=a73e715ebdc56af9d4cce3155bff302d) ## Learn more * [Manage SSH keys](/ssh/manage-keys/#generate-an-ssh-key) * [Sign Git commits](/ssh/git-commit-signing) * [About 1Password SSH Agent security](/ssh/agent/security/) * [Workflow: Secure your SSH & Git workflows](/get-started/secure-ssh-git-workflows) # Use the 1Password Terraform provider Source: https://www.1password.dev/terraform With the [1Password Terraform provider](https://github.com/1Password/terraform-provider-onepassword), you can reference, create, or update items in your vaults using a [1Password Connect Server](/secrets-automation#1password-connect-servers), a [1Password Service Account](/secrets-automation#1password-service-accounts), or the 1Password desktop app. [Using 1Password Connect with Terraform](https://www.youtube.com/embed/92yvxV7F4E0) ## Requirements > [tab] Connect server > > * [Create a Connect server.](/connect/get-started/#step-1) > [tab] Service account > > * [Create a service account](/service-accounts/get-started#create-a-service-account) > [tab] 1Password app > > * Install the latest [beta release](https://support.1password.com/betas#install-a-prerelease-version-of-the-1password-app) of the 1Password desktop app. > > > [!TIP] > > > > If you don't see the option to update to the latest beta in the app, you can download it directly for [Mac](https://releases.1password.com/mac/beta/), [Windows](https://releases.1password.com/windows/beta/), or [Linux](https://releases.1password.com/linux/beta/). ## Get started > [tab] Connect server > > To use the 1Password Terraform provider with a Connect server: > > 1. Specify the Connect server token. > > You can set this value with the `OP_CONNECT_TOKEN` environment variable or with the `connect_token` field in the provider configuration. > > 2. Specify the Connect server hostname, URL, or IP address. > > You can set this value with the `OP_CONNECT_HOST` environment variable or with the `connect_url` field in the provider configuration. > [tab] Service account > > To use the 1Password Terraform provider with a service account, you'll need to provide your service account token. > > You can set this value with the `OP_SERVICE_ACCOUNT_TOKEN` environment variable or with the `service_account_token` field in the provider configuration. > [tab] 1Password app > > First, turn on the "Integrate with 1Password SDKs" setting in the 1Password desktop app. If you don't see this setting, make sure you've installed the [beta version](https://support.1password.com/betas#install-a-prerelease-version-of-the-1password-app) of the app. > > > [tab] Mac > > > > 1. Open and unlock the [1Password app](https://1password.com/downloads/). > > 2. Select your account or collection at the top of the sidebar. > > 3. Navigate to **Settings** > **[Developer](onepassword://settings/developers)**. > > 4. Under Developer Integrations, select **Integrate with 1Password SDKs**. > > 5. If you want to authenticate with Touch ID, navigate to **Settings** > **[Security](onepassword://settings/security)**, then turn on **[Unlock using Touch ID](https://support.1password.com/touch-id-mac/)**. > > > > ![The Integrate with 1Password SDKs setting](/static/img/developer-integrations-sdks-light.png) > > ![The Integrate with 1Password SDKs setting](/static/img/developer-integrations-sdks-dark.png) > > > [tab] Windows > > > > 1. Open and unlock the [1Password app](https://1password.com/downloads/). > > 2. Select your account or collection at the top of the sidebar. > > 3. Navigate to **Settings** > **[Developer](onepassword://settings/developers)**. > > 4. Under Developer Integrations, select **Integrate with 1Password SDKs**. > > 5. If you want to authenticate with Windows Hello, navigate to **Settings** > **[Security](onepassword://settings/security)**, then turn on **[Unlock using Windows Hello](https://support.1password.com/windows-hello/)**. > > > > ![The Integrate with 1Password SDKs setting](/static/img/developer-integrations-sdks-light.png) > > ![The Integrate with 1Password SDKs setting](/static/img/developer-integrations-sdks-dark.png) > > > [tab] Linux > > > > 1. Open and unlock the [1Password app](https://1password.com/downloads/). > > 2. Select your account or collection at the top of the sidebar. > > 3. Navigate to **Settings** > **[Developer](onepassword://settings/developers)**. > > 4. Under Developer Integrations, select **Integrate with 1Password SDKs**. > > 5. If you want to authenticate the same way you sign in to your Linux account, navigate to **Settings** > **[Security](onepassword://settings/security)**, then turn on **[Unlock using system authentication](https://support.1password.com/system-authentication-linux/)**. > > > > ![The Integrate with 1Password SDKs setting](/static/img/developer-integrations-sdks-light.png) > > ![The Integrate with 1Password SDKs setting](/static/img/developer-integrations-sdks-dark.png) > > Then provide your account name or ID in the provider configuration: > > 1. Get the name of your 1Password account as it appears at the top of the left sidebar in the 1Password desktop app. Alternatively, you can use [1Password CLI](/cli/get-started) to run `op account get` to find your account ID. > 2. Set the `OP_ACCOUNT` environment variable or `account` in the provider configuration to your account name or ID. > > Run a Terraform command that requires authentication, and you'll be prompted to authenticate in the same way you unlock your 1Password app, like with biometrics or your 1Password account password. ## Reference The following sections contain reference information for the 1Password Terraform provider: * [Configuration](#configuration) * [Resources](#resources) * [Data sources](#data-sources) ### Configuration The 1Password Terraform provider has fields you must set before you can use it with a 1Password Connect server, service account, or the 1Password desktop app. The following table describes each field. | Field | Type | Description | Required | | - | - | - | - | | `connect_token` | String | A valid token for the 1Password Connect server. You can also source the value from the `OP_CONNECT_TOKEN` environment variable. | Required if using a Connect server. | | `connect_url` | String | The HTTP(s) URL of the 1Password Connect server. You can also source the value from the `OP_CONNECT_HOST` environment variable. | Required if using a Connect server. | | `service_account_token` | String | A valid token for the 1Password Service Account. You can also source the value from the `OP_SERVICE_ACCOUNT_TOKEN` environment variable. | Required if using a service account. | | `account` | String | The 1Password account name as it appears at the top left of the sidebar in the 1Password desktop app. Alternatively, the 1Password account ID. You can also source the value from the `ACCOUNT` environment variable. | Required if using the 1Password desktop app integration. | You can use the following environment variables to specify configuration values. | Environment variable | Description | Configuration field | | - | - | - | | `OP_CONNECT_TOKEN` | A valid token for the 1Password Connect server. | `connect_token` | | `OP_CONNECT_HOST` | The hostname, IP address, or URL of the 1Password Connect server. | `connect_url` | | `OP_SERVICE_ACCOUNT_TOKEN` | A valid token for the 1Password Service Account. | `service_account_token` | | `OP_ACCOUNT` | The 1Password account name as it appears at the top left of the sidebar in the 1Password desktop app. Alternatively, the 1Password account ID. | `account` | #### Configuration examples The following code blocks show configuration examples. > [!TIP] > > The following examples use environment variables. Make sure to set the environment variables beforehand or use plain text. > [tab] Connect server > > The following example shows a provider configuration using a Connect server: > > ```terraform connect-example.tf theme={null} > provider "onepassword" { > connect_url = "OP_CONNECT_HOST" > connect_token = "OP_CONNECT_TOKEN" > } > ``` > [tab] Service account > > The following example shows a provider configuration using a service account: > > ```terraform service-account-example.tf theme={null} > provider "onepassword" { > service_account_token = "OP_SERVICE_ACCOUNT_TOKEN" > } > ``` > [tab] 1Password app > > The following example shows a provider configuration using the 1Password desktop app: > > ```terraform 1password-account-example.tf theme={null} > provider "onepassword" { > account = "OP_ACCOUNT" > } > ``` ### Resources The 1Password Terraform provider has the following resources: * [`onepassword_item` resource](#item-resource) #### Item resource The `onepassword_item` resource represents a 1Password item. You can import a `onepassword_item` with the following syntax: ```shell theme={null} terraform import onepassword_item. vaults//items/ ``` ##### Schema The following tables describe the `onepassword_item` resource schema. | Field | Type | Description | Required | Access | | - | - | - | - | - | | `vault` | String | The UUID of the vault the item is in. | Yes | Read-Write | | `category` | String | The category of the item. **Acceptable values**: `login`, `password`, or `database`. | No | Read-Write | | `database` | String | The name of the database. Only applies to the database category. | No | Read-Write | | `hostname` | String | The address where the database can be found. Only applies to the database category. | No | Read-Write | | `note_value` | String, Sensitive | Secure note value. | No | Read-Write | | `note_value_wo` | String, Sensitive | A write-only secure note value. This value is not stored in the state and is intended for use with ephemeral values. Requires Terraform 1.11 or later. | No | [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) | | `note_value_wo_version` | Number | An integer that must be incremented to trigger an update to the `note_value_wo` field. | No | [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) | | `password` | String, Sensitive | The password for the item. | No | Read-Write | | `password_wo` | String, Sensitive | A write-only password. This value is not stored in the state and is intended for use with ephemeral values. Requires Terraform 1.11 or later. | No | [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) | | `password_wo_version` | Number | An integer that must be incremented to trigger an update to the `password_wo` field. | No | [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) | | `password_recipe` | Block List, Max: 1 | The password recipe for the item. Only applies to Login and Password items. See [`password_recipe`](#password_recipe). | No | Read-Write | | `password_wo` | String, Sensitive | A write-only password. This value is not stored in the state and is intended for use with ephemeral values. Requires Terraform 1.11 or later. | No | [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) | | `password_wo_version` | Number | An integer that must be incremented to trigger an update to the `password_wo` field. | No | [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) | | `port` | String | The port the database is listening on. Only applies to the database category. | No | Read-Write | | `section` | Block List | A list of custom sections in the item. See [`section`](#section). | No | Read-Write | | `section_map` | Map of Object | A map of custom sections for the item, where `label` is the map key. See [`section_map`](#section_map). | No | Read-Write | | `tags` | List of String | An array of strings representing the tags assigned to the item. | No | Read-Write | | `title` | String | The title of the item. | No | Read-Write | | `type` | String | The type of database. Only applies to the database category. **Acceptable values**: `db2`, `filemaker`, `msaccess`, `mssql`, `mysql`, `oracle`, `postgresql`, `sqlite` or `other`. | No | Read-Write | | `url` | String | The primary URL for the item. | No | Read-Write | | `username` | String | The username for the item. | No | Read-Write | | `id` | String | The Terraform resource identifier for the item in the format `vaults//items/`. | N/A | Read-Only | | `uuid` | String | The UUID of the item. Item identifiers are unique within a specific vault. | N/A | Read-Only | #### `password_recipe` > [!TIP] > > Password recipes can only be added to Login and Password items. The nested schema for the `password_recipe` field: | Field | Type | Description | Required | Access | | - | - | - | - | - | | `digits` | Boolean | Use digits `[0-9]` when generating the password. | No | Read-Write | | `length` | Number | The length of the password to be generated. | No | Read-Write | | `symbols` | Boolean | Use symbols `[!@.-_*]` when generating the password. | No | Read-Write | #### `section` The nested schema for the `section` field: | Field | Type | Description | Required | Access | | - | - | - | - | - | | `label` | String | The label for the section. | Yes | Read-Write | | `field` | Block List | A list of custom fields in the section. See [`section.field`](#item-resource-section-field). | No | Read-Write | | `id` | String | A unique identifier for the section. | N/A | Read-Only | #### `section_map` The nested schema for the `section_map` field: | Field | Type | Description | Required | Access | | - | - | - | - | - | | `field_map` | Map of Object | A map of custom fields in the section, where `label` is the map key. See [`field_map`](#field_map). | No | Read-Write | | `id` | String | A unique identifier for the section. | N/A | Read-Only | #### `section.field` The nested schema for the `section.field` field: | Field | Type | Description | Required | Access | | - | - | - | - | - | | `label` | String | The label for the field. | Yes | Read-Write | | `id` | String | A unique identifier for the field. | No | Read-Write | | `password_recipe` | String | The password for the item. Only applies to Login and Password items. See [`section.field.password_recipe`](#item-resource-section-field-password-recipe). | No | Read-Write | | `type` | String | The type of value stored in the field. **Acceptable values**: `STRING`, `EMAIL`, `CONCEALED`, `URL`, `OTP`, `DATE`, `MONTH_YEAR`, or `MENU`. | No | Read-Write | | `value` | String, Sensitive | The value of the field. | No | Read-Write | #### `field_map` The nested schema for the `field_map` field: | Field | Type | Description | Required | Access | | - | - | - | - | - | | `id` | String | A unique identifier for the field. | N/A | Read-Only | | `password_recipe` | The password recipe for the field. | No | Read-Write | | | `type` | String | The type of value stored in the field. | No | Read-Write | | `value` | String, Sensitive | The value of the field. | No | Read-Write | #### `section.field.password_recipe` > [!TIP] > > Password recipes can only be added to Login and Password items. The nested schema for the `section.field.password_recipe` field: | Field | Type | Description | Required | Access | | - | - | - | - | - | | `digits` | Boolean | Use digits `[0-9]` when generating the password. | No | Read-Write | | `length` | Number | The length of the password to be generated. | No | Read-Write | | `symbols` | Boolean | Use symbols `[!@.-_*]` when generating the password. | No | Read-Write | ##### Example The following code block shows an example usage of the `onepassword_item` resource. ```terraform resource.tf theme={null} resource "onepassword_item" "demo_password" { vault = var.demo_vault title = "Demo Password Recipe" category = "password" password_recipe { length = 40 symbols = false } } resource "onepassword_item" "demo_login" { vault = var.demo_vault title = "Demo Terraform Login" category = "login" username = "test@example.com" } resource "onepassword_item" "demo_db" { vault = var.demo_vault category = "database" type = "mysql" title = "Demo TF Database" username = "root" database = "Example MySQL Instance" hostname = "localhost" port = 3306 } ``` ### Data sources The 1Password Terraform provider has the following data sources: * [`onepassword_item` data source](#item-data-source) * [`onepassword_vault` data source](#vault-data-source) * [`onepassword_environment` data source](#environment-data-source) #### Item data source Use the `onepassword_item` data source to get details of a 1Password item. You can identify an item by its vault UUID and either the item's title or UUID. ##### Schema The following tables describe the `onepassword_item` resource schema. | Field | Type | Description | Required | Access | | - | - | - | - | - | | `vault` | String | The UUID of the vault the item is in. | Yes | Read-Write | | `note_value` | String, Sensitive | The Secure Note value. | No | Read-Write | | `title` | String | The title of the item to retrieve. This field populates with the title of the item if the item is looked up by its UUID. | No | Read-Write | | `uuid` | String | The UUID of the item to retrieve. This field populates with the UUID of the item if the item is looked up by its title. | No | Read-Write | | `category` | String | The category of the item. **Acceptable values**: `login`, `password`, or `database`. | No | Read-Only | | `database` | String | The name of the database. Only applies to the database category. | No | Read-Only | | `hostname` | String | The address where the database can be found. Only applies to the database category. | No | Read-Only | | `id` | String | The Terraform resource identifier for the item in the format `vaults//items/`. | No | Read-Only | | `password` | String, Sensitive | The password for the item. | No | Read-Only | | `port` | String | The port the database is listening on. Only applies to the database category. | No | Read-Only | | `section` | List of Object | A list of custom sections in an item. | No | Read-Only | | `tags` | List of String | An array of strings of the tags assigned to the item. | No | Read-Only | | `type` | String | The type of database. Only applies to the database category. **Acceptable values**: `db2`, `filemaker`, `msaccess`, `mssql`, `mysql`, `oracle`, `postgresql`, `sqlite`, or `other`. | No | Read-Only | | `url` | String | The primary URL for the item. | No | Read-Only | | `username` | String | The username for the item. | No | Read-Only | #### `section` The nested schema for the `section` field: | Field | Type | Description | Required | Access | | - | - | - | - | - | | `field` | List of Object | A list of custom fields in the section. See [`section.field`](#item-data-source-section-field). | N/A | Read-Only | | `id` | String | A unique identifier for the section. | N/A | Read-Only | | `label` | String | The label for the section. | N/A | Read-Only | #### `section.field` The nested schema for the `section.field` field: | Field | Type | Description | Required | Access | | - | - | - | - | - | | `id` | String | A unique identifier for the field. | N/A | Read-Only | | `label` | String | The label for the field. | N/A | Read-Only | | `type` | String | The type of value stored in the field. **Acceptable values**: `STRING`, `EMAIL`, `CONCEALED`, `URL`, `OTP`, `DATE`, `MONTH_YEAR`, or `MENU`. | N/A | Read-Only | | `value` | String, Sensitive | The value of the field. | N/A | Read-Only | ##### Example The following example shows how to use the `onepassword_item` data source. ```terraform data-source.tf theme={null} data "onepassword_item" "example" { vault = var.demo_vault uuid = onepassword_item.demo_sections.uuid } ``` #### Vault data source Use the `onepassword_vault` data source to get details of a vault. You can identify a vault with the vault name or UUID. ##### Schema The following tables describe the `onepassword_vault` resource schema. | Field | Type | Description | Required | Access | | - | - | - | - | - | | `name` | String | The name of the vault to retrieve. This field populates with the name of the vault if the vault is looked up by its UUID. | No | Read-Write | | `uuid` | String | The UUID of the vault to retrieve. This field populates with the UUID of the vault if the vault is looked up by its name. | No | Read-Write | | `description` | String | The description of the vault. | No | Read-Only | | `id` | String | The Terraform resource identifier for this item in the format `vaults/`. | No | Read-Only | #### Environment data source Use the `onepassword_environment` data source to read secrets from a [1Password Environment](/environments). Identify an Environment by its ID. > [!TIP] > > This data source is only supported with service account or desktop app authentication. It isn't available with 1Password Connect. ##### Schema The following tables describe the `onepassword_environment` resource schema. | Field | Type | Description | Required | Access | | - | - | - | - | - | | `environment_id` | String | The unique identifier of the 1Password Environment. Learn how to [get an Environment's ID](/environments/read-environment-variables#get-an-environments-id). | Yes | Read-Write | | `id` | String | The Terraform resource identifier for the environment in the format `environments/`. | No | Read-Only | | `variables` | Map of String, Sensitive | A map of the Environment's secret names to their values. Use this for passing secrets into Terraform resources or for use in `environment` blocks. | No | Read-Only | | `metadata` | List of Object | Metadata for each secret in the Environment. Use this when you need the full structure of each secret. See [`metadata`](#environment-data-source-metadata). | No | Read-Only | #### `metadata` The nested schema for the `metadata` field: | Field | Type | Description | Required | Access | | - | - | - | - | - | | `name` | String | The secret's name. | N/A | Read-Only | | `value` | String, Sensitive | The secret's value. | N/A | Read-Only | | `masked` | Boolean | Whether the value is hidden by default in the 1Password app. | N/A | Read-Only | ##### Example The following example shows how to use the `onepassword_environment` data source. ```terraform data-source.tf theme={null} data "onepassword_environment" "example" { environment_id = "your-environment-id" } output "env_variables" { value = data.onepassword_environment.example.variables sensitive = true } ``` ### Ephemeral resources The 1Password Terraform provider has the following ephemeral resources: * [`onepassword_item` ephemeral resource](#item-ephemeral-resource) #### Item ephemeral resource The `onepassword_item` ephemeral resource represents a 1Password item. Use it to retrieve item values without storing them in Terraform state. This is useful for providing sensitive values to write-only arguments or other ephemeral contexts. ##### Schema | Field | Type | Description | Required | Access | | - | - | - | - | - | | `vault` | String | The UUID of the vault the item is in. | Yes | Read-Write | | `title` | String | The title of the item to retrieve. This field will be populated with the title of the item if the item it looked up by its UUID. | No | Read-Write | | `uuid` | String | The UUID of the item to retrieve. This field will be populated with the UUID of the item if the item it looked up by its title. | No | Read-Write | | `credential` | String, Sensitive | API credential for this item. Only applies to the API credential category. | No | Read-Only | | `database` | String | The name of the database. Only applies to the database category. | No | Read-Only | | `hostname` | String | The address where the database can be found. Only applies to the database category. | No | Read-Only | | `id` | String | The Terraform resource identifier for the item in the format `vaults//items/`. | No | Read-Only | | `note_value` | String, Sensitive | Secure Note value. | No | Read-Only | | `password` | String, Sensitive | Password for this item. | No | Read-Only | | `port` | String | The port the database is listening on. Only applies to the database category. | No | Read-Only | | `private_key` | String, Sensitive | SSH Private Key in PKCS#8 for this item. | No | Read-Only | | `private_key_openssh` | String, Sensitive | SSH Private key in OpenSSH format. | No | Read-Only | | `public_key` | String | SSH Public Key for this item. | No | Read-Only | | `type` | String | The type of database or API Credential. Only applies to database and API credential categories | No | Read-Only | | `url` | String | The primary URL for the item. | No | Read-Only | | `username` | String | Username for this item. | No | Read-Only | #### Example ```terraform theme={null} # Example using ephemeral resource to retrieve item values ephemeral "onepassword_item" "example" { vault = "your-vault-id" title = "your-item-title" } # Example using UUID instead of title ephemeral "onepassword_item" "example_by_uuid" { vault = "your-vault-id" uuid = "your-item-uuid" } ``` ## Learn more * [Changelog](https://github.com/1Password/terraform-provider-onepassword/blob/main/CHANGELOG.md) * [Workflow: Secure your deployments](/get-started/secure-deployment) * [Workflow: Build integrations with 1Password](/get-started/build-integrations) # Tutorials Source: https://www.1password.dev/tutorials Step-by-step tutorials for 1Password developer tools. Filter by tool and topic to find what you need. # 1Password Users API Source: https://www.1password.dev/users-api Connect your 1Password account to a security automation platform with the 1Password Users API. Use the 1Password Users API to list, look up, suspend, and reactivate people in your 1Password account from your own security tools. It's a REST API that uses OAuth 2.0 for authorization. Teams use it to: * Enforce 1Password access rules automatically. * Suspend or reactivate a user when your SIEM or the [Events API](/events-api) flags something. * Respond to security incidents faster, with fewer manual steps. > [card] [Try the API in your browser](/users-api/list-users) > > Paste your token and send a real request from the docs. No code needed. ## Requirements The Users API requires you to have: * A [1Password Business](https://1password.com/business-security) or [1Password Enterprise Password Manager](https://1password.com/product/enterprise-password-manager) account (not included with 1Password Teams) * Permissions to manage integrations in your 1Password account (for example, as an [owner](https://support.1password.com/groups/#owners), [administrator](https://support.1password.com/groups/#administrators), or member of the [Security group](https://support.1password.com/groups/#security)) > [!WARNING] > > Integrations with the Users API are not currently supported if you use [automated provisioning](https://support.1password.com/provisioning/) with your 1Password account. You can manage actions, like suspending and reactivating users, through your identity provider. ## Quickstart [Start here](/users-api/get-started) to set up an OAuth integration and send your first authentication request to the Users API. ## Try it in the docs Every endpoint in the [API reference](/users-api/reference) has a **Try it** panel. Paste an access token and send a real request from your browser. No code needed. **1. Get an access token** Follow [Get started](/users-api/get-started) to set up the Users API, then use [Request an access token](/users-api/request-access-token) to get a token. **2. Start with a read-only call** Open [List users](/users-api/list-users). It reads the people in your account without changing anything. **3. Paste your token** Select **Try it**, then paste your access token in the **Authorization** field. **4. Send it, then copy the code** Select **Send** to see the live response. The example panel turns the same request into cURL, Python, JavaScript, Go, and more. > [!WARNING] > > Suspend and reactivate calls change real accounts. Try them on a test user first. ## Guides * [Authorize your integrations using OAuth 2.0](/users-api/authorization) * Read the [API conventions](/users-api/conventions) to learn how to authenticate, structure requests, and interpret responses and errors. * [Get started with 1Password Security Automation](https://support.1password.com/security-automation/) to see integrations built by 1Password partners. ## Reference Use the [API reference](/users-api/reference) to learn more about each endpoint. ### OAuth tokens * [Request an access token](/users-api/request-access-token) * [Introspect an access token](/users-api/introspect-access-token) * [Revoke an access token](/users-api/revoke-access-token) ### Users * [List users](/users-api/list-users) * [Get a user](/users-api/get-user) * [Suspend a user](/users-api/suspend-user) * [Reactivate a user](/users-api/reactivate-user) ## Provide feedback To provide feedback, or if you're interested in partnering with 1Password as an integrated service, you can [contact 1Password](mailto:msp@1password.com). We'd love to hear from you. # Authorize your integrations using OAuth 2.0 Source: https://www.1password.dev/users-api/authorization Learn how to manage OAuth 2.0 authorization for integrations with the 1Password Users API. The 1Password Users API uses the [OAuth 2.0 client credentials flow](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) to authorize server-to-server integrations with 1Password Business or 1Password Enterprise Password Manager. In this approach, an application authenticates using its client credentials to obtain a short-lived, scoped access token only when needed, rather than storing a static token for extended periods. This simplifies token rotation and reduces the impact if an access token is leaked. ## How OAuth 2.0 authorization works The OAuth 2.0 client credentials grant allows your integration to authenticate directly with its own credentials, so no end-user redirect or authorization code exchange is required during token creation. The main components of the authorization flow for authorizing requests to the Users API include:
    Component Description
    OAuth API endpoints The endpoints you call to request, check, and revoke OAuth 2.0 access tokens for your integrations:
    • Request an access token: `POST /v1/oauth/token`
    • Introspect an access token: `POST /v1/oauth/introspect`
    • Revoke an access token: `POST /v1/oauth/revoke`
    Users API resource servers The servers that host the Users API endpoints. These endpoints validate the access token before returning protected data or performing an action.
    • List users: `/v1/accounts//users`
    • Get a single user: `/v1/accounts//users/`
    • Suspend a user: `/v1/accounts//users/:suspend`
    • Reactivate a user: `/v1/accounts//users/:reactivate`
    1Password OAuth application The OAuth application you configure in your 1Password account for an integration. It generates the client credentials and defines what the integration can access.
    Integration (client) The application, service, or automation that uses your client credentials to request an access token, then uses that token to make calls to the Users API.
    Client credentials The client ID and client secret generated by the OAuth application in 1Password. These are used in calls to the `/v1/oauth/token` endpoint to request an access token.
    Access token The opaque bearer token returned by the token endpoint. Access tokens have a lifespan of 15 minutes (900 seconds) and carry the scopes configured for the OAuth application. The access token is sent in the `Authorization` header in requests to the Users API. You can generate multiple tokens with the integration's client credentials. [Access tokens can be revoked](#revoke-an-access-token) as needed.
    ## Create an OAuth application in your 1Password account To get started with the Users API, create an OAuth application in your 1Password account. This will generate the client credentials your integration will use to request an access token. 1. [Sign in](https://start.1password.com/signin) to your 1Password account. 2. Select [**Integrations**](https://start.1password.com/integrations/directory) in the sidebar. If you've set up other integrations in your account, you'll also need to select **Directory** on the Integrations page. 3. Select **OAuth Application**. 4. Select **Client credentials** as the grant type, then select **Next**. 5. Configure your OAuth application: * **Application name**: Enter a name to help you identify the integration. * **Scopes**: Select one or more of the [scopes](#scopes) from the "Select scopes" list, according to the access required for your integration: view users, suspend user, and reactivate user. * **Description**: (Optional) Add a description with additional information about your OAuth application. When you're finished, select **Next** to generate your client ID and client secret. 6. Select **Save in 1Password** and choose the vault where you want to save your client credentials. Then select **View integration**. > [!WARNING] > > The client secret is only shown once, so make sure to save it before you continue. You can now use your generated client ID and client secret to [request an access token](#request-an-access-token) using the OAuth 2.0 client credentials grant. The scopes of an OAuth application can't be changed after it's created. If your integration needs different scopes, create a new application. You can also [rotate the client secret](#rotate-the-client-secret) of an existing application without creating a new one. ### Scopes Choose the least-privileged permissions your integration needs. The available scopes are:
    Scope Permission Access level Users API endpoints
    `users.view` View users Read [List users](/users-api/list-users): `GET /v1/accounts//users`\ \ [Get a user](/users-api/get-user): `GET /v1/accounts//users/`
    `users.suspend` Suspend user Write [Suspend a user](/users-api/suspend-user): `POST /v1/accounts//users/:suspend`
    `users.reactivate` Reactivate user Write [Reactivate a user](/users-api/reactivate-user): `POST /v1/accounts//users/:reactivate`
    The scopes granted to an access token are listed in the `scope` field of the [token response](#receive-an-access-token). A request to a Users API endpoint that isn't covered by the token's scopes returns `403 Forbidden`. Access tokens are also bound to the 1Password account that owns the OAuth application: a request whose path names a different account returns `403 Forbidden`. ### Rotate the client secret If you need to replace your client secret, you can rotate it from the OAuth application in your 1Password account. The new client secret is only shown once, so save it before you continue. When you rotate a client secret, the previous secret stays valid for 6 hours. This grace period allows you to update your integration without downtime. If a client secret is compromised and you need to invalidate it immediately, you can [revoke the OAuth application](#revoke-the-integration-in-your-1password-account). This invalidates the client credentials and every access token issued to them. You can then [create a new OAuth application](#create-an-oauth-application) to generate a new client secret. ## Request an access token After you create the OAuth application and save the client credentials in your 1Password account, request an OAuth access token from the [token endpoint](/users-api/request-access-token). ### Authorization endpoints The OAuth API endpoints are hosted on the same base URL as the Users API. Use the base URL that matches the [region of your 1Password account](https://support.1password.com/regions/): | Account domain | Base URL | | - | - | | 1Password.com | `https://api.1password.com` | | 1Password.ca | `https://api.1password.ca` | | 1Password.eu | `https://api.1password.eu` | | ent.1password.com | `https://api.ent.1password.com` | Access tokens are specific to the region they were issued in. Request the token from the same base URL that your integration uses for Users API requests; a token issued by one region isn't accepted by another. Append the endpoint path to the base URL: `/v1/oauth/token` to [request an access token](/users-api/request-access-token), `/v1/oauth/introspect` to [check whether a token is active](/users-api/introspect-access-token), and `/v1/oauth/revoke` to [revoke a token](/users-api/revoke-access-token). ### Token request headers and body parameters Use the following request headers and body parameters to request an access token:
    Request element Value Required Description
    Header `Authorization: Basic ` Yes HTTP Basic authentication header that includes your base64-encoded client credentials. Recommended. Alternatively, send the credentials as the `client_id` and `client_secret` body parameters instead of this header.
    Header `Content-Type: application/x-www-form-urlencoded` Yes Indicates that the request body is sent as URL-encoded form data.
    Body parameter `grant_type=client_credentials` Yes Specifies the OAuth 2.0 client credentials grant.
    Body parameters `client_id=&client_secret=` No An alternative to the `Authorization` header for sending your client credentials. Don't use both methods in the same request; the request is rejected if you do.
    > [!NOTE] > > Every token request must include your client credentials. Send them either in the `Authorization` header (recommended) or as the `client_id` and `client_secret` body parameters, but not both. You don't request scopes when you request a token. Every access token is issued with the [scopes](#scopes) configured for the OAuth application. ### Example token request Make a POST call to the [`/v1/oauth/token` endpoint](/users-api/request-access-token) to request an access token. Include your client ID and client secret, along with the required headers and request parameters. > [tab] HTTP request > > If you use raw HTTP to send a request, you'll need to base64-encode your OAuth client credentials before you send the request. > > 1. Join your client ID and client secret as a single string, separated by a colon (`:`). > > ``` > : > ``` > > For example, if your client ID is `H3WVOKGN4B7JXQYCQ6DJFAW5ZU` and your client secret is `kq7rV2mXt9pL4wZy8nB1cD6fG3hJ5sA0eUoQ2iR8tYv`, the string would be: > > ``` > H3WVOKGN4B7JXQYCQ6DJFAW5ZU:kq7rV2mXt9pL4wZy8nB1cD6fG3hJ5sA0eUoQ2iR8tYv > ``` > > 2. Base64-encode your client credentials string using your preferred tool or utility. For example, from the command line you can use: > > ```shell theme={null} > printf '%s' "H3WVOKGN4B7JXQYCQ6DJFAW5ZU:kq7rV2mXt9pL4wZy8nB1cD6fG3hJ5sA0eUoQ2iR8tYv" | base64 > #code-result > SDNXVk9LR040QjdKWFFZQ1E2REpGQVc1WlU6a3E3clYybVh0OXBMNHdaeThuQjFjRDZmRzNoSjVzQTBlVW9RMmlSOHRZdg== > ``` > > 3. Make a POST call to the [`/v1/oauth/token` endpoint](/users-api/request-access-token) to request an access token. Include the required headers and request parameters, and use the base64-encoded client credentials string in the `Authorization` header. For example: > > ```http theme={null} > POST /v1/oauth/token HTTP/1.1 > Host: api.1password.com > Content-Type: application/x-www-form-urlencoded > Authorization: Basic SDNXVk9LR040QjdKWFFZQ1E2REpGQVc1WlU6a3E3clYybVh0OXBMNHdaeThuQjFjRDZmRzNoSjVzQTBlVW9RMmlSOHRZdg== > > grant_type=client_credentials > ``` > [tab] Curl request > > If you're using curl, you can pass the client credentials in the `--user` option. Curl takes the raw `client_id:client_secret` string, base64-encodes it, and sends the encoded string in the HTTP Basic authentication header. > > 1. Join your client ID and client secret as a single string, separated by a colon (`:`). > > ``` > : > ``` > > For example, if your client ID is `H3WVOKGN4B7JXQYCQ6DJFAW5ZU` and your client secret is `kq7rV2mXt9pL4wZy8nB1cD6fG3hJ5sA0eUoQ2iR8tYv`, the string would be: > > ``` > H3WVOKGN4B7JXQYCQ6DJFAW5ZU:kq7rV2mXt9pL4wZy8nB1cD6fG3hJ5sA0eUoQ2iR8tYv > ``` > > 2. Make a POST call to the [`/v1/oauth/token` endpoint](/users-api/request-access-token) to request an access token. Include the required headers and request parameters, and use the raw `client_id:client_secret` string in the `--user` option. Access token request structure: > > ```shell theme={null} > curl -X POST /v1/oauth/token \ > --header "Content-Type: application/x-www-form-urlencoded" \ > --user ":" \ > --data "grant_type=client_credentials" > ``` > > Example request: > > ```shell theme={null} > curl -X POST https://api.1password.com/v1/oauth/token \ > --header "Content-Type: application/x-www-form-urlencoded" \ > --user "H3WVOKGN4B7JXQYCQ6DJFAW5ZU:kq7rV2mXt9pL4wZy8nB1cD6fG3hJ5sA0eUoQ2iR8tYv" \ > --data "grant_type=client_credentials" > ``` ## Receive an access token A successful response returns an opaque bearer token that your integration can use with calls to the Users API, along with the scopes granted to the token. For example: ```json theme={null} { "access_token": "op_o_c_H3WVOKGN4B7JXQYCQ6DJFAW5ZU_Q2s4ZmVnaGprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1Njc4OWFi", "token_type": "Bearer", "expires_in": 900, "scope": "users.view users.suspend users.reactivate" } ``` Access tokens have a limited lifespan of 15 minutes (900 seconds), after which the client needs to request a new access token. The OAuth client credentials flow is designed so clients must handle token renewal by requesting a new access token whenever the current token expires. Refresh tokens aren't supported. Token and introspection responses include `Cache-Control: no-store` and `Pragma: no-cache` headers. Make sure your integration doesn't cache access tokens beyond their lifespan, and store them securely. ### Use the access token with the Users API Include the access token in the `Authorization` header for requests to the Users API. Request structure: ```shell theme={null} curl --request METHOD \ --url "/" \ --header "Authorization: Bearer " \ --header "User-Agent: /" ``` Example request to [retrieve a list of users](/users-api/list-users) in an account, with the access token included in the `Authorization` header: ```shell theme={null} curl --request GET \ --url "https://api.1password.com/v1/accounts/WX52YXL2MVEPBK43P3R4XMWKXI/users" \ --header "Authorization: Bearer op_o_c_H3WVOKGN4B7JXQYCQ6DJFAW5ZU_Q2s4ZmVnaGprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1Njc4OWFi" \ --header "User-Agent: Acme/1.0.0" ``` ### Check whether an access token is active If your integration stores access tokens between tasks, you can check whether a token is still active before you use it by calling the [`/v1/oauth/introspect` endpoint](/users-api/introspect-access-token) with your client credentials. The response includes the token's scopes and expiry time, or `"active": false` if the token has expired or been revoked. ## Revoke an access token You can revoke a token when it's no longer needed using the OAuth revoke endpoint. You can also revoke all tokens for an integration by revoking the OAuth application in your 1Password account. ### Use the revoke endpoint Use the [`/v1/oauth/revoke` endpoint](/users-api/revoke-access-token) to revoke a token. Authenticate with the client credentials of the OAuth application the token was issued to. For example: ```shell theme={null} curl -X POST https://api.1password.com/v1/oauth/revoke \ --header "Content-Type: application/x-www-form-urlencoded" \ --user ":" \ --data "token=" ``` A successful revocation request returns `200 OK` with an empty body. The endpoint also returns `200 OK` if the submitted token was already expired, revoked, or unknown, so revocation requests are safe to retry. ### Revoke the integration in your 1Password account You can revoke the OAuth application in your 1Password account. This will remove the application from your active integrations and revoke all access tokens generated with the client credentials for that integration. 1. [Sign in](https://start.1password.com/signin) to your 1Password account. 2. Select [**Integrations**](https://start.1password.com/integrations/) in the sidebar. 3. Select the active OAuth Application for your integration. 4. Select **Revoke integration**, then enter your account password and revoke the integration. ### Delete your integration's client If you decommission an integration and delete the client on your own platform, you should also revoke the OAuth application in your 1Password account. Access tokens already issued remain valid until they expire, and the client credentials remain valid until the OAuth application is revoked. # API conventions Source: https://www.1password.dev/users-api/conventions Conventions used across the 1Password Users API, including authorization, endpoint paths, request headers, pagination, filtering, rate limits, and error handling. The conventions below apply across the 1Password Users API, where applicable, including how to authorize requests, structure requests, and interpret responses and errors. The Users API is a REST-style API that supports standard HTTP methods and follows the [OpenAPI 3.1.0 specification.](https://spec.openapis.org/oas/v3.1.0.html) All communication between clients and servers is over HTTPS. ## Authorization The Users API uses the [OAuth 2.0 authorization framework](https://datatracker.ietf.org/doc/html/rfc6749) to allow an application to act on behalf of your organization. The authorization process uses the [client credentials grant](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) flow to issue access tokens to authenticated clients: 1. [Create an OAuth application](/users-api/authorization#create-an-oauth-application) in your 1Password account to generate scoped client credentials. 2. Make a POST call to the [OAuth 2.0 token request endpoint](/users-api/request-access-token) that includes your client credentials to request a scoped access token. 3. Send the access token in the `Authorization` header when calling the Users API endpoints, prefixed with `Bearer`: ``` Authorization: Bearer ``` 4. Request a new token when the current one expires, or revoke a token when it's no longer needed. Access tokens have a limited lifespan of 15 minutes (900 seconds), after which the client needs to request a new access token. Learn more about [how to authorize your integrations using OAuth 2.0](/users-api/authorization). ## Endpoints The basic structure of an endpoint URL for the Users API includes the base URL and the endpoint path. The endpoint path includes the API endpoint version, the resource(s) you want to access, and any relevant path and query parameters. ### Base URLs The base URL of an endpoint URL indicates the server that hosts the environment you want to work in. Use the base URL that matches the [region of the 1Password account](https://support.1password.com/regions/) you want to access. | Base URL | Description | | - | - | | `https://api.1password.com` | Server for working with accounts hosted in the 1Password.com region. | | `https://api.1password.ca` | Server for working with accounts hosted in the 1Password.ca region. | | `https://api.1password.eu` | Server for working with accounts hosted in the 1Password.eu region. | | `https://api.ent.1password.com` | Server for working with accounts hosted on ent.1password.com. | Integrations should be designed to allow the base URL to be configurable to accommodate accounts in different regions. ### Endpoint paths Endpoint paths are appended to the base URL and include the endpoint version, target resource path, and any path parameters. For example, the endpoint path to retrieve a single user in a 1Password account looks like this: ``` /v1/accounts/{account}/users/{user} ``` The `{account}` path parameter is the unique identifier of the 1Password account, and the `{user}` path parameter is the unique identifier of the user. Both are 26-character uppercase IDs, for example `WX52YXL2MVEPBK43P3R4XMWKXI`. A malformed ID returns `400 Bad Request`, and an ID that doesn't exist returns `404 Not Found`. The path may also include a custom action, which is indicated by a colon (`:`) separator followed by an action verb. For example: `:suspend` or `:reactivate`. Custom actions are placed at the end of the endpoint path and before any query parameters: ``` POST https://api.1password.eu/v1/accounts/{account}/users/{user}:suspend ``` Endpoint paths are matched exactly. Don't add a trailing slash, and don't include the `:suspend` or `:reactivate` action on endpoints that don't support it. Check the [API reference documentation](/users-api/reference) for more information about the available endpoints. ## Requests ### Request methods Requests to the Users API use standard HTTP methods: | Method | Usage | | - | - | | `GET` | Retrieve resources. For example: [list users](/users-api/list-users) or [get a user](/users-api/get-user). | | `POST` | Perform an action on a resource. For example: [suspend](/users-api/suspend-user) or [reactivate](/users-api/reactivate-user) a user. | The Users API accepts JSON over HTTPS only. Requests that use gRPC or Connect protocols return `415 Unsupported Media Type`. ### Request headers * **`Authorization`**: Your OAuth access token, prefixed with `Bearer`. Required on every request. See [Authorization](#authorization). * **`User-Agent`**: Recommended. Send an identifiable `User-Agent` header in the format `/` so requests can be attributed to a specific integration. This helps with support and troubleshooting, and with analytics on integration usage. ``` Authorization: Bearer User-Agent: AcmeSOAR/1.0.0 ``` Requests to the OAuth API endpoints send their parameters as a URL-encoded form and require a `Content-Type: application/x-www-form-urlencoded` header. Learn more about [requesting an access token](/users-api/authorization#request-an-access-token). ### Request bodies Users API requests don't include a request body. The [suspend](/users-api/suspend-user) and [reactivate](/users-api/reactivate-user) actions identify the target user in the endpoint path. ## Query parameters You can use query parameters in your API request as optional modifiers after the endpoint path. Use a query separator (`?`) at the end of the endpoint path, then add any query parameters you want to include, separated by a query delimiter (`&`). For example, you can list users in an account and use query parameters to [filter the results](#filtering) to active users and set the maximum number of results to return per [page](#pagination): ```text theme={null} GET https://api.1password.com/v1/accounts/{account}/users?filter=user.isActive()&max_page_size=100 ``` Make sure your client URL-encodes query parameter values. Filter expressions contain parentheses, so the request above is sent as: ```text theme={null} GET https://api.1password.com/v1/accounts/{account}/users?filter=user.isActive%28%29&max_page_size=100 ``` Check the [API reference documentation](/users-api/reference) for more information about the available query parameters for each endpoint. A request that includes a query parameter the endpoint doesn't support returns `400 Bad Request`. ### Filtering The [list users](/users-api/list-users) endpoint accepts a `filter` query parameter to return only users in a specific [state](#user-states): * `user.isActive()` returns only active users. * `user.isSuspended()` returns only suspended users. Filter values are case-sensitive and must match exactly. When the filter is omitted or empty, both active and suspended users are returned. Any other value returns `400 Bad Request` with an `invalid_argument` error, for example: `invalid filter "user.isDeleted()": must be "user.isActive()" or "user.isSuspended()"`. ### Pagination The [list users](/users-api/list-users) endpoint supports token-based pagination. Use these query parameters to page through results: * `max_page_size`: The maximum number of users to return per page. Defaults to 100 when omitted or set to `0`. The maximum is 1000; values greater than 1000 are limited to 1000, and negative values return `400 Bad Request`. * `page_token`: The token that identifies the page of results to return. If more than one page of results is available, the response includes an opaque `next_page_token`. To retrieve the next page, send the same request with `page_token` set to that value. Repeat until the response no longer includes a `next_page_token`. A page with no results is returned as an empty JSON object (`{}`), so treat a missing `results` field as an empty list. When you send a `page_token`, include the same `filter` value as the original request; the token doesn't store it. `max_page_size` is ignored on requests that include a `page_token`, because the page size is fixed by the token. Page tokens don't expire. If users are added, suspended, or reactivated while you page through results, some users may shift between pages. ```shell theme={null} curl --request GET \ --url "https://api.1password.com/v1/accounts//users?max_page_size=100&page_token=" \ --header "Authorization: Bearer " \ --header "User-Agent: /" ``` ## Responses The API returns JSON (`application/json`) for all responses. A successful request returns `200 OK`. The [suspend](/users-api/suspend-user) and [reactivate](/users-api/reactivate-user) actions return the updated user in the response body, so you can read back the user's current `state`. Learn more about [error responses](#errors) and [paginated list responses](#pagination). ### Dates and times Timestamps are returned in [RFC 3339 format](https://datatracker.ietf.org/doc/html/rfc3339), for example `2024-01-15T10:30:00Z`. ## Rate limits Requests to the Users API are rate limited per 1Password account and per endpoint: * 100 requests per minute * 6,000 requests per hour Every response from the Users API includes `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers that report the current limit, how many requests remain in the window, and when the window resets (as a Unix timestamp in seconds). Rate limits are applied before a request's scopes are checked, so requests that return `403 Forbidden` also count toward the limit. Requests that are rejected because the access token is missing or invalid (`401 Unauthorized`) don't reach the API, so they don't include the `RateLimit-*` headers and don't count toward the limit. Requests to the [OAuth API endpoints](/users-api/authorization#authorization-endpoints) (token, introspection, and revocation) are rate limited separately. The limits are shared across the three endpoints: * Per OAuth application: 60 requests per minute and 3,600 requests per hour * Per 1Password account: 600 requests per minute and 36,000 requests per hour If you exceed the allowed rates, the API returns a `429 Too Many Requests` response with a `Retry-After` header that indicates how long to wait, in seconds, before retrying. Rate-limited Users API responses use the standard [error format](#errors) with the `resource_exhausted` code and include the `RateLimit-*` headers with `RateLimit-Remaining: 0`. Rate-limited OAuth API responses include a JSON error body with the `slow_down` error code. ## Errors The API uses standard HTTP status codes to indicate the result of a request. A `2xx` code indicates success. A `4xx` code indicates a problem with the request (for example, missing authorization or invalid input). A `5xx` code indicates an unexpected server error. Error responses use a consistent format with a machine-readable `code` and a human-readable `message`: ```json theme={null} { "code": "invalid_argument", "message": "invalid filter \"user.isDeleted()\": must be \"user.isActive()\" or \"user.isSuspended()\"" } ``` > [!WARNING] > > The error response format, including the `code` and `message` fields, is provisional and may change in a future release. Use the HTTP status code to handle errors in your integration, and don't rely on the text of the `message` field. | Status | Code | Meaning | | - | - | - | | `400 Bad Request` | `invalid_argument` | A request parameter is invalid. For example, an unsupported `filter` value, an unsupported query parameter, an invalid `page_token`, a negative `max_page_size`, a malformed account or user ID, or a malformed `Authorization` header (`malformed authorization header`). Also returned when the target user is a service account (`user_is_service_account`), which can't be suspended or reactivated. | | `400 Bad Request` | `failed_precondition` | The user can't be [suspended](/users-api/suspend-user) or [reactivated](/users-api/reactivate-user) in their current state, for example because they're pending confirmation (`user_not_suspendable`, `user_not_reactivatable`). | | `401 Unauthorized` | `unauthenticated` | The request doesn't include a valid access token. The `Authorization` header is missing (`authentication required`), or the token is invalid, expired, or revoked (`invalid access token`). Also returned for tokens that weren't issued by the [OAuth API](/users-api/authorization), such as tokens from the legacy OAuth service. [Request a new access token](/users-api/authorization#request-an-access-token). | | `403 Forbidden` | `permission_denied` | The access token doesn't include the [scope](/users-api/authorization#scopes) required for the endpoint, the account ID in the path doesn't belong to the OAuth application's account (`account_uuid_mismatch`), or the action isn't allowed for the target user, for example when [suspending](/users-api/suspend-user#restrictions) the last remaining owner of an account. | | `404 Not Found` | `not_found` | The user doesn't exist. | | `415 Unsupported Media Type` | `invalid_argument` | The request used a gRPC or Connect content type. The API accepts JSON only. | | `429 Too Many Requests` | `resource_exhausted` | The rate limit was exceeded. See [Rate limits](#rate-limits). | | `500 Internal Server Error` | `internal` | An unexpected error occurred. Retry the request later. | | `503 Service Unavailable` | `unavailable` | The service is temporarily unavailable. Retry the request later. | Requests with a missing, invalid, expired, or revoked access token are rejected before they reach the API. The response is `401 Unauthorized` with the `unauthenticated` code and a `WWW-Authenticate: Bearer` header. When a token was sent but isn't valid, the header also includes `error="invalid_token"`: ```http theme={null} HTTP/2 401 Content-Type: application/json WWW-Authenticate: Bearer realm="1Password", error="invalid_token", error_description="invalid access token" { "code": "unauthenticated", "message": "invalid access token" } ``` A malformed `Authorization` header, for example `Bearer` with no token or a token followed by extra text, returns `400 Bad Request` with the `invalid_argument` code and a `WWW-Authenticate: Bearer` header that includes `error="invalid_request"`. These responses don't include the `RateLimit-*` headers. [Request a new access token](/users-api/authorization#request-an-access-token) if the token has expired. ## Audit events [User lifecycle actions](/events-api/beta/audit-events#user-lifecycle) performed through the Users API are recorded in your account's audit log and identify `Oauth app` as the actor. Suspending a user generates a `user.suspend` audit event, and reactivating a user generates a `user.reactivate` audit event. You can review these events in your account's [audit log](https://support.1password.com/audit-log/) or retrieve them with the [1Password Events API](/events-api). ## User states A user's `state` field reflects their current status in the 1Password account: | State | Meaning | | - | - | | `ACTIVE` | The user has access to the account. Active users can be [suspended](/users-api/suspend-user). | | `SUSPENDED` | The user's access to the account has been suspended. Suspended users can be [reactivated](/users-api/reactivate-user). | | `STATE_UNSPECIFIED` | The user is in another state, for example pending confirmation or account recovery. For these users, the `state` field is omitted from the response, they aren't included in [list users](/users-api/list-users) results, and they can't be suspended or reactivated (`400 Bad Request`, `failed_precondition`). | Users who have been invited but haven't joined the account yet don't have a user ID and aren't available through the API. Additional states may be added in the future. Make sure your integration handles unknown values, and a missing `state` field, gracefully. # Get started with the 1Password Users API Source: https://www.1password.dev/users-api/get-started Learn how to set up an OAuth application and make your first requests to the 1Password Users API. You can use the 1Password Users API as part of your SOC workflows. Allow an external system, such as a security automation platform, to take access remediation actions in 1Password Enterprise Password Manager (EPM) as part of your incident response process. The Users API can be used to list users, retrieve a user's details, and suspend or reactivate a user in a 1Password account. This guide walks you through making your first authenticated request. ## Requirements Before you get started with the Users API, you'll need: * A [1Password Business](https://1password.com/business-security) or [1Password Enterprise Password Manager](https://1password.com/product/enterprise-password-manager) account (not included with 1Password Teams) * Permissions to manage integrations in your 1Password account (for example, as an [owner](https://support.1password.com/groups/#owners), [administrator](https://support.1password.com/groups/#administrators), or member of the [Security group](https://support.1password.com/groups/#security)) > [!WARNING] > > Integrations with the Users API are not currently supported if you use [automated provisioning](https://support.1password.com/provisioning/) with your 1Password account. You can manage actions, like suspending and reactivating users, through your identity provider. ## Step 1: Create an OAuth application in your 1Password account To call the Users API, you'll first create an OAuth application in your 1Password account, which generates the client credentials your integration will use to request an access token. 1. [Sign in](https://start.1password.com/signin) to your 1Password account. 2. Select [**Integrations**](https://start.1password.com/integrations/directory) in the sidebar. If you've set up other integrations in your account, you'll also need to select **Directory** on the Integrations page. 3. Select **OAuth Application**. 4. Select **Client credentials** as the grant type, then select **Next**. 5. Configure your OAuth application: * **Application name**: Enter a name to help you identify the integration. * **Scopes**: Select one or more of the [scopes](/users-api/authorization#scopes) from the "Select scopes" list, according to the access required for your integration: view users, suspend user, and reactivate user. * **Description**: (Optional) Add a description with additional information about your OAuth application. When you're finished, select **Next** to generate your client ID and client secret. 6. Select **Save in 1Password** and choose the vault where you want to save your client credentials. Then select **View integration**. > [!WARNING] > > The client secret is only shown once, so make sure to save it before you continue. The scopes of an OAuth application can't be changed after it's created. If your integration needs different scopes, you can create a new application. Learn more about [how to manage OAuth 2.0 authorization](/users-api/authorization). ## Step 2: Request an access token After you create the OAuth application in your 1Password account, you'll need an access token to make your first call to the Users API. Using [curl](https://curl.se/) on the command line, make a POST call to the [`/v1/oauth/token` endpoint](/users-api/request-access-token). Pass your client ID and client secret in the `--user` option so that curl will encode your credentials and send them in the HTTP Basic header. For example: ```shell theme={null} curl -X POST https://api.1password.com/v1/oauth/token \ --header "Content-Type: application/x-www-form-urlencoded" \ --user ":" \ --data "grant_type=client_credentials" ``` > [!NOTE] > > See the [example token request](/users-api/authorization#example-token-request) in the OAuth authorization guide for more information. A successful response will return an access token, along with the scopes granted to it. For example: ```json theme={null} { "access_token": "op_o_c_H3WVOKGN4B7JXQYCQ6DJFAW5ZU_Q2s4ZmVnaGprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1Njc4OWFi", "token_type": "Bearer", "expires_in": 900, "scope": "users.view users.suspend users.reactivate" } ``` Learn more about [OAuth 2.0 authorization](/users-api/authorization) in the Users API. ## Step 3: Send a test request to the Users API Use your access token in the `Authorization` header to authorize a request to the Users API. Make sure the endpoint you call can be used with the [scopes](/users-api/authorization#scopes) you set for the access token. For example, if your access token is scoped to list all users, you can make a call to the `/v1/accounts/{account}/users` endpoint. Make sure the [base URL](/users-api/conventions#base-urls) you use in the endpoint matches the region of your 1Password account. To limit the number of results per page, use the `max_page_size` query parameter. For example: ```shell theme={null} curl -X GET \ "https://api.1password.com/v1/accounts//users?max_page_size=5" \ --header "Authorization: Bearer " \ --header "User-Agent: /" ``` A successful request will return a JSON response with an array of users. If additional pages of results are available, the response will also include a `next_page_token`. For example: ```json theme={null} { "results": [ { "id": "IR7VJHJ36JHINBFAD7V2T5MP3E", "email": "wendy_appleseed@agilebits.com", "display_name": "Wendy Appleseed", "state": "ACTIVE", "create_time": "2024-01-15T10:30:00Z", "path": "accounts/WX52YXL2MVEPBK43P3R4XMWKXI/users/IR7VJHJ36JHINBFAD7V2T5MP3E" }, ... ], "next_page_token": "CAIQAg" } ``` If you have more pages of results, take the `next_page_token` from the response, then use it with the `page_token` query parameter to fetch the next page of results. Learn more about [pagination](/users-api/conventions#pagination) in the Users API. ## Step 4: Connect your 1Password account to an integration When you can successfully authenticate calls, you can use the API to build your own client that connects your 1Password account with your security automation platform. See the [API reference](/users-api/reference) and [API conventions](/users-api/conventions) to learn more about working with the API. You can also try out one of the connectors built by 1Password partners that leverage the Users API. Check if your preferred platform is in the [list of partner integrations](https://support.1password.com/security-automation/). ## Try out more examples You can use the [API reference](/users-api/reference) to find more code examples for each endpoint. You can also access the interactive API playground on the reference pages for any of the user endpoints (list, get, suspend, and reactivate). Select **Try it** in the endpoint header, enter your own values in the input fields, then send requests directly from the playground. > [!WARNING] > > Requests you send from the API playground are routed through the documentation platform's proxy service. If you prefer to keep your access tokens strictly between your systems and 1Password, copy a code example and run it with your own tools instead. To use the examples with another tool, select the dropdown menu on a code example and choose which language option you want, select copy , then paste the example code into your preferred testing tool. You can also download the OpenAPI specification files for the [Users API ](/static/files/users-api/1password-users-api_v1_2026-10-05.yaml) and the [OAuth API ](/static/files/users-api/1password-oauth-api_v1_2026-10-05.yaml), then use them to feed into code-generation tools, create mock servers, or import into API clients. ## Learn more * [Authorize your integrations using OAuth 2.0](/users-api/authorization) * [API conventions](/users-api/conventions) * [Users API reference](/users-api/reference) * [Get started with 1Password Security Automation](https://support.1password.com/security-automation/#step-2-connect-your-security-automation-platform) # Get a user Source: https://www.1password.dev/users-api/get-user openapi/users_api.yaml GET /v1/accounts/{account}/users/{user} Retrieve a single user in a 1Password account. Retrieve a single user by their user ID. Use this endpoint to look up a user's email address, display name, and current [state](/users-api/conventions#user-states) before taking an action on their account. The `state` field is omitted for users who are neither active nor suspended, such as users who are pending confirmation. To find a user's ID, [list the users](/users-api/list-users) in the account. # Introspect an access token Source: https://www.1password.dev/users-api/introspect-access-token openapi/oauth_api.yaml POST /v1/oauth/introspect Check whether an OAuth 2.0 access token for the 1Password Users API is active and retrieve its scopes and expiry time. Check whether an access token is still active and retrieve its metadata, such as its scopes and expiry time, before you use it. Authenticate with the client credentials of the OAuth application the token was issued to. The response returns `200 OK` for an active token. If a token has expired, been revoked, is unknown, or was issued to a different OAuth application, the response also returns `200 OK`, but with `"active": false` and no other fields, so the response doesn't reveal anything about tokens that don't belong to your application. If the `token` parameter isn't included in the request, the response returns a `400 Bad Request` error. This endpoint is rate limited. Requests that exceed the limit return a `429 Too Many Requests` error. Learn more about [errors](/users-api/conventions#errors) and [rate limits](/users-api/conventions#rate-limits). # List users Source: https://www.1password.dev/users-api/list-users openapi/users_api.yaml GET /v1/accounts/{account}/users Retrieve a list of users in a 1Password account. Use the `filter` query parameter to return only active users (`user.isActive()`) or only suspended users (`user.isSuspended()`). Omit the filter to return both. Users in any other [state](/users-api/conventions#user-states) aren't included. This endpoint supports [pagination](/users-api/conventions#pagination). Use `max_page_size` to set the number of users returned per page (100 by default, up to 1000). Pass the `next_page_token` from each response in the `page_token` query parameter to fetch the next page, along with the same `filter` value. # Reactivate a user Source: https://www.1password.dev/users-api/reactivate-user openapi/users_api.yaml POST /v1/accounts/{account}/users/{user}:reactivate Reactivate a suspended user in a 1Password account. When you reactivate a user, the user's [state](/users-api/conventions#user-states) transitions from `SUSPENDED` to `ACTIVE`, and their access to the account is restored. A successful request returns the updated user with the state set to `ACTIVE`. The `:reactivate` action is idempotent. Using this action on a user who is already active returns the user with no changes to their state. Only suspended users can be reactivated. Reactivating a user who is in another [state](/users-api/conventions#user-states) returns `400 Bad Request` with the `failed_precondition` code and the message `user_not_reactivatable`. This endpoint doesn't accept a request body. # 1Password Users API reference Source: https://www.1password.dev/users-api/reference Complete reference documentation for the 1Password Users API (v1) and the OAuth API used to authorize requests. This reference documents every endpoint in the 1Password Users API (v1), along with the OAuth API endpoints used to authorize requests. Each Users API endpoint page includes the parameters, response schemas, and an interactive playground you can use to send test requests. For more information about authorization and how the Users API works, review the [API conventions](/users-api/conventions). > [!WARNING] > > Integrations with the Users API are not currently supported if you use [automated provisioning](https://support.1password.com/provisioning/) with your 1Password account. You can manage actions, like suspending and reactivating users, through your identity provider. ## Endpoints ### OAuth tokens * [Request an access token](/users-api/request-access-token) * [Introspect an access token](/users-api/introspect-access-token) * [Revoke an access token](/users-api/revoke-access-token) ### Users * [List users](/users-api/list-users) * [Get a user](/users-api/get-user) * [Suspend a user](/users-api/suspend-user) * [Reactivate a user](/users-api/reactivate-user) ## OpenAPI specifications The Users API and OAuth API follow the [OpenAPI 3.1.0 specification.](https://spec.openapis.org/oas/v3.1.0.html) To work with the APIs in another tool, download the specifications: * [1Password Users API (v1) specification ](/static/files/users-api/1password-users-api_v1_2026-10-05.yaml) * [1Password OAuth API (v1) specification ](/static/files/users-api/1password-oauth-api_v1_2026-10-05.yaml) # Request an access token Source: https://www.1password.dev/users-api/request-access-token openapi/oauth_api.yaml POST /v1/oauth/token Request an OAuth 2.0 access token to authorize calls to the 1Password Users API. Exchange the client ID and client secret of your [OAuth application](/users-api/authorization#create-an-oauth-application) for a short-lived access token using the OAuth 2.0 client credentials grant. Send the credentials in the `Authorization` header with HTTP Basic authentication (recommended), or as the `client_id` and `client_secret` form fields. Use one method or the other, not both. The access token expires after 15 minutes and carries the [scopes](/users-api/authorization#scopes) configured for your OAuth application. Include it in the `Authorization` header of Users API requests as `Bearer `. Refresh tokens aren't issued, so request a new access token when the current one expires. Learn how to [encode your client credentials](/users-api/authorization#example-token-request), and review the [rate limits](/users-api/conventions#rate-limits) that apply to the OAuth API endpoints. # Revoke an access token Source: https://www.1password.dev/users-api/revoke-access-token openapi/oauth_api.yaml POST /v1/oauth/revoke Revoke an OAuth 2.0 access token used to authorize calls to the 1Password Users API. Revoke an access token before it expires, such as when your integration finishes a task or if you suspect the token was exposed. Authenticate with the client credentials of the OAuth application the token was issued to. A successful request returns `200 OK` with an empty body. The endpoint also returns `200 OK` if the token is already expired, revoked, unknown, or issued to a different OAuth application, so revocation requests are safe to retry. To revoke all tokens issued to an integration at once, [revoke the OAuth application](/users-api/authorization#revoke-the-integration-in-your-1password-account) in your 1Password account. # Suspend a user Source: https://www.1password.dev/users-api/suspend-user openapi/users_api.yaml POST /v1/accounts/{account}/users/{user}:suspend Suspend a user in a 1Password account. When you suspend a user, the user's [state](/users-api/conventions#user-states) transitions from `ACTIVE` to `SUSPENDED`, and their access to the account is removed. A successful request returns the updated user with the state set to `SUSPENDED`. The `:suspend` action is idempotent. Using this action on a user who is already suspended returns the user with no changes to their state. Only active users can be suspended. Suspending a user who is in another [state](/users-api/conventions#user-states), such as pending confirmation, returns `400 Bad Request` with the `failed_precondition` code and the message `user_not_suspendable`. This endpoint doesn't accept a request body. ## Restrictions The following users can't be suspended from a 1Password account: * People in the [External Account Managers group](https://support.1password.com/msp-technician-permissions/). * The last remaining owner of an account. Attempting to suspend the last owner returns `403 Forbidden` with the message `Cannot suspend user: no_owner_remain`. Your integration should handle these outcomes gracefully (for example, log the failure and notify an administrator). # 1Password for VS Code Source: https://www.1password.dev/vscode 1Password for VS Code provides you with a set of tools to integrate your development workflow with 1Password, powered by [1Password CLI](/cli/). ## Requirements Before you can use the VS Code extension, you'll need to: * Install 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux). * Install the latest version of [1Password CLI](/cli/get-started/#step-1-install-1password-cli). * [Integrate 1Password CLI with the 1Password app.](/cli/get-started/#step-2-turn-on-the-1password-desktop-app-integration) ## Installation You can install the 1Password for VS Code extension through the VS Code Marketplace or GitHub. > [tab] VS Code Marketplace > > The best way to install the 1Password for VS Code extension is through the VS Code Marketplace because it keeps the extension up to date automatically. > > Install from the Marketplace > [tab] GitHub > > You can also install 1Password for VS Code directly from GitHub. This option works well if you don't want automatic updates, or you want to use an older version of the extension. The GitHub Releases page lists all previous releases. > > Releases include a [VSIX file](https://code.visualstudio.com/docs/editor/extension-marketplace#_install-from-a-vsix) that you can install in VS Code. > > Install from GitHub After installation, the extension prompts you to choose a 1Password account and vault. > [!WARNING] > > You must select a 1Password account and vault to use the extension's features. To select an account and vault later: 1. Open the [**Command Palette**.](https://code.visualstudio.com/api/ux-guidelines/command-palette) 2. Enter `1Password: Choose account` to select a 1Password account. 3. Enter `1Password: Choose vault` to select a vault. ## Extension settings 1Password for VS Code has a few settings you can configure. To access the 1Password for VS Code settings: 1. Go to **Code** > **Preferences** > **Settings**. 2. Scroll to or search for **1Password**. The following table lists the extension settings. | Name | Setting ID | Default Value | Details | | - | - | - | - | | **Items: Cache Values** | `1password.items.cacheValues` | `true` | Use CLI cache when performing operations. Learn more about [caching](/cli/reference/#cache-item-and-vault-information). | | **Items: Password Recipe** | `1password.items.passwordRecipe` | `"letters,digits,symbols,32"` | The recipe to use when generating passwords. Learn more about [password recipes](/cli/reference/management-commands/item/#generate-a-password). | | **Items: Use Secret References** | `1password.items.useSecretReferences` | `true` | Use secret reference syntax for storing and retrieving values. Learn more about [secret references](/cli/secret-reference-syntax/). | | **Editor: Suggest Storage** | `1password.editor.suggestStorage` | `true` | Suggest storing a value when it looks like a secret. | | **Debug: Enabled** | `1password.debug.enabled` | `false` | Log debugger data. Reload required. | ## Feature The best defense against secrets leaking from your code is for them not to be in your code to start with. To help with this, we've introduced secret references, and 1Password for VS Code is built with them in mind. [Learn more](/cli/secret-reference-syntax/) and read further down to see how we're making it easy to use secret references in VS Code. By default, all operations use secret references when retrieving and storing item fields. If you'd rather not use secret references, you can turn off the "Items: Use Secret References" setting to instead insert or keep the raw field values. You can use the 1Password VS Code plugin to: * [Save in 1Password](#save-in-1password) * [Detect secrets](#detect-secrets) * [Get values from 1Password](#get-values) * [Create secrets](#create-secrets) * [Preview secret references](#preview-secret-references) * [Open secrets in 1Password](#open-secrets-in-1password) ### Save in 1Password You can use the 1Password extension to save items in 1Password from code in your document: 1. Select an exposed secret in a file. 2. Open the [**Command Palette**.](https://code.visualstudio.com/api/ux-guidelines/command-palette) 3. Enter `1Password: Save in 1Password`. 4. Provide a name for the item. The extension prompts you to fill out the item name and a field from each selection. It automatically tries to infer the field label if it looks like an email, URL, or credit card. After creating the item (and saving it in 1Password), the extension replaces the selection with a secret reference pointing to that item and field. > [!TIP] > > You can save multiple items at the same time by selecting more than one item in the file before opening the [Command Palette.](https://code.visualstudio.com/api/ux-guidelines/command-palette) [Learn more about multiple selections in VS Code.](https://code.visualstudio.com/docs/editor/codebasics#_multiple-selections-multicursor) ### Detect secrets 1Password for VS Code automatically watches for bits of code that look like secrets and offers to store them in 1Password. The behavior varies slightly between regular files and `.env` files: * It checks for strings that match known secret patterns across all regular files. * It inspects `.env` files for keywords to make an educated guess if the value is a secret. When the extension finds a match, it displays a "Save in 1Password" [CodeLens](https://learn.microsoft.com/en-us/visualstudio/ide/find-code-changes-and-other-history-with-codelens) above the line that you can select to save the secret in 1Password. You can control this feature with the "Editor: Suggest Storage" [setting](#extension-settings). ### Get values from 1Password The 1Password for VS Code extension allows you to use values that already exist in 1Password in your code: 1. Open the [**Command Palette**.](https://code.visualstudio.com/api/ux-guidelines/command-palette) 2. Enter `1Password: Get from 1Password`. 3. Enter the item name or UUID. 4. Select the field to use. The extension inserts a secret reference pointing to that item and field. > [!TIP] > > Already know the vault, item, and field you want to use? Start typing `secret reference` or `op://`. The extension provides a code snippet for you to fill out the individual parts of a secret reference. ### Create secrets You can create secrets for your project from VS Code: 1. Place your cursor in the document. 2. Open the [**Command Palette**.](https://code.visualstudio.com/api/ux-guidelines/command-palette) 3. Type `1Password: Generate password` in the Command Palette. 4. Enter a name for your item. The 1Password VS Code extension creates the item with a randomly generated password and inserts a secret reference in the document pointing to that item and field. > [!TIP] > > You can use the "Editor: Password Recipe" [setting](#extension-settings) to customize the recipe 1Password for VS Code uses to generate passwords. ### Preview secret references 1Password for VS Code analyzes open documents and looks for secret references, underlining each one it finds. It also allows you to preview individual secret references or load the secret reference values in a file. To inspect the details of a secret reference: 1. Hover your cursor over the secret reference. The secret reference details appear in a VS Code [CodeLens.](https://learn.microsoft.com/en-us/visualstudio/ide/find-code-changes-and-other-history-with-codelens) The [CodeLens](https://learn.microsoft.com/en-us/visualstudio/ide/find-code-changes-and-other-history-with-codelens) window only displays non-sensitive information about the secret, like the creation date. It doesn't show values of sensitive fields (such as passwords and SSH keys). To preview what a file looks like with its secret references converted to real values: 1. Select the unlock icon () found in the top-right of a document. This opens an unsaved copy of your document with the secret references replaced with real values, which you can then save or delete. > [!TIP] > > On Mac and Linux, you can also show a file's secrets through the Command Palette using the "1Password: Preview with secrets" command. ### Open secrets in 1Password You can open a secret reference in the 1Password application by holding Option, then selecting the secret reference. Alternatively, you can hover your cursor over the secret reference, then select **Follow link** in the [CodeLens](https://learn.microsoft.com/en-us/visualstudio/ide/find-code-changes-and-other-history-with-codelens) window. ## Contributing and feedback 1Password for VS Code is an open source project. If you discover a problem or want to share feedback, [open a GitHub issue.](https://github.com/1Password/op-vscode/issues/new) Everyone is welcome to contribute to the extension. Refer to the [contribution guidelines](https://github.com/1Password/op-vscode/blob/main/CONTRIBUTING.md) for more information. # 1Password Developer Watchtower Source: https://www.1password.dev/watchtower > [!TIP] > > If you're an owner or administrator of a 1Password Business account, learn more about the [developer secrets discovery report](https://support.1password.com/developer-secrets-report/). 1Password Developer Watchtower can check for developer secrets stored on your local disk, such as SSH keys that are unencrypted or that use outdated cryptography, and `.env` files that contain plaintext variables. Developer Watchtower will alert you about secrets that don't follow best practices, so you can mitigate secrets risk and improve the security of your workflow. 1Password only looks for developer secrets in defined locations on your local disk. Secret values are never collected or revealed, and no one at 1Password can see or access your data. ![Developer Watchtower showing several discovered insecure SSH keys and .env files with plaintext secrets.](/static/img/developer-watchtower-results.png) ## Requirements Before you can use Developer Watchtower, you'll need to: * [Sign up for 1Password.](https://1password.com/pricing/password-manager) * Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux). * Install and sign in to [1Password CLI](/cli/get-started) (only required for Windows). [Video on how to keep SSH keys safe with 1Password Developer Watchtower.](https://www.youtube.com/embed/OOy-6zjUyXY) ## Step 1: Turn on local disk scanning 1. In the 1Password desktop app, select **Developer** in the sidebar, then select **View Watchtower**.\ Or, navigate to **Settings** > [**Developer**](onepassword://settings/developers) and go to the Watchtower section. 2. Choose the types of secrets you want 1Password to check for: * Select **SSH keys** to scan your `~/.ssh` directory for insecure and unencrypted SSH keys. * Select **.env files** to scan your local disk for `.env` files that contain plaintext secrets. Then [view your results](#step-2-view-your-results-in-watchtower) in Developer Watchtower. Local disk scanning doesn't collect or reveal secret values. Learn more about local disk scanning for [SSH keys](#about-ssh-key-scanning) and [`.env` files](#about-env-file-scanning) in Developer Watchtower. > [!NOTE] > > If you use 1Password as part of an organization, local disk scanning may be controlled by an account policy. > > You can go to **Settings** > [**Developer**](onepassword://settings/developers) > **Watchtower** to check if there's a message that local disk scanning is managed by your organization. Contact your administrator to learn more. ## Step 2: View your results in Watchtower After local disk scanning is turned on, Developer Watchtower will list any [SSH keys](#take-action-on-ssh-key-alerts) and [`.env` files](#import-plaintext-secrets-from-local-env-files) found on disk, according to your settings. You can import the identified keys and environment variables into 1Password to keep them secure, and remove the plaintext secrets from your local disk. ### Take action on SSH key alerts SSH key alerts are listed according to the attributes with the highest security impact. To act on an alert: 1. Select an SSH key item in the list to see more information about the issue. 2. Select the down arrow to the right of the item to see a list of available actions. 3. Remediate issues based on the type of alert for each key. Use the following table for more information about SSH key alerts and remediation: | Alert message | Description | Recommended Action | | - | - | - | | Insecure key type | An SSH key in an outdated format that's known to be vulnerable. | Remove the public key from the `authorized_keys` file of any server and service you've used it with. Then generate a new, secure SSH key in 1Password and delete the insecure key file from disk. [Learn more about insecure keys.](#insecure-key-type) | | This key is unencrypted | An SSH key stored in plaintext on disk. | Import the key into 1Password and remove the unencrypted copy from your disk, or use the `ssh-keygen` command to encrypt the file on disk. [Learn more about unencrypted keys.](#unencrypted-key) | | Import into 1Password | An SSH key that's encrypted and supported in 1Password but hasn't been imported yet. | Import the key into 1Password, then delete the redundant copy of your SSH key on disk. [Learn more about importing keys.](#import-into-1password) | | Already exists in 1Password | An SSH key you've already saved in 1Password. | Delete the redundant copy of your SSH key on disk and keep the key you've already secured in 1Password. [Learn more about duplicate keys.](#already-exists-in-1password) | | N/A (no message) | An SSH key that isn't supported in 1Password. | Generate a new SSH key in 1Password if you want to use it with the 1Password SSH Agent. [Learn more about unsupported keys.](#unsupported-key) | Learn more about [how SSH key scanning works](#about-ssh-key-scanning). ### Import plaintext secrets from local `.env` files > [!NOTE] > > This feature is being rolled out in stages and requires 1Password version 8.12.32 or later. If you don't see the option to import `.env` files with plaintext secrets in Developer Watchtower, you can [update to the latest version](https://support.1password.com/update-1password/) of the desktop app or [switch to the beta or nightly release channel](https://support.1password.com/betas/). Developer Watchtower will alert you about any `.env` files it finds on disk that contain plaintext secrets. Use Developer Watchtower to import those secrets into new or existing [1Password Environments](/environments) and remove the original `.env` files from your local disk. You can then securely access the secrets you’ve stored in your 1Password Environments without writing plaintext secrets to disk. Learn more about [how `.env` file scanning works](#about-env-file-scanning). > [tab] Mac > > > [!WARNING] > > > > When you use Developer Watchtower to import an environment file, the original `.env` file is removed from your local disk. > > 1. In the 1Password desktop app, select **Developer** in the sidebar, then select **View Watchtower**. > > 2. Select an item in the list to see more information about the project secrets and variables in the `.env` file. > > 3. Select **Import** on an item to import the secrets into 1Password. > > 4. Choose if you want to import your environment secrets into a new or existing Environment and if you want to mount the file: > > 1. Select **New environment** to create a new 1Password Environment. Enter a name for the Environment and select the 1Password account you want to save the Environment in. > > 2. Select **Existing environment** if you already have a 1Password Environment you want to import the secrets into. Choose your Environment from the list. > > To mount the environment file, make sure **Mount .env file at** is selected. > > 5. Select **Import environment**. > > 1Password will import the environment variables from your `.env` file into a new or existing Environment as secrets, then remove the original `.env` file from your local disk. If you also mounted the environment file, 1Password will replace it with a [locally mounted `.env` file](/environments/local-env-file) at the same path. > [tab] Windows > > > [!WARNING] > > > > When you use Developer Watchtower to import an environment file, the original `.env` file is removed from your local disk. > > > [!NOTE] > > > > You'll need to install [1Password CLI](/cli/get-started) to securely access the secrets you store in 1Password Environments from your local development projects. > > 1. In the 1Password desktop app, select **Developer** in the sidebar, then select **View Watchtower**. > > 2. Select an item in the list to see more information about the project secrets and variables in the `.env` file. > > 3. Select **Import** on an item to import the secrets into 1Password. > > 4. Choose if you want to import your environment secrets into a new or existing Environment: > > 1. Select **New environment** to create a new 1Password Environment. Enter a name for the Environment and select the 1Password account you want to save the Environment in. > > 2. Select **Existing environment** if you already have a 1Password Environment you want to import the secrets into. Choose your Environment from the list. > > Then select **Import**. 1Password will import the environment variables from your `.env` file into a new or existing Environment as secrets and remove the original file containing plaintext secrets from your local disk. > > 5. Select **Go to Environment** to open the Environment where you imported your secrets. > > 6. Under "Connect to", select **View run command** next to 1Password CLI. > > You'll see an [`op run`](/cli/secret-references#with-op-run) command with your Environment ID. For example: > > ```shell theme={null} > op run --environment=fxx14mc6e2xuilwf5m32x3og3i -- > ``` > > 7. Copy and paste the `op run` command into your terminal. Replace `` with the command you use to start your project. For example: > > ```shell theme={null} > op run --environment=fxx14mc6e2xuilwf5m32x3og3i -- npm run dev > ``` > > 8. Run the command. If 1Password prompts you to allow your terminal app to get 1Password CLI access, authorize the request. > > You can continue to use the `op run --environment` command to access the secrets stored in your 1Password Environment from your local development project. > [tab] Linux > > > [!WARNING] > > > > When you use Developer Watchtower to import an environment file, the original `.env` file is removed from your local disk. > > 1. In the 1Password desktop app, select **Developer** in the sidebar, then select **View Watchtower**. > > 2. Select an item in the list to see more information about the project secrets and variables in the `.env` file. > > 3. Select **Import** on an item to import the secrets into 1Password. > > 4. Choose if you want to import your environment secrets into a new or existing environment and if you want to mount the file: > > 1. Select **New environment** to create a new 1Password Environment. Enter a name for the environment and select the 1Password account you want to save the environment in. > > 2. Select **Existing environment** if you already have a 1Password Environment you want to import the secrets into. Choose your environment from the list. > > To mount the environment file, make sure **Mount .env file at** is selected. > > 5. Select **Import environment**. > > 1Password will import the environment variables from your `.env` file into a new or existing Environment as secrets, then remove the original `.env` file from your local disk. If you also mounted the environment file, 1Password will replace it with a [locally mounted `.env` file](/environments/local-env-file) at the same path. ## About SSH key scanning > [!WARNING] > > If you use 1Password as part of an organization that has a local disk scanning policy enabled, some metadata for [unencrypted SSH private keys](#unencrypted-key) may be included in a [developer secrets discovery report](https://support.1password.com/developer-secrets-report/). > > The report is only available to people in the [Owners](https://support.1password.com/groups/#owners) and [Security](https://support.1password.com/groups/#security) groups of the account. Secret values are never collected or revealed. Developer Watchtower scans your `$HOME` directory for SSH keys in the following location and formats: | Location | Credential type | | - | - | | `~/.ssh` (up to 3 nested directories) | SSH private keys in OpenSSH, PKCS#8, or PKCS#1 format | 1Password doesn't follow symlinks or traverse file systems (for example, an external drive mounted at `~/.ssh/other` will be skipped). Files over 1 MiB (mebibyte) in size are also skipped. If any SSH keys are found within these parameters, they'll be added to Developer Watchtower to alert you to security issues and provide recommendations to improve your SSH key management. ### Ignore files If you want 1Password to ignore specific files when checking for developer secrets, you can create a `.ignore` file in your SSH folder. Then add entries to the `~/.ssh/.ignore` file to specify which files 1Password should ignore. For example: ```text Example entries in ~/.ssh/.ignore file theme={null} test_key *_development ``` ### SSH key alerts #### Insecure key type An insecure SSH key is a critical security issue that needs to be addressed. Insecure keys are vulnerable to being cracked, which can provide attackers with the ability to infiltrate and compromise servers. Insecure keys include: * DSA keys * RSA keys less than 2048 bits in strength [OpenSSH](https://lists.mindrot.org/pipermail/openssh-unix-announce/2024-January/000156.html) is removing support for these insecure key types, along with major developer platforms like [GitHub](https://github.blog/2021-09-01-improving-git-protocol-security-github/) and GitLab. If Developer Watchtower alerts you to an insecure SSH key, it's imperative that you remove the SSH key file from your disk *and* from the `authorized_keys` file of every server it's used with. First, remove the insecure key from the `authorized_keys` file of every server, or from any service, where it's used. Next, [generate a new, secure SSH key in 1Password](/ssh/manage-keys#generate-an-ssh-key) and use the new key to replace the insecure key anywhere it was used. Then, in Developer Watchtower, select the action menu for the insecure key and choose **Delete SSH key from disk** to permanently remove the key from disk. #### Unencrypted key A private key file stored in plaintext is a security vulnerability and provides [an easy target for malware.](https://www.scmagazine.com/news/github-npm-registry-abused-to-host-ssh-key-stealing-malware) Encrypting your SSH private keys with passphrases provides another layer of protection and is a common practice supported by SSH clients. If Developer Watchtower alerts you to an unencrypted key on your local disk, you can choose one of the following options from the action menu: * **Import**: When you import an SSH key into 1Password, it's [automatically encrypted for you](https://support.1password.com/1password-security/#encryption). After you import the key into 1Password, you can permanently remove the redundant copy from your disk. Select the action menu for the unencrypted key in Developer Watchtower and choose **Delete SSH key from disk**. * **Copy Encryption Command**: If you prefer to keep a copy on disk, you should encrypt the key file with a passphrase. This option copies the `ssh-keygen` command to your clipboard, including the path to your key. You can run the command in your terminal app: ```shell theme={null} ssh-keygen -pf path/to/your/key ``` The `-pf` flag prompts you to create a passphrase and specify the private key file you want to encrypt. #### Import into 1Password Storing your SSH keys in 1Password allows you to securely authenticate all your Git and SSH commands from 1Password using the [1Password SSH Agent](/ssh/agent). Your private keys never leave 1Password, are never stored locally, and are never used without your consent. Learn more [about 1Password SSH Agent security](/ssh/agent/security). If Developer Watchtower detects an SSH key that is both encrypted and a [supported key type](/ssh/manage-keys#supported-ssh-key-types), you can import the key into 1Password. Select the down arrow on the right of the item, then select **Import**. After you import the SSH key, you can [remove the redundant copy of the key](#already-exists-in-1password) from your local disk. #### Already exists in 1Password 1Password compares the public fingerprint of the SSH key on your local disk with the fingerprints of your SSH Key items in 1Password to determine if you've already saved the key there. If Developer Watchtower indicates that a key in your local `~/.ssh` folder has already been saved 1Password, you can remove the redundant copy of the SSH key on disk. Select the item's action menu and choose **Delete SSH key from disk** to permanently remove the key from disk. #### Unsupported key An SSH key that isn't supported in 1Password can't be imported. Check the list of [supported SSH key types](/ssh/manage-keys#supported-ssh-key-types) for more information. If Developer Watchtower lets you know that a key on your local disk is unsupported, consider [generating a new SSH key](/ssh/manage-keys#generate-an-ssh-key) if you want to use it with the [1Password SSH Agent](/ssh/agent). You may also be able to convert some keys to a format 1Password does support. For example, 1Password doesn't support keys in the PuTTY format (`.ppk`), but [PuTTYgen](https://www.puttygen.com/) lets you export your PPK keys into the OpenSSH format, which is supported. ## About `.env` file scanning > [!WARNING] > > If you use 1Password as part of an organization that has a local disk scanning policy enabled, some metadata for `.env` files containing plaintext secrets may be included in a [developer secrets discovery report](https://support.1password.com/developer-secrets-report/). > > The report is only available to people in the [Owners](https://support.1password.com/groups/#owners) and [Security](https://support.1password.com/groups/#security) groups of the account. Secret values are never collected or revealed. Developer Watchtower scans your `$HOME` directory for `.env` files that contain plaintext secrets in the following locations: * `~/code` * `~/dev` * `~/Developer` - `~/git` - `~/projects` - `~/Projects` * `~/repos` * `~/src` * `~/work` It also checks for any variant matching the `^\.env(\..+)?$` pattern, such as `.env`, `.env.local`, or `.env.production`. [Check which libraries are compatible with the use of local `.env` files in 1Password Environments.](/environments/local-env-file#dotenv-library-compatibility) 1Password only provides alerts for `.env` files that contain values likely to be sensitive, like API keys or tokens. The following files aren't surfaced: * Files that contain only non-sensitive values, such as `NODE_ENV=development`. * Files whose values are already managed by 1Password. When you use Developer Watchtower to import an environment file with plaintext secrets, 1Password removes the original `.env` file. You can then securely access the secrets you’ve stored in your 1Password Environment without writing plaintext secrets to disk. To access environment variables during local development: * On Mac and Linux: Connect a [local `.env` file](/environments/local-env-file) to your Environment. When you mount an existing `.env` file from your local disk, 1Password replaces the original file at the same path without storing the plaintext contents on your device. You can also create a local `.env` file path from your Environment at any time. * On Windows: Use [1Password CLI](/cli/get-started) with the `op run --environment` command to access the secrets you stored in your Environment from your local development projects. Learn more about how [Environments](/environments) and [locally mounted `.env` files](/environments/local-env-file#how-it-works) work in 1Password. ## Learn more * [1Password for SSH & Git](/ssh) * [Manage SSH keys in 1Password](/ssh/manage-keys) * [1Password Environments](/environments) * [Access secrets from 1Password through local .env files](/environments/local-env-file) * [Use Watchtower to find account details you need to change](https://support.1password.com/watchtower/) # Add the Save in 1Password button to your website Source: https://www.1password.dev/web/add-1password-button-website When you add the Save in 1Password button to your website, visitors can easily save their sign-in details, credit cards, or crypto wallets to their 1Password account in one step. If you set up an [integration with 1Password](https://1password.com/partnerships), the button can also be used to save API keys. The Save in 1Password button on your site communicates directly with 1Password in the browser, so no unencrypted information leaves the customer's browser. ![](https://mintcdn.com/ab-634991b8/9g9fZmRyYnb5i5sQ/static/img/save-in-1password-button.png?fit=max\&auto=format\&n=9g9fZmRyYnb5i5sQ\&q=85\&s=153aba1ecd62e8f674f94933d5b8fa79) ## Add the button to your site To add the button to your site, you'll need to install the Save in 1Password button, build a save request, and import the button into your file with the required attributes and values. The button is disabled by default. When the page loads, 1Password will check for the button and make it available to the user. Item URLs, if applicable, are determined by 1Password, so a login item can only be filled for the domain on which it was saved. The button element specifies the type of item to create and the information it'll contain. The information is a Base64-encoded save request in JSON format. ### Install the button To get started, install the [Save in 1Password button](https://www.npmjs.com/package/@1password/save-button) using your preferred package manager: ```shell npm theme={null} npm install @1password/save-button --save-dev ``` ```shell Yarn theme={null} yarn add @1password/save-button -D ``` Then import the package into your HTML file. For example: ```html theme={null} ``` ### Build a save request The save request needs these values: | Field | Type | Description | | - | - | - | | `title` | string | The suggested title for the item to be saved. | | `fields` | array | Each object in the array has these properties:
    • `autocomplete` (string): The type of field to fill.
    • `value` (string): The value to be filled in the field Use the autocomplete field name and values defined in the Autofill section of the [HTML Living Standard.](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill) The custom autocomplete fields for Crypto Wallet items are `crypto-address` for wallet address and `crypto-recovery-seed` for recovery phrase. The custom autocomplete fields for Login items are `one-time-code` for one-time password fields and `recovery-code` for an individual masked recovery code.
    | | `notes` (optional) | string | Notes to save with the item. These can be formatted with Markdown. | For example: ```javascript theme={null} const saveRequest = { title: "ACME Credit Card", fields: [ { autocomplete: "cc-name", value: "Wendy J. Appleseed", }, { autocomplete: "cc-number", value: "4111111111111111", }, { autocomplete: "cc-exp", value: "202512", }, { autocomplete: "cc-csc", value: "123", }, { autocomplete: "cc-type", value: "visa", }, { autocomplete: "street-address", value: "512 Main Street", }, { autocomplete: "address-level2", value: "Cambridge", }, { autocomplete: "address-level1", value: "MA", }, { autocomplete: "postal-code", value: "12345", }, { autocomplete: "country", value: "US", }, ], notes: "Plain text. You can use [Markdown](https://support.1password.com/markdown/) too.", }; ``` To encode the example above to a Base64 string in JSON format, use the built-in `encodeOPSaveRequest` function: ```javascript theme={null} const encodedSaveRequest = encodeOPSaveRequest(saveRequest); ``` Then copy and paste the resulting Base64-encoded string as the `value` attribute of the Save in 1Password button. For example: ``` "eyJ0aXRsZSI6IkFDTUUgQ3JlZGl0IENhcmQiLCJmaWVsZHMiOlt7ImF1dG9jb21wbGV0ZSI6ImNjLW5hbWUiL CJ2YWx1ZSI6IldlbmR5IEouIEFwcGxlc2VlZCJ9LHsiYXV0b2NvbXBsZXRlIjoiY2MtbnVtYmVyIiwidmFsdW UiOiI0MTExMTExMTExMTExMTExIn0seyJhdXRvY29tcGxldGUiOiJjYy1leHAiLCJ2YWx1ZSI6IjIwMjUxMiJ 9LHsiYXV0b2NvbXBsZXRlIjoiY2MtY3NjIiwidmFsdWUiOiIxMjMifSx7ImF1dG9jb21wbGV0ZSI6ImNjLXR5 cGUiLCJ2YWx1ZSI6InZpc2EifSx7ImF1dG9jb21wbGV0ZSI6InN0cmVldC1hZGRyZXNzIiwidmFsdWUiOiI1M TIgTWFpbiBTdHJlZXQifSx7ImF1dG9jb21wbGV0ZSI6ImFkZHJlc3MtbGV2ZWwyIiwidmFsdWUiOiJDYW1icm lkZ2UifSx7ImF1dG9jb21wbGV0ZSI6ImFkZHJlc3MtbGV2ZWwxIiwidmFsdWUiOiJNQSJ9LHsiYXV0b2NvbXB sZXRlIjoicG9zdGFsLWNvZGUiLCJ2YWx1ZSI6IjEyMzQ1In0seyJhdXRvY29tcGxldGUiOiJjb3VudHJ5Iiwi dmFsdWUiOiJVUyJ9XSwibm90ZXMiOiJQbGFpbiB0ZXh0LiBZb3UgY2FuIHVzZSBbTWFya2Rvd25dKGh0dHBzO i8vc3VwcG9ydC4xcGFzc3dvcmQuY29tL21hcmtkb3duLykgdG9vLiJ9" ``` Or update the Base64-encoded value of the button: ```javascript theme={null} document .querySelector("onepassword-save-button") .shadowRoot.querySelector("button[data-onepassword-save-button]") .setAttribute("value", encodedSaveRequest); ``` ### Add the button to your page Add the Save in 1Password button to your page with the two required attributes: `data-onepassword-type` and `value`. You can also add optional attributes to change the button language, color, theme, or padding: `lang`, `class`, `data-theme`, or `padding`. | Attribute | Value | | - | - | | `data-onepassword-type` | The type of item the button will create: `credit-card`, `login`, or `crypto-wallet`. | | `value` | The Base64-encoded [save request](#build-a-save-request). | | `lang` (optional) | The language code for [one of the supported languages](#appendix-supported-language-codes). If no language attribute is provided, the package will determine the browser language using the [NavigatorLanguage Web API.](https://www.science.co.il/language/Locale-codes.php) If the browser language isn't supported, the package will default to English. | | `class` (optional) | The color of the button: `black` or `white`. If no class attribute is provided, the button color will default to blue. | | `data-theme` (optional) | The optimized button theme for a website with a light or dark background: `light` or `dark`. If no data-theme attribute is provided, the button will default to the light theme. | | `padding` (optional) | The button padding: `normal` or `compact` or `none`. If no value is provided, or if the value is `normal`, the button padding will default to 24 pixels. If the value is `compact`, the padding will be 16 pixels. If the value is `none`, the padding will be 0 pixels. | For example: ```html theme={null} ``` If you're building a single-page app, you may need to call the `activateOPButton()` function to activate the button. This will dispatch a custom event on the page to tell 1Password to enable the Save in 1Password button. ## Appendix: Supported language codes | Language | Code | Language | Code | | - | - | - | - | | English | `en` | Japanese | `ja` | | French | `fr` | Korean | `ko` | | German | `de` | Portuguese | `pt` | | Italian | `it` | Russian | `ru` | | Chinese, simplified | `zh-CN` | Spanish | `es` | | Chinese, traditional | `zh-TW` | | | # Design your website to work best with 1Password Source: https://www.1password.dev/web/compatible-website-design 1Password is designed to generate, fill, and save passwords on most websites. You shouldn't have to do anything special to support 1Password on your website, as long as you develop your pages according to best practices. This will make the intention of each page element clear. 1Password will have an easier time understanding your page even when you make changes to it. > [!TIP] > > 1Password also supports [saving and signing in with passkeys](https://support.1password.com/save-use-passkeys/). Learn how to [design your website to work with passkeys.](https://passkeys.dev/docs/intro/what-are-passkeys/) ## Build logical forms If 1Password has trouble saving or filling on your site, make sure you're following best practices with your forms: * Use a unique element `id` or `name` for every field and form. * Enclose `` fields in `
    ` elements. * Group related fields (like usernames and passwords) together in the same `` element. * Separate unrelated fields into different `` elements. For example, put registration and sign-in fields in different forms. * Set the correct `method` on the form. The 1Password browser extension will automate a button click with `element.click()`. If your form doesn't specifically handle this case, the form may be submitted with `get`, which bypasses other listeners and could unintentionally leak credentials in the URL. ### Ignore offers to save or fill specific fields If you don't want 1Password to offer to save or fill on a field, you can use the `data-1p-ignore` or `data-op-ignore` attribute to tell 1Password it should ignore the field. For example: ```html theme={null} ``` If your tools don't accept data attributes that start with a digit, you can use `data-op-ignore` instead. ### Ignore offers to save or fill an entire page If you don't want 1Password to offer to save or fill for a whole page, add the `data-1p-ignore` or `data-op-ignore` attribute to the `` element. 1Password will skip every field on the page, so you don't need to mark inputs one by one. ```html theme={null} ``` ### Password change and reset forms On password change forms, ask for the current password, the new password, and a password confirmation in that order. This makes the intention of each form element clear. For example: ```html theme={null} ``` On password reset and "forgot password" forms, include the username for the password that is being reset. This helps 1Password determine which item to update with the new password. For example: ```html theme={null}
    ``` ## Provide password requirements 1Password can generate passwords that fit your website's password requirements. 1Password uses Apple's [Password Manager Resources](https://github.com/apple/password-manager-resources) to identify a website's unique password rules along with the [shared credential backends](https://github.com/apple/password-manager-resources/blob/main/quirks/websites-with-shared-credential-backends.json) file in the same repository for multiple domains that share the same account system. To provide the rules 1Password will use to generate smart passwords, add the following attributes to each `` element: * `passwordrules` * `minlength` * `maxlength` [Learn how to create a `passwordrules` attribute.](https://developer.apple.com/password-rules/) ## Embrace accessibility Making your website accessible benefits everyone who uses your website. As a bonus, making your site accessible provides clues to 1Password as well. When examining a page, 1Password can take advantage of accessibility cues to locate fields: * Give every field a `