Multiple API Keys per Endpoint

Gigantics supports assigning multiple API keys to a single endpoint, enabling sophisticated access management scenarios including zero-downtime key rotation, multi-party access control, and gradual credential migration.

Overview

Each API endpoint can be associated with multiple API keys. When a request comes in, the system validates the provided key against all assigned keys until it finds a match. This means any of the assigned keys can authenticate the same endpoint, providing flexibility in how you manage and distribute credentials.

┌──────────────────────────────────────────────────────┐
│ API Endpoint: /api/org/proj/model/1/dataset/42       │
├──────────────────────────────────────────────────────┤
│ Assigned API Keys:                                   │
│   • api-key-production-2024                          │
│   • api-key-backup-2024                              │
│   • api-key-migration-temp                           │
└──────────────────────────────────────────────────────┘
         │
         │ Any of these keys authenticates
         ▼
┌──────────────────────────────────────────────────────┐
│ Request with x-api-key: api-key-production-2024      │
│ → ✓ Authenticated                                    │
└──────────────────────────────────────────────────────┘

User Interface

Assigning Multiple Keys

When assigning API keys to a dataset or pipeline endpoint, you'll see a selection modal that allows choosing multiple keys:

Quick Assignment Behavior

When you have only one API key available in your project, the system automatically assigns it without showing the modal. This streamlines the workflow for simpler setups.

Selection Management

• Adding keys: Click "Assign" on any unselected key to add it to the current endpoint
• Removing keys: Click "Assigned" on a selected key to remove it
• Multiple selection: You can select as many keys as needed before confirming

Authentication Flow

When a request arrives at an endpoint, the authentication middleware performs the following validation:

1. Extract the key: Reads the API key from either:

   • Query parameter: ?api_key=your-key-here
   • Authorization header: Authorization: Bearer your-key-here

2. Load endpoint: Retrieves the endpoint configuration from the database

3. Iterate through assigned keys: For each key in the apiKeys array:

   • Load the key record from the database
   • Skip if the key doesn't exist
   • Skip if the key is inactive (isActive: false)
   • Compare the provided key against the stored hash using bcrypt
   • If match found, authentication succeeds

4. Return result: If any key matches, the request is authenticated. If none match, a 403 error is returned.

Use Cases

Zero-Downtime Key Rotation

Rotate production keys without interrupting service:

1. Step 1: Create a new API key with a descriptive purpose (e.g., "Production Key 2025")
2. Step 2: Assign both the old and new keys to the endpoint
3. Step 3: Update your clients to use the new key
4. Step 4: Monitor usage to confirm all clients have migrated
5. Step 5: Remove the old key from the endpoint

During the transition period, both keys work simultaneously, ensuring no service interruption.

Multi-Party Access Control

Provide different keys to different consumers for better tracking and revocation:

• Partner A receives api-key-partner-a-2024
• Partner B receives api-key-partner-b-2024
• Internal Team receives api-key-internal-service

All keys work with the same endpoint, but you can:

• Track which partner made which requests (via usage logs)
• Revoke individual partner access without affecting others
• Set different rate limits or access policies per key (if configured)

Gradual Migration

When migrating from one authentication system to another:

1. Assign both the legacy key and the new key structure
2. Gradually migrate clients to the new format
3. Remove the legacy key once migration is complete

Backup Access Keys

Maintain a backup key that's rarely used but available if the primary key is compromised:

• Primary key: Used by all production systems
• Backup key: Stored securely, only used in emergencies

If the primary key is compromised, you can revoke it immediately while the backup key continues to provide access until a new primary is issued.

Best Practices

Key Naming Conventions

Use descriptive purposes when creating keys:

• Production Key 2024-Q4
• Backup Access Key
• Partner Integration - Acme Corp
• Migration Temporary - 2025-01

This makes it easier to identify keys in the selection modal and manage them over time.

Key Lifecycle Management

1. Before rotation: Create the new key and assign both old and new
2. During rotation: Monitor which keys are being used via API logs
3. After rotation: Remove unused keys promptly to reduce attack surface

Security Considerations

• Minimum keys: Only assign as many keys as necessary. More keys means more potential attack vectors
• Regular audits: Periodically review which keys are assigned to each endpoint
• Purpose tracking: Use descriptive purposes to remember why each key exists
• Inactive keys: Deactivate unused keys rather than deleting them immediately, in case you need to audit past usage

Monitoring Usage

All API calls generate job entries that include the API key used. Use these logs to:

• Track which keys are active
• Identify keys that should be rotated
• Detect unauthorized usage patterns
• Plan rotation schedules based on actual usage

Integration with Access Control

Multiple API keys work seamlessly with Gigantics' role-based access control:

• Users with ManageAPIKeys permission can assign multiple keys
• Each key must be created within the same project as the endpoint
• Key rotation doesn't affect role-based permissions in the UI
• API access via keys is independent of UI user roles

For more details, see Access Control.

Related Documentation

• API Endpoint Assignment - Learn how to create and manage endpoints
• Authentication - Understand how API authentication works
• Access Control - Review role-based permissions for API management