Generate Proxy Plugin

The generate proxy command creates a proxy plugin configuration that allows Qelos to forward API requests from a local path to an external endpoint. This is useful for integrating external APIs into your Qelos application while maintaining a clean URL structure.

Overview

Proxy plugins in Qelos enable you to:

• Forward requests from /api/[path] to external endpoints
• Add optional authentication tokens to proxied requests
• Maintain a consistent API structure within your application
• Hide external API complexities from your frontend code

Usage

qelos generate proxy <pathFrom> <endpointTo> [--token]

Arguments

• <pathFrom> - The local path for the proxy (without /api/ prefix)

  • Example: external, payments, analytics
  • Qelos automatically prefixes with /api/[path]

• <endpointTo> - The external endpoint URL to proxy to

  • Must be a full URL including protocol
  • Example: https://api.example.com, https://api.stripe.com

Options

• --token - Optional authentication token for the proxy
  • Can also be set using the QELOS_PROXY_TOKEN environment variable
  • Command line flag takes precedence over environment variable

Examples

Basic Proxy Without Authentication

qelos generate proxy external https://api.example.com

This creates a plugin that forwards requests from /api/external to https://api.example.com.

Proxy with Command Line Token

qelos generate proxy payments https://api.stripe.com --token sk_test_123456789

This adds the authentication token to all proxied requests.

Proxy with Environment Variable

export QELOS_PROXY_TOKEN=sk_test_123456789
qelos generate proxy payments https://api.stripe.com

The token is read from the environment variable.

Generated Plugin Structure

The command generates a plugin file with the following structure:

{
  "name": "external",
  "description": "external api",
  "manifestUrl": "",
  "apiPath": "external",
  "authAcquire": {
    "refreshTokenKey": "refresh_token",
    "accessTokenKey": "access_token"
  },
  "proxyUrl": "https://api.example.com",
  "subscribedEvents": [],
  "microFrontends": [],
  "injectables": [],
  "navBarGroups": [],
  "cruds": [],
  "token": "optional-token-if-provided"
}

Fields Explained

• name: Generated from pathFrom by replacing / with -
• apiPath: The path used for routing (matches <pathFrom>)
• proxyUrl: The external endpoint where requests are forwarded
• token: Optional authentication token added to proxied requests
• authAcquire: Configuration for OAuth token handling (if needed)

Request Flow

When a proxy plugin is active:

1. Client makes request to /api/external/some/endpoint
2. Qelos receives the request
3. Request is forwarded to https://api.example.com/some/endpoint
4. Qelos automatically adds the following headers to the proxied request:
   • Authorization: Bearer [token] - If a token is configured in the plugin
   • user: [JSON] - Contains the authenticated user information (if available)
5. Response from external API is returned to the client

Automatic Headers

Qelos automatically enhances proxied requests with important authentication and user context:

Authorization Header

• Format: Authorization: Bearer [plugin-token]
• Source: The token configured in the plugin (via --token flag or QELOS_PROXY_TOKEN env var)
• Purpose: Allows the external API to authenticate the request
• Note: Only added if a token is configured in the plugin

User Header

• Format: user: [JSON-string]
• Source: The authenticated Qelos user making the request
• Purpose: Provides user context to the external API
• Example:

  {
    "_id": "user123",
    "username": "john.doe",
    "email": "john@example.com",
    "fullName": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "birthDate": "1990-01-01",
    "roles": ["admin", "user"],
    "workspace": {
      "_id": "workspace456",
      "name": "Acme Corp",
      "roles": ["admin"],
      "labels": ["enterprise"]
    }
  }

• Note: Only added if the user is authenticated in Qelos

Updating Existing Proxies

If a proxy plugin already exists, the command will:

• Update the apiPath and proxyUrl with new values
• Update the token only if a new token is provided (via flag or env)
• Preserve all other configuration (micro-frontends, cruds, etc.)

Security Considerations

Token Management

• Command Line: Tokens are visible in shell history
• Environment Variable: More secure, not visible in command history
• Plugin File: Tokens are stored in plain text in the plugin JSON file

Best Practices

1. Use environment variables for production tokens
2. Rotate tokens regularly
3. Use separate tokens for different environments
4. Limit token permissions to only what's necessary

Common Use Cases

Payment Gateway Integration

qelos generate proxy payments https://api.stripe.com --token $STRIPE_SECRET_KEY

Frontend can now use /api/payments/charges instead of directly calling Stripe API.

Third-party Analytics

qelos generate proxy analytics https://analytics.googleapi.com --token $GA_API_KEY

Analytics requests are proxied through Qelos, keeping API keys secure.

Legacy API Integration

qelos generate proxy legacy https://legacy-api.company.com/v2

Modern frontend can interact with legacy APIs through a clean URL structure.

Deployment

After generating the proxy plugin:

1. Review the generated plugin file in plugins/[name].plugin.json
2. Test the proxy locally
3. Push to Qelos:

qelos push plugins ./plugins/external.plugin.json

4. The proxy will be available at /api/[path] in your Qelos instance

Troubleshooting

Common Issues

1. 404 Errors: Ensure the plugin has been pushed to Qelos
2. Authentication Failures: Verify the token is correct and has proper permissions
3. CORS Issues: The external API must allow requests from your Qelos domain
4. Timeouts: Large responses may timeout; consider increasing timeout values

Debugging

Check the plugin configuration:

cat plugins/external.plugin.json

Verify the proxy is working:

curl -X GET "https://your-qelos-instance.com/api/external/health"

Related Commands

• qelos push - Deploy the proxy plugin to Qelos
• qelos generate connection - Create secure connection configurations
• qelos agent - Interact with AI agents

Related Resources

• Plugin Development - Complete plugin development guide
• API Proxy Plugin - Advanced proxy configuration
• Authentication - OAuth and token management