External API guide

Use scoped API tokens for scripts, CI/CD, and backends. Every token belongs to a service and can only manage that service's files under its key prefix.

1. Create a service and token

Sign in at /dashboard/login
Create a service (name + default key prefix, e.g. blog/)
Open API tokens, pick that service, grant permissions
Copy the secret once — it cannot be retrieved later

Open API tokens

2. Authenticate

Authorization: Bearer sa_YOUR_TOKEN

401 = missing/invalid/expired token. 403 = missing permission, wrong prefix, or file belongs to another service.

3. Discover identity

curl -s \
  -H "Authorization: Bearer $SA_TOKEN" \
  "https://your-domain.com/api/me"

Returns type, permissions, keyPrefix, service, and token id. Use keyPrefix when building object keys; the server also applies it on upload.

Permissions

Permission	Allows
(any token)	GET /api/me, GET /api/services (own)
files:list	GET /api/files
files:read	GET /api/files/[key]
files:write	POST /api/files, PUT /api/files/[key]
files:delete	DELETE /api/files/[key]
stats:read	GET /api/stats (own token/service)

Upload

curl -X POST \
  -H "Authorization: Bearer $SA_TOKEN" \
  -F "file=@./report.pdf" \
  -F "key=documents/report.pdf" \
  "https://your-domain.com/api/files"

Tokens do not send serviceId — the file is attached to the token's service and stored under the effective prefix.

Statistics

GET /api/stats?from=&to= returns call counts, bytes in/out, stored size, and percent shares by token, service, and route. Tokens only see their own traffic.

Public reads

GET /files/[key] serves the object with no auth. Anyone with the URL can read it. Do not store secrets in the bucket.

Full reference: docs/EXTERNAL-API.md and docs/API.md in the repository.