Authentication

All API requests must be authenticated with your API key.

Passing Your API Key

You can authenticate your API requests in any of three ways. Use whichever is most convenient for your environment:

MethodExampleRecommended for
Bearer token (header) Authorization: Bearer your_api_key Server-side code, curl, CLI tools
Custom header X-Api-Key: your_api_key When you can't set Authorization header
Query parameter ?api_key=your_api_key Browser-based requests, quick testing
Tip The Bearer token method is the most secure and widely supported. Avoid the query parameter method in production — API keys in URLs can be logged by proxies and web servers.

Example: Bearer Token (curl)

curl -H "Authorization: Bearer your_api_key" \
  https://cp.pinguzo.com/api/v1/rest.php?resource=servers

Example: X-Api-Key Header (curl)

curl -H "X-Api-Key: your_api_key" \
  https://cp.pinguzo.com/api/v1/rest.php?resource=monitors

Example: Query Parameter (curl)

curl "https://cp.pinguzo.com/api/v1/rest.php?resource=servers&api_key=your_api_key"

Authentication Errors

If authentication fails, you will receive a 401 Unauthorized response:

{
  "error": "Missing or invalid API key. Pass via Authorization: Bearer <key>, X-Api-Key header, or ?api_key=",
  "code": 401
}

Common causes:

Plan Access Errors

If your account doesn't have API access, you will receive a 403 Forbidden response:

Free plan

{
  "error": "API access is not available on the Free plan. Upgrade to a paid plan to use the API.",
  "code": "API_ACCESS_NOT_AVAILABLE",
  "plan": "free"
}

Expired plan

{
  "error": "Your plan has expired. Renew your plan to continue using the API.",
  "code": "PLAN_EXPIRED",
  "plan": "professional"
}

Next Steps