NyaProxy

A lightweight, header-based API proxy for managing authenticated upstream services.

English | 简体中文 | 日本語

Centralize credential injection, quota-aware routing, rate limiting, retries, and observability for any HTTP API that uses keys or tokens.

Overview

NyaProxy is a small API gateway for services that authenticate with API keys, bearer tokens, or custom request headers. Applications call NyaProxy with an internal proxy key, and NyaProxy forwards the request to the configured upstream service with the correct upstream credentials and policy controls.

It is useful when a team needs one place to manage access to external or internal APIs such as AI providers, image generation APIs, SaaS APIs, data vendor APIs, or private services.

Use NyaProxy only with credentials and traffic patterns that are allowed by the upstream service terms.

Features

Common Use Cases

• Central access gateway for third-party APIs used by multiple applications.
• Secure credential injection for browser, mobile, or internal clients that should not hold upstream secrets.
• Quota-aware routing for providers with per-key, per-minute, or per-day limits.
• Failover for services where a key or region may intermittently return 429 or 5xx.
• Request normalization across API providers with slightly different JSON payload requirements.
• Usage monitoring for teams sharing paid API credentials.

Quick Start

Install From PyPI

pip install nya-proxy
nyaproxy

NyaProxy starts on http://localhost:8080 by default.

Open:

• http://localhost:8080/config for the configuration UI
• http://localhost:8080/dashboard for metrics and queue status
• http://localhost:8080/info for configured API information

Run With a Config File

nyaproxy --config config.yaml

Install From Source

git clone https://github.com/Nya-Foundation/nyaproxy.git
cd nyaproxy
pip install -e .
nyaproxy

Docker

docker run -d \
  -p 8080:8080 \
  -v ${PWD}/config.yaml:/app/config.yaml \
  -v ${PWD}/app.log:/app/app.log \
  k3scat/nya-proxy:latest

Configuration

NyaProxy is configured with YAML. Examples are available in configs.

server:
  api_key:
    - your_admin_proxy_key
    - your_application_proxy_key
  logging:
    enabled: true
    level: info
    log_file: app.log
  dashboard:
    enabled: true
  cors:
    allow_origins: ["*"]
    allow_credentials: true
    allow_methods: ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"]
    allow_headers: ["*"]

default_settings:
  key_variable: keys
  key_concurrency: true
  load_balancing_strategy: round_robin
  allowed_paths:
    enabled: false
    mode: whitelist
    paths:
      - "*"
  allowed_methods: ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"]
  queue:
    max_size: 200
    max_workers: 10
    expiry_seconds: 300
  rate_limit:
    enabled: true
    endpoint_rate_limit: 1000/h
    key_rate_limit: 60/m
    ip_rate_limit: 5000/d
    user_rate_limit: 5000/d
    rate_limit_paths:
      - "*"
  retry:
    enabled: true
    mode: key_rotation
    attempts: 3
    retry_after_seconds: 1
    retry_request_methods: [POST, GET, PUT, DELETE, PATCH, OPTIONS]
    retry_status_codes: [429, 500, 502, 503, 504]
  timeouts:
    request_timeout_seconds: 300

apis:
  example_service:
    name: Example Service
    endpoint: https://api.example.com/v1
    key_variable: keys
    headers:
      Authorization: "Bearer ${{keys}}"
    variables:
      keys:
        - upstream_key_1
        - upstream_key_2
    load_balancing_strategy: least_requests

Request Format

Requests are forwarded through /api/<api_name>/<path>.

For this API config:

apis:
  example_service:
    endpoint: https://api.example.com/v1

This proxy request:

POST http://localhost:8080/api/example_service/messages

is forwarded to:

POST https://api.example.com/v1/messages

API Examples

Generic Bearer Token API

apis:
  data_vendor:
    name: Data Vendor API
    endpoint: https://api.vendor.example/v2
    key_variable: tokens
    headers:
      Authorization: "Bearer ${{tokens}}"
    variables:
      tokens:
        - vendor_token_1
        - vendor_token_2
    rate_limit:
      enabled: true
      endpoint_rate_limit: 5000/d
      key_rate_limit: 60/m

Custom Header API

apis:
  internal_service:
    name: Internal Service
    endpoint: https://internal.example.com
    key_variable: service_tokens
    headers:
      X-Service-Token: "${{service_tokens}}"
      X-Client-Name: "nyaproxy"
    variables:
      service_tokens:
        - service_token_1
        - service_token_2

OpenAI-Compatible API

apis:
  openai_compatible:
    name: OpenAI-Compatible Provider
    endpoint: https://api.provider.example/v1
    key_variable: keys
    headers:
      Authorization: "Bearer ${{keys}}"
    variables:
      keys:
        - provider_key_1
        - provider_key_2
    allowed_paths:
      enabled: true
      mode: whitelist
      paths:
        - "/chat/*"
        - "/images/*"
    request_body_substitution:
      enabled: true
      rules:
        - name: "Remove unsupported field"
          operation: remove
          path: "frequency_penalty"
          conditions:
            - field: "frequency_penalty"
              operator: "exists"

Image Generation API

apis:
  image_service:
    name: Image Generation Service
    endpoint: https://image.example.com
    key_variable: tokens
    headers:
      Authorization: "Bearer ${{tokens}}"
    variables:
      tokens:
        - image_token_1
        - image_token_2
    load_balancing_strategy: round_robin
    rate_limit:
      enabled: true
      endpoint_rate_limit: 100/h
      key_rate_limit: 10/m

Security Notes

• Set server.api_key before exposing NyaProxy outside localhost.
• if server.api_key is not configured, NyaProxy falls back to SUPER_SECURE_PASSWORD!!!.
• The first key in server.api_key is treated as the admin key for dashboard and configuration access.
• Additional proxy keys can be used by applications for regular proxied API requests.
• Do not share upstream provider credentials with clients. Store them in NyaProxy configuration or your deployment secret manager.
• Restrict server.cors.allow_origins to trusted origins when using credentials in browsers.
• Use allowed_paths and allowed_methods to limit what clients can call.
• Keep logs private. Debug logs may contain request metadata that should be treated as sensitive.

Rate Limiting

NyaProxy supports multiple limiter scopes:

• endpoint_rate_limit: total request rate for one configured upstream API.
• key_rate_limit: request rate for each upstream credential.
• ip_rate_limit: request rate per client IP.
• user_rate_limit: request rate per proxy API key.

Supported formats:

10/s     # 10 requests per second
60/m     # 60 requests per minute
1000/h   # 1000 requests per hour
5000/d   # 5000 requests per day
1/15s    # 1 request per 15 seconds

Request Body Substitution

Request body substitution can set or remove JSON fields before forwarding the request. This is useful for provider compatibility, default values, and policy enforcement.

request_body_substitution:
  enabled: true
  rules:
    - name: "Cap temperature"
      operation: set
      path: "temperature"
      value: 0.7
      conditions:
        - field: "temperature"
          operator: "gt"
          value: 0.7

See Request Body Substitution for the full rule syntax.

Management Endpoints

Deployment Guides

• Docker Deployment Guide
• PIP Installation Guide

Project Status

NyaProxy is in active development. Configuration and behavior may change between releases. Pin a tested version for production deployments and review the changelog before upgrading.

Community

• Issues: GitHub Issues
• Discord: Nya Foundation
• Contact: [email protected]

License

NyaProxy is released under the MIT License.