How to Access the xCloud API

The xCloud API lets you control your xCloud servers and sites from your own scripts and tools. Developers, store owners and agencies can use it to connect xCloud to their own tools and automate routine server and site work.

To start, create an API token under Settings → Developers → API Tokens and give it only the permissions your script needs. This guide lists every permission and shows how to make your first request.

Key benefits of using the xCloud API

• Wide platform access: Run server and site operations from your own scripts, not only from the dashboard.
• Integration: Connect xCloud to your existing tools and pipelines.
• Automation: Run restarts, deployments, and routine tasks without manual effort.
• Server insights: Check the latest CPU, RAM and disk usage on demand.
• Custom dashboards: Build your own views on top of your server data.
• Scoped permissions: Give each token only the kinds of access it needs, such as viewing servers or managing sites.
• Bulk management: Manage multiple servers and sites in one workflow.

Step 1: Open the API Tokens page

In your xCloud dashboard, click Settings in the left-hand menu. Then open Developers → API Tokens. The page lists your tokens and any connected AI apps.

White-label dashboards do not show the Developers menu.

Step 2: Click Create New Token

Click Create New Token at the top right of the page. The Create A New API Token window opens.

Step 3: Name the token and choose its permissions

Enter a Token Name that says what the token is for, such as deploy-script. Under Permissions, keep Full Access (all API permissions) or tick only the permissions you need, then click Create Token. See what each permission allows below.

If you start from Full Access and untick a box, commands:run and read:email-logs stay ticked, so the token keeps both permissions. Untick them unless you need them.

If you belong to more than one team, a Teams list also appears. The token always works on your current team, and you can add others. See how to manage API tokens and MCP connections across teams.

Step 4: Copy and store your API token

Your new token appears under Token Created — Copy it now!. Click Copy and store it somewhere safe. xCloud does not show it again, so if you lose it, create a new token.

Step 5: Make your first request

Send the token in the Authorization header to https://app.xcloud.host/api/v1. This request lists your servers and needs read:servers:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  https://app.xcloud.host/api/v1/servers

Expected result: a JSON response with "success": true and your servers under data.items.

To read every server and site with its status in one request, use GET /api/v1/overview with a token that has both read:servers and read:sites. See how to get a fleet overview of all servers and sites.

If you get a 403 with the message Invalid ability provided., the token lacks the permission that request needs. You can’t edit a token’s permissions, so create a new one with the right permissions and delete the old one. You can have up to 10 tokens. If you are at the limit, delete one first.

What each API permission allows

Each request needs a specific permission. Read permissions view data, and write permissions change it and unlock a few sensitive details. A write permission does not include its read permission, so tick both if your script needs both.

Permission	What the token can do
read:servers	View servers, databases, cron jobs, PHP versions, PHP extensions, php.ini settings and monitoring
write:servers	Manage those same server resources, and create sites
read:sites	View sites, backups, SSL, domains and deployments
write:sites	Manage sites, and read a one-click app’s login details. Creating a site needs write:servers.
read:billing	View your plan, bills, invoices, packages, products, payment methods and subscriptions
read:addons	View your mailboxes and Mail Delivery, and their plans
write:addons	Buy mailboxes and Mail Delivery, verify DNS, read mailbox connection settings and Mail Delivery sending credentials, pay an invoice, and delete a mailbox with all the data inside it
read:tokens	List your API tokens in the current team
write:tokens	Revoke one of your API tokens in the current team
commands:run	Run one-off commands on a site and read their results
read:email-logs	Read and export Mail Delivery email logs
mcp:invoke	Let an AI agent use this token over MCP

A few permissions work differently from the rest:

• Reading one-click app login details needs write:sites. The details include the app’s admin and database passwords, so a read-only token can’t see them. The app’s status only needs read:sites.
• read:tokens and write:tokens are opt-in. No other permission includes them; Full Access does. write:tokens does not include read:tokens. If you untick any other box while Full Access is on, these two are unticked as well.
• commands:run is not part of Full Access, even though its box looks ticked while Full Access is on. To use it, untick Full Access and tick commands:run, leaving at least one other box unticked. Your account also needs two-factor authentication. See how to run and track site commands.
• read:email-logs is included in Full Access, but no other permission includes it. It works only for team admins who are allowed to view email logs, on teams that have Mail Delivery email logs turned on. It does not work in white-label teams.
• mcp:invoke is not part of Full Access. It sits in its own box below the permissions list. An agent can still only do what the token’s other permissions allow. Ticking it also shows MCP toolsets, which are optional. Select none to give the agent every tool. The Compact tool surface (4 tools instead of ~150) box below them is for clients that limit how many tools a server can offer, such as Cursor.

Connect an AI agent with MCP

To manage xCloud from an AI assistant such as Claude or Cursor, open Settings → Developers → MCP. It opens the setup page with the server URL and the steps for each client. See how to connect xCloud MCP to an AI agent for the full guide.

Most clients sign in through your browser, so they don’t need a token. If your client can’t open a browser, create a token with mcp:invoke and the permissions the agent should have.

Delete an API token

To remove a token you no longer need, click the delete icon in its Actions column on the API Tokens page. A Revoke API Token confirmation opens. Click Yes, revoke it. xCloud shows Token revoked successfully. and removes the token from the list. Any script using that token stops working.

To see when each token was last used, revoke connected AI clients, or share one token across several teams, see how to manage API tokens and MCP connections across teams.

Explore the API documentation

With your token ready, open the API documentation to see the available endpoints. You can also open it from View API documentation on the API Tokens page. The xCloud API overview covers authentication and rate limits.

Frequently asked questions

Does Full Access include every permission?

No. Full Access covers every permission except commands:run and mcp:invoke. Tick those separately. To use commands:run, untick Full Access as well. If you start from Full Access and untick a box, commands:run and read:email-logs stay ticked, so the token keeps both permissions. Untick them unless you need them.

Which permission do I need to read a one-click app’s login details?

write:sites. These details include the app’s admin and database passwords, so a token with only read:sites cannot read them.

Why does my token get a 403 with “Invalid ability provided”?

The token does not have the permission that request needs. You can’t edit a token’s permissions, so create a new token with the right ones and delete the old one.

Do I need an API token to connect an AI agent?

Usually not. Most AI clients connect to xCloud MCP by signing in through your browser. A token is for clients that can’t open a browser, and it must have mcp:invoke.

If you face any issues, please do not hesitate to contact our support team.