API Keys

API keys allow programmatic access to FlatRun's API. Manage keys from the API Keys page or from your user profile.

API Keys Overview

The API Keys page lists all keys you have access to:

• Name — Key identifier
• Owner — User who created the key
• Role — Permission level
• Deployments — Scoped deployments (if any)
• Created — Creation date
• Expires — Expiration date (if set)
• Last Used — Most recent API call
• Status — Active or revoked

Creating an API Key

1. Click "Create API Key"
2. Configure the key:
   • Name — Descriptive identifier
   • Description — Purpose of the key (optional)
   • Role — Permission level (Admin, Operator, Viewer)
   • Deployments — Limit to specific deployments (optional)
   • Expiration — Set expiration time (optional)
3. Click "Create"
4. Copy the key immediately — It's only shown once

Key Permissions

API keys inherit the role's permissions:

Scoping Keys to Deployments

Restrict a key to specific deployments for enhanced security:

1. When creating a key, click "Add Deployments"
2. Select one or more deployments
3. The key will only work for those deployments

Using API Keys

Include the API key in the X-API-Key header:

curl "http://localhost:8090/api/deployments" \
  -H "X-API-Key: your-api-key"

Or use Bearer authentication:

curl "http://localhost:8090/api/deployments" \
  -H "Authorization: Bearer your-api-key"

Key Expiration

Set an expiration time when creating a key:

• No expiration — Key is valid until revoked
• Custom duration — Key expires after specified time

Common expiration options:

• 1 hour (for temporary access)
• 24 hours (for daily tasks)
• 7 days (for short-term projects)
• 30 days (for monthly rotation)
• 90 days (for quarterly rotation)

Revoking Keys

Revoke a key to immediately disable it:

1. Find the key in the list
2. Click "Revoke" or the revoke icon
3. Confirm the action

Revoked keys:

• Cannot be used for API access
• Remain in the list for audit purposes
• Cannot be re-activated (create a new key instead)

Deleting Keys

Permanently remove a key:

1. Select the key
2. Click "Delete"
3. Confirm deletion

Viewing Key Details

Click on a key to view:

• Full configuration
• Creation details
• Usage statistics
• Recent API calls

Managing Your Own Keys

Access your personal API keys from your profile:

1. Click your username in the header
2. Select "Profile"
3. Go to "API Keys" tab

Admin Key Management

Administrators can view and manage all API keys:

• See keys for all users
• Revoke any key
• Create keys for other users
• View usage across all keys

Key Security Best Practices

• Minimal permissions — Use the lowest role that meets requirements
• Scope to deployments — Limit keys to specific deployments when possible
• Set expiration — Avoid keys without expiration
• Rotate regularly — Replace keys periodically
• Secure storage — Store keys in secrets managers, not code
• Revoke unused keys — Remove keys that are no longer needed
• Monitor usage — Review key usage for suspicious activity

CI/CD Integration

Create dedicated keys for CI/CD pipelines:

GitHub Actions Example

name: Deploy
on: push
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to FlatRun
        run: |
          curl -X POST "${{ secrets.FLATRUN_URL }}/api/deployments/my-app/restart" \
            -H "X-API-Key: ${{ secrets.FLATRUN_API_KEY }}"

GitLab CI Example

deploy:
  stage: deploy
  script:
    - curl -X POST "$FLATRUN_URL/api/deployments/my-app/restart"
        -H "X-API-Key: $FLATRUN_API_KEY"

Keyboard Shortcuts