Authentication

How to authenticate requests with the AI Flow API.

API Key Authentication

The AI Flow service can authenticate your webhook endpoint using shared secrets.

Setting Up Shared Secrets

When configuring your webhook settings, you can optionally store a shared secret if you want to use AI Flow authentication:

1. In your webhook settings, optionally store a shared secret for AI Flow authentication
2. The service will send this shared secret in request headers for validation
3. Validate the shared secret in your webhook handler to authenticate requests

Verifying Shared Secrets

AI Flow sends the shared secret in the request headers. Validate this shared secret in your webhook handler:

Python (Flask)

from flask import Flask, request, abort
import os

# The shared secret you configured in your webhook settings
SHARED_SECRET = os.environ.get('AI_FLOW_SHARED_SECRET')

@app.route('/webhook', methods=['POST'])
def webhook():
    # Verify shared secret sent by AI Flow
    provided_secret = request.headers.get('X-API-TOKEN')
    if provided_secret != SHARED_SECRET:
        abort(401)

    # Process event
    event = request.json
    # ...

Node.js (Express)

// The shared secret you configured in your webhook settings
const SHARED_SECRET = process.env.AI_FLOW_SHARED_SECRET;

app.post('/webhook', (req, res) => {
  const providedSecret = req.headers['X-API-TOKEN'];

  if (providedSecret !== SHARED_SECRET) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  // Process event
  const event = req.body;
  // ...
});

Go

import "os"

// The shared secret you configured in your webhook settings
var sharedSecret = os.Getenv("AI_FLOW_SHARED_SECRET")

func webhook(w http.ResponseWriter, r *http.Request) {
    providedSecret := r.Header.Get("X-API-TOKEN")
    if providedSecret != sharedSecret {
        w.WriteHeader(http.StatusUnauthorized)
        return
    }

    // Process event
    // ...
}

Request Headers

The AI Flow service sends the following headers:

• X-API-TOKEN - The shared secret you configured in your webhook settings
• Content-Type: application/json - Always JSON
• User-Agent - Service identifier

Response Headers

Your responses should include:

• Content-Type: application/json - When returning an action
• HTTP Status Code:
  • 200 - Action returned
  • 204 - No action (No Content)
  • 400 - Invalid request
  • 401 - Unauthorized
  • 500 - Server error

Security Best Practices

1. Use HTTPS - Always use HTTPS in production
2. Validate Shared Secrets - Always verify the shared secret sent by AI Flow
3. Store Secrets Securely - Use environment variables or secret management
4. Use Strong Secrets - Generate cryptographically secure random secrets
5. Rate Limiting - Implement rate limiting to prevent abuse
6. Input Validation - Validate all incoming events

Environment Variables

Store shared secrets securely:

Python

import os

SHARED_SECRET = os.environ.get('AI_FLOW_SHARED_SECRET')

Node.js

const SHARED_SECRET = process.env.AI_FLOW_SHARED_SECRET;

Go

import "os"

sharedSecret := os.Getenv("AI_FLOW_SHARED_SECRET")

Next Steps

• HTTP Webhooks - Complete HTTP integration guide
• Quick Start - Build your first integration