Admin REST API Overview
What is the Admin REST API?
The Admin REST API lets you manage your MTCaptcha account from your own code instead of the admin console. It is meant for developers who want to automate site setup, for example when onboarding many websites.
With it you can:
- Sites: list your sites and update a site's name and settings.
- Domains: view, add and remove production and development domains for a site.
- IP whitelist: view, add and remove whitelisted IP addresses for a site.
The API works only with your own account. Your plan's limits apply exactly as they do in the admin console.
The Admin REST API is different from the CheckToken API used to validate a verified token. The Admin REST API manages your account. The CheckToken API verifies a captcha result on your server.
Before you start
- Ask for access. The Admin REST API is not turned on by default. Contact support@mtcaptcha.com to enable it for your account.
- Generate your API key. Once enabled, your account's Super Admin can open Admin API in the left menu of the admin console and generate the key there.
Treat the API key like a password. Use it only from your server, never in browser code, mobile apps or public repositories. If it may have been exposed, regenerate it from the Admin API page. The old key and any tokens issued with it stop working immediately.
What you can do
A summary of the available calls. All paths start with /v1.
Sites
| Method | Path | Description |
|---|---|---|
GET | /sites | List your sites. Optional filters: from, to, sortField, sortOrder. |
PATCH | /sites/{sitePublicId} | Update a site's name and settings. |
Domains
| Method | Path | Description |
|---|---|---|
GET | /sites/{sitePublicId}/domains | List all domains. Add /prod or /dev to filter. |
POST | /sites/{sitePublicId}/domains/{type} | Add a domain. type is prod or dev. |
DELETE | /sites/{sitePublicId}/domains/{type}/{domainName} | Remove a domain. |
IP whitelist
| Method | Path | Description |
|---|---|---|
GET | /sites/{sitePublicId}/ip-whitelist | List whitelisted IP addresses. |
POST | /sites/{sitePublicId}/ip-whitelist | Add an IP address. |
DELETE | /sites/{sitePublicId}/ip-whitelist?ipAddress=... | Remove an IP address. |
Getting started
Authentication has two steps. You exchange your API key for a short-lived access token, then include that token in every request. Replace YOUR_API_KEY and YOUR_TOKEN with your own values, and run these from your server or terminal, never from a web page.
Step 1: Get an access token
curl -X POST "https://admin-api.mtcaptcha.com/auth/token" \
-H "X-Api-Key: YOUR_API_KEY"
You get back the token. Use it in the next step:
{ "status": "success", "token": "..." }
Step 2: List your sites
curl "https://admin-api.mtcaptcha.com/v1/sites" \
-H "Authorization: Bearer YOUR_TOKEN"
Step 3: Keep going, and refresh when needed
Include the same Authorization: Bearer YOUR_TOKEN header in every request. Tokens are short-lived: when you get a 401 response, repeat Step 1 to get a new token. Do not request a new token for every call.
Errors are returned as JSON with a status and a message that explains what to fix.
API reference
The full list of endpoints, request and response formats, and a way to try each call is available in the Swagger reference:
Open the Admin REST API reference (Swagger)
Didn't find what you needed? Please feel free to reach out to our support team at support@mtcaptcha.com or drop us a note at our contact us page.