Skip to content

Commit 5c1d47d

Browse files
cap10morgankriszyp
cap10morgan
and
kriszyp
authored
Usage license redux (#220)
* Add install and get usage licenses * Fix some usage license details --------- Co-authored-by: Kris Zyp <[email protected]>
1 parent e0cdff0 commit 5c1d47d

File tree

1 file changed

+159
-0
lines changed

1 file changed

+159
-0
lines changed

‎docs/developers/operations-api/registration.md

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,166 @@ Returns the registration data of the Harper instance.
2727

2828
---
2929

30+
## Install Usage License
31+
32+
Install a Harper license for a block of usage. Multiple usage blocks may be installed, and they will be used up sequentially, with the earliest installed blocks used first. A license is installed
33+
by creating a string that consists of three base64url encoded blocks, separated by dots. The three blocks consist of:
34+
- `header`: This is a JSON object with two properties:
35+
- `typ`: should be "Harper-License"
36+
- `alg`: should be "EdDSA"
37+
38+
This JSON object should be converted to base64url (conversion from utf-8 to base64url) and is the first base64url block.
39+
40+
- license payload: This is a JSON object with properties:
41+
- `id` _(required)_ - A unique id for the license
42+
- `level` _(required)_ - Usage level number
43+
- `region` _(required)_ - The region id where this license can be used
44+
- `reads` _(required)_ - The number of allowed reads
45+
- `readBytes` _(required)_ - The number of allowed read bytes
46+
- `writes` _(required)_ - The number of allowed writes
47+
- `writeBytes` _(required)_ - The number of allowed write bytes
48+
- `realTimeMessages` _(required)_ - The number of allowed real-time messages
49+
- `realTimeBytes` _(required)_ - The number of allowed real-time message bytes
50+
- `cpuTime` _(optional)_ - The allowed amount of CPU time consumed by application code
51+
- `storage` _(optional)_ - Maximum of storage that may be used
52+
- `expiration` _(required)_ - The date when this block expires, as an ISO date
53+
54+
This JSON object should be converted to base64url (conversion from utf-8 to base64url) and is the second base64url block.
55+
56+
For example:
57+
```json
58+
{
59+
"id": "license-717b-4c6c-b69d-b29014054ab7",
60+
"level": 2,
61+
"region": "us-nw-2",
62+
"reads": 2000000000,
63+
"readBytes": 8000000000000,
64+
"writes": 500000000,
65+
"writeBytes": 1000000000000,
66+
"realTimeMessages": 10000000000,
67+
"realTimeBytes": 40000000000000,
68+
"cpuTime": 108000,
69+
"storage": 400000000000000,
70+
"expiration": "2025-07-25T21:17:21.248Z"
71+
}
72+
```
73+
74+
- `signature`: This is the cryptographic signature, signed by Harper, of the first two blocks, separated by a dot, `header.payload`. This is also converted to base64url.
75+
76+
The three base64url blocks are combined to form the `license` property value in the operation.
77+
78+
- `operation` _(required)_ - must always be `install_usage_license`
79+
- `license` _(required)_ - This is the combination of the three blocks in the form `header.payload.signature`
80+
81+
### Body
82+
83+
```json
84+
{
85+
"operation": "install_usage_license",
86+
"license": "abc...0123.abc...0123.abc...0123",
87+
}
88+
```
89+
90+
### Response: 200
91+
92+
```json
93+
{
94+
"message": "Successfully installed usage license"
95+
}
96+
```
97+
98+
---
99+
100+
## Get Usage Licenses
101+
102+
This will retrieve and return all active usage licenses, with counts of how much of the limits have been consumed.
103+
104+
- `operation` _(required)_ - must always be `get_usage_licenses`
105+
106+
### Body
107+
108+
```json
109+
{
110+
"operation": "get_usage_licenses"
111+
}
112+
```
113+
114+
### Response: 200
115+
116+
```json
117+
[
118+
{
119+
"id": "license-717b-4c6c-b69d-b29014054ab7",
120+
"level": 2,
121+
"region": "us-nw-2",
122+
"reads": 2000000000,
123+
"usedReads": 1100000000,
124+
"readBytes": 8000000000000,
125+
"usedReadBytes": 3000000000000,
126+
"writes": 500000000,
127+
"usedWrites": 300000000,
128+
"writeBytes": 1000000000000,
129+
"usedWriteBytes": 4300000000000,
130+
"realTimeMessages": 10000000000,
131+
"usedRealTimeMessages": 2000000000,
132+
"realTimeBytes": 40000000000000,
133+
"usedRealTimeBytes": 13000000000000,
134+
"cpuTime": 108000,
135+
"usedCpuTime": 41000,
136+
"storage": 400000000000000,
137+
"expiration": "2025-07-25T21:17:21.248Z"
138+
},
139+
{
140+
"id": "license-4c6c-b69d-b29014054ab7-717b",
141+
"level": 2,
142+
"region": "us-nw-2",
143+
"reads": 2000000000,
144+
"usedReads": 0,
145+
"readBytes": 8000000000000,
146+
"usedReadBytes": 0,
147+
"writes": 500000000,
148+
"usedWrites": 0,
149+
"writeBytes": 1000000000000,
150+
"usedWriteBytes": 0,
151+
"realTimeMessages": 10000000000,
152+
"usedRealTimeMessages": 0,
153+
"realTimeBytes": 40000000000000,
154+
"usedRealTimeBytes": 0,
155+
"cpuTime": 108000,
156+
"usedCpuTime": 0,
157+
"storage": 400000000000000,
158+
"expiration": "2025-09-25T21:17:21.248Z"
159+
},
160+
{
161+
"id": "license-4c6c-b69d-b29014054ab7-717b",
162+
"level": 2,
163+
"region": "us-se-2",
164+
"reads": 2000000000,
165+
"usedReads": 0,
166+
"readBytes": 8000000000000,
167+
"usedReadBytes": 0,
168+
"writes": 500000000,
169+
"usedWrites": 0,
170+
"writeBytes": 1000000000000,
171+
"usedWriteBytes": 0,
172+
"realTimeMessages": 10000000000,
173+
"usedRealTimeMessages": 0,
174+
"realTimeBytes": 40000000000000,
175+
"usedRealTimeBytes": 0,
176+
"cpuTime": 108000,
177+
"usedCpuTime": 0,
178+
"storage": 400000000000000,
179+
"expiration": "2025-11-25T21:17:21.248Z"
180+
}
181+
]
182+
```
183+
184+
---
185+
186+
30187
## Get Fingerprint
31188

189+
(Deprecated)
32190
Returns the Harper fingerprint, uniquely generated based on the machine, for licensing purposes.
33191

34192
_Operation is restricted to super_user roles only_
@@ -47,6 +205,7 @@ _Operation is restricted to super_user roles only_
47205

48206
## Set License
49207

208+
(Deprecated)
50209
Sets the Harper license as generated by Harper License Management software.
51210

52211
_Operation is restricted to super_user roles only_

0 commit comments

Comments
 (0)