Guardian Hub API Guide — Complete Reference

1. Overview

The Guardian Hub API provides programmatic access to the entire platform: manage WordPress sites, configure Autopilot automation, handle billing, process tickets, and receive real-time notifications. Every action available in the web dashboard can be performed through the API.

Base URL

All API endpoints are served under the /api/v1/ prefix:

https://guardian.bluix.net/api/v1/

If your tenant uses a white-label domain, replace the host accordingly (e.g. https://manage.youragency.com/api/v1/).

Versioning

The API is versioned via the URL path. The current and only stable version is v1. Breaking changes will be introduced in a new version prefix (e.g. /api/v2/) and the previous version will remain available for at least 12 months after deprecation notice.

2. Authentication

Guardian Hub supports three authentication mechanisms depending on the use case.

2.1 Sanctum Token (Primary)

The recommended method for web and mobile clients. Obtain a token by posting credentials to the login endpoint:

POST /api/v1/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your-password"
}

The response includes a bearer token:

{
  "success": true,
  "status": "success",
  "message": "Success",
  "data": {
    "token": "1|abc123def456...",
    "user": { "id": 1, "name": "John", "email": "user@example.com", ... }
  }
}

Include the token in all subsequent requests:

Authorization: Bearer 1|abc123def456...

2.2 Passport OAuth (Alexa / Third-Party)

For voice assistants and third-party integrations, Guardian Hub uses Laravel Passport with scoped tokens. Alexa endpoints require scope:alexa.read or scope:alexa.action via OAuth bearer tokens obtained through the standard OAuth2 authorization code flow.

2.3 API Key (Plugin / Agent)

The WordPress plugin (GuardianPlug) authenticates using a site-specific API key and HMAC signature. License endpoints under /api/v1/licenses are protected by API key, not Sanctum. The Autopilot handshake and telemetry endpoints use a dedicated autopilot.signature middleware.

2.4 Social Auth

Users can authenticate via Google, Apple, Microsoft, or custom OIDC providers. The flow uses redirect/callback endpoints under /api/v1/auth/social/{provider}/.

3. Rate Limiting

Rate limits vary by endpoint category to balance availability and fair usage.

Handling 429 Responses

HTTP/1.1 429 Too Many Requests
Retry-After: 30

{
  "message": "Too many requests. Please try again later."
}

4. Request Format

Required Headers

Pagination

List endpoints support Laravel-style pagination:

Filtering and Sorting

Many list endpoints accept filter parameters as query strings. For example, the tickets endpoint supports:

GET /api/v1/tickets?status=open&priority=high&search=ssl&per_page=25

Refer to individual endpoint documentation for available filters.

5. Response Format

All responses follow a standardized JSON envelope:

Success Response

{
  "success": true,
  "status": "success",
  "message": "Success",
  "data": { ... }
}

Error Response

{
  "success": false,
  "status": "error",
  "message": "Human-readable error description",
  "errors": null | { "field": ["Validation message"] }
}

HTTP Status Codes

Paginated Response

List endpoints wrap data in Laravel's paginator structure inside the data envelope:

{
  "success": true,
  "status": "success",
  "message": "Success",
  "data": {
    "current_page": 1,
    "data": [ { ... }, { ... } ],
    "last_page": 5,
    "per_page": 15,
    "total": 73,
    "next_page_url": "/api/v1/tickets?page=2",
    "prev_page_url": null
  }
}

6. API Endpoints by Category

Auth

Guardian Sites

All site endpoints require Sanctum auth + tenant context.

Autopilot

Billing

Billing endpoints require Sanctum auth + tenant context.

Tickets

Sanctum auth + tenant context required.

Notifications

Admin

Admin endpoints require Sanctum auth + superadmin role. Rate-limited under the admin throttle.

Webhooks (Inbound)

Mobile

Telemetry

Health

7. Webhook Integration

Guardian Hub sends outbound webhooks for billing events (via Stripe) and receives inbound webhooks from messaging platforms.

Stripe Webhooks

Stripe sends events to /api/v1/stripe/connect/webhook. Guardian Hub validates the webhook signature using the STRIPE_CONNECT_WEBHOOK_SECRET.

Signature Validation

All inbound webhooks are validated before processing:

• Stripe: HMAC-SHA256 signature in the Stripe-Signature header, verified with the webhook secret.
• WhatsApp: Verification token challenge on GET, plus token validation on POST.
• WeChat: SHA1 signature verification using the configured token and AES key.
• WHMCS: HMAC validation using WHMCS_WEBHOOK_SECRET for service lifecycle events (activate, suspend, terminate, upgrade, payment).

Retry Policy

Stripe retries failed webhook deliveries for up to 3 days with exponential backoff. Ensure your endpoint returns 200 OK quickly and processes events asynchronously. WhatsApp and WeChat follow their respective platform retry policies.

8. Error Handling

Common Error Patterns

// Validation error (422)
{
  "success": false,
  "status": "error",
  "message": "The email field is required.",
  "errors": {
    "email": ["The email field is required."],
    "password": ["The password must be at least 8 characters."]
  }
}

// Authentication error (401)
{
  "success": false,
  "status": "error",
  "message": "Unauthenticated.",
  "errors": null
}

// Authorization error (403)
{
  "success": false,
  "status": "error",
  "message": "This action is unauthorized.",
  "errors": null
}

// Not found (404)
{
  "success": false,
  "status": "error",
  "message": "Resource not found.",
  "errors": null
}

Graceful Error Handling

9. Best Practices

Idempotency

For critical write operations (billing, provisioning), include a client-generated idempotency key. Stripe checkout endpoints pass this through to Stripe. If you retry a request with the same key, the original result is returned without creating a duplicate.

Caching

Cache responses from read-heavy endpoints like /autopilot/catalog, /checkout/catalog, and /mobile/config. These change infrequently. Use a TTL of 5-15 minutes. Always respect Cache-Control headers when present.

Pagination

Never fetch all records at once. Use page and per_page parameters. For large datasets (sites, tickets), iterate through pages until next_page_url is null.

Security

Environment Separation

Always develop and test against staging first. Stripe test-mode keys are used in staging, so no real charges occur. Admin Stripe actions are enabled by default outside production.

10. SDKs & Tools

Swagger / OpenAPI

The full API specification is available as an OpenAPI 3.x YAML file and rendered via Swagger UI:

• Swagger UI: /api-docs/ — interactive browser for all endpoints
• OpenAPI spec: /api-docs/openapi.yaml — download for code generation

Postman Collection

A ready-to-use Postman collection is available for quick testing:

• Download: /api-docs/collection.json

Code Generation

Use the OpenAPI spec to generate client SDKs in any language:

# Generate a TypeScript client
npx openapi-generator-cli generate \
  -i https://your-hub-domain/api-docs/openapi.yaml \
  -g typescript-fetch \
  -o ./guardian-hub-client

# Generate a PHP client
npx openapi-generator-cli generate \
  -i https://your-hub-domain/api-docs/openapi.yaml \
  -g php \
  -o ./guardian-hub-php-client

11. Changelog

API changes are documented in the following locations:

• Release notes: Published with each Guardian Hub release in the dashboard under What's New.
• OpenAPI spec diff: Compare openapi.yaml between versions to see added/removed/changed endpoints.
• Deprecation warnings: Deprecated endpoints return a X-Deprecated header and a Sunset header with the removal date.