1Password Naming Conventions for scandora.net Infrastructure¶

Last Updated: 2026-02-16 Status: ENFORCED - All new secrets MUST follow these conventions

Standards Hierarchy¶

Priority 1: Our Standards (MANDATORY)

Item names: lowercase_with_underscores
Custom field names: lowercase_with_underscores
NO spaces, NO hyphens, NO camelCase in names we control

Priority 2: Use 1Password Defaults When Compliant

✅ Use standard fields when available: username, password, credential, hostname, filename
✅ Accept system fields as-is: notesPlain, validFrom, valid from, expires

Priority 3: Create Custom Fields When Needed

If 1Password doesn't have a compliant standard field, create custom using lowercase_with_underscores
Examples: api_key, server_url, access_key_id, secret_access_key

Rationale: We control what we create. Automation and scripting require consistent, predictable naming.

Item Naming Pattern¶

{service}_{type}_{scope}_{environment}_{description}

Components:

service: Platform/service (aws, gcp, github, gitlab, cloudflare, zerotier, powerdns, opnsense)
type: Credential type (access_key, service_account_key, pat, api_key, api_token, password)
scope: What it applies to (user, repo, org, network, project, instance, host)
environment: Where used (production, dev, localstack, docker)
description: Additional context (owner, admin, readonly, full_access)

Not all components required - use what makes sense.

Examples ✅¶

Item Name	Pattern Breakdown
`aws_access_key_luna_workstation`	service_type_scope_environment
`gcp_service_account_key_scandoraproject_owner`	service_type_scope_description
`github_pat_user_scandora_full_access`	service_type_scope_scope_description
`cloud_sql_scandora_postgres_user_joe`	service_scope_scope_scope_description
`powerdns_api_key_bogart_production`	service_type_scope_environment
`opnsense_api_key_owl_production`	service_type_scope_environment
`zerotier_api_token_network_management`	service_type_scope_description
`mediawiki_secret_key`	service_type
`slack_webhook_scandora_notifications`	service_type_scope_description

Anti-Patterns ❌¶

Bad Name	Issue	Correct Name
`AWS Access Key`	Spaces, capitals	`aws_access_key_luna_workstation`
`GCP Service Account Key - luna`	Hyphens, spaces	`gcp_service_account_key_scandoraproject_owner`
`apiKey`	camelCase	`api_key`
`api-key`	Hyphens	`api_key`

Field Naming¶

Use 1Password Standard Fields First¶

When creating items, prefer 1Password's standard fields if they're compliant:

Standard Field	Use For	Compliant?
`username`	Usernames	✅ Yes
`password`	Passwords	✅ Yes
`credential`	API credentials	✅ Yes
`hostname`	Server hostnames	✅ Yes
`filename`	Certificate/key files	✅ Yes
`notesPlain`	Documentation	✅ Yes (system field)

Create Custom Fields When Needed¶

If 1Password doesn't have a suitable standard field, create custom using lowercase_with_underscores:

Examples (Correct ✅):

api_key
api_secret
api_token
server_url
api_version
access_key_id
secret_access_key
default_region

Examples (Incorrect ❌):

api key → Use api_key
API Secret → Use api_secret or standard credential
serverURL → Use server_url
access-key-id → Use access_key_id

Well-Known Abbreviations¶

Use these standard abbreviations - they're industry-recognized:

Abbreviation	Meaning	Example
`api`	Application Programming Interface	`api_key`, `api_token`
`vm`	Virtual Machine	`opnsense_dev_vm`
`prd` / `prod`	Production	`owl_production`
`dev`	Development	`localstack_dev`
`db`	Database	`postgres_db`
`sql`	Structured Query Language	`cloud_sql`
`svc`	Service	`svc_account`
`mgmt`	Management	`network_management`
`pat`	Personal Access Token	`github_pat`
`rds`	Relational Database Service	`mysql_rds`
`pg`	PostgreSQL	`bogart_pg`

Don't abbreviate if it's not well-known:

Use workstation not wks
Use automation not auto
Use notifications not notif

Vault Assignment by Risk Level¶

scandora-super (CRITICAL)¶

Access: Manual load only Items: Can destroy infrastructure, manage IAM, access all data

