API Key Management

Secure API keys for programmatic access with rotation and usage tracking

Overview

API key management provides programmatic access scoped to a specific workspace at creation time — a key cannot be used to access data from any other workspace, regardless of what the caller requests. This scoping is enforced by the same authentication middleware that validates session JWTs across all service layers.

Usage is tracked per key for quota accounting and audit purposes. When a key is presented on a request, the middleware records the call against that key's usage counters. This lets you see exactly which integration is consuming quota and identify keys that are no longer active.

Real-World Example: Teams using n8n integration create dedicated API keys for their automation workflows. When a new CRM record is created, n8n uses the API key to trigger form filling automatically without requiring 2FA.

Creating separate keys per integration — one for development, one for staging, one for production — means a compromised key can be revoked instantly without touching any other environment. API keys are exempt from interactive 2FA requirements since the key itself is the second factor for server-to-server calls.

Key Capabilities

• Workspace-Scoped Keys: Every key is bound to a workspace at creation; cross-workspace access is blocked at the middleware level regardless of key permissions
• Per-Key Usage Tracking: Request counts are recorded per key for quota and audit; visible in the API dashboard
• Shared JWT Middleware Validation: API keys are validated by the same JWT middleware used across all service layers — no separate authentication path
• Multiple Keys Per Workspace: Create separate keys for CI/CD pipelines, staging, production, or individual integrations
• Instant Revocation: Deleting a key takes effect immediately; in-flight requests with the revoked key are rejected
• No Interactive 2FA: Server-to-server callers authenticate with the key alone — 2FA prompts apply only to interactive browser-based logins
• Inherited Workspace Permissions: A key carries the permissions of the workspace it was scoped to; it cannot escalate beyond those permissions

How It Works

1. Create API Key:

   • Navigate to Account Settings → API Keys
   • Click "Create New API Key" and assign a name (e.g., "Production Server", "CI/CD Pipeline")
   • Select the target workspace — the key is bound to this workspace and cannot access other workspaces
   • Copy the key immediately; it is shown only once and stored as a hash — it cannot be retrieved later

2. Use API Key:

   curl https://api.instafill.ai/v1/sessions \
     -H "Authorization: Bearer YOUR_API_KEY"
   

   Authentication middleware validates the key and scopes all queries to the key's workspace automatically.

Real-World Example: A legal firm automated email processing using API keys. When litigation documents arrive via email, their system uses an API key to automatically create form sessions and trigger batch processing.

3. Monitor Usage:

   • View per-key request counts in the API dashboard
   • Identify active versus idle keys to determine which can be safely rotated or deleted
   • Track quota consumption per key for capacity planning

4. Rotate Keys:

   • Create a new key for the target workspace
   • Update the integration or service to use the new key
   • Verify the new key is working correctly
   • Delete the old key — revocation is immediate

Use Cases

API key management is essential for any team integrating Instafill.ai into automated systems. Engineering teams generate separate keys for CI/CD pipelines, staging, and production environments so a compromised test key cannot affect live workspace data — each key's workspace scope prevents it from reaching any other environment's data even if the key itself leaks. Backend services filling W-4 onboarding packets, 1003 mortgage applications, or CMS-1500 insurance claims use dedicated workspace-scoped keys so each integration's activity is separately tracked and independently revocable. Individual integration keys can be deleted instantly without disrupting any other active connections.

Benefits

• Hard Workspace Isolation: The workspace boundary is enforced at the middleware level, not by convention — a key literally cannot return data from another workspace
• Simple Authentication: A single Bearer token header, no OAuth flow required for server-to-server calls
• Immediate Revocation: Deleting a key blocks it on the next request — no propagation delay
• Environment Separation: Per-environment keys mean that rotating a production key does not require touching development or staging configurations
• Usage Accountability: Per-key tracking shows exactly which integration is consuming API quota

Security & Privacy

All data is workspace-scoped and protected via shared authentication middleware running across all service layers.

Storage:

• Never commit API keys to version control
• Store in environment variables or a secrets manager (e.g., AWS Secrets Manager, HashiCorp Vault)
• Use a distinct key per environment and per integration

Rotation:

• Rotate keys periodically (every 90 days is a common baseline)
• Rotate immediately if a key is potentially compromised
• Test the new key before deleting the old one to avoid downtime

Scoping:

• Scope each key to the minimum-privilege workspace required by the integration
• Use service accounts with limited workspace roles for API-only access
• Review key usage regularly and delete idle keys

Monitoring:

• Check per-key usage in the API dashboard for unexpected spikes
• Unexplained usage volume on a key is a signal to rotate or revoke immediately

Common Questions