Authentication

How to authenticate with Engramma: API keys, JWT Bearer tokens, refresh flow, and MFA setup.

Authentication methods

Engramma supports two authentication methods. Choose based on your use case:

Method	Best for	Header
API Key	Server-to-server, SDKs, CI/CD	`X-API-Key: nx_live_...`
JWT Bearer	User sessions, web apps, short-lived access	`Authorization: Bearer eyJ...`

API Key authentication

API keys are the simplest way to authenticate. Include your key in the X-API-Key header:

import os
from engramma_cloud import EngrammaClient

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

# The SDK automatically sends X-API-Key header

Key format

Prefix	Environment	Use
`nx_live_`	Production	Real data, billing applies
`nx_test_`	Development	Sandbox, no billing

Keys are 48 characters total (8-char prefix + 40-char random string).

Key scopes

Each API key can be restricted to specific operations:

Scope	Allows
`memory:read`	Retrieve, recall, explain, search
`memory:write`	Store, batch store, forget, tag, link
`memory:admin`	Consolidation, diagnostics, config
`org:read`	View organization details and members
`org:write`	Manage members, create keys
`billing:read`	View plans and invoices
`billing:write`	Change plan, manage subscription

Tip

Follow the principle of least privilege. Give each key only the scopes it needs.

JWT Bearer authentication

For user-facing applications, use JWT tokens obtained via the login flow:

from engramma_cloud import EngrammaClient

client = EngrammaClient()

# Step 1: Login to get tokens
tokens = client.auth.login(
    email='[email protected]',
    password='your-password'
)
print(tokens.access_token)   # JWT, expires in 15 minutes
print(tokens.refresh_token)  # Long-lived, expires in 7 days

# Step 2: Use access token for requests
client = EngrammaClient(access_token=tokens.access_token)

Token lifecycle

Token	Lifetime	Storage recommendation
Access token	15 minutes	Memory only (never persist)
Refresh token	7 days	Secure HTTP-only cookie or encrypted storage

Refresh flow

When the access token expires, use the refresh token to get a new one without re-authenticating:

# Access token expired — refresh it
new_tokens = client.auth.refresh(refresh_token=tokens.refresh_token)
print(new_tokens.access_token)  # new JWT, 15 more minutes

# Update the client
client = EngrammaClient(access_token=new_tokens.access_token)

Info

The SDKs handle token refresh automatically when configured with both tokens. You only need to handle this manually with raw HTTP.

Multi-Factor Authentication (MFA)

MFA adds a second layer of protection using TOTP (Time-based One-Time Password) apps like Google Authenticator or Authy.

Enable MFA

# Step 1: Initiate MFA setup — returns a QR code URL
setup = client.auth.mfa_enable()
print(setup.qr_code_url)     # Show this QR to the user
print(setup.secret)          # Manual entry backup
print(setup.backup_codes)    # One-time recovery codes

# Step 2: Verify setup with a code from the authenticator app
client.auth.mfa_verify(code='123456')
print('MFA is now active')

When MFA is enabled, the login flow requires a second step:

# Login returns a partial token that requires MFA verification
partial = client.auth.login(
    email='[email protected]',
    password='your-password'
)
# partial.mfa_required == True

# Complete login with TOTP code
tokens = client.auth.mfa_verify(
    mfa_token=partial.mfa_token,
    code='123456'
)
# Now you have full access_token and refresh_token

Backup codes

Store backup codes securely when MFA is first enabled. Each code can only be used once:

# Use a backup code if you lose access to your authenticator
tokens = client.auth.mfa_verify(
    mfa_token=partial.mfa_token,
    code='ABCD-EFGH-IJKL'  # one of the backup codes
)
# The used backup code is immediately invalidated

Choosing the right method

Scenario	Recommended	Why
Backend service / cron job	API Key	Long-lived, no refresh needed
CI/CD pipeline	API Key (test)	`nx_test_` key, limited scope
Web app (user sessions)	JWT Bearer	Short-lived, per-user access
Mobile app	JWT Bearer	Refresh flow for seamless UX
Admin dashboard	JWT + MFA	Maximum security for sensitive ops
Third-party integration	Scoped API Key	Minimal permissions

Security checklist

Never commit keys — Use environment variables or a secrets manager
Use test keys for development — nx_test_ keys have no billing impact
Scope keys minimally — Only grant permissions the service actually needs
Enable MFA — Required for organization admins, recommended for all users
Rotate keys regularly — Use the rotation endpoint with a grace period
Monitor the audit log — Watch for failed logins and unexpected key usage

Next steps

API Key Best Practices — Rotation, scoping, and environment separation
Your Data Rights — GDPR export, erasure, and consent
Security API Reference — Audit logs and session management