API Key Management

Supascale's API key system allows you to grant programmatic access to your instance with fine-grained permission controls. This is useful for automation, CI/CD pipelines, and external integrations.

Overview

API keys provide an alternative to session-based authentication for the Supascale API. Each key can have specific permissions, limiting what actions it can perform.

Creating an API Key

1. Navigate to Settings > API Keys

2. Click Create API Key

3. Configure the key:

   • Name: A descriptive name (e.g., "CI/CD Pipeline", "Backup Script")
   • Expiration: Optional expiration date
   • Permissions: Select access levels for each resource

4. Click Create

5. Important: Copy the API key immediately - it won't be shown again

API Key Format

Supascale API keys use the format:

supascale_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

The supascale_ prefix helps identify the key type and prevents accidental exposure.

Permissions

Each API key has granular permissions for different resources:

Permission Levels

• None: No access to this resource
• Read: Can view but not modify
• Write: Full access (includes read)

Using API Keys

Include the API key in the Authorization header:

curl -H "Authorization: Bearer supascale_your_api_key" \
     https://your-supascale-instance/api/v1/projects

Or in JavaScript:

const response = await fetch('/api/v1/projects', {
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
});

Managing API Keys

Viewing Keys

1. Go to Settings > API Keys
2. View all created keys with:
   • Name
   • Creation date
   • Expiration date (if set)
   • Permissions summary

Note: The actual key value is never shown after creation - only a hash is stored.

Revoking Keys

To revoke an API key:

1. Go to Settings > API Keys
2. Find the key to revoke
3. Click Delete
4. Confirm the deletion

Revoked keys are immediately invalidated.

Security Best Practices

Key Management

1. Use descriptive names: Know what each key is used for
2. Set expiration dates: Limit key lifetime, especially for temporary access
3. Minimal permissions: Only grant permissions the key actually needs
4. Rotate regularly: Create new keys and revoke old ones periodically

Key Storage

1. Never commit keys to version control: Use environment variables
2. Use secrets management: Store in secure vaults (AWS Secrets Manager, HashiCorp Vault)
3. Limit access: Only share keys with systems that need them

Monitoring

1. Review key usage: Check activity logs for API key access
2. Audit periodically: Review which keys exist and their permissions
3. Investigate failures: Failed API key attempts are logged

Example Use Cases

CI/CD Pipeline

Create a key with limited permissions for deployments:

• Projects: Write (to deploy/update)
• Backups: Read (to verify backup status)
• Others: None

Backup Script

For an automated backup script:

• Backups: Write (to create backups)
• Cloud Storage: Read (to verify storage config)
• Others: None

Monitoring Integration

For external monitoring tools:

• Projects: Read (to check status)
• System: Read (to check health)
• Others: None

Troubleshooting

Invalid API Key

If you receive an authentication error:

1. Verify the key is copied correctly (no extra spaces)
2. Check the key hasn't expired
3. Ensure the key hasn't been revoked
4. Verify the Authorization header format

Permission Denied

If you receive a 403 error:

1. Check the key has the required permission level
2. Verify the key has access to the specific resource type
3. Review the permission settings for the key

Key Not Working After Creation

1. Ensure you copied the complete key including the supascale_ prefix
2. The key is active immediately - no delay
3. Check for any typos in the Authorization header