MagicWP Docs

An API token lets a script, CI pipeline or AI assistant work with your sites without your password. Each token belongs to you, works in one workspace, and can do only what you allow it, never more than your own role there.

Create a token

Go to Settings → API tokens and fill in:

Name: to recognise it later, for example CI deploys.
Workspace: the workspace the token works in.
Permissions: tick what the token may do. You can only pick permissions your role has in that workspace. Magic Login and the SFTP and database credentials are never ticked for you, because each of them means full control of a site; tick them only if the token really needs them.
Expires after: 1 to 365 days, 90 by default.
Only from these addresses (optional): IPv4 or IPv6 addresses or ranges, such as 203.0.113.0/24 or 2001:db8::/32. Requests from anywhere else are refused.

Click Create token and copy it now: it is shown only once. MagicWP keeps only a fingerprint of it, so a lost token can't be recovered; create a new one and revoke the old.

Two-factor authentication is required

Creating a token needs two-factor authentication. If you turn 2FA off later, all your tokens stop working.

Use a token

Send requests to https://api.magicwp.io, with every path starting with /v1, and the token as a bearer token:

curl https://api.magicwp.io/v1/sites \
  -H "Authorization: Bearer mwp_your_token_here"

The token already knows its workspace; you don't send one. Tokens work only on api.magicwp.io, and only for the endpoints listed in the API reference. Everything else answers 404 there.

OpenAPI document

The API describes itself at https://api.magicwp.io/v1/openapi.json (OpenAPI 3.1, no token needed): every endpoint, its parameters and responses, and the permission it needs. Load it into Postman, Insomnia, a code generator or an AI assistant.

Every response has the same shape:

{
  "success": true,
  "data": { },
  "message": "",
  "status_code": 200,
  "timestamp": "2026-10-06T12:00:00+00:00",
  "meta": null
}

On an error, success is false, message says why, and data may carry a code such as permission_denied, with the permission that was missing.

Long-running actions

Actions such as restarting, resetting, cloning or creating a site return a task right away and finish in the background. Check on it with GET /v1/tasks/{task_id} until its status is completed or failed. Polling once a second is fine.

To see what is going on:

GET /v1/tasks lists the tasks running now on every site you can reach in the workspace.
GET /v1/sites/{site_id}/tasks lists one site's tasks, newest first. Add ?status=running, completed or failed to filter.

Each task has its id, type, status, started_at, finished_at and, if it failed, an error. Tasks don't report a percentage: while a site is being built, progress shows the build step it is on (for example files_setup).

Lists come in pages of up to 100 (limit, 50 by default). When there is more, the response has a next_cursor; pass it back as ?cursor= for the next page.

What a token can do

A token can do what both its own permissions and your current role in the workspace allow. That is checked on every request:

If the Owner changes your role, your tokens follow at once.
If you are removed from the workspace, or leave it, your tokens for it are revoked and stay revoked even if you are invited back.
A token can't manage members, buy or cancel a plan, apply coupons or pay invoices. Those stay in the dashboard.

Rate limits

Each token can make 300 read requests (GET) and 60 write requests (everything else) per minute. Every response tells you where you stand:

Header	Meaning
`X-RateLimit-Limit`	Requests allowed in the current minute
`X-RateLimit-Remaining`	Requests left in the current minute
`X-RateLimit-Reset`	When the minute resets (Unix time, seconds)

Over the limit, you get 429 Too Many Requests with a Retry-After header (seconds to wait). After 20 failed sign-ins (invalid, expired or revoked tokens) from one address within 10 minutes, that address is refused for the rest of those 10 minutes, even with a valid token.

Errors

Status	What it means
`401`	The token is missing, wrong, expired or revoked; your 2FA is off; or you are no longer in the workspace
`403`	The token or your role lacks the permission (see `data.permission`); the request came from an address the token doesn't allow; or you named a different workspace
`404`	The endpoint isn't available to tokens, or the site or item isn't in this workspace
`429`	Rate limit reached; wait for `Retry-After` seconds

Manage your tokens

Settings → API tokens lists your tokens with their workspace, permissions, expiry, and when and from which address each was last used. Click Revoke to stop a token at once. Revoked and expired tokens stay in the list so you can see what they were.

Actions made with a token appear in the workspace's activity log with an API token badge.

API tokens