Skip to main content

API Keys

Create and manage Personal Access Tokens for programmatic access to the Supaflow API.

Overview​

Personal Access Tokens (PATs) are long-lived JWT tokens that allow you to access the Supaflow API from scripts, applications, and third-party tools. These tokens authenticate your API requests and have the same permissions as your user account.

Important: Tokens are displayed only once when created. You cannot retrieve them again, so copy and store them securely immediately.

To access: Navigate to Settings → API Keys in the sidebar.

Why Use API Keys​

API keys enable you to:

  • Automate workflows - Trigger pipelines from CI/CD systems (GitHub Actions, GitLab CI)
  • Integrate with tools - Connect Supaflow to monitoring, alerting, or workflow automation tools
  • Build applications - Develop custom applications that interact with Supaflow
  • Access from scripts - Query pipeline status, manage activities, or configure datasources programmatically

Security: Since tokens are long-lived and have full account permissions, treat them like passwords.

Creating an API Key​

Step 1: Start Creation​

  1. Go to Settings → API Keys
  2. Click Create API Key button (top right)
  3. Enter a descriptive name for your token
    • Good: "Production CI/CD", "Airflow Integration", "Development Testing"
    • Bad: "Token 1", "My Token", "Test"
  4. Click Create Token

Step 2: Copy Your Token (CRITICAL)​

⚠️ You'll see this warning:

Make sure to copy your personal access token now. You won't be able to see it again!

This token has the same permissions as your account. Keep it secure and don't share it.

Your JWT token will be displayed in full - this is the ONLY time you'll see it.

To save it:

  1. Click the Copy button next to the token
  2. Wait for "Copied!" confirmation to appear
  3. Immediately paste it into your password manager or secure storage
  4. Click Done (only enabled after you copy the token)

After closing this dialog:

  • The full token is gone forever
  • Only the last 4 characters will be shown in the table
  • You cannot retrieve the token again
  • If lost, you must create a new token

Managing API Keys​

Viewing Your Tokens​

On the API Keys page, you'll see a table with all your tokens:

  • Name - The name you assigned when creating the token
  • Token - Masked (only last 4 characters shown): •••••••••••••••••ab3f
  • Created - When the token was created
  • Last Used - Last time the token was used, or "Never"
  • Actions - Revoke button

Revoking a Token​

When to revoke:

  • Token may have been compromised or exposed
  • Application no longer needs access
  • Token hasn't been used in 90+ days
  • Employee leaves the team

How to revoke:

  1. Click Revoke button next to the token
  2. Confirm in the dialog that appears
  3. Token is immediately invalidated

Impact:

  • Any applications using this token will immediately lose access
  • API requests with this token will return 401 Unauthorized
  • This action cannot be undone
  • You'll need to create a new token if access is still needed

Using Your API Key​

Authentication Format​

Include your token in the Authorization header of API requests:

Authorization: Bearer <your_jwt_token>

Example: cURL​

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  https://api.supa-flow.io/v1/pipelines

Example: JavaScript/TypeScript​

const token = process.env.SUPAFLOW_API_TOKEN; // Load from environment

fetch('https://api.supa-flow.io/v1/pipelines', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
})
  .then(response => response.json())
  .then(data => console.log(data));

Example: Python​

import os
import requests

token = os.getenv('SUPAFLOW_API_TOKEN')  # Load from environment

headers = {
    'Authorization': f'Bearer {token}'
}

response = requests.get(
    'https://api.supa-flow.io/v1/pipelines',
    headers=headers
)

pipelines = response.json()

Token Security​

Critical Security Rules​

1. Never Commit Tokens to Version Control

❌ Don't do this:

const token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."; // Hardcoded!

✅ Do this instead:

const token = process.env.SUPAFLOW_API_TOKEN; // From environment

2. Use Environment Variables

Store tokens in environment files that are NOT committed to git:

# .env file (add to .gitignore!)
SUPAFLOW_API_TOKEN=your_jwt_token_here
# .gitignore
.env
.env.local
*.env

3. Restrict Access to Tokens

  • Store in password managers (1Password, LastPass, Bitwarden)
  • Use secret management systems (AWS Secrets Manager, HashiCorp Vault)
  • Limit who has access to production tokens
  • Don't share tokens via email, Slack, or chat

4. Rotate Tokens Regularly

Since tokens are long-lived, rotate them periodically:

  • Production environments: Every 90 days
  • Development environments: Every 180 days
  • Immediately if a token may have been exposed

5. Monitor Token Usage

Check the "Last Used" column regularly:

  • Never used - May indicate the token was lost or the application was never deployed
  • Not used recently - Application may be decommissioned (safe to revoke)
  • Used recently - Token is active and in use

Common Use Cases​

CI/CD Pipelines​

Use case: Trigger Supaflow pipelines from GitHub Actions, GitLab CI, Jenkins, or CircleCI.

