DEV3 Keyquay REST API

Base URL /api/v1 · Authenticate with Authorization: Bearer n3k_… · OpenAPI 3.1 JSON

post/api/v1/licenses/validatescope: public

Validate a licence (and refresh its offline token)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "product": {
      "type": "string",
      "minLength": 2,
      "maxLength": 60
    },
    "key": {
      "type": "string",
      "minLength": 8,
      "maxLength": 80
    },
    "fingerprint": {
      "type": "object",
      "properties": {
        "domain": {
          "type": "string",
          "maxLength": 300
        },
        "machine": {
          "type": "string",
          "maxLength": 200
        },
        "user": {
          "type": "string",
          "maxLength": 200
        }
      },
      "additionalProperties": false
    },
    "token": {
      "type": "string",
      "maxLength": 4000
    },
    "version": {
      "type": "string",
      "maxLength": 40
    }
  },
  "required": [
    "product",
    "key"
  ],
  "additionalProperties": false
}
post/api/v1/licenses/activatescope: public

Activate a machine, domain or user (takes a seat; idempotent per fingerprint)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "product": {
      "type": "string",
      "minLength": 2,
      "maxLength": 60
    },
    "key": {
      "type": "string",
      "minLength": 8,
      "maxLength": 80
    },
    "fingerprint": {
      "type": "object",
      "properties": {
        "domain": {
          "type": "string",
          "maxLength": 300
        },
        "machine": {
          "type": "string",
          "maxLength": 200
        },
        "user": {
          "type": "string",
          "maxLength": 200
        }
      },
      "additionalProperties": false
    },
    "version": {
      "type": "string",
      "maxLength": 40
    }
  },
  "required": [
    "product",
    "key",
    "fingerprint"
  ],
  "additionalProperties": false
}
post/api/v1/licenses/deactivatescope: public

Release a seat

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "product": {
      "type": "string",
      "minLength": 2,
      "maxLength": 60
    },
    "key": {
      "type": "string",
      "minLength": 8,
      "maxLength": 80
    },
    "fingerprint": {
      "type": "object",
      "properties": {
        "domain": {
          "type": "string",
          "maxLength": 300
        },
        "machine": {
          "type": "string",
          "maxLength": 200
        },
        "user": {
          "type": "string",
          "maxLength": 200
        }
      },
      "additionalProperties": false
    },
    "version": {
      "type": "string",
      "maxLength": 40
    }
  },
  "required": [
    "product",
    "key",
    "fingerprint"
  ],
  "additionalProperties": false
}
post/api/v1/licenses/heartbeatscope: public

Heartbeat: touches an activation or renews a floating lease

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "product": {
      "type": "string",
      "minLength": 2,
      "maxLength": 60
    },
    "key": {
      "type": "string",
      "minLength": 8,
      "maxLength": 80
    },
    "fingerprint": {
      "type": "object",
      "properties": {
        "domain": {
          "type": "string",
          "maxLength": 300
        },
        "machine": {
          "type": "string",
          "maxLength": 200
        },
        "user": {
          "type": "string",
          "maxLength": 200
        }
      },
      "additionalProperties": false
    },
    "token": {
      "type": "string",
      "maxLength": 4000
    },
    "version": {
      "type": "string",
      "maxLength": 40
    }
  },
  "required": [
    "product",
    "key"
  ],
  "additionalProperties": false
}
post/api/v1/licenses/checkoutscope: public

Check out a floating-seat lease

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "product": {
      "type": "string",
      "minLength": 2,
      "maxLength": 60
    },
    "key": {
      "type": "string",
      "minLength": 8,
      "maxLength": 80
    },
    "fingerprint": {
      "type": "object",
      "properties": {
        "domain": {
          "type": "string",
          "maxLength": 300
        },
        "machine": {
          "type": "string",
          "maxLength": 200
        },
        "user": {
          "type": "string",
          "maxLength": 200
        }
      },
      "additionalProperties": false
    },
    "version": {
      "type": "string",
      "maxLength": 40
    }
  },
  "required": [
    "product",
    "key",
    "fingerprint"
  ],
  "additionalProperties": false
}
post/api/v1/licenses/releasescope: public

