Skip to main content

​
Authentication Methods

XyraPanel supports two primary authentication methods:
  1. API Keys - For programmatic access and automation
  2. Session Cookies - For browser-based applications and web interfaces

​
API Key Authentication

API keys provide secure, long-lived authentication tokens for automated access to the XyraPanel API.

​
Creating an API Key

API keys can be created through the XyraPanel web interface:
  1. Navigate to Account Settings → API Keys
  2. Click Create API Key
  3. Set an expiration date (max 90 days, default 90 days)
  4. Copy your API key immediately - it will only be shown once

​
Using API Keys

API keys can be provided in two ways: 
curl -X GET https://panel.example.com/api/client/servers \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"

​
Custom Header

curl -X GET https://panel.example.com/api/client/servers \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json"

​
API Key Configuration

API keys are configured in server/utils/auth.ts: 
apiKey({
  apiKeyHeaders: ['x-api-key'],
  customAPIKeyGetter: (ctx) => {
    // Supports both Bearer and x-api-key headers
    const bearerHeader = ctx.headers?.get('authorization');
    if (bearerHeader?.startsWith('Bearer ')) {
      return bearerHeader.slice(7).trim();
    }
    return ctx.headers?.get('x-api-key') || null;
  },
  enableSessionForAPIKeys: true,
  disableKeyHashing: false,
  defaultKeyLength: 32,
  keyExpiration: {
    defaultExpiresIn: 60 * 60 * 24 * 90, // 90 days
    minExpiresIn: 1,
    maxExpiresIn: 90,
  },
})

​
API Key Properties

  • Length: 32 characters (default)
  • Storage: Hashed in database using bcrypt
  • Expiration: 90 days (default), configurable between 1-90 days
  • Permissions: Inherits user permissions
  • Revocation: Can be deleted at any time via the API or web interface

​
Security Best Practices

  • Store API keys securely in environment variables or secret managers
  • Never commit API keys to version control
  • Rotate API keys regularly (every 30-90 days)
  • Use separate API keys for different applications
  • Delete unused or compromised API keys immediately
Session cookies are automatically set when you log in through the web interface. These are ideal for browser-based applications.

​
Session Configuration

Sessions are configured via Better Auth: 
session: {
  expiresIn: 14 * 24 * 60 * 60,        // 14 days
  updateAge: 12 * 60 * 60,              // Update every 12 hours
  freshAge: 5 * 60,                      // Fresh for 5 minutes
  cookieCache: {
    enabled: true,
    maxAge: 5 * 60,
    strategy: 'compact',
  },
}

​
Session Features

  • Multi-Session: Up to 5 concurrent sessions per user
  • Auto-Renewal: Sessions refresh automatically
  • Secure Cookies: HttpOnly, Secure (in production), SameSite=Lax
  • Session Management: View and revoke active sessions
defaultCookieAttributes: {
  httpOnly: true,
  secure: isProduction,
  sameSite: 'lax',
}

​
Authentication Headers

When using API keys or sessions, all authenticated requests should include: 
Authorization: Bearer your_api_key_here
Content-Type: application/json

​
Authentication Errors

​
401 Unauthorized

{
  "statusCode": 401,
  "message": "Authentication required"
}
Causes:
  • Missing or invalid API key
  • Expired API key
  • Missing or expired session

​
401 API Key Required

{
  "statusCode": 401,
  "message": "API key authentication required. Provide a valid API key via Authorization: Bearer <key> or x-api-key header."
}
Causes:
  • Endpoint requires API key authentication specifically
  • Session cookies are not accepted for this endpoint

​
Example: Complete API Request

curl -X GET https://panel.example.com/api/client/servers \
  -H "Authorization: Bearer xyra_k3y_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

​
Example: Creating a Server

curl -X POST https://panel.example.com/api/admin/servers \
  -H "Authorization: Bearer xyra_k3y_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Minecraft Server",
    "node_id": "node-uuid",
    "egg_id": "egg-uuid",
    "memory": 2048,
    "disk": 10240,
    "cpu": 100
  }'

​
Managing API Keys Programmatically

​
List Your API Keys

curl -X GET https://panel.example.com/api/account/api-keys \
  -H "Authorization: Bearer your_api_key_here"

​
Delete an API Key

curl -X DELETE https://panel.example.com/api/account/api-keys/{identifier} \
  -H "Authorization: Bearer your_api_key_here"

​
Environment Variables

Authentication is configured via environment variables:
.env.example
# Authentication Secret (required in production)
BETTER_AUTH_SECRET="your-32-character-secret-here"

# Application URL
BETTER_AUTH_URL=https://panel.example.com
NUXT_PUBLIC_APP_URL=https://panel.example.com

# Trusted Origins
BETTER_AUTH_TRUSTED_ORIGINS=https://panel.example.com
The BETTER_AUTH_SECRET must be at least 32 characters in production. Generate one using:
openssl rand -base64 32

​
Advanced: Admin API Key Permissions

Admin API keys can have granular permissions using Access Control Lists (ACL):
  • servers.read - List and view servers
  • servers.write - Create and update servers
  • users.read - View users
  • users.write - Manage users
  • nodes.read - View nodes
  • nodes.write - Manage nodes
These permissions are enforced via requireAdminApiKeyPermission() middleware.

Build docs developers (and LLMs) love

Get started for freeTalk to us