Authentication

Flow API uses API key authentication. All requests to the /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!

Your API key format:

flow_sk_live_<prefix>_<secret>

Using Your API Key

Include your API key in the Authorization header of every request:

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

Using SDKs

The 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 posts
• channels:read - Read channels
• channels:write - Create/update channels
• connections:read - Read connections
• connections:write - Manage connections
• webhooks:read - Read webhooks
• webhooks:write - Manage webhooks

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

Security Best Practices

1. Never commit API keys to version control

   • Use environment variables
   • Use secret management tools

2. Use different keys for different environments

   • Production keys
   • Development keys
   • Testing keys

3. Rotate keys regularly

   • Delete unused keys
   • Create new keys periodically

4. Use the least privilege principle

   • Only grant necessary permissions
   • Create separate keys for different use cases

5. Monitor key usage

   • Check the API key usage in your dashboard
   • Set up alerts for unusual activity

Error Responses

Invalid API Key

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

Status Code: 401 Unauthorized

Missing API Key

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

Status Code: 401 Unauthorized

Insufficient Permissions

{
  "error": {
    "type": "authorization_error",
    "message": "Insufficient permissions",
    "code": "INSUFFICIENT_PERMISSIONS"
  }
}

Status Code: 403 Forbidden

Testing Authentication

You can 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.