Skip to content

Commit f08bd61

Browse files
alexellisalexellis
committed
Public docs for management API
Signed-off-by: Alex Ellis (OpenFaaS Ltd) <alexellis2@gmail.com>
1 parent 5dc0c4c commit f08bd61

4 files changed

Lines changed: 203 additions & 0 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
/site

‎docs/reference/billing-management-api.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# Billing Management API
2+
3+
The Billing Management API is available to approved customers who need to update the billable quantity for a subscription from their own automation.
4+
5+
Each billing API key is tied to a specific subscription. If you have more than one subscription, request a separate API key for each subscription that needs automated quantity updates.
6+
7+
This API is separate from:
8+
9+
* your inlets Pro or Inlets Uplink license key
10+
* the Inlets Uplink Client API used to create and manage tunnels
11+
* any Kubernetes Secret used by the Uplink operator
12+
13+
The billing API uses a separate bearer token issued by the inlets team.
14+
15+
## Request access
16+
17+
API access requires a separate agreement and vetting. Once approved, the inlets team will issue access manually.
18+
19+
### Generate an encryption keypair
20+
21+
To request an API key, generate an encryption keypair and send us your public key:
22+
23+
```sh
24+
inlets-pro seal keygen
25+
```
26+
27+
The command writes a private key to `~/.inlets/seal.key` and a public key to `~/.inlets/seal.pub`.
28+
29+
The private key stays on your machine. Do not send it to anyone.
30+
31+
The command also prints the public key with a message similar to:
32+
33+
```text
34+
Email the below to the inlets team:
35+
36+
inlets-seal-pub-v1:...
37+
```
38+
39+
Email the printed public key to the inlets team when requesting API access.
40+
41+
### Unseal the API key
42+
43+
The inlets team will create a billing API key linked to your subscription, seal it with your public key, and send the sealed value back to you.
44+
45+
```sh
46+
inlets-pro unseal < encrypted_key_you_received.txt
47+
```
48+
49+
Put the unsealed API key in permanent storage such as a KMS, HashiCorp Vault, or a password manager, then add it to your automation.
50+
51+
After that, you can delete the seal keypair:
52+
53+
```sh
54+
rm ~/.inlets/seal.key ~/.inlets/seal.pub
55+
```
56+
57+
The seal keypair is only used to deliver an API key to you. Generate a new seal keypair if you need a replacement API key, a rotated API key, or an API key for a different subscription.
58+
59+
## Authentication
60+
61+
Use the unsealed API key as a bearer token. Your product license key remains the credential used by the product itself. The billing API key only authorises billing-related API calls and uses this format:
62+
63+
```text
64+
inlets_live_<key-id>.<secret>
65+
```
66+
67+
The key is shown once when issued. If it is lost or exposed, ask the inlets team to rotate it.
68+
69+
## Fetch quantity
70+
71+
Fetch the current quantity and policy for the subscription linked to the billing API key:
72+
73+
```http
74+
GET /v1/billing/quantity
75+
Authorization: Bearer inlets_live_<key-id>.<secret>
76+
```
77+
78+
Response:
79+
80+
```json
81+
{
82+
"billable_quantity": 15,
83+
"licensed_quantity": 15,
84+
"policy": {
85+
"included_quantity": 10,
86+
"quantity_step": 5
87+
}
88+
}
89+
```
90+
91+
## Update quantity
92+
93+
Report the number of units you want your subscription to cover. The product and subscription are resolved from the billing API key issued by the inlets team. For Inlets Uplink and standalone inlets Pro, the quantity is the number of tunnels.
94+
95+
```http
96+
PUT /v1/billing/quantity
97+
Authorization: Bearer inlets_live_<key-id>.<secret>
98+
Content-Type: application/json
99+
100+
{
101+
"quantity": 11
102+
}
103+
```
104+
105+
Response:
106+
107+
```json
108+
{
109+
"requested_quantity": 11,
110+
"billable_quantity": 15,
111+
"licensed_quantity": 15,
112+
"policy": {
113+
"included_quantity": 10,
114+
"quantity_step": 5
115+
}
116+
}
117+
```
118+
119+
Inlets Uplink is sold as provider capacity. Each subscription includes a base tunnel allowance, and additional capacity is sold in bands.
120+
121+
For example, if your subscription includes 10 tunnels and the additional capacity step is 5:
122+
123+
| Inlets Uplink requested tunnels | Billable capacity |
124+
| ---: | ---: |
125+
| 1-10 | 10 |
126+
| 11-15 | 15 |
127+
| 16-20 | 20 |
128+
| 21-25 | 25 |
129+
130+
Standalone inlets Pro subscriptions are billed with per-tunnel granularity after the minimum quantity.
131+
132+
For example, if your subscription has a minimum billable quantity of 5:
133+
134+
| inlets Pro requested tunnels | Billable capacity |
135+
| ---: | ---: |
136+
| 1-5 | 5 |
137+
| 6 | 6 |
138+
| 7 | 7 |
139+
| 8 | 8 |
140+
| 9 | 9 |
141+
| 10 | 10 |
142+
| 11 | 11 |
143+
144+
The API returns the billable quantity after applying the current subscription policy.
145+
146+
## Fetch license entitlement
147+
148+
Inlets Uplink can use the license entitlement endpoint to fetch the tunnel limit for a license key. This endpoint is authenticated by the inlets Pro or Inlets Uplink license key, not by the billing API key.
149+
150+
```http
151+
GET /v1/license/inlets/entitlement
152+
Authorization: Bearer <license-key>
153+
```
154+
155+
Response:
156+
157+
```json
158+
{
159+
"valid": true,
160+
"provider": "lemonsqueezy",
161+
"product": "inlets-uplink",
162+
"quantity": 15,
163+
"entitlements": {
164+
"tunnels": 15
165+
},
166+
"subscription": {
167+
"product_name": "Inlets Uplink",
168+
"variant_name": "Provider"
169+
},
170+
"policy": {
171+
"included_quantity": 10,
172+
"quantity_step": 5
173+
}
174+
}
175+
```
176+
177+
## Errors
178+
179+
The API uses standard HTTP status codes:
180+
181+
| Status | Meaning |
182+
| --- | --- |
183+
| `400` | The request body is invalid or the quantity is missing. |
184+
| `401` | The bearer token is missing or invalid. |
185+
| `403` | The token is not authorised for quantity updates. |
186+
| `409` | The subscription could not be resolved unambiguously. |
187+
| `500` | The request could not be completed. |
188+
189+
Example error:
190+
191+
```json
192+
{
193+
"error": "quantity must be greater than zero"
194+
}
195+
```

‎docs/reference/index.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,12 @@ Learn how to set up the inlets-operator for Kubernetes, which provisions public
1212

1313
* [inlets-operator reference](/reference/inlets-operator/)
1414

15+
## Billing Management API
16+
17+
Learn how approved customers can update subscription quantities through the Billing Management API.
18+
19+
* [Billing Management API reference](/reference/billing-management-api/)
20+
1521
## GitHub repositories
1622

1723
* [inlets-pro](https://github.com/inlets/inlets-pro)

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -142,6 +142,7 @@ nav:
142142
- Overview: reference/index.md
143143
- Inlets Operator: reference/inlets-operator.md
144144
- inletsctl: reference/inletsctl.md
145+
- Billing Management API: reference/billing-management-api.md
145146

146147
extra:
147148
analytics:

0 commit comments

Comments
 (0)