# Opslink Servers API

OpsLink provides a secure REST + Socket.IO API for authentication, server listings, moderation, reviews, and QR-based login.

***

{% hint style="warning" %}
The API is currently \<b>NOT\</b> public! We are working to make a public version, until then please note any attempts to connect are logged and audited.
{% endhint %}

## 🚀 Onboarding

### Base URL

<https://opslinkservers-backend.onrender.com/api>

### Requirements

* HTTPS client
* JSON support
* JWT storage (localStorage or memory)

***

## 🔐 Authentication

### Login Flow

{% stepper %}
{% step %}

### User logs in

Client sends credentials to the login endpoint.
{% endstep %}

{% step %}

### Server returns JWT

On successful authentication the server responds with a JWT and user info.
{% endstep %}

{% step %}

### JWT sent via Authorization header

For subsequent authenticated requests include the token:

Authorization: Bearer YOUR\_JWT\_TOKEN
{% endstep %}
{% endstepper %}

### Token Invalidation

* Password change invalidates old tokens
* Token version mismatch → 401

***

## 👤 Auth Endpoints

POST `/auth/login`

### Request

```json
{ "email": "user@example.com", "password": "password123" }
```

### Response

```json
{ "token": "JWT_TOKEN", "user": { "id": "abc123", "username": "kareem", "role": "user" } }
```

{% tabs %}
{% tab title="cURL" %}
{% code title="curl" %}

```bash
curl -X POST https://opslinkservers-backend.onrender.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"password123"}'
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript" %}
{% code title="login.js" %}

```javascript
const res = await fetch('/api/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email, password })
});
const data = await res.json();
```

{% endcode %}
{% endtab %}
{% endtabs %}

***

## 📱 QR Login (Socket.IO)

Flow: Desktop → QR Token Mobile → Scan → Approve Socket → JWT delivered

GET `/auth/qr-generate`

### Response

```json
{ "token": "qr_temp_token" }
```

### Socket.IO Subscribe

```javascript
const socket = io("https://opslinkservers-backend.onrender.com", { path: "/socket.io" });
socket.emit("subscribe-token", qrToken);
socket.on("qr-success", data => {
  console.log("JWT:", data.token);
});
```

***

## 🌐 Server Listings

GET `/servers`

### Response

```json
[
  { "_id": "server123", "name": "OpsLink Hub", "tags": ["gaming", "tech"], "rating": 4.9, "approved": true }
]
```

POST `/servers` Auth Required

### Request

```json
{ "name": "My Server", "description": "Community server", "tags": ["community"] }
```

***

## ⭐ Reviews

POST `/servers/:id/reviews` Auth Required

### Request

```json
{ "rating": 5, "comment": "Amazing server" }
```

***

## 🛠 Admin API

PATCH `/admin/servers/:id/status` Admin

### Request

```json
{ "status": "approved" }
```

***

## 📦 SDKs

{% tabs %}
{% tab title="JavaScript" %}
{% code title="opslink.js" %}

```javascript
class OpsLink {
  constructor(token) {
    this.token = token;
    this.base = 'https://opslinkservers-backend.onrender.com/api';
  }
  async getServers() {
    return fetch(`${this.base}/servers`).then(r => r.json());
  }
  async submitServer(data) {
    return fetch(`${this.base}/servers`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(data)
    }).then(r => r.json());
  }
}
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code title="opslink.py" %}

```python
import requests

class OpsLink:
    def __init__(self, token):
        self.base = "https://opslinkservers-backend.onrender.com/api"
        self.headers = {"Authorization": f"Bearer {token}"}

    def get_servers(self):
        return requests.get(f"{self.base}/servers").json()
```

{% endcode %}
{% endtab %}
{% endtabs %}

***

## 🚦 Rate Limits

* Auth: 10 req/min
* General API: 60 req/min
* QR Login: 5 req/min

***

## 🚨 Errors

```json
{ "error": "Unauthorized" }
```

<details>

<summary>Status Codes</summary>

* 400 – Bad Request
* 401 – Unauthorized
* 403 – Forbidden
* 404 – Not Found
* 500 – Server Error

</details>

***

## 🔐 Security

* JWT validation
* CORS allowlist
* Socket room isolation

***

## ✅ You Are Done

This documentation is production-ready and public-facing.