Setup:

  1. Create token: "CI/CD Pipeline - GitHub Actions"
  2. Add as secret in your CI system
  3. Use in workflow to trigger activities or check status

Example: GitHub Actions

name: Trigger Supaflow Pipeline

on:
  push:
    branches: [main]

jobs:
  trigger-pipeline:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Pipeline
        run: |
          curl -X POST \
            -H "Authorization: Bearer ${{ secrets.SUPAFLOW_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{"pipeline_id": "your-pipeline-id"}' \
            https://api.supa-flow.io/v1/jobs

Data Orchestration Tools​

Use case: Integrate Supaflow with Airflow, Prefect, or Dagster.

Setup:

  1. Create token: "Airflow Integration"
  2. Store in orchestration tool's secret management
  3. Use to trigger pipelines or monitor activity status

Analytics & Monitoring​

Use case: Query pipeline status and activity metrics for dashboards or alerts.

Setup:

  1. Create token: "Datadog Integration" or "Grafana Dashboards"
  2. Configure in monitoring tool
  3. Pull metrics via API for visualization

Development & Testing​

Use case: Local development and testing of integrations.

Setup:

  1. Create token: "Dev Environment - [Your Name]"
  2. Store in local .env file (add to .gitignore)
  3. Use for testing API integrations

Troubleshooting​

Can't Close the Token Creation Dialog​

What it means: The dialog won't close until you copy the token.

Why: This is intentional security behavior to prevent you from losing the token, which can never be retrieved again.

How to resolve:

  1. Click the Copy button next to the token
  2. Wait for "Copied!" confirmation to appear
  3. The Done button will then become enabled
  4. Click Done to close

Token Not Working (401 Unauthorized)​

What it means: Your API requests are being rejected.

How to resolve:

  1. Verify the token was copied correctly

    • No extra spaces or line breaks
    • Full token, not just the last 4 characters
    • Includes the entire JWT (starts with "eyJ...")

  2. Check the Authorization header format

    • Must include "Bearer " prefix with a space
    • Format: Authorization: Bearer <token>
    • Don't use Token, JWT, or other prefixes

  3. Test with a simple request

    curl -H "Authorization: Bearer YOUR_TOKEN" \
      https://api.supa-flow.io/v1/health

  4. If you lost the token

    • You cannot retrieve it
    • Create a new token
    • Update your applications with the new token
    • Revoke the old token

Can't Create Token (Name Already Exists)​

What it means: You already have a token with that name.

How to resolve:

  1. Choose a unique name:
    • Add a version: "Production API Key v2"
    • Add date: "Production API Key - Dec 2024"
    • Add more detail: "Production API Key - CI/CD - GitHub"
  2. Or revoke the existing token first, then reuse the name

Token Shows "Never Used" But Is Being Used​

What it means: The "Last Used" timestamp hasn't updated yet.

How to resolve:

  1. Wait a few minutes - timestamps may lag slightly
  2. Refresh the page
  3. Verify you're checking the correct token (compare last 4 characters)
  4. Ensure your application is successfully making API calls (check for 401 errors)

Best Practices​

Use Descriptive Token Names​

Choose names that clearly identify the token's purpose:

✅ Good examples:

  • "Production CI/CD - GitHub Actions"
  • "Airflow DAG - Data Warehouse Sync"
  • "Monitoring - Datadog Integration"
  • "Dev Environment - MacBook Pro"

❌ Poor examples:

  • "Token 1"
  • "Test"
  • "My Token"
  • "Temp"

Why: Makes it easy to identify and revoke tokens when reviewing your token list.

Create Separate Tokens Per Environment​

Don't reuse the same token across environments:

  • Development: "Dev Environment API Key"
  • Staging: "Staging Environment API Key"
  • Production: "Production CI/CD API Key"

Benefits:

  • Revoke compromised tokens without affecting other environments
  • Track usage per environment
  • Implement different rotation schedules

Audit Tokens Monthly​

Set a calendar reminder to review your tokens:

  1. Check "Last Used" timestamps
  2. Identify tokens not used in 90+ days
  3. Investigate unused tokens:
    • Application decommissioned? → Revoke
    • Backup token? → Keep but document why
    • Forgotten/lost? → Revoke
  4. Update token names if purposes have changed

Rotate Tokens Before They're Compromised​

Don't wait for a security incident. Establish a rotation schedule:

Rotation process:

  1. Create new token with same name + "v2"
  2. Update all applications to use new token
  3. Verify applications work correctly
  4. Monitor for a day to ensure no issues
  5. Revoke the old token
  6. Rename new token (remove "v2" if desired)

Recommended frequency:

  • Production: Every 90 days
  • Staging: Every 180 days
  • Development: Annually or as needed

Support​

Need help with API keys? Contact us at support@supa-flow.io

Last updated on by pungaa
AI Tools
Ask ChatGPTClaudeAsk Claude
On this page