Authentication

All API endpoints require authentication using API keys. Gigantics supports two methods for providing the API key with each request.

Authentication Methods

Query Parameter

Include the API key as a query parameter:

curl "https://yourserver/api/org/proj/model/1/dataset/42?api_key=abc123xyz-def456uvw-ghi789rst"

Authorization Header

Include the API key in the Authorization header using Bearer token format:

curl -H "Authorization: Bearer abc123xyz-def456uvw-ghi789rst" \
  "https://yourserver/api/org/proj/model/1/dataset/42"

Priority: If both methods are provided, the query parameter takes precedence.

API Key Format

API keys generated by Gigantics follow this format:

{prefix}-{key}

Where:

• prefix - 10 characters (used for identification in the UI)
• key - 21 characters
• Total length: 31 characters
• Format: URL-safe alphanumeric characters

Example: abc123xyz-def456uvw-ghi789rst

Key Validation Process

When a request arrives at an endpoint, the system:

1. Extracts the key from either the query parameter or Authorization header
2. Loads the endpoint configuration from the database
3. Iterates through assigned keys for that endpoint:
   • Loads each API key record
   • Skips inactive keys (isActive: false)
   • Compares the provided key against the stored bcrypt hash
   • Stops on first match
4. Returns result:
   • If a match is found → request is authenticated
   • If no match → returns 403 Forbidden with message "Unknown API key"

Multiple Keys per Endpoint

When multiple API keys are assigned to an endpoint, any of the assigned keys will authenticate the request. This enables:

• Zero-downtime key rotation
• Multi-party access with different keys
• Backup keys for emergency access

The system checks all assigned keys until it finds a match. See Multiple API Keys per Endpoint for more details.

Key Security

Storage

• API keys are stored as bcrypt hashes in the database
• The plain-text key is only shown once during creation
• Keys cannot be retrieved after creation - they must be regenerated

Key States

• Active (isActive: true) - Key can authenticate requests
• Inactive (isActive: false) - Key is disabled and will not authenticate

Key Management

• Keys can be edited to change their purpose or active status
• Keys can be deleted, which immediately revokes access
• Deleting a key does not delete the endpoints - endpoints just lose that authentication method

Error Responses

Missing Key

Status: 403 Forbidden

Response:

{
  "message": "Not authorized"
}

Invalid Key

Status: 403 Forbidden

Response:

{
  "message": "Unknown API key"
}

Inactive Key

Status: 403 Forbidden

Response:

{
  "message": "Disabled API key"
}

Unknown Endpoint

Status: 403 Forbidden

Response:

{
  "message": "Unknown API Endpoint"
}

Usage Tracking

When a request is successfully authenticated:

1. The endpoint's calls counter is incremented
2. The API key's updatedAt timestamp is updated
3. This data is visible in the UI:
   • Endpoint call counts appear on the API Keys page
   • Last used time shows when the key was last used

Best Practices

1. Never commit keys to version control - Use environment variables or secret managers
2. Use HTTPS only - API keys sent over HTTP can be intercepted
3. Rotate keys regularly - Especially if a key might be compromised
4. Deactivate instead of delete - When troubleshooting, deactivate keys so you can reactivate them without recreating endpoints
5. Use descriptive purposes - Name keys by their use case (e.g., "Production Dashboard", "ETL Job")
6. Monitor usage - Check the "Last called" and call counts to detect unauthorized access

Related Documentation

• API Endpoint Assignment - Learn how to create and assign endpoints
• Multiple API Keys per Endpoint - Understand multiple key assignment
• Access Control - Review permissions for managing API keys