Authentication

Every FluidCloud Partner API request is authenticated with an API key — a single long-lived secret that identifies your tenant and carries a fixed set of permissions (scopes). There are no per-request signatures, OAuth flows, or token exchanges to manage: you send your key on every call and FluidCloud resolves it to your account.

This page covers how to create a key, how to send it, the difference between live and test keys, and exactly what a partner key is and is not allowed to do.

Base URL: https://api-cloud.fluidvip.com/api/v1
Dashboard (where keys are created): https://cloud.fluidvip.com

Get a key

API keys are created in the FluidCloud dashboard, not through the API. (There is no endpoint to create, list, or rotate keys with a partner key — key lifecycle is a dashboard-only, human-in-the-loop operation by design.)

Sign in at https://cloud.fluidvip.com.
Go to Settings → Developer → API keys.
Click Create key, give it a label (e.g. prod-backend), and choose Live or Test mode.
Copy the secret immediately.

The secret is shown exactly once. FluidCloud stores only a SHA-256 hash of your key — the plaintext is never persisted and cannot be recovered. If you lose it, revoke the key in the dashboard and create a new one.

You need an active subscription

The FluidCloud API is part of the Elite subscription tier. The Create key button appears only when your account includes API access. If your subscription lapses or is downgraded after a key was issued, that key stops working at request time — see A lapsed subscription below.

A key looks like one of:

fck_live_3f9c2a7b8e1d4056a1b2c3d4e5f60718
fck_test_9d1e0c4a7b6f2358e9a0b1c2d3e4f506

The fck_live_ / fck_test_ prefix tells you which mode the key is in; the rest is the secret.

Send the key

Send your key on every request in the X-API-Key header:

bash

curl https://api-cloud.fluidvip.com/api/v1/me \
  -H "X-API-Key: fck_live_3f9c2a7b8e1d4056a1b2c3d4e5f60718"

You may also send it as a bearer token, which is convenient for HTTP clients that have first-class Authorization support:

bash

curl https://api-cloud.fluidvip.com/api/v1/me \
  -H "Authorization: Bearer fck_live_3f9c2a7b8e1d4056a1b2c3d4e5f60718"

Both forms are equivalent. The X-API-Key header takes precedence if you send both.

The SDKs handle this for you

You configure the key once when you construct the client; every call thereafter is authenticated automatically.

python

# pip install fluidcloud
from fluidcloud import FluidCloud

fc = FluidCloud(api_key="fck_live_3f9c2a7b8e1d4056a1b2c3d4e5f60718")

me = fc.me()  # the key travels on every request

typescript

// npm install fluidcloud
import { FluidCloud } from "fluidcloud";

const fc = new FluidCloud({ apiKey: "fck_live_3f9c2a7b8e1d4056a1b2c3d4e5f60718" });

const me = await fc.me(); // the key travels on every request

Prefer reading the key from an environment variable or secret manager rather than hard-coding it. See Security for handling and rotation guidance.

Live vs test keys

Prefix	Mode	Use it for
`fck_live_`	Live	Production traffic that counts against your plan.
`fck_test_`	Test	Integration and development.

The mode is fixed at creation. Keep separate keys per environment so you never point a staging build at production data — and so revoking one never disrupts the other.

What a partner key can do (scopes)

Every API key carries a fixed set of scopes. A scope names a capability (a resource plus an action). When you create a self-serve partner key, FluidCloud grants this exact set — you cannot widen, narrow, or customize it:

Scope	Grants
`spaces:read`	List and read spaces.
`spaces:write`	Create, rename, and delete spaces.
`folders:read`	List and read folders.
`folders:write`	Create, rename, move, and delete folders.
`files:read`	List, read, and download file metadata.
`files:write`	Upload, move, rename, and delete files.
`shares:read`	List and read share links.
`shares:write`	Create and revoke share links.
`quota:read`	Read your storage and share-link usage and limits.

That set covers the full partner surface: organizing storage, uploading and downloading files, minting raw links, and reading usage. Every endpoint in the API reference declares which of these scopes it requires, and a partner key holds all of them — so under normal operation you will never hit a scope error.

Scopes use AND semantics

An endpoint may require more than one scope, and the request must satisfy every one of them. For example, creating a share link requires both files:read (to look up the file) and shares:write (to mint the link). A key missing any required scope is rejected — there is no partial pass.

A missing scope returns 403 `insufficient_scope`

Because a partner key always holds the full set above, you should only ever see this if you call something outside the partner surface. The response is a 403 with a structured body naming what was required and what was missing:

json

{
  "detail": {
    "error": "insufficient_scope",
    "required": ["files:write"],
    "missing": ["files:write"]
  }
}

The SDKs raise a typed PermissionError (Python) / PermissionError (TypeScript) for this case. See Errors for the full mapping.

Out of scope for partner keys. Federation / delegation (acting on behalf of another user), team and member management, and key creation/rotation are first-party only and are not available to API keys. The SDK does not expose them for partner use. Do not rely on any scope outside the table above.

A lapsed subscription

Partner keys are continuously re-checked against the owner's plan. If your subscription no longer includes API access — for example after a downgrade from Elite — your key is rejected at request time with a 403 and a structured body:

json

{
  "detail": {
    "error": "feature_not_in_plan",
    "feature": "fluidcloud_api",
    "upgrade": "elite"
  }
}

This is independent of scopes: the key may be valid and fully scoped, but the account it belongs to is no longer entitled to the API. Restore the subscription in the dashboard to re-enable the key — you do not need to mint a new one. The SDKs surface this as a PermissionError.

What an invalid key returns

Condition	Status	Notes
No key sent	`401`	`detail: "Not authenticated"`
Malformed / unknown / revoked key	`401`	`detail: "Invalid API key"`
Valid key, missing a required scope	`403`	`error: "insufficient_scope"` (see above)
Valid, scoped key, but plan dropped access	`403`	`error: "feature_not_in_plan"` (see above)

A 401 means re-check the credential: the key is missing, mistyped, or has been revoked in the dashboard. A 403 means the credential is recognized but not permitted for that action or under the current plan. The SDKs map 401 to AuthError and 403 to PermissionError. The complete catalog is on the Errors page.

Rate limits

Limits are enforced per API key. The default ceiling is 600 requests per minute, with tighter per-action caps on certain operations (creating share links, starting uploads, starting URL imports). Exceeding a limit returns 429 with a Retry-After header. See Rate limits for the full table and back-off guidance.

Next steps

Quickstart — make your first authenticated call end to end.
Concepts — spaces, folders, files, and share links.
API reference — every endpoint and the scopes it requires.
Security — storing, rotating, and scoping access to your keys.

Authentication ​

Get a key ​

You need an active subscription ​

Send the key ​

The SDKs handle this for you ​

Live vs test keys ​

What a partner key can do (scopes) ​

Scopes use AND semantics ​

A missing scope returns 403 insufficient_scope ​

A lapsed subscription ​

What an invalid key returns ​

Rate limits ​

Next steps ​