Install and configure 1Password
Get op:// secret resolution working in under five minutes. This page covers prerequisites, authentication setup, and a validation workflow to confirm everything works end-to-end.
Prerequisites
| Requirement | How to verify |
|---|---|
| A 1Password service account token | Starts with ops_... — create one in 1Password |
| Vault access | The service account must have read access to every vault referenced by your workflow |
| Loom CLI available | Run loom --version to confirm |
Loom uses the 1Password Go SDK for secret resolution. No op CLI installation is required.
Step 1: Export your service account token
Set the token in your shell before running any Loom command:
export OP_SERVICE_ACCOUNT_TOKEN="ops_..."
Loom reads this variable at runtime — it is never written to workflow files or logs.
Store this export in a local .env file (excluded from version control) and source it at the start of each session. This avoids retyping the token every time.
Step 2: Verify connectivity
Confirm the token can reach 1Password by listing your accessible vaults:
loom secrets op vault list
Expected output:
name=Engineering id=vlt_abc123
name=Platform id=vlt_def456
If the command returns an error, check:
- The token value is correct and not truncated.
- Your network can reach the 1Password API.
- The service account has at least one vault assigned.
Step 3: Validate with a workflow
Add an op:// secret to a job
deploy:
stage: ci
target: linux
secrets:
DEPLOY_TOKEN:
ref: op://Engineering/deploy/token
script:
- echo "Secret injected successfully"
Check and run
loom check
loom run --local --workflow .loom/workflow.yml
If resolution succeeds, the job runs with the secret injected and redacted in output. If it fails, Loom returns one of the error codes documented in the overview.
CI/CD configuration
In CI environments, set OP_SERVICE_ACCOUNT_TOKEN as a masked/protected variable in your runner configuration:
| CI system | Where to set |
|---|---|
| GitLab CI | Settings > CI/CD > Variables (masked, protected) |
| GitHub Actions | Repository or environment secrets |
| Other | Inject as an environment variable in the job execution shell |
Loom reads the token the same way in CI as locally — no additional configuration is needed.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
SECRETS_PROVIDER_UNAVAILABLE | Token missing, empty, or rejected by 1Password API | Export a valid OP_SERVICE_ACCOUNT_TOKEN |
SECRETS_REF_NOT_FOUND | Vault, item, or field does not exist | Verify the ref exists in 1Password; check vault access for the service account |
SECRETS_REF_INVALID | Malformed op:// URI | Check for missing segments or illegal characters (no query/fragment allowed) |
vault list returns nothing | Token lacks vault permissions | Update the service account's vault access in 1Password |
| Network timeout | Firewall or proxy blocking 1Password API | Ensure outbound HTTPS to my.1password.com is allowed |
Next steps
- CLI commands — manage vaults and items from the terminal.
- Provider overview — URI format, resolution flow, and security guarantees.
- All providers — compare with KeePass and environment passthrough.