Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/calagopus/panel/llms.txt

Use this file to discover all available pages before exploring further.

The Calagopus API supports two authentication methods: session cookies (used automatically by the browser) and API keys (for programmatic access from scripts, CLI tools, or integrations).

​
Session cookies

When you log in through the panel UI, the server sets a signed session cookie. All subsequent requests made from the browser include this cookie automatically. You do not need to manage session cookies manually unless you are building a browser-based integration.
Session cookies are intended for interactive browser sessions. For automated or programmatic access, create an API key instead.

​
API keys

API keys let you authenticate without a browser session. You pass the key in the Authorization header as a Bearer token. 
curl https://your-panel.example.com/api/client/servers \
  -H "Authorization: Bearer ptlc_YourApiKeyHere"
The token must be exactly 48 characters (the Bearer prefix is stripped, leaving a 48-character key).

​
Creating an API key

1

Open your account settings

Log in to the panel and navigate to Account → API Keys.
2

Create a new key

Click Create API Key and enter a name for the key. Optionally restrict the key to specific IP addresses and configure the permission scopes.
3

Copy the key

The full key value is shown only once after creation. Copy it and store it securely.

​
API key scopes

Each API key carries three separate sets of permissions. A key can only grant permissions that your own account already holds — you cannot escalate privileges through a key.
​
user_permissions
string[]
Controls access to account-level operations such as account.infos, api-keys.read, api-keys.create, servers.read, and servers.view.
​
admin_permissions
string[]
Controls access to admin-level operations such as users.read, servers.create, nodes.delete, and nests.update. Only relevant if your account has admin rights.
​
server_permissions
string[]
Controls access to individual server operations such as control.start, files.read, backups.create, and databases.read.
​
allowed_ips
string[]
Optional list of IP addresses or CIDR ranges allowed to use this key. If empty, requests from any IP are accepted.
​
expires
string (ISO 8601 datetime)
Optional expiry timestamp. The key becomes invalid after this time.

​
Example: creating an API key via the API

curl -X POST https://your-panel.example.com/api/client/account/api-keys \
  -H "Authorization: Bearer ptlc_ExistingKey" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "deploy-bot",
    "allowed_ips": [],
    "user_permissions": ["servers.read"],
    "admin_permissions": [],
    "server_permissions": ["control.start", "control.stop"]
  }'
The response includes the full key value in the key field. This is the only time the full key is returned. 
{
  "api_key": {
    "uuid": "...",
    "name": "deploy-bot",
    "key_start": "ptlc_dep",
    "created": "2026-01-01T00:00:00Z"
  },
  "key": "ptlc_YourNewKeyHere"
}

​
Common authentication errors

StatusError messageCause
401missing authorizationNo Authorization header or session cookie was sent.
401invalid authorization headerThe Authorization header is present but has the wrong length.
401invalid api keyThe key does not match any active key in the database.
401invalid sessionThe session cookie is invalid or has expired.
403ip address not allowed for this api keyThe request came from an IP not in the key’s allowed_ips list.
403two-factor authentication requiredThe account requires 2FA but it is not enabled.
401unauthorizedAdmin API: your account does not have any admin permissions.
Never commit API keys to source control or log them to standard output. If a key is compromised, delete it immediately from Account → API Keys.

Build docs developers (and LLMs) love

Get started for freeTalk to us