REST API

Comprehensive REST API with OpenAPI 3.0 specification for external integrations and automation

Overview

FlagFlow provides a comprehensive REST API with OpenAPI 3.0 specification for external integrations, automation workflows, and CI/CD pipelines. All API endpoints are protected with JWT Bearer authentication and provide complete CRUD operations for users, sessions, flags, and migrations.

OpenAPI 3.0 Specification: Full API documentation is available at /api/openapi.json endpoint with interactive exploration capabilities.

Endpoint Groups: The REST API organizes endpoints into four main groups: authentication, flag management, session management, and migration operations.

Authentication

Important: The REST API only works with FlagFlow's built-in user management system. JWT Bearer tokens from Keycloak authentication cannot be used with REST API endpoints. You must create users through the built-in user management system to access the REST API.

All REST API endpoints (except /api/login) require JWT Bearer token authentication from the built-in user system. Obtain tokens through the login endpoint and include them in the Authorization header for all operations.

Login and Token Acquisition

The login endpoint authenticates users created through FlagFlow's built-in user management system only. Keycloak users cannot authenticate via this endpoint.

Authentication Login

# Request
POST /api/login
Content-Type: application/json

{
  "username": "admin",
  "password": "your-password"
}

# Response
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "user-id",
    "username": "admin",
    "permissions": ["flag:read", "flag:write", ...]
  }
}

Using Bearer Tokens

Bearer Token Usage

# Include token in Authorization header for protected endpoints
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."      -X GET http://localhost:3000/api/users

API Endpoint Groups

The REST API organizes endpoints into four main groups. All endpoints require JWT Bearer authentication except for the login endpoint.

Authentication Group

Method	Endpoint	Description	Auth
`POST`	`/api/login`	Authenticate and obtain JWT token	None
`GET`	`/api/users`	List all users	Bearer
`POST`	`/api/users`	Create new user	Bearer
`GET`	`/api/users/{userId}`	Get user by ID	Bearer
`PUT`	`/api/users/{userId}`	Update user	Bearer
`DELETE`	`/api/users/{userId}`	Delete user	Bearer

Flag Group

Method	Endpoint	Description	Auth
`GET`	`/api/flags`	List all flags with metadata	Bearer
`POST`	`/api/flags`	Create new flag	Bearer
`GET`	`/api/flags/{flagName}`	Get flag details	Bearer
`PUT`	`/api/flags/{flagName}`	Update flag	Bearer
`DELETE`	`/api/flags/{flagName}`	Delete flag	Bearer

Session Group

Method	Endpoint	Description	Auth
`GET`	`/api/sessions`	List active sessions	Bearer
`DELETE`	`/api/sessions/{sessionId}`	Terminate session	Bearer

Migration Group

Method	Endpoint	Description	Auth
`GET`	`/api/migrations/export`	Export flags as migration file	Bearer
`PUT`	`/api/migrations`	Execute migration from file upload	Bearer
`PATCH`	`/api/migrations`	Execute migration from remote URL	Bearer

Usage Examples

Authentication Group Examples

# Login to get JWT token
curl -X POST http://localhost:3000/api/login   -H "Content-Type: application/json"   -d '{
    "username": "admin",
    "password": "your-password"
  }'

# Create a new user
curl -X POST http://localhost:3000/api/users   -H "Authorization: Bearer YOUR_TOKEN"   -H "Content-Type: application/json"   -d '{
    "username": "developer",
    "password": "secure-password",
    "permissions": ["flag:read", "flag:write"]
  }'

# List all users
curl -X GET http://localhost:3000/api/users   -H "Authorization: Bearer YOUR_TOKEN"

# Update user permissions
curl -X PUT http://localhost:3000/api/users/user-123   -H "Authorization: Bearer YOUR_TOKEN"   -H "Content-Type: application/json"   -d '{
    "permissions": ["flag:read", "flag:write", "user:read"]
  }'

Flag Group Examples

# Create a new boolean flag
curl -X POST http://localhost:3000/api/flags   -H "Authorization: Bearer YOUR_TOKEN"   -H "Content-Type: application/json"   -d '{
    "name": "features/new-dashboard",
    "type": "BOOLEAN",
    "value": false,
    "description": "Enable new dashboard layout"
  }'

# List all flags with metadata
curl -X GET http://localhost:3000/api/flags   -H "Authorization: Bearer YOUR_TOKEN"

# Get specific flag details
curl -X GET http://localhost:3000/api/flags/features/new-dashboard   -H "Authorization: Bearer YOUR_TOKEN"

