API Reference

The GeckoGuard API is a RESTful API that uses JSON for request and response bodies.

Base URL

All API requests should be made to:

https://api.geckoguard.net

Authentication

Different endpoints accept different credentials. The short version:

About the /v1/dashboard/* prefix: despite the name, this is the public management API. Use it from your backend with a Bearer JWT — API keys are not accepted on dashboard routes and will return 401 UNAUTHORIZED. The path is kept stable for backwards compatibility.

See the Authentication guide for the full auth matrix, the request-signing recipe for /v1/licenses/authorize, and /v1/whoami token introspection.

Request Format

• Content-Type: application/json header for POST/PATCH requests
• JSON body for POST/PATCH requests
• Query parameters for filtering and pagination

Response Format

All responses follow this structure:

{
  "ok": true,
  "data": { /* response data */ }
}

Error responses:

{
  "ok": false,
  "error": {
    "message": "Error description",
    "code": "ERROR_CODE"
  }
}

Pagination

List endpoints use page-based pagination. There is no cursor option today.

GET /v1/dashboard/orgs/:orgId/licenses?page=1&pageSize=50

Per-endpoint pageSize ceilings:

Responses always include a pagination envelope with total and totalPages:

{
  "ok": true,
  "data": {
    "licenses": [ /* … */ ],
    "pagination": { "page": 1, "pageSize": 50, "total": 342, "totalPages": 7 }
  }
}

Consistency is best-effort — if rows are inserted while you paginate, you may see overlap or gaps. For exact snapshots of large datasets use the export endpoints (e.g. GET /v1/dashboard/orgs/:orgId/licenses/export?format=csv), which stream the full set in a single request without paging.

Rate Limiting

Buckets are credential-dependent: API-key calls hit per-IP + per-key + per-product; JWT-only calls (/v1/dashboard/* with a Bearer token) only hit the per-IP bucket (default 120/min). A bot batching dashboard operations from one IP needs to pace below that.

/v1/licenses/authorize adds an extra 20/min per license key to make credential stuffing expensive.

429 responses return RATE_LIMITED or PRODUCT_RATE_LIMITED — always honor Retry-After. Full breakdown of buckets, defaults, and headers: Authentication → Rate limits.

Idempotency

Mutating endpoints accept an Idempotency-Key header. Replaying the same key within 24 hours returns the original response with Idempotent-Replayed: true. Mismatched bodies return 409 IDEMPOTENCY_KEY_REUSE. See Authentication → Idempotency.

---

Endpoints Overview

Building a backend integration? Start with the Backend Quickstart — five steps with curl that exercise the core path (login → smoke test → list IDs → create license → refresh loop). The reference below is the lookup table you'll come back to.

Token Introspection

Use these to verify a credential is valid before writing code against it:

Auth — for backend integrators

The three endpoints a bot or backend script actually calls:

Dashboard-UI plumbing. /v1/auth/register, /v1/auth/forgot-password, /v1/auth/reset-password, /v1/auth/verify-email, /v1/auth/totp/verify-login exist for the GeckoGuard web UI — backend integrators don't call these directly. Sign up your service-account user via the dashboard once; after that, only the three above matter.

License Validation (API Key Auth + Signed Request)

Detailed documentation with code examples · Request signing recipe

Management Endpoints (API Key + Scopes)

The recommended path for backend integrations (Discord bots, admin tools, CRMs). All routes accept X-Api-Key and authorize against the scopes on the key. No login flow, no refresh tokens. See Backend Quickstart for a 5-minute curl walkthrough.

End-user lookups come in two flavors. /v1/end-users searches across every product in the API key's org — useful for a unified Discord bot that handles all your products. /v1/products/:productId/end-users is the same shape but filtered to one product, so a key bound to product A literally cannot see product B's customers. Pick whichever matches your blast-radius preference. All three filters are case-insensitive: ?username= (exact), ?email= (exact), ?search= (partial match across both).

Owner fields on license responses. GET /v1/products/:productId/licenses and …/licenses/:licenseId return endUserId, endUserUsername, endUserEmail (each null when unassigned) — but only when the API key has the end_user:read scope. Without that scope, the fields are omitted entirely. Filter the licenses list by owner with ?endUserId=<uuid>.

Every write accepts Idempotency-Key. Wrong-product calls return 403 FORBIDDEN. Missing scope returns 403 PERMISSION_DENIED with the missing scope name in the message.

Organizations

Products

Licenses

Detailed documentation with examples

Per-License Endpoints (via dashboard)

Sessions

API Keys

Blacklists

Webhooks

Verifying webhook deliveries: every outbound delivery is signed with HMAC-SHA256. Header is X-GeckoGuard-Signature-V2: t=<unixSec>,v1=<hex>, where <hex> is HMAC-SHA256(endpoint_secret, "${t}.${rawBody}"). Receivers must reject when |now − t| > 300s. Full verification recipe with per-event payloads, Node.js / Python / Go examples →

Endpoints are managed under /v1/dashboard/webhooks/products/:productId. Retry policy: up to 6 attempts with exponential backoff capped at 16 minutes. See Webhooks for the full event catalog with example payloads.

---

Specialized endpoints

The endpoints below aren't part of the core integrator path. Each section has its own page so the main reference stays focused — skip whichever ones don't apply to your integration.

See API Errors for the full error-code reference.