# 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,
        },
    },
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.iynxdev.com/configuration-files/web-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.