Skip to main content

Authentication

Complete guide to authenticating with the Flow API.

API Keys​

Flow API uses API key authentication. All requests to /v1/* endpoints require a valid API key.

Getting Your API Key​

  1. Log in to your Flow dashboard
  2. Navigate to Settings → API Keys
  3. Click Create API Key
  4. Give it a descriptive name
  5. Copy the key immediately - it's only shown once!

API Key Format​

flow_sk_live_<prefix>_<secret>

Example: flow_sk_live_abc12345_xyz78901234567890abcdefghijklmnopqrstuvwxyz

Using Your API Key​

Include your API key in the Authorization header:

curl https://api.flow.dev/v1/channels \
  -H "Authorization: Bearer flow_sk_live_abc12345_xyz789..."

Using SDKs​

SDKs handle authentication automatically:

TypeScript:

import { Flow } from '@flowdev/sdk';

const flow = new Flow('flow_sk_live_abc12345_xyz789...');

Python:

from flow_sdk import Flow

flow = Flow(api_key='flow_sk_live_abc12345_xyz789...')

Go:

import "github.com/flowdev/go-sdk"

client := flow.NewClient("flow_sk_live_abc12345_xyz789...")

API Key Permissions​

API keys can have specific permissions:

  • posts:read - Read posts
  • posts:write - Create/update/delete posts
  • channels:read - Read channels
  • channels:write - Create/update/delete channels
  • connections:read - Read connections
  • connections:write - Manage connections
  • webhooks:read - Read webhooks
  • webhooks:write - Manage webhooks
  • api-keys:read - Read API keys
  • api-keys:write - Manage API keys
  • analytics:read - Read analytics
  • media:read - Read media
  • media:write - Upload/delete media

When creating an API key, you can specify which permissions it should have. By default, new keys have all permissions.

Creating a Scoped API Key​

const { apiKey } = await flow.apiKeys.create({
  name: 'Read-only Key',
  permissions: ['posts:read', 'channels:read'],
});

Security Best Practices​

1. Never Commit API Keys​

# ❌ Never commit .env files
git add .env

# ✅ Add to .gitignore
echo ".env" >> .gitignore

2. Use Environment Variables​

// ✅ Use environment variables
const apiKey = process.env.FLOW_API_KEY;

3. Use Different Keys for Different Environments​

const apiKey = process.env.NODE_ENV === 'production'
  ? process.env.FLOW_API_KEY_PROD
  : process.env.FLOW_API_KEY_DEV;

4. Rotate Keys Regularly​

  • Delete unused keys
  • Create new keys periodically
  • Monitor key usage

5. Use Least Privilege​

Only grant necessary permissions:

// ✅ Scoped key for specific use case
const readOnlyKey = await flow.apiKeys.create({
  name: 'Monitoring Key',
  permissions: ['posts:read', 'analytics:read'],
});

Error Responses​

Invalid API Key (401)​

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key",
    "code": "INVALID_API_KEY"
  }
}

Solutions:

  • Check that your API key is correct
  • Ensure the Authorization header is formatted correctly
  • Verify the API key hasn't been revoked

Missing API Key (401)​

{
  "error": {
    "type": "authentication_error",
    "message": "API key required",
    "code": "MISSING_API_KEY"
  }
}

Solutions:

  • Include the Authorization header in your request
  • Format: Authorization: Bearer flow_sk_live_...

Insufficient Permissions (403)​

{
  "error": {
    "type": "authorization_error",
    "message": "Insufficient permissions",
    "code": "INSUFFICIENT_PERMISSIONS",
    "details": [
      {
        "field": "permission",
        "message": "Required permission: posts:write"
      }
    ]
  }
}

Solutions:

  • Check your API key permissions
  • Create a new API key with the required permissions

Testing Authentication​

Test your API key with a simple request:

curl https://api.flow.dev/v1/health \
  -H "Authorization: Bearer flow_sk_live_..."

A successful response confirms your API key is valid.

Next Steps​