Return a floating-seat lease

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "product": {
      "type": "string",
      "minLength": 2,
      "maxLength": 60
    },
    "key": {
      "type": "string",
      "minLength": 8,
      "maxLength": 80
    },
    "fingerprint": {
      "type": "object",
      "properties": {
        "domain": {
          "type": "string",
          "maxLength": 300
        },
        "machine": {
          "type": "string",
          "maxLength": 200
        },
        "user": {
          "type": "string",
          "maxLength": 200
        }
      },
      "additionalProperties": false
    },
    "version": {
      "type": "string",
      "maxLength": 40
    }
  },
  "required": [
    "product",
    "key",
    "fingerprint"
  ],
  "additionalProperties": false
}
get/api/v1/updatesscope: public

Newest eligible release with a signed 10-minute download URL

Parameters: product (query), key (query), channel (query), current (query), version (query)

get/api/v1/products/{id}/keysscope: public

Public signing keys (JWK set) for a product slug

Parameters: id (path)

get/api/v1/download/{token}scope: public

Signed release download (range requests supported)

Parameters: token (path)

post/api/v1/hooks/store/{id}scope: public

Inbound store webhook (X-Keyquay-Signature: t=..,v1=..)

Parameters: id (path)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "order_id": {
          "type": "string"
        }
      },
      "required": [
        "order_id"
      ],
      "additionalProperties": {}
    }
  },
  "required": [
    "id",
    "type",
    "data"
  ],
  "additionalProperties": false
}
get/api/v1/mescope: read

The workspace this key belongs to

get/api/v1/usagescope: read

Metered usage in the current billing period

get/api/v1/productsscope: products:read

List products

Parameters: status (query), page (query), limit (query)

post/api/v1/productsscope: products:write

Create a product (generates its Ed25519 signing key)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "key_prefix": {
      "type": "string",
      "pattern": "^[A-Za-z0-9]{2,5}$"
    },
    "platform": {
      "type": "string",
      "enum": [
        "wordpress",
        "php",
        "desktop",
        "cli",
        "mobile",
        "other"
      ]
    },
    "slug": {
      "type": "string",
      "maxLength": 48
    },
    "homepage": {
      "type": "string",
      "maxLength": 300
    },
    "store_url": {
      "type": "string",
      "maxLength": 300
    }
  },
  "required": [
    "name",
    "key_prefix"
  ],
  "additionalProperties": false
}
get/api/v1/products/{id}scope: products:read

Get a product (public keys only)

Parameters: id (path)

post/api/v1/products/{id}/rotate-keyscope: products:write

Rotate the signing key (old public key stays published until its tokens expire)

Parameters: id (path)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
get/api/v1/products/{id}/sdkscope: products:read

Generated SDK snippets for the product

Parameters: id (path), lang (query), base_url (query)

get/api/v1/policiesscope: products:read

List policies

Parameters: product_id (query), page (query), limit (query)

post/api/v1/policiesscope: products:write

Create a policy

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{24}$"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "kind": {
      "type": "string",
      "enum": [
        "perpetual",
        "subscription",
        "trial",
        "floating"
      ]
    },
    "duration_days": {
      "type": "integer",
      "minimum": 0,
      "maximum": 36500
    },
    "max_activations": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    },
    "activation_scope": {
      "type": "string",
      "enum": [
        "machine",
        "domain",
        "user"
      ]
    },
    "fingerprint_rules": {
      "type": "object",
      "properties": {
        "strip_www": {
          "type": "boolean"
        },
        "allow_subdomains": {
          "type": "boolean"
        },
        "dev_allowance": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100
        }
      },
      "additionalProperties": false
    },
    "offline_token_days": {
      "type": "integer",
      "minimum": 0,
      "maximum": 365
    },
    "grace_days": {
      "type": "integer",
      "minimum": 0,
      "maximum": 365
    },
    "require_heartbeat_hours": {
      "type": "integer",
      "minimum": 1,
      "maximum": 720
    },
    "entitlements": {
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 60
      }
    },
    "updates_until_rule": {
      "type": "string",
      "enum": [
        "forever",
        "expiry",
        "days_after_purchase"
      ]
    },
    "updates_days": {
      "type": "integer",
      "minimum": 0,
      "maximum": 36500
    }
  },
  "required": [
    "product_id",
    "name",
    "kind"
  ],
  "additionalProperties": false
}
delete/api/v1/policies/{id}scope: products:write

