API Reference Overview

Welcome to the Keymint API reference. Here you will find the base URL, authentication standards, response structures, and HTTP error codes.

The Keymint API is organized around REST. All requests must use HTTPS, accept JSON-formatted payloads, and return JSON responses.

Base URL

All requests must be made to the following base URL:

https://api.keymint.dev

Authentication

Every API request requires authentication using a Bearer token in the Authorization header. You can generate API keys with scoped permissions in the developer settings.

curl https://api.keymint.dev/customer \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Format

All successful responses return a JSON object with a consistent structure:

{
  "action": "getCustomers",
  "status": true,
  "data": [],
  "code": 0
}

When an error occurs, the API returns an appropriate HTTP status code along with an error payload:

{
  "message": "Activation limit reached",
  "code": 2
}

HTTP Status Codes

The API uses standard HTTP response codes to indicate the success or failure of an API request.

Versioning & Deprecation Policy

The Keymint API is versioned by date, and the version is declared in two places you can rely on:

• Webhook payloads carry an api_version field ("2026-06-21" format) so consumers always know which contract produced an event.
• OpenAPI spec (https://keymint.dev/openapi.json) declares the current semantic version in info.version.

Policy:

• Backward-compatible changes (new optional fields, new endpoints, new response headers) ship without notice inside the current version.
• Breaking changes (renamed/removed fields, changed response shapes, new required parameters) are introduced only in a new dated contract and announced in the changelog and release emails at least 30 days before the old contract stops working.
• Deprecation signaling: deprecated endpoints and fields are listed in the changelog with a removal timeline, and sunsetting endpoints respond with a Deprecation and Sunset HTTP header naming the retirement date.
• The current API surface is documented by the OpenAPI spec — treat the spec as the contract, and your integration as stable when it consumes only fields declared there.

Idempotency

All mutating endpoints (POST, PATCH, DELETE) support safe retries by passing an Idempotency-Key (or X-Idempotency-Key) header. This prevents duplicate resource creation (e.g., generating multiple license keys or double-leasing concurrent seats) if the connection drops.

• Key Format: Any unique string (recommended: UUID v4).
• Expiry: Idempotency keys and cached response payloads are retained for 24 hours.
• Payload Verification: If you send the same idempotency key with a different request body payload, the API returns a 400 Bad Request to prevent accidental cache collisions.
• Concurrent Lock: If you send duplicate requests with the same key simultaneously before the first one completes, the second request will return a 409 Conflict.

Example Request

curl -X POST https://api.keymint.dev/key/checkout \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -d '{"productId": "prod_Nx8K2mLpQ4rVtW9sBc", "licenseKey": "XXXXX-XXXXX-XXXXX-XXXXX"}'

Core Concepts

Understanding the basic resources before making API requests:

• Products: The software titles you distribute.
• Customers: The entities that purchase or lease your licenses.
• License Keys: Unique alphanumeric identifiers specifying seat limits and flags.
• Activations: Links binding a license key to a specific device via a hostId.

Next Steps

• Authenticate your integration: Authentication
• Handle rate-limiting: Rate Limits
• Inspect standard errors: Error Codes