Authentication

FlatRun uses a two-step authentication process: API keys for initial login and JWT tokens for subsequent requests.

Authentication Flow

1. Client sends API key to login endpoint
2. Server validates API key and returns JWT token
3. Client includes JWT token in all subsequent requests
4. When token expires, client logs in again

API Keys

API keys are configured in the agent's config file. These are the secrets used to authenticate and obtain JWT tokens.

auth:
  enabled: true
  api_keys:
    - "your-api-key-here"
    - "another-key-for-different-client"
  jwt_secret: "random-secret-for-signing"

Login

Exchange an API key for a JWT token:

POST /api/auth/login
Content-Type: application/json

{
  "api_key": "your-api-key-here"
}

Response

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2024-01-02T12:00:00Z"
}

Example

# Login and store token
TOKEN=$(curl -s -X POST http://localhost:8090/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"api_key": "your-api-key"}' | jq -r '.token')

echo $TOKEN

Using JWT Tokens

Include the JWT token in the Authorization header:

Authorization: Bearer <token>

Example

curl http://localhost:8090/api/deployments \
  -H "Authorization: Bearer $TOKEN"

Check Auth Status

Check if authentication is enabled (no auth required):

GET /api/auth/status

Response

{
  "enabled": true
}

Validate Token

Check if a token is still valid:

GET /api/auth/validate
Authorization: Bearer <token>

Response

{
  "valid": true,
  "expires_at": "2024-01-02T12:00:00Z"
}

Token Expiration

JWT tokens expire after a configured period (default: 24 hours). When a token expires:

• API requests return 401 Unauthorized
• Client must login again with API key

Error Responses

Invalid API Key

HTTP 401 Unauthorized

{
  "error": "Invalid API key"
}

Missing Token

HTTP 401 Unauthorized

{
  "error": "Authorization header required"
}

Invalid Token

HTTP 401 Unauthorized

{
  "error": "Invalid or expired token"
}

Complete Example

A bash script that handles authentication:

#!/bin/bash

API_URL="http://localhost:8090/api"
API_KEY="your-api-key"
TOKEN_FILE="/tmp/flatrun-token"

# Function to get or refresh token
get_token() {
  # Check if we have a cached token
  if [ -f "$TOKEN_FILE" ]; then
    TOKEN=$(cat "$TOKEN_FILE")
    # Validate token
    VALID=$(curl -s -o /dev/null -w "%{http_code}" \
      "$API_URL/auth/validate" \
      -H "Authorization: Bearer $TOKEN")
    if [ "$VALID" = "200" ]; then
      echo "$TOKEN"
      return
    fi
  fi

  # Get new token
  TOKEN=$(curl -s -X POST "$API_URL/auth/login" \
    -H "Content-Type: application/json" \
    -d "{\"api_key\": \"$API_KEY\"}" | jq -r '.token')

  echo "$TOKEN" > "$TOKEN_FILE"
  echo "$TOKEN"
}

# Get token
TOKEN=$(get_token)

# Use token in API call
curl -s "$API_URL/deployments" \
  -H "Authorization: Bearer $TOKEN" | jq

Disabling Authentication

For development or trusted environments, authentication can be disabled:

auth:
  enabled: false