API Keys

API Keys authenticate your applications with the Hindsight API. This page covers managing API keys through the Hindsight Cloud UI.

Accessing API Keys

1. Log in to Hindsight Cloud
2. Open the Organization menu in the top navigation bar and select API Keys

Viewing API Keys

The API Keys page displays all keys for your organization:

Column	Description
Name	The descriptive name you gave the key
Key Prefix	First few characters for identification
Created	When the key was created
Last Used	Most recent API call using this key
Expires	Expiration date (if set)
Status	Active or Revoked

Filtering Keys

Use the Active only checkbox to:

• Checked - Show only active keys (default)
• Unchecked - Show all keys including revoked ones

Revoked keys appear grayed out with a "Revoked" badge.

Creating an API Key

Permissions Required

Only Owners and Admins can create API keys. Members can view keys but cannot create or revoke them.

1. Click Create API Key
2. Enter a Name for the key (e.g., "Production Server", "CI/CD Pipeline")
3. Choose an Expiration period:

Option	Description
Never	Key doesn't expire
1 hour	Short-lived for testing
1 day	Temporary access
7 days	Weekly rotation
30 days	Monthly rotation
90 days	Quarterly rotation
1 year	Annual rotation
Custom	Enter specific number of days

4. Optionally, restrict the key to specific banks
5. Click Create

After Creation

Copy Your Key Immediately

Your API key is only shown once after creation. Copy it immediately and store it securely.

If you lose your key, you'll need to create a new one.

The dialog will display:

• Full API key (click to copy)
• Instructions for secure storage
• Close button

Bank-Scoped Keys

By default, API keys have access to all memory banks in your organization. You can restrict a key to only access specific banks, limiting the blast radius if a key is compromised.

Creating a Bank-Scoped Key

1. When creating a key, check Restrict to specific banks
2. Select one or more banks from the list
3. Click Create

The key will only be able to access the selected banks. Requests to any other bank will return a 403 Forbidden error.

Viewing Bank Scope

Each key card shows its bank scope:

• All banks — unrestricted access
• Bank: my-bank — restricted to a single bank
• Banks: bank-1, bank-2, ... — restricted to multiple banks

Editing Bank Restrictions

To change which banks a key can access:

1. Click the Edit (pencil) icon on an active key card
2. Check or uncheck Restrict to specific banks
3. Update the bank selection
4. Click Save

note

Bank restrictions cannot be edited on revoked, expired, or programmatically created keys. Keys created via the programmatic API are immutable — revoke and recreate them instead.

Use Cases

Scenario	Recommended Scope
Production service using one bank	Restrict to that single bank
CI/CD pipeline for specific environments	Restrict to staging/test banks
Admin tooling that manages all banks	Unrestricted (all banks)
Per-agent MCP connections	Restrict to the agent's bank

Programmatic Key Creation

API keys with the create_scoped_keys capability can programmatically create, list, and revoke bank-scoped child keys via the API. This is useful for integrations and agents that need to provision short-lived, least-privilege keys without admin/UI access.

Prerequisites

An Owner or Admin must first create a parent API key with the scoped key creation capability enabled:

1. Go to the API Keys page
2. Click Create API Key
3. Enter a name (e.g., "Key Creator - CI/CD")
4. Set an expiration period
5. Optionally restrict to specific banks
6. Under Capabilities, check Allow creating scoped child keys
7. Click Create

Keys with this capability display a Key Creator badge in the API Keys list. Programmatically created keys display a Created by <parent key name> badge.

Creating a Scoped Key

Use Authorization: Bearer <parent-key> to create child keys:

curl -X POST https://api.hindsight.vectorize.io/v1/api-keys/scoped \
  -H "Authorization: Bearer <parent-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Agent - Task 42",
    "allowed_bank_ids": ["bank-a"],
    "expires_in_days": 7,
    "metadata": {"agent_id": "task-42"}
  }'

Constraints:

• allowed_bank_ids is required (at least one bank) and must be a subset of the parent key's bank scope
• expires_in_days is required (max 365 days) and cannot exceed the parent key's expiration
• Child keys never receive the create_scoped_keys capability — only admin-created keys can create other keys
• Child keys are immutable — their bank scope cannot be edited after creation. Revoke and recreate instead.

Listing Scoped Keys

List all keys created by the calling key:

curl https://api.hindsight.vectorize.io/v1/api-keys/scoped \
  -H "Authorization: Bearer <parent-key>"

Returns key metadata (id, name, prefix, bank scope, expiration, etc.) but never the raw key.

Revoking a Scoped Key

Revoke a child key by ID:

curl -X DELETE https://api.hindsight.vectorize.io/v1/api-keys/scoped/<key-id> \
  -H "Authorization: Bearer <parent-key>"

You can only revoke keys that were created by your parent key.

Use Cases

Scenario	Approach
CI/CD pipeline provisioning per-job keys	Parent key creates short-lived child per job
Multi-agent system with per-agent isolation	Parent key creates child scoped to agent's bank
Customer-facing integration tokens	Parent key creates customer-scoped child keys
Temporary debug access	Parent key creates 1-hour child for specific bank

Revoking an API Key

Revoke a key when:

• It's no longer needed
• It may have been compromised
• You're rotating credentials

To revoke a key:

1. Find the key in the list
2. Click the Delete (trash) icon
3. Confirm the revocation

Revocation is Permanent

Revoked keys cannot be recovered or reactivated. Any applications using the key will immediately lose access.

Cascade revocation: Revoking a parent key (one with the Key Creator capability) automatically revokes all of its child keys.

Best Practices

Naming Conventions

Use descriptive names that identify:

• The application or service using the key
• The environment (production, staging, development)
• The purpose or team

Examples:

• Production API Server
• CI/CD Pipeline - GitHub Actions
• Development - Local Testing
• Mobile App - iOS

Key Rotation

Regularly rotating API keys improves security:

1. Create a new key before the old one expires
2. Update your application to use the new key
3. Verify the new key works correctly
4. Revoke the old key

Expiration Policies

Choose expiration based on your security requirements:

Use Case	Recommended Expiration
Production services	90 days or 1 year
CI/CD pipelines	30-90 days
Development/testing	7-30 days
Quick debugging	1 hour or 1 day

Security Tips

• Never commit keys to version control - Use environment variables or secret managers
• Restrict keys to specific banks - Use bank-scoped keys to limit access to only the banks each service needs
• Limit key scope - Create separate keys for different services
• Monitor usage - Check "Last Used" to detect unauthorized access
• Revoke unused keys - Remove keys that are no longer needed
• Use short-lived keys when possible - Reduces risk if compromised