How to load secrets and environment variables from 1Password programmatically using the official @1password/sdk (JavaScript/TypeScript). Use this skill whenever code needs to read a 1Password secret, resolve an op:// reference, fetch many secrets at once, discover the fields/sections of a 1Password item (e.g. to import API keys), or read a 1Password Environment — even if the user doesn't name the SDK explicitly. Triggers on: "@1password/sdk", "op://", "OP_SERVICE_ACCOUNT_TOKEN", "DesktopAuth", "resolve a secret from 1Password", "1Password service account", "1Password Environments", "fetch API keys from 1Password", or wiring 1Password into a Node/Bun/TypeScript app. Prefer this in-process SDK over shelling out to the `op` CLI unless the task specifically needs the user's interactive `op signin` session.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
How to load secrets and environment variables from 1Password programmatically using the official @1password/sdk (JavaScript/TypeScript). Use this skill whenever code needs to read a 1Password secret, resolve an op:// reference, fetch many secrets at once, discover the fields/sections of a 1Password item (e.g. to import API keys), or read a 1Password Environment — even if the user doesn't name the SDK explicitly. Triggers on: "@1password/sdk", "op://", "OP_SERVICE_ACCOUNT_TOKEN", "DesktopAuth", "resolve a secret from 1Password", "1Password service account", "1Password Environments", "fetch API keys from 1Password", or wiring 1Password into a Node/Bun/TypeScript app. Prefer this in-process SDK over shelling out to the `op` CLI unless the task specifically needs the user's interactive `op signin` session.
1Password JavaScript/TypeScript SDK
The official @1password/sdk reads secrets from 1Password in-process — no op
CLI subprocess, no op signin. It authenticates directly (service-account token
or desktop biometric) and resolves op://vault/item/field references to their
values. Use it whenever an app needs to pull credentials at runtime.
Why prefer the SDK over the op CLI: one auth model, one authorization
event (the CLI + SDK each prompt separately, so mixing them double-prompts),
no external binary to depend on, batched resolution, and structured per-reference
errors. The CLI's only edge is using a user's existing interactive op signin
session — the SDK cannot do that; it needs its own auth (below).
Install
bun add @1password/sdk # or npm install @1password/sdk
For 1Password Environments (the environments API), the stable release does
NOT include it — you need the beta:
bun add @1password/sdk@0.4.1-beta.1
Authenticate — create the client once
Every operation goes through a client. integrationName and
integrationVersion are required (they identify your app in 1Password's
audit log — note they do NOT change the desktop authorization prompt, which
always shows the calling process).
import { createClient, DesktopAuth } from"@1password/sdk";
// Service account — headless / CI / servers. No prompt, no desktop app.const client = awaitcreateClient({
auth: process.env.OP_SERVICE_ACCOUNT_TOKEN!,
integrationName: "my-app",
integrationVersion: "1.0.0",
});
// OR Desktop app — laptops, biometric (Touch ID). Prompts to authorize.const client = awaitcreateClient({
auth: newDesktopAuth("my-account-name"), // account name or UUIDintegrationName: "my-app",
integrationVersion: "1.0.0",
});
Choosing auth:
OP_SERVICE_ACCOUNT_TOKEN → headless, no prompt, but cannot read Private/Personal
vaults (shared vaults only). The token is itself a full-decryption secret — never
log or persist it.
DesktopAuth → uses the running desktop app, can read your Private vault, prompts
for Touch ID. Requires the desktop app's SDK integration to be enabled.
createClient, and every method below, are async — await them.
Resolve secrets — the core operation
// One secret:const apiKey = await client.secrets.resolve("op://Vault/Item/credential");
// Many at once (one round-trip, per-reference errors — prefer this for >1):const res = await client.secrets.resolveAll([
"op://Vault/Item/username",
"op://Vault/Item/password",
]);
for (const [ref, response] ofObject.entries(res.individualResponses)) {
if (response.error) { console.error(`failed ${ref}:`, response.error); continue; }
console.log(response.content.secret); // the value
}
Keep resolved secrets in-memory only — never write them to disk or logs.
→ Full resolution details (reference syntax, OTP/SSH query params, field types,
validating a reference, the response shapes): references/resolve-secrets.md
Read a 1Password Environment (beta)
A named set of env vars managed in the desktop app, addressed by an opaque ID:
const res = await client.environments.getVariables("<environment-id>");
for (const v of res.variables) {
process.env[v.name] = v.value; // { name, value, masked }
}
Requires the beta SDK and the Environment ID (copied from the desktop
app: Developer → View Environments → Manage environment → Copy environment ID).
→ Details + the response shape: references/environments.md
Discover an item's fields (for globbed / bulk imports)
When you want to pull many fields from one item — e.g. an item whose fields are
each named after an env var (OPENAI_API_KEY, ANTHROPIC_API_KEY, …) — you must
discover them first. items.get() takes IDs, not names, so the flow is:
// 1. name → vault IDconst vaults = await client.vaults.list();
const vaultId = [...vaults].find(v => v.title === "Jack")!.id;
// 2. name → item IDconst items = await client.items.list(vaultId);
const itemId = items.find(i => i.title === "API keys")!.id;
// 3. fetch the item → fields + sectionsconst item = await client.items.get(vaultId, itemId);
for (const f of item.fields) {
// f.title (label), f.sectionId, f.fieldType, f.value// join f.sectionId → item.sections[].title for the section label
}
Note:items.get() returns every field's decrypted value — there is no
"names without values" mode. This is the same as the op CLI's op item get
(both decrypt in memory; neither writes to disk), so it's not a security
regression — just don't persist what you don't use.
→ Full glob/discovery recipe (name→ID resolution, section-label joins, building
op:// references, filtering by a glob): references/glob-discovery.md
What the SDK can and cannot do
Need
SDK
Notes
Resolve op:// (single + batch)
✅
secrets.resolve / resolveAll
Validate a reference syntactically
✅
Secrets.validateSecretReference (static, no network)
List vaults / items, get item fields
✅
IDs only — resolve names→IDs yourself
Read a 1Password Environment
✅ beta
environments.getVariables, beta SDK only
Use an existing op signin session
❌
SDK needs its own token/DesktopAuth
Read Private vault headless
❌
service accounts = shared vaults only
Other languages
The SDK is also available for Go and Python with the same shapes (different
casing/idioms). → references/other-languages.md
