# 1Password Service Accounts Reference

## What is a Service Account?

A 1Password service account is a non-human identity that can authenticate to
1Password programmatically using a token (`OP_SERVICE_ACCOUNT_TOKEN`). It is
designed for headless environments: CI/CD, servers, containers, and automated
agents.

Service accounts are **read-only** — they can read secrets but cannot create,
update, or delete items.

## Creating a Service Account

1. Open **1Password** web console → **Developer** → **Infrastructure Secrets** → **Service Accounts**.
2. Click **New Service Account**.
3. Name it (e.g., `netcup-gateway`).
4. **Grant vault access**: select which vaults the account can read from.
   - Only grant the minimum vaults needed.
   - Each vault must be explicitly granted — service accounts have no access by default.
5. **Copy the token** (`ops_...`). It is shown once and cannot be retrieved later.

## Token Format

```
ops_<base64-encoded-data>
```

Tokens start with `ops_` and are typically 200+ characters long.
Store the token securely. If lost, revoke and create a new one.

## Environment Setup

Set the token as an environment variable:

```bash
# In .env file (gateway picks this up automatically)
OP_SERVICE_ACCOUNT_TOKEN=ops_...

# Or export directly
export OP_SERVICE_ACCOUNT_TOKEN="ops_..."
```

No `op signin` is needed — the CLI authenticates automatically when
`OP_SERVICE_ACCOUNT_TOKEN` is set.

## Limitations

| Feature                           | Supported?                   |
| --------------------------------- | ---------------------------- |
| Read secrets                      | Yes                          |
| Read TOTP codes                   | Yes                          |
| Read file attachments             | Yes                          |
| Create/update/delete items        | No (read-only)               |
| Access to Personal vaults         | No (only shared/team vaults) |
| `op connect` integration          | No (different product)       |
| Interactive sign-in (`op signin`) | Not needed, not used         |
| Desktop app integration           | Not needed, not used         |

## Secret Reference Format

```
op://vault-name/item-name/field-name
```

- **vault-name**: The vault the item is stored in (e.g., `Private`, `Automation`).
- **item-name**: The title of the item (e.g., `susii-console`, `stripe-api`).
- **field-name**: The field within the item (e.g., `password`, `username`, `secret-key`).

Special fields:

- `one-time password?attribute=otp` — generates current TOTP code
- `notesPlain` — the notes field
- Section fields: `section-name/field-name`

## Security Best Practices

1. **Rotate tokens** periodically (quarterly or after personnel changes).
2. **Limit vault access** to only what the service account needs.
3. **Never commit tokens** to version control.
4. **Use `op run`** to inject secrets into processes instead of writing to disk.
5. **Monitor usage** via the 1Password admin console activity log.
6. **Revoke immediately** if a token is exposed.

## Verifying Access

```bash
# Check who you are (should show service account name)
op whoami

# List vaults the account can access
op vault list

# List items in a specific vault
op item list --vault="Private"
```

## CLI Reference (Service Account Subset)

```bash
# Read a secret value
op read "op://vault/item/field"

# Read to a file
op read --out-file ./output.txt "op://vault/item/field"

# Inject secrets into a command's environment
op run -- command-to-run

# Inject from a template file
op run --env-file=".env.tpl" -- command-to-run

# Inject into a template (stdin → stdout)
echo "password: {{ op://vault/item/password }}" | op inject
```