Examples:

aws_access_key_luna_workstation
gcp_service_account_key_scandoraproject_owner
github_pat_user_scandora_full_access
onepassword_service_account_token_scandora_super

scandora-prd-automation (HIGH)¶

Access: Manual load for production operations Items: Can modify production systems

Naming pattern: Include _production suffix where applicable

Examples:

opnsense_api_key_owl_production
powerdns_api_key_bogart_production
cloud_sql_bogart_pg_user_pdns

scandora-automation (MEDIUM)¶

Access: Auto-loaded by default Items: Read-only or limited scope, shared

Naming pattern: No environment suffix (implies shared use)

Examples:

cloudflare_api_token_dns_automation
zerotier_api_token_network_management
github_pat_repo_webhook_management

scandora-dev-automation (LOW)¶

Access: Auto-loaded by default Items: Development only, ephemeral

Naming pattern: Include _dev suffix

Examples:

aws_access_key_localstack_dev
oracle_xe_docker_dev
opnsense_api_key_dev_vm

Creation Workflow¶

Creating a New Secret¶

Choose vault based on risk level
Name the item following pattern:

{service}_{type}_{scope}_{environment}_{description}

Use standard fields when possible:

# If 1Password has a standard field, use it
op item create --category="Login" \
  --title="new_service_credentials" \
  --vault="scandora-automation" \
  username="admin" \
  password="<generated>"

Create custom fields when needed (use underscores):

op item create --category="API Credential" \
  --title="new_service_api_key_production" \
  --vault="scandora-prd-automation" \
  --generate-password='letters,digits,32' \
  'api_key[password]=' \
  api_url[text]="https://api.example.com"

Let 1Password generate credentials (don't generate externally)
Add tags: scandora.net, infrastructure, risk level
Document in Notes:
What it's for
Where it's used
Scope/permissions
Rotation schedule

Validation¶

Check Naming Compliance¶

Run the Phase 5 validation script:

cd ~/src/scandora.net/docs/operations/secret-inventory-20260216
./PHASE5-CLEANUP-SCRIPT.sh --dry-run

Look for "Naming violation" warnings.

Code Review Checklist¶

When reviewing code that references 1Password items:

✅ Good:

op item get "aws_access_key_luna_workstation" --vault scandora-super
op item get "powerdns_api_key_bogart_production" --vault scandora-prd-automation --fields api_key

❌ Reject in PR:

op item get "AWS Access Key" --vault scandora.net                    # Spaces, capitals
op item get "service-api-key" --vault scandora-automation            # Hyphens
op item get "apiKey" --vault scandora-automation                     # camelCase
op item get "service" --fields "api key"                             # Space in field name

FAQ¶

Q: Can I use numbers in item names? A: Yes! scandora_postgres_user_joe, opnsense_dev_vm are fine.

Q: What if the service name has capitals (AWS, GCP)? A: Always lowercase: aws_access_key, gcp_service_account_key.

Q: Can I use hyphens in project names like "coop-389306"? A: Convert to underscores in item name: gcp_service_account_key_coop_389306_owner. (It's OK in field values/notes, just not in names)

Q: What about system fields like "notesPlain"? A: Accept as-is! We only control item names and custom fields we create.

Q: Should I use username/password or create custom fields? A: Use 1Password's standard fields when they fit. Only create custom fields when needed.

Migration from Legacy Naming¶

If you find an item with legacy naming:

Rename:

op item edit "Old Item Name" --title "new_item_name" --vault vault-name

Update all references in codebase:

grep -r "Old Item Name" ~/src/scandora.net/

Test automation still works
Commit changes

References¶

Reorganization docs: docs/operations/secret-inventory-20260216/
CLAUDE.md: Project context with credential management policy
Phase 3: Renamed 18 items (PHASE3-RENAME-SCRIPT.sh)
Phase 4: Migrated 15 items (PHASE4-VAULT-MIGRATION-SCRIPT.sh)
Phase 5: Deleted 9 duplicates, validated naming (PHASE5-CLEANUP-SCRIPT.sh)

Remember: Consistent naming enables automation, reduces errors, and makes credentials easy to find.

When in doubt: lowercase_with_underscores