Authentication

FlowGenX supports two primary authentication methods for API access: API Keys and OAuth 2.0 with JWT tokens via Keycloak integration.

API Key Management

Key Features

• Lifecycle Management: Create, rotate, and delete keys with ease
• Expiration Control: Set custom expiration dates or create non-expiring keys
• Grace Period Rotation: Zero-downtime key rotation with configurable grace periods
• Security Controls: Rate limiting, IP allowlisting, and metadata support
• Usage Tracking: Monitor when keys were last used and their status

Creating an API Key

1. Navigate to ACL Management → API Keys section
2. Click Create API Key
3. Configure the key:

4. Click Create API Key
5. Important: Copy the generated key immediately - it cannot be retrieved later!

Key Rotation

To rotate a key:

1. Locate the key in the API Keys list
2. Click the Rotate button (refresh icon)
3. Set the Grace Period (default: 7 days)
4. Click Rotate Key
5. Copy the new key and update your applications
6. Test with the new key before the grace period expires

Key Status Indicators

Filtering and Search

Find keys quickly using advanced filters:

• Search Bar: Filter by key name, consumer username, or description
• Status Filter: Active, Inactive, Expired, Expiring Soon
• Consumer Filter: View keys for specific consumers
• Date Filter: Expires in 30 days, Already expired, Never expires
• Sort Options: By creation date, expiry date, or key name (ascending/descending)

Best Practices

✓ Use descriptive key names that indicate application/service purpose ✓ Set expiration dates for production keys (recommended: 90-365 days) ✓ Rotate keys regularly using the grace period feature ✓ Delete unused keys immediately to reduce attack surface ✓ Use IP allowlisting for sensitive endpoints ✓ Monitor "Last Used" timestamps to identify stale keys ✓ Never commit keys to version control

OAuth & JWT Management

OAuth Client Types

• Service Account Clients: Machine-to-machine authentication
• OpenID Connect: Standard OAuth 2.0 protocol support
• ACL Integration: Automatic permission inheritance from consumer groups

Client Properties

Each OAuth client includes:

Creating an OAuth Client

Steps to create:

1. Navigate to ACL Management → Consumers
2. Select or create a consumer
3. Click the OAuth action for that consumer
4. Click Create OAuth Client
5. Configure:
   • Client ID: Auto-generated or custom
   • Name: Descriptive name
   • Description: Optional purpose
   • ACL Groups: Inherited from consumer
   • Enable Service Account: For machine-to-machine auth
   • Redirect URIs: Optional for web flows
6. Click Create
7. Critical: Save the client secret immediately!

Testing OAuth Flow

1. Go to OAuth & JWT Management section
2. Click the Test OAuth flow button (terminal icon) for your client
3. Enter the client secret
4. Click Get Access Token
5. Review results:
   • Token validity status
   • ACL claim presence
   • Inherited ACL groups
   • Token expiration time
   • Decoded JWT payload

Managing Client Secrets

View Secret:

• Click the View secret button (eye icon)
• Secret displayed in secure modal
• Copy if needed

Regenerate Secret:

• Click the Regenerate secret button (key icon)
• Confirm action (old secret stops working immediately!)
• Copy new secret
• Update all applications

ACL Group Inheritance

OAuth clients automatically inherit permissions:

graph LR
    A[Consumer] -->|Assigned to| B[ACL Groups]
    A -->|Has| C[OAuth Client]
    C -->|Inherits| B
    C -->|Issues| D[JWT Token]
    D -->|Contains| E[acl_groups claim]

1. Assign groups to consumer
2. OAuth client inherits all consumer group permissions
3. JWT tokens include acl_groups claim
4. Permission changes reflect immediately in new tokens

Best Practices

✓ Create separate OAuth clients for each application/service ✓ Use service accounts for backend services (machine-to-machine) ✓ Store secrets in secure vaults (AWS Secrets Manager, HashiCorp Vault) ✓ Regenerate secrets if compromised ✓ Disable clients instead of deleting for temporary suspension ✓ Test tokens after creation to verify permissions ✓ Use descriptive names indicating application purpose ✓ Document which applications use which clients

Environment Filtering

Both API Keys and OAuth clients support environment-specific filtering:

• Use the Environment Selector dropdown
• Filter by: Development, Staging, Production, or All
• Keys and clients are environment-specific
• Provides complete isolation across deployment stages

Common Use Cases

API Keys

• Mobile apps requiring simple authentication
• IoT devices with limited resources
• Third-party integrations
• Testing and development environments

OAuth/JWT

• Microservices architecture with service-to-service auth
• Enterprise applications requiring SSO integration
• Multi-tenant SaaS platforms
• Compliance-driven audit requirements

Security Considerations

API Keys:

• Treat as passwords - never commit to repositories
• Use HTTPS only
• Implement quarterly rotation policies
• Monitor usage patterns for anomalies
• Set expiration dates to limit exposure

OAuth Clients:

• Store secrets in secure vaults
• Use service accounts for non-interactive apps
• Implement token refresh flows
• Monitor validation failures
• Regenerate on suspected compromise

Troubleshooting

API Key Issues

Key Not Working

• Verify key status (not expired/disabled)
• Check IP restrictions
• Confirm consumer association
• Review rate limit status

Rotation Failed

• Ensure sufficient grace period
• Verify old key still valid
• Check application configuration

OAuth Issues

Token Request Failed

• Verify client secret accuracy
• Check client enabled status
• Confirm Keycloak realm configuration
• Validate service account settings

Access Denied Despite Valid Token

• Review ACL groups in decoded token
• Verify consumer group assignments
• Confirm route permissions
• Check Kong gateway sync status