API Key Best Practices

Key format

Engramma API keys follow a predictable format that makes them easy to identify and manage:

nx_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4
└─────┘└──────────────────────────────────────────────────────┘
 prefix                   40-char random string

Environment separation

Never use production keys in development. The two-prefix system makes this easy to enforce:

# Development — uses sandbox data, no charges
ENGRAMMA_API_KEY=nx_test_dev1234567890abcdefghijklmnopqrstuvwxyz12

Scoping

Every API key should have the minimum permissions required for its use case:

# Create a scoped key via the API
new_key = client.organizations.create_key(
    org_id='org_abc123',
    name='Read-Only Analytics',
    scopes=['memory:read']
)
print(f'Key: {new_key.key}')  # only shown once

Rotation

Rotate keys regularly to limit the blast radius of a leak. The rotation endpoint provides a grace period so you can update services without downtime:

# Rotate with a 24-hour grace period
rotation = client.organizations.rotate_key(
    org_id='org_abc123',
    key_id='key_old01',
    grace_period_hours=24
)
print(f'New key: {rotation.new_key}')       # start using this
print(f'Old key valid until: {rotation.old_key_expires_at}')

# During the grace period, BOTH keys work
# After it expires, only the new key works

Rotation schedule

Secret management

Where to store keys

Gitignore rules

Always ensure your .gitignore excludes secret files:

# Environment files
.env
.env.local
.env.production
.env.*.local

# Secret files
*.pem
*.key
credentials.json
secrets.yaml

Pre-commit hook

Prevent accidental key commits with a pre-commit hook:

#!/bin/bash
# .git/hooks/pre-commit
# Block commits containing Engramma API keys

if git diff --cached --diff-filter=ACMR | grep -qE 'nx_(live|test)_[a-z0-9]{40}'; then
  echo 'ERROR: Engramma API key detected in staged changes.'
  echo 'Remove the key and use an environment variable instead.'
  exit 1
fi

Key lifecycle

Create → Scope → Deploy → Monitor → Rotate → Revoke

1. Create — Generate a new key with a descriptive name
2. Scope — Assign minimum required permissions
3. Deploy — Store in secrets manager, reference via environment variable
4. Monitor — Check the audit log for unusual usage
5. Rotate — Replace periodically with grace period
6. Revoke — Immediately invalidate compromised keys

Emergency revocation

If a key is leaked, revoke it immediately:

# Immediate revocation — no grace period
client.organizations.revoke_key(
    org_id='org_abc123',
    key_id='key_compromised'
)
# Key stops working instantly

Common mistakes

Next steps

• Authentication — Full auth flow with JWT and MFA
• Your Data Rights — GDPR export and erasure
• Organizations API — Key management endpoints
• Security API — Audit log and sessions