Документация

Введение

О Xneon Skins

Xneon Skins - это современный сервер аутентификации для Minecraft с поддержкой OAuth2, позволяющий интегрировать систему авторизации в ваши приложения и сервисы.

API предоставляет полный контроль над пользователями, скинами, плащами и OAuth приложениями.

Требования

Сервер работает только на HTTPS
Все запросы должны использовать Content-Type: application/json
OAuth токены передаются через заголовок Authorization: Bearer TOKEN

Быстрый старт

За 5 минут

1. Создайте OAuth приложение

Создать приложение можно тут

2. Начните использовать OAuth2

Следуйте инструкциям в разделе Процесс авторизации

OAuth 2.0 - Обзор

Что такое OAuth 2.0?

OAuth 2.0 - это протокол авторизации, который позволяет приложениям получать ограниченный доступ к учетным записям пользователей без необходимости передачи пароля.

Наша реализация поддерживает Authorization Code Flow с refresh токенами для безопасной интеграции.

OAuth Scopes

Доступные области доступа

account_info

Базовая информация о пользователе (username, UUID, дата регистрации)

account_email

Email адрес пользователя

offline_access

Refresh token для обновления токена доступа

Процесс авторизации

Authorization Code Flow

1. Создание OAuth приложения

POST /api/oauth/apps
Content-Type: application/json

{
  "name": "My App",
  "redirectUri": "https://myapp.com/callback",
  "description": "Описание приложения",
  "userId": "YOUR_USER_ID"
}

Сохраните clientId и clientSecret из ответа

2. Перенаправление на страницу авторизации

GET /oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://myapp.com/callback&
  scope=account_info account_email offline_access

Пользователь вводит логин и пароль

3. Получение authorization code

https://myapp.com/callback?code=AUTHORIZATION_CODE

Код действителен 10 минут

4. Обмен code на access token

POST /api/oauth2/v1/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "AUTHORIZATION_CODE",
  "redirect_uri": "https://myapp.com/callback",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

Ответ:

{
  "access_token": "abc123...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "xyz789..."
}

5. Использование access token

GET /api/account/v1/info
Authorization: Bearer YOUR_ACCESS_TOKEN

Ответ:

{
  "id": 123456,
  "uuid": "abc-123-def-456",
  "username": "Player",
  "registeredAt": 1732262930,
  "email": "player@xneon.local"
}

Важно

Сервер работает только на HTTPS
Access token действителен 24 часа
Refresh token бессрочный (пока не отозван)
Используйте offline_access для получения refresh token

Управление приложениями Войти в систему

Работа с токенами

Обновление токена

Когда access token истекает, используйте refresh token для получения нового:

POST /api/oauth2/v1/token
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

Отзыв токена

Для отзыва токена (logout):

POST /api/oauth2/v1/revoke
Content-Type: application/json

{
  "token": "TOKEN_TO_REVOKE",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

API - Пользователи

Управление пользователями

POST /api/register

Регистрация нового пользователя

{
  "username": "player",
  "password": "password123"
}

GET /api/account/v1/info

Получение информации о пользователе (требуется OAuth токен)

API - OAuth Apps

Управление OAuth приложениями

POST /api/oauth/apps

Создание нового OAuth приложения

{
  "name": "My App",
  "redirectUri": "https://myapp.com/callback",
  "description": "Описание приложения",
  "userId": "YOUR_USER_ID"
}

GET /api/oauth/apps

Получение списка ваших приложений

DELETE /api/oauth/apps/:clientId

Удаление OAuth приложения

API - Скины и плащи

Управление скинами

POST /api/user/profile/:uuid/skin

Загрузка скина

Content-Type: multipart/form-data

skin: [PNG файл 64x64 или 64x32]
model: "default" или "slim"

POST /api/user/profile/:uuid/cape

Загрузка плаща

Content-Type: multipart/form-data

cape: [PNG файл 64x32]

DELETE /api/user/profile/:uuid/skin

Удаление скина

API - Профили

Работа с профилями

GET /api/user/profile/:uuid

Получение профиля пользователя по UUID

GET /textures/:uuid.png

Получение скина пользователя

GET /capes/:uuid.png

Получение плаща пользователя

Примеры - JavaScript

JavaScript (Node.js)

const axios = require('axios');

// Получение токена
const tokenResponse = await axios.post(
  'https://localhost:3000/api/oauth2/v1/token',
  {
    grant_type: 'authorization_code',
    code: 'AUTHORIZATION_CODE',
    redirect_uri: 'https://myapp.com/callback',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET'
  }
);

const accessToken = tokenResponse.data.access_token;

// Использование токена
const userInfo = await axios.get(
  'https://localhost:3000/api/account/v1/info',
  {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  }
);

console.log(userInfo.data);

Примеры - Python

Python

import requests

# Получение токена
token_response = requests.post(
    'https://localhost:3000/api/oauth2/v1/token',
    json={
        'grant_type': 'authorization_code',
        'code': 'AUTHORIZATION_CODE',
        'redirect_uri': 'https://myapp.com/callback',
        'client_id': 'YOUR_CLIENT_ID',
        'client_secret': 'YOUR_CLIENT_SECRET'
    }
)

access_token = token_response.json()['access_token']

# Использование токена
user_info = requests.get(
    'https://localhost:3000/api/account/v1/info',
    headers={'Authorization': f'Bearer {access_token}'}
)

print(user_info.json())

Примеры - cURL

cURL

# Получение токена
curl -X POST https://localhost:3000/api/oauth2/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "AUTHORIZATION_CODE",
    "redirect_uri": "https://myapp.com/callback",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'

# Использование токена
curl https://localhost:3000/api/account/v1/info \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"