> For the complete documentation index, see [llms.txt](https://docs.iynxdev.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.iynxdev.com/configuration-files/web-api.md).

# Web API

## <mark style="color:blue;">Introduction</mark>

The Web API configuration file (`web_api.json`) manages the built-in web server for API endpoints, webhooks, and external integrations.

***

## <mark style="color:blue;">Port</mark>

**Type:** String

Server port for the Web API.

```json
port: "3111"
```

The bot will listen for HTTP requests on this port.

***

## <mark style="color:blue;">Authentication Key</mark>

**Type:** Array of Strings

API keys required to access endpoints.

```json
authentication_key: ['09563-34763-36235-36235', 'second-key-here']
```

{% hint style="danger" %}
**Security Warning:** Change the default authentication key immediately! Never share these keys publicly.
{% endhint %}

Requests must include one of these keys in the authentication header.

***

## <mark style="color:blue;">Whitelisted IPs</mark>

**Type:** Array of Strings

IP addresses allowed to access the API.

```json
whitelisted_ips: ['18.209.80.3', '54.87.231.232', '203.0.113.0']
```

**Default IPs included:**

* `18.209.80.3` - Tebex server
* `54.87.231.232` - Tebex server

{% hint style="warning" %}
**Important:** Do not remove the Tebex IPs if you use the Tebex integration, or webhooks will fail.
{% endhint %}

***

## <mark style="color:blue;">Secure Mode</mark>

**Type:** Boolean

Restrict API to whitelisted IPs only.

```json
secure_mode: false
```

**When `true`:** Only whitelisted IPs can access the API (still requires authentication)\
**When `false`:** All IPs can access with valid authentication key

***

## <mark style="color:blue;">Base IP</mark>

**Type:** String

Base URL for API hooks and webhooks.

```json
base_ip: "bot.example.com"
```

**Format options:**

* With domain: `"bot.example.com"` or `"api.example.com"`
* Without domain: `"192.168.1.100:3111"` (IP:port format)

Used to construct full URLs for external services like Tebex webhooks.

***

## <mark style="color:blue;">Rate Limit</mark>

Prevent API abuse with request limiting.

### <mark style="color:yellow;">enabled</mark>

**Type:** Boolean

Enable rate limiting.

```json
rate_limit: {
    enabled: true,
}
```

***

### <mark style="color:yellow;">window\_ms</mark>

**Type:** Number

Time window for rate limit in milliseconds.

```json
window_ms: 300000
```

**Example:** `300000` = 5 minutes (300,000 milliseconds)

After this window elapses, the request count resets for that client.

***

### <mark style="color:yellow;">max</mark>

**Type:** Number

Maximum requests per window.

```json
max: 150
```

Clients exceeding this limit during the time window will be rate limited.

***

### <mark style="color:yellow;">proxied</mark>

**Type:** Boolean

Whether API is behind a reverse proxy.

```json
proxied: false
```

**When `true`:** Bot uses proxy headers to identify real client IP (required for Nginx/Apache)\
**When `false`:** Direct connection IP is used

{% hint style="info" %}
**Reverse Proxy Users:** If you use Nginx, Apache, or Cloudflare in front of the bot, set this to `true` to ensure correct IP detection for rate limiting and security.
{% endhint %}

***

### <mark style="color:yellow;">proxies\_between\_user\_and\_server</mark>

**Type:** Number

Number of proxy layers between client and bot.

```json
proxies_between_user_and_server: 1
```

Only relevant when `proxied` is `true`.

**Examples:**

* Direct proxy: `1`
* Cloudflare + Nginx: `2`

***

## <mark style="color:blue;">Complete Configuration Example</mark>

Here's a production-ready Web API configuration:

```json
{
    config: {
        port: "3111",

        authentication_key: ['your-secure-key-here-change-this'],

        whitelisted_ips: [
            '18.209.80.3',      // Tebex
            '54.87.231.232',    // Tebex
            '203.0.113.10',     // Your server IP
        ],

        secure_mode: true,

        base_ip: "api.yourserver.com",

        rate_limit: {
            enabled: true,
            window_ms: 300000,
            max: 150,
            proxied: true,
            proxies_between_user_and_server: 1,
        },
    },
}
```