API Keys

Create API keys for programmatic access to Supascale's REST API.

API Key Overview

API keys allow external applications to access Supascale without user credentials. Each key has:

• Unique identifier
• Granular permissions
• Optional expiration date
• Activity tracking

Create API Key

Via Web UI

1. Go to Settings > API Keys
2. Click Create API Key
3. Enter name and select permissions
4. Set expiration (optional)
5. Click Create
6. Copy the key (shown only once!)

Via API

curl -X POST https://supascale.example.com/api/v1/settings/api-keys \
  -H "X-API-Key: existing-admin-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Integration",
    "permissions": {
      "projects": "write",
      "backups": "write",
      "tasks": "read",
      "cloudStorage": "none",
      "system": "read"
    },
    "expiresAt": "2027-01-19T00:00:00Z"
  }'

Response:

{
  "success": true,
  "apiKey": {
    "id": "key-123",
    "name": "CI/CD Integration",
    "key": "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "permissions": {
      "projects": "write",
      "backups": "write",
      "tasks": "read",
      "cloudStorage": "none",
      "system": "read"
    },
    "expiresAt": "2027-01-19T00:00:00Z",
    "createdAt": "2026-01-19T12:00:00Z"
  }
}

The full API key is only shown once. Store it securely immediately.

API Key Format

sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Prefix: sk_live_ (live key)
• Length: 32 characters after prefix
• Characters: Alphanumeric

Permissions

Permission Levels

Resources

Example Permission Sets

Read-only monitoring:

{
  "projects": "read",
  "backups": "read",
  "tasks": "read",
  "cloudStorage": "read",
  "system": "read"
}

Backup automation:

{
  "projects": "read",
  "backups": "write",
  "tasks": "none",
  "cloudStorage": "read",
  "system": "none"
}

Full access:

{
  "projects": "write",
  "backups": "write",
  "tasks": "write",
  "cloudStorage": "write",
  "system": "write"
}

List API Keys

curl https://supascale.example.com/api/v1/settings/api-keys \
  -H "X-API-Key: your-api-key"

Response:

{
  "apiKeys": [
    {
      "id": "key-123",
      "name": "CI/CD Integration",
      "keyPreview": "sk_live_xxxx...xxxx",
      "permissions": { ... },
      "expiresAt": "2027-01-19T00:00:00Z",
      "lastUsed": "2026-01-19T11:00:00Z",
      "createdAt": "2026-01-19T10:00:00Z"
    }
  ]
}

Note: Full key is never returned in list requests.

Delete API Key

Via Web UI

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

Via API

curl -X DELETE "https://supascale.example.com/api/v1/settings/api-keys?id=key-123" \
  -H "X-API-Key: your-api-key"

Using API Keys

HTTP Header

Include in requests:

curl https://supascale.example.com/api/v1/projects \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Authentication Flow

1. Request includes X-API-Key header
2. Supascale validates key exists and not expired
3. Permissions checked against requested operation
4. Request proceeds or returns 403

Key Expiration

Set Expiration

{
  "expiresAt": "2027-01-19T00:00:00Z"
}

No Expiration

Omit expiresAt for keys that don't expire:

{
  "name": "Permanent Key",
  "permissions": { ... }
}

Expired Key Behavior

• Returns 401 Unauthorized
• Message: "API key has expired"
• Must create new key

Security Best Practices

Key Management

1. Use descriptive names - Know what each key is for
2. Minimum permissions - Only grant what's needed
3. Set expirations - Rotate keys periodically
4. One key per integration - Easier to revoke

Storage

1. Never commit to code - Use environment variables
2. Encrypt at rest - Use secrets management
3. Limit access - Only give to those who need it

Monitoring

1. Review usage - Check lastUsed regularly
2. Audit permissions - Verify they're still needed
3. Delete unused keys - Reduce attack surface

Rotation Schedule

Troubleshooting

"Invalid API key"

1. Verify key is correct (no typos)
2. Check key hasn't been deleted
3. Verify key format is correct

"API key expired"

1. Check expiration date
2. Create new key with fresh expiration
3. Update integrations with new key

"Permission denied"

1. Check key permissions
2. Verify endpoint requires available permission
3. Consider creating key with additional permissions

"Rate limited"

1. Reduce request frequency
2. Implement request batching
3. Contact support for limit increase