# Update flag value
curl -X PUT http://localhost:3000/api/flags/features/new-dashboard   -H "Authorization: Bearer YOUR_TOKEN"   -H "Content-Type: application/json"   -d '{
    "value": true
  }'

# Delete flag
curl -X DELETE http://localhost:3000/api/flags/features/new-dashboard   -H "Authorization: Bearer YOUR_TOKEN"

Session Group Examples

# List active sessions
curl -X GET http://localhost:3000/api/sessions   -H "Authorization: Bearer YOUR_TOKEN"

# Terminate a specific session
curl -X DELETE http://localhost:3000/api/sessions/session-abc123   -H "Authorization: Bearer YOUR_TOKEN"

Migration Group Examples

# Export all flags to migration file
curl -X GET http://localhost:3000/api/migrations/export   -H "Authorization: Bearer YOUR_TOKEN"   -o flags-backup.json

# Import flags from file upload
curl -X PUT http://localhost:3000/api/migrations   -H "Authorization: Bearer YOUR_TOKEN"   -H "Content-Type: application/json"   -d @flags-backup.json

# Import flags from remote URL
curl -X PATCH http://localhost:3000/api/migrations   -H "Authorization: Bearer YOUR_TOKEN"   -H "Content-Type: application/json"   -d '{
    "url": "https://example.com/flags-export.json"
  }'

OpenAPI Specification

FlagFlow provides a complete OpenAPI 3.0 specification for the REST API, enabling automatic client generation and interactive exploration.

Accessing the OpenAPI Spec

OpenAPI Specification Access

# Get the OpenAPI 3.0 specification
GET http://localhost:3000/api/openapi.json

# The specification includes:
# - All endpoint definitions
# - Request/response schemas
# - Authentication requirements
# - Error response formats
# - Example payloads

Interactive API Explorer: Use the OpenAPI specification with tools like Swagger UI, Postman, or Insomnia for interactive API exploration and testing.

Client Generation

Client Generation Examples

# Generate TypeScript client
npx @openapitools/openapi-generator-cli generate   -i http://localhost:3000/api/openapi.json   -g typescript-fetch   -o ./src/api-client

# Generate Python client
openapi-generator generate   -i http://localhost:3000/api/openapi.json   -g python   -o ./flagflow-client

Error Handling

The REST API provides consistent error responses with detailed information for debugging and error handling in client applications.

Error Response Format

Error Response Structure

# Standard error response format
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Validation failed",
    "details": {
      "field": "username",
      "reason": "Username is required"
    }
  }
}

Common HTTP Status Codes

Status Code	Description	Common Causes
`400`	Bad Request	Invalid JSON, validation errors
`401`	Unauthorized	Missing or invalid JWT token
`403`	Forbidden	Insufficient permissions
`404`	Not Found	Resource does not exist
`409`	Conflict	Resource already exists

Best Practices

Authentication

Store JWT tokens securely
Implement token refresh logic
Handle authentication failures gracefully
Use HTTPS in production

Error Handling

Always check HTTP status codes
Parse error response details
Implement retry logic for transient failures
Log API errors for debugging

Integration Tips

CI/CD Integration: Use the REST API for automated flag management in deployment pipelines
Environment Sync: Use migration endpoints to synchronize flags across environments
Monitoring: Set up monitoring for API rate limits and error rates
Documentation: Keep your API integration documentation updated with the OpenAPI spec

Explore these related topics for comprehensive FlagFlow REST API usage:

REST API

Overview

Authentication

Login and Token Acquisition

Using Bearer Tokens

API Endpoint Groups

Authentication Group

Flag Group

Session Group

Migration Group

Usage Examples

Authentication Group Examples

Flag Group Examples

Session Group Examples

Migration Group Examples

OpenAPI Specification

Accessing the OpenAPI Spec

Client Generation

Error Handling

Error Response Format

Common HTTP Status Codes

Best Practices

Authentication

Error Handling

Integration Tips

Authentication

Permissions

Migration System

Flag Types

REST API

Overview

Authentication

Login and Token Acquisition

Using Bearer Tokens

API Endpoint Groups

Authentication Group

Flag Group

Session Group

Migration Group

Usage Examples

Authentication Group Examples

Flag Group Examples

Session Group Examples

Migration Group Examples

OpenAPI Specification

Accessing the OpenAPI Spec

Client Generation

Error Handling

Error Response Format

Common HTTP Status Codes

Best Practices

Authentication

Error Handling

Integration Tips

Related Documentation

Authentication

Permissions

Migration System

Flag Types