# API Endpoints

## General

## Authenticate User

<mark style="color:green;">`POST`</mark> `/api/auth/token`

You have to authenticate the client and retrieve Bearer token in order to send requests to API Endpoints.

#### Headers

| Name   | Type | Description      |
| ------ | ---- | ---------------- |
| Accept |      | application/json |

#### Request Body

| Name                                           | Type   | Description                                                              |
| ---------------------------------------------- | ------ | ------------------------------------------------------------------------ |
| username<mark style="color:red;">\*</mark>     | String | Alphanumeric username of the client                                      |
| password<mark style="color:red;">\*</mark>     | String | Password of the client                                                   |
| device\_name<mark style="color:red;">\*</mark> | String | The device name the user tries to authenticate from. (Ex: Liam's iPhone) |

{% tabs %}
{% tab title="200: OK Returns an authorization token to be used as Bearer token for API requests." %}

```javascript
{
    "success": true,
    "message": null,
    "token": "12|TDLLcUvoJlzYKMgMi398WwxjW6tcY8OJtZkWcfTC"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity The given data was invalid. (Ex: Password was not sent)" %}

```javascript
{
    "message": "The given data was invalid.",
    "errors": {
        "password": [
            "The password field is required."
        ]
    }
}
```

{% endtab %}

{% tab title="400: Bad Request Your account has been suspended." %}

```javascript
{
    "status": false,
    "error": "Your account has been suspended.",
    "suspend_reason": null
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity The provided credentials are incorrect." %}

```javascript
{
    "success": false,
    "message": "The provided credentials are incorrect."
}
```

{% endtab %}
{% endtabs %}

## Account Details

<mark style="color:blue;">`GET`</mark> `/api/account`

Retrieve general details of user account

#### Headers

| Name                                            | Type   | Description                                                            |
| ----------------------------------------------- | ------ | ---------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer <mark style="color:yellow;">**Authorization-Token-Here**</mark> |
| Accept<mark style="color:red;">\*</mark>        | String | application/json                                                       |

{% tabs %}
{% tab title="200: OK Return user data" %}

```javascript
{
    "success": true,
    "message": null,
    "data": {
        "user_id": 1,
        "username": "admin",
        "email": "admin@example.com",
        "status": 2,
        "suspend_reason": null,
        "service": [
            {
                "id": 1,
                "user_id": 1,
                "plan_id": 3,
                "name": "Gold Plan",
                "next_payment": "2022-06-15T00:06:00.000000Z",
                "auto_renew": 1,
                "status": 1
            }
        ],
        "created_at": null,
        "updated_at": "2021-12-21T20:16:32.000000Z"
    }
}
```

{% endtab %}

{% tab title="401: Unauthorized Missing or wrong Bearer token" %}

```javascript
{
    "success": false,
    "message": "Unauthenticated."
}
```

{% endtab %}
{% endtabs %}

## Server List

<mark style="color:blue;">`GET`</mark> `/api/servers`

Get all VPN servers available

#### Headers

| Name                                            | Type   | Description                                                            |
| ----------------------------------------------- | ------ | ---------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer <mark style="color:yellow;">**Authorization-Token-Here**</mark> |
| Accept<mark style="color:red;">\*</mark>        | String | application/json                                                       |

#### Request Body

| Name     | Type    | Description                                  |
| -------- | ------- | -------------------------------------------- |
| paginate | Integer | The results with be paginated by set amount. |

{% tabs %}
{% tab title="200: OK Results without pagination" %}

```javascript
{
    "data": [
        {
            "id": 1,
            "name": "Test Server",
            "country": "Germany",
            "country_slug": "germany",
            "country_iso_code": "de",
            "city": "",
            "state": "Frankfurt",
            "host": "",
            "ipaddr": "127.0.0.1",
            "protocol": "openvpn",
            "config_id": 1,
            "wg_available_slots": 253,
            "wg_slots": 0
        },
        {
            "id": 2,
            "name": "Test Server 2",
            "country": "Germany",
            "country_slug": "germany",
            "country_iso_code": "de",
            "city": "",
            "state": "Frankfurt",
            "host": "",
            "ipaddr": "127.0.0.2",
            "protocol": "wireguard",
            "config_id": null,
            "wg_available_slots": 253,
            "wg_slots": 0
        }
    ]
}
```

{% endtab %}

{% tab title="200: OK Results paginated to 1 data per page" %}

```javascript
{
    "current_page": 1,
    "data": [
        {
            "id": 1,
            "name": "Test Server",
            "country": "Germany",
            "country_slug": "germany",
            "country_iso_code": "de",
            "city": "",
            "state": "Frankfurt",
            "host": "",
            "ipaddr": "127.0.0.1",
            "protocol": "openvpn",
            "config_id": 1,
            "wg_available_slots": 253,
            "wg_slots": 0
        }
    ],
    "first_page_url": "http://127.0.0.1:8000/api/servers?page=1",
    "from": 1,
    "last_page": 2,
    "last_page_url": "http://127.0.0.1:8000/api/servers?page=2",
    "links": [
        {
            "url": null,
            "label": "&laquo; Previous",
            "active": false
        },
        {
            "url": "http://127.0.0.1:8000/api/servers?page=1",
            "label": "1",
            "active": true
        },
        {
            "url": "http://127.0.0.1:8000/api/servers?page=2",
            "label": "2",
            "active": false
        },
        {
            "url": "http://127.0.0.1:8000/api/servers?page=2",
            "label": "Next &raquo;",
            "active": false
        }
    ],
    "next_page_url": "http://127.0.0.1:8000/api/servers?page=2",
    "path": "http://127.0.0.1:8000/api/servers",
    "per_page": "1",
    "prev_page_url": null,
    "to": 1,
    "total": 2
}
```

{% endtab %}

{% tab title="401: Unauthorized Missing or wrong Bearer token" %}

```javascript
{
    "success": false,
    "message": "Unauthenticated."
}
```

{% endtab %}
{% endtabs %}

## OpenVPN

## OpenVPN Profile

<mark style="color:blue;">`GET`</mark> `/api/openvpn/profile`

Retrieve the OpenVPN profile for specific vpn server.

#### Headers

| Name                                            | Type   | Description                                                            |
| ----------------------------------------------- | ------ | ---------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer <mark style="color:yellow;">**Authorization-Token-Here**</mark> |
| Accept<mark style="color:red;">\*</mark>        | String | application/json                                                       |

#### Request Body

| Name                                         | Type    | Description                                                                                                                      |
| -------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
| server\_id<mark style="color:red;">\*</mark> | Integer | The server id that you want to retrieve OpenVPN profile data.                                                                    |
| cert\_only                                   | Boolean | If you wish to retrieve only the ca.crt content instead of whole profile data, you can send this as True. By default it's False. |

{% tabs %}
{% tab title="200: OK Full OpenVPN profile data" %}

```javascript
{
    "success": true,
    "message": null,
    "data": "client\ndev tun\nproto udp\nremote 127.0.0.1 1194\nresolv-retry infinite\nnobind\npersist-tun\nauth-user-pass\nreneg-sec 0\nblock-outside-dns\ncipher AES-128-GCM\ntls-version-min 1.2\ntls-cipher TLS-ECDHE-ECDSA-WITH-AES-128-GCM-SHA256\nmute-replay-warnings\nverb 0\nclient-cert-not-required\nignore-unknown-option block-outside-dns\nsetenv opt block-outside-dns # Prevent Windows 10 DNS leak\n<ca>\n-----BEGIN CERTIFICATE-----\r\nMIIB2DCCAX2gAwIBAgIUOgwSKMY1IqPDbjvrVJ5S5/m5IrQwCgYIKoZIzj0EAwIw\r\nHjEcMBoGA1UEAwwTY25fenBnenhZa1J4b2dRNHJ0eTAeFw0yMTEyMjExNTU2MzVa\r\nFw0zMTEyMTkxNTU2MzVaMB4xHDAaBgNVBAMME2NuX3pwZ3p4WWtSeG9nUTRydHkw\r\nWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAAQ/BGhelZoeNxRn/ppaxxM0b3jZqbHv\r\ny0u8dXIhMWpfw+bM9zEFYxixP24Lqpt7RTiW0ML9pcBSQ/xKQGNQB3nao4GYMIGV\r\nMB0GA1UdDgQWBBSHNinCzJ65lMK0oKaanWtnfbYGvjBZBgNVHSMEUjBQgBSHNinC\r\nzJ65lMK0oKaanWtnfbYGvqEipCAwHjEcMBoGA1UEAwwTY25fenBnenhZa1J4b2dR\r\nNHJ0eYIUOgwSKMY1IqPDbjvrVJ5S5/m5IrQwDAYDVR0TBAUwAwEB/zALBgNVHQ8E\r\nBAMCAQYwCgYIKoZIzj0EAwIDSQAwRgIhAMMyz27x4tc1mWkkMqaPa7WCYJ2hAVCl\r\nsXnxlX+efW1dAiEA24iaSKjJKNsXyyzslTDegu9ktHg2AiHOVdrCIoD1Nk4=\r\n-----END CERTIFICATE-----\r\n\n</ca>\n"
}
```

{% endtab %}

{% tab title="200: OK Certificate only" %}

```javascript
{
    "success": true,
    "message": null,
    "data": "-----BEGIN CERTIFICATE-----\r\nMIIB2DCCAX2gAwIBAgIUOgwSKMY1IqPDbjvrVJ5S5/m5IrQwCgYIKoZIzj0EAwIw\r\nHjEcMBoGA1UEAwwTY25fenBnenhZa1J4b2dRNHJ0eTAeFw0yMTEyMjExNTU2MzVa\r\nFw0zMTEyMTkxNTU2MzVaMB4xHDAaBgNVBAMME2NuX3pwZ3p4WWtSeG9nUTRydHkw\r\nWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAAQ/BGhelZoeNxRn/ppaxxM0b3jZqbHv\r\ny0u8dXIhMWpfw+bM9zEFYxixP24Lqpt7RTiW0ML9pcBSQ/xKQGNQB3nao4GYMIGV\r\nMB0GA1UdDgQWBBSHNinCzJ65lMK0oKaanWtnfbYGvjBZBgNVHSMEUjBQgBSHNinC\r\nzJ65lMK0oKaanWtnfbYGvqEipCAwHjEcMBoGA1UEAwwTY25fenBnenhZa1J4b2dR\r\nNHJ0eYIUOgwSKMY1IqPDbjvrVJ5S5/m5IrQwDAYDVR0TBAUwAwEB/zALBgNVHQ8E\r\nBAMCAQYwCgYIKoZIzj0EAwIDSQAwRgIhAMMyz27x4tc1mWkkMqaPa7WCYJ2hAVCl\r\nsXnxlX+efW1dAiEA24iaSKjJKNsXyyzslTDegu9ktHg2AiHOVdrCIoD1Nk4=\r\n-----END CERTIFICATE-----\r\n"
}
```

{% endtab %}

{% tab title="401: Unauthorized Missing or wrong Bearer token" %}

```javascript
{
    "success": false,
    "message": "Unauthenticated."
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity User does not pass checks or operation failed" %}

```javascript
{
    "success": false,
    "message": "You do not have an active service."
}
```

{% endtab %}
{% endtabs %}

## OpenVPN Authentication Details

<mark style="color:blue;">`GET`</mark> `/api/openvpn/auth`

Retrieve the required username and password to be used with OpenVPN profile files in order to connect to the vpn server.

#### Headers

| Name                                            | Type   | Description                                                            |
| ----------------------------------------------- | ------ | ---------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer <mark style="color:yellow;">**Authorization-Token-Here**</mark> |
| Accept<mark style="color:red;">\*</mark>        | String | application/json                                                       |

{% tabs %}
{% tab title="200: OK OpenVPN auth details retrieved successfully." %}

```javascript
{
    "success": true,
    "message": null,
    "data": {
        "id": 1,
        "user_id": 1,
        "service_id": 1,
        "username": "admin",
        "password": "HZovQQZlQori",
        "devices": 10,
        "enabled": 1,
        "created_at": "2021-12-21T20:16:32.000000Z",
        "updated_at": "2021-12-21T20:20:21.000000Z"
    }
}
```

{% endtab %}

{% tab title="401: Unauthorized Missing or wrong Bearer token" %}

```javascript
{
    "success": false,
    "message": "Unauthenticated."
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity You do not have an active service." %}

```javascript
{
    "success": false,
    "message": "You do not have any service."
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Your service is not active." %}

```javascript
{
    "success": false,
    "message": "Your service is not active."
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Your service is expired." %}

```javascript
{
    "success": false,
    "message": "Your service is expired."
}
```

{% endtab %}

{% tab title="404: Not Found The server is not found or enabled." %}

```javascript
{
    "success": false,
    "message": "The server is not found or enabled."
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity The server is not using OpenVPN protocol." %}

```javascript
{
    "success": false,
    "message": "The server is not using OpenVPN protocol."
}
```

{% endtab %}

{% tab title="404: Not Found OpenVPN profile is not found for this server." %}

```javascript
{
    "success": false,
    "message": "OpenVPN profile is not found for this server."
}
```

{% endtab %}
{% endtabs %}

## WireGuard

## WireGuard Configurations

<mark style="color:blue;">`GET`</mark> `/api/wireguard/configs`

Retrieve all WireGuard configurations for specific vpn server.

#### Headers

| Name                                            | Type   | Description                                                            |
| ----------------------------------------------- | ------ | ---------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer <mark style="color:yellow;">**Authorization-Token-Here**</mark> |
| Accept<mark style="color:red;">\*</mark>        | String | application/json                                                       |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "status": true,
    "message": null,
    "data": [
        {
            "id": 5,
            "config": null,
            "status": 2, // 0 - Pending creation, 1 - Active, 2 - Pending deletion
            "fail_reason": null,
            "created_at": "2021-12-21T21:29:45.000000Z",
            "updated_at": "2021-12-21T21:40:02.000000Z"
        }
    ]
}
```

When a configuration status is "1" that means it was created on the server and it will set "config" data to connect WireGuard.
{% endtab %}

{% tab title="401: Unauthorized Missing or wrong Bearer token" %}

```javascript
{
    "success": false,
    "message": "Unauthenticated."
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity You do not have any service." %}

```javascript
{
    "success": false,
    "message": "You do not have any service."
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Your service is not active." %}

```javascript
{
    "success": false,
    "message": "Your service is not active."
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Your service is expired." %}

```javascript
{
    "success": false,
    "message": "Your service is expired."
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity The server is not using WireGuard protocol." %}

```javascript
{
    "success": false,
    "message": "The server is not using WireGuard protocol."
}
```

{% endtab %}

{% tab title="404: Not Found The server is not found or enabled." %}

```javascript
{
    "success": false,
    "message": "The server is not found or enabled."
}
```

{% endtab %}

{% tab title="404: Not Found No configuration found for this server." %}

```javascript
{
    "success": false,
    "message": "No configuration found for this server."
}
```

{% endtab %}
{% endtabs %}

## WireGuard Configuration

<mark style="color:green;">`POST`</mark> `/api/wireguard/create`

Create a new WireGuard configuration on specific vpn server.

#### Headers

| Name                                            | Type   | Description                                                            |
| ----------------------------------------------- | ------ | ---------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer <mark style="color:yellow;">**Authorization-Token-Here**</mark> |
| Accept<mark style="color:red;">\*</mark>        | String | application/json                                                       |

#### Request Body

| Name                                         | Type    | Description                                                                   |
| -------------------------------------------- | ------- | ----------------------------------------------------------------------------- |
| server\_id<mark style="color:red;">\*</mark> | Integer | The server id that you want to create a new WireGuard configuration for user. |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "status": true,
    "message": "WireGuard configuration create job dispatched. It will be completed shortly."
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity You do not have any service." %}

```javascript
{
    "success": false,
    "message": "You do not have any service."
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Your service is not active." %}

```javascript
{
    "success": false,
    "message": "Your service is not active."
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Your service is expired." %}

```javascript
{
    "success": false,
    "message": "Your service is expired."
}
```

{% endtab %}

{% tab title="404: Not Found The server is not found or enabled." %}

```javascript
{
    "success": false,
    "message": "The server is not found or enabled."
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity The server is not using WireGuard protocol." %}

```javascript
{
    "success": false,
    "message": "The server is not using WireGuard protocol."
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity The server has reached the maximum allowed user limit. Please try again later or choose a different server." %}

```javascript
{
    "success": false,
    "message": "The server has reached the maximum allowed user limit. Please try again later or choose a different server."
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Looks like you reached maximum allowed device limit on your plan. Please retry after disconnecting from OpenVPN or deleting WireGuard configurations that you have generated before." %}

```javascript
{
    "success": false,
    "message": "Looks like you reached maximum allowed device limit on your plan. Please retry after disconnecting from OpenVPN or deleting WireGuard configurations that you have generated before."
}
```

{% endtab %}

{% tab title="401: Unauthorized Missing or wrong Bearer token" %}

```javascript
{
    "success": false,
    "message": "Unauthenticated."
}
```

{% endtab %}
{% endtabs %}

## WireGuard Configuration

<mark style="color:red;">`DELETE`</mark> `/api/wireguard/delete`

Delete a specific WireGuard configuration.

#### Headers

| Name                                            | Type   | Description                                                            |
| ----------------------------------------------- | ------ | ---------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer <mark style="color:yellow;">**Authorization-Token-Here**</mark> |
| Accept<mark style="color:red;">\*</mark>        | String | application/json                                                       |

#### Request Body

| Name                                         | Type    | Description                                                   |
| -------------------------------------------- | ------- | ------------------------------------------------------------- |
| config\_id<mark style="color:red;">\*</mark> | Integer | Pass the WireGuard configuration id you would like to delete. |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "success": true,
    "message": "WireGuard configuration delete job dispatched. It will be completed shortly."
}
```

{% endtab %}

{% tab title="401: Unauthorized Missing or wrong Bearer token" %}

```javascript
{
    "success": false,
    "message": "Unauthenticated."
}
```

{% endtab %}

{% tab title="404: Not Found The WireGuard configuration is not found." %}

```javascript
{
    "success": false,
    "message": "The WireGuard configuration is not found."
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity The WireGuard configuration is pending creation or deletion." %}

```javascript
{
    "success": false,
    "message": "The WireGuard configuration is pending creation or deletion."
}
```

{% endtab %}
{% endtabs %}


---

# 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.vpnscript.net/api-endpoints.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.