| 1 |
# License Key API Guide |
| 2 |
|
| 3 |
The License Key API lets software applications validate and manage license keys issued through Makenotwork. All endpoints are public (no authentication required) and rate-limited. |
| 4 |
|
| 5 |
Endpoints are available at both `/api/keys/` and `/api/v1/keys/` paths. New integrations should use the `/api/v1/` prefix. |
| 6 |
|
| 7 |
## Validate and Activate a Key |
| 8 |
|
| 9 |
Validates a license key and optionally activates it on a machine. |
| 10 |
|
| 11 |
``` |
| 12 |
POST https://makenot.work/api/v1/keys/validate |
| 13 |
Content-Type: application/json |
| 14 |
|
| 15 |
{ |
| 16 |
"key": "XXXX-XXXX-XXXX-XXXX", |
| 17 |
"machine_id": "unique-machine-identifier", |
| 18 |
"label": "Alice's MacBook Pro" |
| 19 |
} |
| 20 |
``` |
| 21 |
|
| 22 |
### Parameters |
| 23 |
|
| 24 |
|
| 25 |
|
| 26 |
| `key` | Yes | The license key string | |
| 27 |
| `machine_id` | Yes | A stable, unique identifier for this machine | |
| 28 |
| `label` | No | Human-readable name for this activation | |
| 29 |
|
| 30 |
### Response |
| 31 |
|
| 32 |
```json |
| 33 |
{ |
| 34 |
"valid": true, |
| 35 |
"activated": true, |
| 36 |
"license": { |
| 37 |
"item_id": "550e8400-...", |
| 38 |
"max_activations": 3, |
| 39 |
"activation_count": 1, |
| 40 |
"created_at": "2026-03-13T10:00:00Z" |
| 41 |
} |
| 42 |
} |
| 43 |
``` |
| 44 |
|
| 45 |
### Error Cases |
| 46 |
|
| 47 |
```json |
| 48 |
{ |
| 49 |
"valid": false, |
| 50 |
"error": "invalid_key" |
| 51 |
} |
| 52 |
``` |
| 53 |
|
| 54 |
|
| 55 |
|
| 56 |
| `invalid_key` | Key does not exist | |
| 57 |
| `key_revoked` | Key has been revoked by the creator | |
| 58 |
| `activation_limit_reached` | All activation slots are in use | |
| 59 |
|
| 60 |
### Idempotent Activation |
| 61 |
|
| 62 |
If the same `key` + `machine_id` combination is submitted again, the existing activation is refreshed (timestamp updated) without consuming an additional slot. |
| 63 |
|
| 64 |
## Check Key Status |
| 65 |
|
| 66 |
Check whether a key is valid without activating it. |
| 67 |
|
| 68 |
``` |
| 69 |
GET https://makenot.work/api/v1/keys/{key_code}/status |
| 70 |
``` |
| 71 |
|
| 72 |
Response: |
| 73 |
|
| 74 |
```json |
| 75 |
{ |
| 76 |
"valid": true, |
| 77 |
"license": { |
| 78 |
"item_id": "550e8400-...", |
| 79 |
"max_activations": 3, |
| 80 |
"activation_count": 2, |
| 81 |
"remaining_activations": 1, |
| 82 |
"created_at": "2026-03-13T10:00:00Z" |
| 83 |
} |
| 84 |
} |
| 85 |
``` |
| 86 |
|
| 87 |
Use this for periodic license checks without affecting activation state. |
| 88 |
|
| 89 |
## Deactivate a Key |
| 90 |
|
| 91 |
Release an activation slot (e.g., when the user uninstalls your software). |
| 92 |
|
| 93 |
``` |
| 94 |
POST https://makenot.work/api/v1/keys/deactivate |
| 95 |
Content-Type: application/json |
| 96 |
|
| 97 |
{ |
| 98 |
"key": "XXXX-XXXX-XXXX-XXXX", |
| 99 |
"machine_id": "unique-machine-identifier" |
| 100 |
} |
| 101 |
``` |
| 102 |
|
| 103 |
Response: |
| 104 |
|
| 105 |
```json |
| 106 |
{ |
| 107 |
"success": true, |
| 108 |
"message": "Activation removed" |
| 109 |
} |
| 110 |
``` |
| 111 |
|
| 112 |
## License Verification (Offline Grace Period) |
| 113 |
|
| 114 |
For apps that need to work offline, use the verification endpoint. It validates and activates the key, then returns a signed JWT token valid for 7 days. The token acts as a time-boxed offline grace credential: your app caches it and honors it until the `exp` claim passes, without contacting the server in between. |
| 115 |
|
| 116 |
The token is signed with HS256, a symmetric scheme keyed on the server's secret. That secret is never distributed, so your app cannot cryptographically verify the signature locally. Genuine signature verification happens server-side on the next re-verify. Treat the cached token as a trusted receipt of a recent successful verification (read its `exp` to know when to re-verify), not as something you can independently authenticate offline. As with any client-side licensing, offline enforcement is a soft grace window, not a tamper-proof gate. |
| 117 |
|
| 118 |
This endpoint requires the project to have license verification enabled (configured by the creator in project settings). |
| 119 |
|
| 120 |
``` |
| 121 |
POST https://makenot.work/api/v1/license/verify |
| 122 |
Content-Type: application/json |
| 123 |
|
| 124 |
{ |
| 125 |
"key": "XXXX-XXXX-XXXX-XXXX", |
| 126 |
"machine_fingerprint": "unique-machine-identifier" |
| 127 |
} |
| 128 |
``` |
| 129 |
|
| 130 |
### Response |
| 131 |
|
| 132 |
```json |
| 133 |
{ |
| 134 |
"valid": true, |
| 135 |
"token": "eyJhbGciOiJIUzI1NiIs...", |
| 136 |
"expires_in": 604800 |
| 137 |
} |
| 138 |
``` |
| 139 |
|
| 140 |
|
| 141 |
|
| 142 |
| `valid` | Whether the key is valid and activated | |
| 143 |
| `token` | Signed JWT for offline verification (7-day validity) | |
| 144 |
| `expires_in` | Token lifetime in seconds (604800 = 7 days) | |
| 145 |
|
| 146 |
### JWT Claims |
| 147 |
|
| 148 |
The token contains: |
| 149 |
|
| 150 |
|
| 151 |
|
| 152 |
| `sub` | License key ID | |
| 153 |
| `machine` | Machine fingerprint | |
| 154 |
| `item` | Item ID | |
| 155 |
| `iat` | Issued at (Unix timestamp) | |
| 156 |
| `exp` | Expires at (Unix timestamp) | |
| 157 |
|
| 158 |
### Offline Flow |
| 159 |
|
| 160 |
1. Call `/api/v1/license/verify` on app launch (when online) |
| 161 |
2. Cache the returned JWT locally |
| 162 |
3. On subsequent offline launches, read the `exp` claim and honor the license until it passes (the signature is not locally verifiable, see above) |
| 163 |
4. Re-verify with the server when the token nears expiry or when connectivity returns |
| 164 |
|
| 165 |
### Deactivation via Verify API |
| 166 |
|
| 167 |
``` |
| 168 |
POST https://makenot.work/api/v1/license/deactivate |
| 169 |
Content-Type: application/json |
| 170 |
|
| 171 |
{ |
| 172 |
"key": "XXXX-XXXX-XXXX-XXXX", |
| 173 |
"machine_fingerprint": "unique-machine-identifier" |
| 174 |
} |
| 175 |
``` |
| 176 |
|
| 177 |
|
| 178 |
|
| 179 |
| `invalid_key` | Key does not exist | |
| 180 |
| `key_revoked` | Key has been revoked by the creator | |
| 181 |
| `activation_limit_reached` | All activation slots are in use | |
| 182 |
| `verification_not_enabled` | Project does not have license verification enabled | |
| 183 |
|
| 184 |
## License Text |
| 185 |
|
| 186 |
Retrieve the license agreement for an item in plain text: |
| 187 |
|
| 188 |
``` |
| 189 |
GET https://makenot.work/api/v1/items/{item_id}/license.txt |
| 190 |
``` |
| 191 |
|
| 192 |
Returns the license text configured by the creator (MIT, Apache 2.0, custom, etc.) as `text/plain`. |
| 193 |
|
| 194 |
## Revocation |
| 195 |
|
| 196 |
Creators can revoke keys from their dashboard. A revoked key returns `key_revoked` on all endpoints and cannot be reactivated. |
| 197 |
|
| 198 |
## PWYW Compatibility |
| 199 |
|
| 200 |
License keys work with Pay What You Want (PWYW) items. Any customer who completes a purchase receives a key if the creator has keys enabled. |
| 201 |
|
| 202 |
## Machine ID Guidelines |
| 203 |
|
| 204 |
The `machine_id` (or `machine_fingerprint` for the verify API) should be: |
| 205 |
- **Stable**: Same value across app restarts and updates |
| 206 |
- **Unique**: Different on each machine |
| 207 |
- **Not personally identifiable**: Avoid using MAC addresses or usernames |
| 208 |
|
| 209 |
Good approaches: |
| 210 |
- Generate a UUID on first launch and store it in the app's data directory |
| 211 |
- Use a hardware-derived hash (disk serial, motherboard ID) |
| 212 |
- Use the OS machine ID (e.g., `/etc/machine-id` on Linux) |
| 213 |
|
| 214 |
## Rate Limits |
| 215 |
|
| 216 |
License key endpoints are rate-limited per IP. See [API Overview](./api-overview.md) for current limits. |
| 217 |
|
| 218 |
## Integration Pattern |
| 219 |
|
| 220 |
Recommended flow for desktop applications: |
| 221 |
|
| 222 |
1. **On first launch**: Prompt for license key, call `/api/v1/keys/validate` with a generated machine ID |
| 223 |
2. **On subsequent launches**: Call `/api/v1/license/verify` for offline-capable apps, or `/api/v1/keys/{key_code}/status` for online-only apps |
| 224 |
3. **On uninstall**: Call `/api/v1/keys/deactivate` to release the activation slot |
| 225 |
4. **On activation failure**: Show the error message and allow the user to enter a different key |
| 226 |
|
| 227 |
## Error Response Format |
| 228 |
|
| 229 |
```json |
| 230 |
{ |
| 231 |
"error": "descriptive message" |
| 232 |
} |
| 233 |
``` |
| 234 |
|
| 235 |
|
| 236 |
|
| 237 |
| 400 | Invalid request body | |
| 238 |
| 404 | Key not found (for status endpoint) | |
| 239 |
| 429 | Rate limit exceeded | |
| 240 |
|
| 241 |
## See Also |
| 242 |
|
| 243 |
- [Pricing & Monetization](../guide/03-selling.md): License key setup for creators |
| 244 |
- [API Overview](./api-overview.md): Authentication and rate limits |
| 245 |
|