API Keys — Docs

Create, rotate, scope, and revoke API keys for your organization. Best practices for key management in teams.

API key basics

Every API call to Engramma requires an API key. Organization API keys are shared across the team — all usage counts toward the organization's plan limits.

Key property	Description
Prefix	`nx_live_` (production) or `nx_test_` (development)
Length	48 characters
Scopes	What the key can do (read, write, admin)
Rate limit	Per-key rate limit (overrides default if set)
Expiration	Optional expiry date

Creating API keys

import os
from engramma_cloud import EngrammaClient

client = EngrammaClient(api_key=os.environ["ENGRAMMA_API_KEY"])

# Create a production key with full access
prod_key = client.organizations.create_api_key(
    org_id="org_abc123",
    name="Production Backend",
    scopes=["memory:read", "memory:write", "engine:consolidate"],
    environment="production"
)

print(f"Key: {prod_key.key}")  # Only shown once!
print(f"Name: {prod_key.name}")
print(f"Scopes: {prod_key.scopes}")

# Create a read-only key for analytics
read_key = client.organizations.create_api_key(
    org_id="org_abc123",
    name="Analytics Dashboard",
    scopes=["memory:read"],
    environment="production"
)

# Create a dev key with expiration
dev_key = client.organizations.create_api_key(
    org_id="org_abc123",
    name="Dev Environment",
    scopes=["memory:read", "memory:write"],
    environment="development",
    expires_in_days=90
)

Danger

The full API key is only displayed once at creation time. Store it securely immediately. If you lose it, you'll need to create a new key.

Available scopes

Scope	Allows
`memory:read`	Retrieve, recall, explain, stats
`memory:write`	Store, forget, batch-store
`engine:consolidate`	Trigger consolidation cycles
`engine:advanced`	Semantic neighbors, explorer, diagnostics
`webhooks:manage`	Create, delete, list webhooks
`org:read`	List members, view org settings
`org:admin`	Invite/remove members, manage settings

Listing keys

# List all API keys (key values are masked)
keys = client.organizations.list_api_keys(org_id="org_abc123")

for key in keys:
    print(f"{key.name}")
    print(f"  Prefix: {key.prefix}...{key.suffix}")
    print(f"  Scopes: {key.scopes}")
    print(f"  Created: {key.created_at}")
    print(f"  Last used: {key.last_used_at}")
    print(f"  Environment: {key.environment}")

Rotating keys

Rotation creates a new key and gives you a grace period to update your applications before the old key expires:

# Rotate a key (old key stays valid for grace period)
new_key = client.organizations.rotate_api_key(
    org_id="org_abc123",
    key_id="key_old123",
    grace_period_hours=24  # Old key works for 24 more hours
)

print(f"New key: {new_key.key}")
print(f"Old key expires: {new_key.old_key_expires_at}")

# Update your application with the new key
# Then the old key auto-expires after the grace period

Revoking keys

# Immediately revoke a key (no grace period)
client.organizations.revoke_api_key(
    org_id="org_abc123",
    key_id="key_compromised"
)

# The key stops working immediately
# All in-flight requests with this key will fail

Warning

Revoking is immediate and irreversible. Any application using the revoked key will get 401 errors immediately. Use rotation instead if you want a grace period.

Best practices

Environment separation

Environment	Key scopes	Rate limit	Expiration
Production	Full (read + write + consolidate)	Tier default	No expiration
Staging	Full	Lower (50% of prod)	No expiration
Development	Read + write	Low (10 req/s)	90 days
CI/CD	Read only	Low	30 days

Key naming convention

Use descriptive names that tell you exactly where the key is used:

✓ "Production Backend - Main API"
✓ "Staging - Integration Tests"
✓ "Dev - Alice's Local Environment"
✗ "key1"
✗ "test"

Rotation schedule

Key type	Rotation frequency	Reason
Production	Every 90 days	Limit exposure window
Development	Every 30 days	Devs change, environments shift
CI/CD	Every deployment	Fresh key per pipeline
Compromised	Immediately	Revoke + create new

Tip

Set up a reminder to rotate production keys quarterly. Use the grace period feature so you can update your deployment without downtime.

Next steps

Billing Management — Understand how key usage maps to billing
API Key Best Practices — Security-focused key management
Members & Roles — Who can create and manage keys