You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -33,8 +33,42 @@ Sign in at [cloud.runonflux.com/flux-drive](https://cloud.runonflux.com/flux-dri
33
33
34
34
#### 3. Generate an API Key
35
35
36
-
* In the FluxDrive web UI, generate an **API\_KEY\_SECRET** mapped to your FluxID
37
-
* Custom (PRO) plans can be arranged by contacting the Flux team — fill out the [PRO Plan Request Form](https://runonflux.bitrix24.com/pub/form/33_fluxdrive_pro_request_/2xp87g/?view=preview\&preview=inline) for a custom storage allocation
36
+
Sign in at [cloud.runonflux.com/flux-drive](https://cloud.runonflux.com/flux-drive) and scroll to the **API Keys** panel, below your storage usage.
37
+
38
+
<imgsrc="/.gitbook/assets/fluxdrive-apikeys-panel.png"alt="The API Keys panel in the FluxDrive web UI, with no keys created yet"/>
39
+
40
+
**1. Click Create key**, then give the key a name you'll recognise later — something that identifies the app or machine that will use it.
41
+
42
+
<imgsrc="/.gitbook/assets/fluxdrive-apikeys-create.png"alt="The Create API key dialog with a key name entered"/>
43
+
44
+
**2. Click Generate.** Your new key is displayed along with a ready-to-run `curl` command that already has your FluxID filled in. Use the copy button to the right of either field.
45
+
46
+
<imgsrc="/.gitbook/assets/fluxdrive-apikeys-reveal.png"alt="The new API key dialog showing the generated key, a ready-to-run curl command, and a warning that the key is shown only once"/>
47
+
48
+
> ⚠️ **The key is shown only once.** FluxDrive stores only a hash of it, so it cannot be displayed or recovered again after you close that dialog. If you lose a key, revoke it and create a new one.
49
+
50
+
**3. Store the key somewhere safe** — a password manager, or your deployment's secret store — then click **I've saved it**.
51
+
52
+
Custom (PRO) plans can be arranged by contacting the Flux team — fill out the [PRO Plan Request Form](https://runonflux.bitrix24.com/pub/form/33_fluxdrive_pro_request_/2xp87g/?view=preview\&preview=inline) for a custom storage allocation.
53
+
54
+
#### 4. Managing Your Keys
55
+
56
+
The same panel lists every key on your account, showing its name, first 8 characters, when it was created, and when it was last used — so you can tell which key an integration is actually using before you touch it. A key that has never been used shows **Never**.
57
+
58
+
<imgsrc="/.gitbook/assets/fluxdrive-apikeys-manage.png"alt="The API Keys panel listing two keys with their name, key prefix, creation date, last-used date, and a revoke button"/>
59
+
60
+
| Action | How | Effect |
61
+
| ------ | --- | ------ |
62
+
|**Revoke a key**| Trash icon next to the key | Immediate. Any application using it starts receiving `401`. |
63
+
|**Create another**|**Create key**| Up to 10 keys per subscription. |
64
+
65
+
Some practical notes:
66
+
67
+
* Keys do not expire — they stay valid until you revoke them or the subscription lapses
68
+
* A key only works while the subscription is **active**; an unpaid or expired subscription returns `402` on every request
69
+
* Keys carry full access to your FluxDrive storage, so treat one like a password: keep it out of client-side code and out of version control
70
+
* Use a separate named key per application, so revoking one never takes down the others
71
+
* Keys cannot be used to create or revoke other keys — key management always requires a Zelcore signature from the web UI
38
72
39
73
***
40
74
@@ -57,45 +91,64 @@ All endpoints are accessed via **POST** requests with HTTP Basic authentication:
57
91
| Limit | Value | Notes |
58
92
| ----- | ----- | ----- |
59
93
| Maximum file size | 5 GB per file | Larger uploads return HTTP 413 |
60
-
| PUT rate limit | 150 requests / second | Per ZELID + IP |
61
-
| Read rate limit | 1500 requests / second | Per ZELID + IP, applies to `/cat`,`/get`, `/ls`, `/status`, `/thumb`|
94
+
| PUT rate limit | 150 requests / second | Per ZELID + IP, applies to `/put` and `/putfolder`|
95
+
| Read rate limit | 1500 requests / second | Per ZELID + IP, applies to every`/api/v0` endpoint|
62
96
| Storage capacity | Plan-dependent | See plans on the [overview page](README.md)|
97
+
| API keys | 10 per subscription | Revoke one to create another |
63
98
64
-
Exceeding a rate limit returns HTTP 429 with `Retry-After` headers.
99
+
Exceeding a rate limit returns HTTP 429. The rate-limit budget is keyed on your ZELID combined with your client IP, so separate machines using the same key each get their own allowance.
65
100
66
101
***
67
102
68
103
### Authentication & Errors
69
104
70
-
Every request must include valid Basic auth. Failed requests return JSON with an `error` field.
105
+
Every request must include valid Basic auth (`-u "<ZELID>:<API_KEY_SECRET>"`). Failed requests return JSON with an `error` field, except for rate limiting — see below.
106
+
107
+
**Authentication failures**
108
+
109
+
| Status |`error`| Cause |
110
+
| ------ | ------- | ----- |
111
+
|`401`|`Missing or invalid Authorization header`| No `Authorization: Basic ...` header, or it could not be decoded |
112
+
|`401`|`Subscription not found`| No FluxDrive subscription exists for that ZELID |
113
+
|`401`|`Invalid API key`| The key is wrong, or it was revoked |
114
+
|`402`|`Subscription payment is not active`| Subscription is unpaid, expired, or cancelled |
115
+
|`403`|`IP address is not whitelisted`| Your account has an IP allow-list set and the request came from another address |
116
+
117
+
> ℹ️ **IP allow-listing is optional and off by default.** If you want your keys usable only from specific addresses, contact the Flux team to have an allow-list applied to your subscription.
71
118
72
-
**Common error responses:**
119
+
**Request failures**
73
120
74
121
```json
75
-
// 401 — invalid or missing API key
76
-
{ "error": "Invalid credentials" }
122
+
// 400 — hash missing or malformed
123
+
{ "error": "Invalid or missing hash" }
77
124
78
-
// 402 — subscription not active (e.g., expired or unpaid)
125
+
// 400 — upload request carried no file
126
+
{ "error": "No file provided" }
127
+
128
+
// 402 — subscription lapsed between auth and upload
// 413 — upload would exceed your plan's storage capacity
83
135
{ "error": "Storage capacity exceeded" }
84
136
85
-
// 404 — hash not found in your account
137
+
// 404 — hash is not present in your account
86
138
{ "error": "File not found" }
87
-
88
-
// 429 — rate limited
89
-
{ "error": "Too many requests" }
90
139
```
91
140
141
+
> ⚠️ **HTTP 429 is not JSON.** Rate-limited requests return the plain-text body `Too many requests, please try again later.` — parse defensively rather than assuming an `error` field.
142
+
92
143
***
93
144
94
145
### Supported API Endpoints
95
146
147
+
All endpoints are **POST**. Parameters are sent in the **request body** (form-encoded or JSON), *not* as query-string arguments.
148
+
96
149
#### 1. `/api/v0/status`
97
150
98
-
**Description:** Get current storage usageand remaining capacity.
151
+
**Description:** Get current storage usage, capacity, and subscription state.
**Description:** Upload one or more files. Subject to the 5 GB per-file limit and your plan's storage capacity.
222
+
**Description:** Upload a **single file**. Subject to the 5 GB per-file limit and your plan's remaining capacity. To upload several files in one request, use `/putfolder`.
223
+
224
+
The form field name is not significant — the first uploaded file in the request is used.
> ℹ️ **`/putfolder` reports per-file outcomes.** The request can return `200` while individual entries carry an `error` field. Always inspect each entry rather than relying on the status code alone.
279
+
207
280
***
208
281
209
282
#### 5. `/api/v0/cat`
210
283
211
-
**Description:** Output the contents of a file from IPFS.
284
+
**Description:** Stream the contents of a file inline.
285
+
286
+
**Arguments:**
287
+
288
+
*`hash`_(string, required)_ — IPFS hash of a file in your account
Responses are served with `X-Content-Type-Options: nosniff`, and HTML/SVG/XML content types are downgraded to `application/octet-stream` so the API cannot be used to host executable web content.
222
298
223
299
***
224
300
225
301
#### 6. `/api/v0/get`
226
302
227
-
**Description:** Download a file from IPFS.
303
+
**Description:** Download a file as an attachment. Identical to `/cat` except that a `Content-Disposition: attachment` header is set.
**Description:** Remove a file from your FluxDrive account. The hash is unpinned from your subscription; if no other accounts pin it, the cluster will eventually garbage-collect the underlying blocks.
317
+
**Description:** Remove a file from your FluxDrive account. The hash is unpinned from your subscription; if no other account references it, the cluster will eventually garbage-collect the underlying blocks.
**Description:** Retrieve the generated thumbnail for a file, as `image/jpeg`. Returns `404` with `{ "error": "No thumbnail" }` when the file has none.
* All commands must be executed from a terminal (e.g., **VSCode integrated terminal**, **Ubuntu**, or similar).
264
-
* API access is protected via **ZELID** and **API\_KEY\_SECRET** — keep your key secret. If a key is leaked, rotate it immediately by generating a new one in the web UI.
351
+
* Parameters go in the request body — `/api/v0` does not read query-string arguments.
352
+
* API access is protected via **ZELID** and **API\_KEY\_SECRET** — keep your key secret. If a key is leaked, revoke it in the web UI and generate a replacement.
0 commit comments