Authentication Guide

The Market VPSBot API uses API Key authentication. Include your API key in the x-api-key header with every request.

API keys themselves are managed under a signed-in session, not with an API key: see Managing API Keys.

Using Your API Key

Header	Value	Description
x-api-key	<your_api_key>	Your API key

Managing API Keys

Creating and deleting API keys needs the session of a signed-in account. A create or delete request that carries x-api-key is refused with HTTP 403 and code: "forbidden".

Create an API Key in the Panel

1. Sign in at market.vpsbot.io.
2. Open Settings in the sidebar.
3. In the API Keys section, enter a name for the key under Create new API key (for example, production) and click Create.
4. Copy the key from the API Key Created window.

WARNING

The key is shown only once. Save it right away: it cannot be shown again. If it is lost, delete it and create a new one.

The same section lists your keys with their creation and last-use dates, and deletes a key with the trash icon next to it.

Manage Keys over HTTP

The endpoints below take the session of a signed-in account instead of x-api-key:

1. Sign in with POST /api/auth/login. A successful sign-in answers success: true and sets the session cookies.
2. Send these cookies with every key request, from the same client (the same User-Agent). Keep the cookies the responses set: the session is renewed through them.
3. When a key request answers HTTP 401 with code: "unauthorized", the session has expired: sign in again.

Two-factor authentication

An account with two-factor authentication cannot sign in over HTTP: the sign-in answers HTTP 403 with code: "forbidden". Create its keys in the panel.

Sign In

POST /api/auth/login
Content-Type: application/json

{
  "login": "your_username",
  "password": "your_password"
}

Field	Type	Required	Description
login	string	Yes	Your login or email
password	string	Yes	Your password

Wrong credentials answer HTTP 401 with code: "unauthorized".

Create an API Key

POST /api/auth/api-keys
Content-Type: application/json
Cookie: <session cookies from the sign-in>

{
  "name": "my-bot-key"
}

Field	Type	Required	Description
name	string	Yes	Key name, 1–100 characters, unique among your keys

Response (HTTP 201):

{
  "success": true,
  "data": {
    "name": "my-bot-key",
    "api_key": "vpsbot_xxxxxxxxxxxxxxxxxxxx",
    "created_at": "2024-01-15T10:00:00.000Z"
  }
}

WARNING

Save api_key right away: it is returned only in this response.

HTTP	code	Meaning
400	validation_failed	name is missing, empty or longer than 100 characters
401	unauthorized	No session, or it has expired. Sign in again
403	forbidden	The request carries x-api-key. Send the session cookies instead
409	conflict	You already have a key with this name

List API Keys

GET /api/auth/api-keys
Cookie: <session cookies from the sign-in>

Response:

{
  "success": true,
  "data": [
    {
      "name": "my-bot-key",
      "created_at": "2024-01-15T10:00:00.000Z",
      "last_used_at": "2024-01-16T08:30:00.000Z"
    }
  ]
}

last_used_at is null for a key that has never been used.

Delete an API Key

DELETE /api/auth/api-keys
Content-Type: application/json
Cookie: <session cookies from the sign-in>

{
  "name": "my-bot-key"
}

Response:

{
  "success": true,
  "data": {
    "name": "my-bot-key"
  }
}

HTTP	code	Meaning
401	unauthorized	No session, or it has expired. Sign in again
403	forbidden	The request carries x-api-key. Send the session cookies instead
404	not_found	You have no key with this name

Example

A cookie jar keeps the session between the calls:

# Sign in: the session cookies go to cookies.txt
curl -c cookies.txt -X POST "https://market.vpsbot.io/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"login": "your_username", "password": "your_password"}'

# Create a key with the session
curl -b cookies.txt -c cookies.txt -X POST "https://market.vpsbot.io/api/auth/api-keys" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-bot-key"}'

Get Current User

Works with an API key or a session.

GET /api/auth/me
x-api-key: YOUR_API_KEY

Response:

{
  "success": true,
  "data": {
    "id": "uuid",
    "login": "your_username",
    "first_name": "John",
    "last_name": "Doe",
    "avatar": null,
    "role": "project"
  }
}

Code Examples

Node.js

const axios = require('axios');

const client = axios.create({
  baseURL: 'https://market.vpsbot.io/api',
  headers: {
    'x-api-key': 'YOUR_API_KEY'
  }
});

const { data } = await client.get('/items');

if (!data.success) {
  throw new Error(`${data.code}: ${data.error}`);
}

console.log(data.data);

cURL

curl -X GET "https://market.vpsbot.io/api/items" \
  -H "x-api-key: YOUR_API_KEY"

Access Control

Only accounts with the project role can use the API. A request that fails authentication answers:

HTTP	code	error	When
401	unauthorized	Unauthorized	The API key is missing or invalid. For key management: the session is missing or has expired
403	forbidden	Forbidden	The account does not have the project role, or an API key was used to create or delete API keys
500	internal_error	Internal server error	The credentials could not be checked. Retry later

See Response Format.