Delete a policy (archived instead when licences use it)

Parameters: id (path)

get/api/v1/licensesscope: licenses:read

List/search licences (status, product, email, last5, order id)

Parameters: status (query), product_id (query), email (query), last5 (query), order_id (query), page (query), limit (query)

post/api/v1/licensesscope: licenses:write

Issue a licence (the key is returned once)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{24}$"
    },
    "policy_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{24}$"
    },
    "customer": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string",
          "format": "email",
          "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
        },
        "name": {
          "type": "string",
          "maxLength": 200
        }
      },
      "additionalProperties": false
    },
    "source": {
      "type": "string",
      "enum": [
        "manual",
        "api",
        "store_webhook",
        "trial_signup"
      ]
    },
    "external_order_id": {
      "type": "string",
      "maxLength": 200
    },
    "expires_at": {
      "type": "string"
    },
    "entitlements": {
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 60
      }
    },
    "notes": {
      "type": "string",
      "maxLength": 4000
    },
    "max_activations_override": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 1,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    },
    "send_email": {
      "type": "boolean"
    }
  },
  "required": [
    "product_id",
    "policy_id"
  ],
  "additionalProperties": false
}
get/api/v1/licenses/{id}scope: licenses:read

Get a licence

Parameters: id (path)

patch/api/v1/licenses/{id}scope: licenses:write

Suspend, unsuspend, revoke, extend or edit notes/overrides

Parameters: id (path)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "suspend",
        "unsuspend",
        "revoke",
        "extend",
        "update"
      ]
    },
    "reason": {
      "type": "string",
      "maxLength": 300
    },
    "days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3650
    },
    "notes": {
      "type": "string",
      "maxLength": 4000
    },
    "max_activations_override": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 1,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    },
    "entitlements": {
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 60
      }
    }
  },
  "required": [
    "action"
  ],
  "additionalProperties": false
}
post/api/v1/licenses/{id}/reset-activationsscope: licenses:write

Deactivate every activation (audited)

Parameters: id (path)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
post/api/v1/licenses/{id}/resend-keyscope: licenses:write

Rotate the key and return the new one (old key stops working)

Parameters: id (path)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
get/api/v1/licenses/{id}/activationsscope: licenses:read

List a licence's activations (masked labels)

Parameters: id (path)

get/api/v1/releasesscope: releases:read

List releases

Parameters: product_id (query), channel (query), status (query), page (query), limit (query)

post/api/v1/releasesscope: releases:write

Upload a release (multipart/form-data: product_id, version, channel, notes_md, min_entitlement, file=.zip)

post/api/v1/releases/{id}/publishscope: releases:write

Publish a draft release

Parameters: id (path)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
post/api/v1/releases/{id}/yankscope: releases:write

Withdraw a published release (downloads stop at once)

Parameters: id (path)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
get/api/v1/reports/usagescope: reports:read

Daily usage, results, versions in the field and expiring licences

Parameters: product_id (query), days (query)

get/api/v1/webhooksscope: webhooks

List outbound webhook endpoints

post/api/v1/webhooksscope: webhooks

Add an outbound webhook endpoint (secret returned once)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "maxLength": 500,
      "format": "uri"
    },
    "events": {
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "description": {
      "type": "string",
      "maxLength": 200
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}
delete/api/v1/webhooks/{id}scope: webhooks

Remove a webhook endpoint

Parameters: id (path)