Authentication

Hippocortex supports two authentication methods: API keys for programmatic access and JWT tokens for dashboard and user-facing flows.

---

API Key Authentication

API keys are the primary authentication method for SDK and direct API access.

Key Formats

Prefix	Environment	Purpose
hx_live_	Production	Production data, billed usage
hx_test_	Test	Test data, no billing

Usage

Include the API key as a Bearer token:

curl -X POST https://api.hippocortex.dev/v1/capture \
  -H "Authorization: Bearer hx_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"type": "message", "sessionId": "s1", "payload": {"role": "user", "content": "hello"}}'

Creating API Keys

API keys are created via the dashboard or the API keys endpoint:

Dashboard:

1. Log in to dashboard.hippocortex.dev
2. Navigate to API Keys
3. Click "Create Key"
4. Select permissions (read, write, or both)
5. Copy the key (shown only once)

API:

curl -X POST https://api.hippocortex.dev/v1/api-keys \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent-key", "permissions": ["read", "write"]}'

Response:

{
  "ok": true,
  "data": {
    "id": "key-abc123",
    "name": "my-agent-key",
    "key": "hx_live_abc123...",
    "permissions": ["read", "write"],
    "createdAt": "2025-01-15T10:00:00Z"
  }
}

The full key value is returned only on creation. Store it securely.

Key Permissions

Permission	Allowed Operations
read	synthesize, listArtifacts, getArtifact, getMetrics, list memories
write	capture, captureBatch, learn, delete artifacts

Keys can have both permissions or just one.

Key Rotation

To rotate a key:

1. Create a new key with the same permissions
2. Update your agents/services to use the new key
3. Revoke the old key

# Revoke old key
curl -X DELETE https://api.hippocortex.dev/v1/api-keys/key-old123 \
  -H "Authorization: Bearer <jwt_token>"

Key Listing

curl https://api.hippocortex.dev/v1/api-keys \
  -H "Authorization: Bearer <jwt_token>"

Response:

{
  "ok": true,
  "data": {
    "keys": [
      {
        "id": "key-abc123",
        "name": "my-agent-key",
        "prefix": "hx_live_abc...",
        "permissions": ["read", "write"],
        "lastUsedAt": "2025-01-15T14:30:00Z",
        "createdAt": "2025-01-15T10:00:00Z"
      }
    ]
  }
}

Note: The full key value is never returned in list responses. Only the prefix is shown.

---

JWT Authentication (Clerk)

JWT tokens are used for dashboard authentication and user-facing flows. Hippocortex uses Clerk for identity management.

Flow

1. User authenticates via Clerk (sign-in page)
2. Clerk issues a JWT token
3. Dashboard includes the JWT in API requests
4. API validates the JWT signature and extracts user identity

Usage

curl https://api.hippocortex.dev/v1/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

JWT tokens are typically short-lived (1 hour) and refreshed automatically by the Clerk SDK in the dashboard.

JWT Claims

The API extracts the following from the JWT:

Claim	Purpose
sub	User ID
org_id	Organization ID (if set)
iat	Issued at timestamp
exp	Expiration timestamp

---

Rate Limit Headers

Every authenticated response includes rate limit information:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 594
X-RateLimit-Reset: 1709251200

Header	Description
X-RateLimit-Limit	Maximum requests per minute for this key
X-RateLimit-Remaining	Remaining requests in current window
X-RateLimit-Reset	Unix timestamp when the window resets

---

Security Best Practices

1. Never expose API keys in client-side code: Use server-side proxies
2. Use test keys for development: hx_test_* keys do not affect production data
3. Apply least-privilege permissions: Use read-only keys when write is not needed
4. Rotate keys regularly: Create new keys and revoke old ones periodically
5. Monitor key usage: Check lastUsedAt to detect unused or compromised keys
6. Use environment variables: Store keys in env vars, not in source code