{"openapi":"3.1.0","info":{"title":"VZ Vault API","version":"1.0.0","description":"License validation and management for VZ Vault. Use keys with only the `licenses:validate` scope inside distributed applications. Administrative scopes must never be shipped to clients."},"servers":[{"url":"https://api.vznetwork.online"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"vz_live_<prefix>_<secret>"}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}},"Validation":{"type":"object","properties":{"valid":{"type":"boolean"},"status":{"type":"string","enum":["ACTIVE","EXPIRED","SUSPENDED","REVOKED","NOT_FOUND"]},"reason":{"type":["string","null"]},"license":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"product":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"}}},"expiresAt":{"type":["string","null"],"format":"date-time"},"maxActivations":{"type":"integer"},"activeActivations":{"type":"integer"}}},"activation":{"type":"object","properties":{"activated":{"type":"boolean"}}}}},"Product":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":["string","null"]},"licenseType":{"type":"string","enum":["PERPETUAL","SUBSCRIPTION","TRIAL"]},"durationDays":{"type":["integer","null"]},"maxActivations":{"type":"integer"},"status":{"type":"string"}}}}},"paths":{"/api/v1/licenses/validate":{"post":{"summary":"Validate a license key","description":"Scope `licenses:validate`. Optional fingerprint reports whether that device is activated.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["key"],"properties":{"key":{"type":"string"},"fingerprint":{"type":"string"},"product":{"type":"string","description":"product slug"}}}}}},"responses":{"200":{"description":"Validation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Validation"}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited or brute-force lockout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/licenses/activate":{"post":{"summary":"Activate a device","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["key","fingerprint"],"properties":{"key":{"type":"string"},"fingerprint":{"type":"string"},"label":{"type":"string"}}}}}},"responses":{"200":{"description":"Activated (or already active)","content":{"application/json":{"schema":{"type":"object","properties":{"activationId":{"type":"string"},"alreadyActive":{"type":"boolean"},"licenseId":{"type":"string"}}}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"License not active or activation limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited or brute-force lockout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/licenses/deactivate":{"post":{"summary":"Deactivate a device","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["key","fingerprint"],"properties":{"key":{"type":"string"},"fingerprint":{"type":"string"}}}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","properties":{"deactivated":{"type":"boolean"}}}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited or brute-force lockout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/licenses":{"post":{"summary":"Create a license (server-side only)","description":"Scope `licenses:write`. The plaintext key is returned once.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["productId"],"properties":{"productId":{"type":"string","format":"uuid"},"customer":{"type":"object","properties":{"discordId":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"}}},"expiresAt":{"type":"string","format":"date-time"},"maxActivations":{"type":"integer"},"metadata":{"type":"object"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string"},"license":{"type":"object"}}}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited or brute-force lockout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/licenses/{id}/revoke":{"post":{"summary":"Revoke a license","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"Revoked license"},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited or brute-force lockout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/products":{"get":{"summary":"List products","responses":{"200":{"description":"Products","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited or brute-force lockout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a product","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","slug"],"properties":{"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string"},"licenseType":{"type":"string"},"durationDays":{"type":"integer"},"maxActivations":{"type":"integer"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited or brute-force lockout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}