API Surface

All endpoints are under /api/v1. Interactive OpenAPI docs are served at http://<backend>/docs (Swagger UI) and http://<backend>/redoc.

Routers

Router	Responsibility
`auth`	Login (local + Entra), token refresh, callback
`tokens`	Personal access token (PAT) create / list / revoke
`buckets`	Bucket CRUD, listing / browsing, quotas
`objects`	Object listing, deletion, copy / move, bulk copy / move, presigned download
`upload`	Multipart init / complete, simple upload
`images`	Authenticated image proxy with optional on-the-fly transforms
`share` + `public`	Expiring / revocable tokenized public links + unauthenticated serving at `/public/s/{token}`
`policies`	Cleanup policy CRUD and manual runs
`webhooks`	Webhook endpoint CRUD, delivery log, and test delivery (admin)
`users` / `groups`	User and group management, permission assignment, Entra import
`settings`	Runtime settings (auth toggles, auto-provisioning, quotas)
`audit`	Audit-log queries (filtering + pagination)

Common endpoints

The tables below list the endpoints referenced throughout these docs. Consult the live OpenAPI schema at http://<backend>/docs for request/response models and the complete surface.

Auth & tokens

Method	Path	Notes
POST	`/api/v1/auth/token`	Local login (form: `username`, `password`)
GET	`/api/v1/auth/login`	Returns the Entra `auth_url`
GET	`/api/v1/auth/callback`	OIDC redirect target
POST	`/api/v1/auth/refresh`	Exchange a refresh token
POST / GET / DELETE	`/api/v1/tokens` · `/api/v1/tokens/{id}`	Create / list / revoke PATs

Buckets & objects

Method	Path	Notes
POST / DELETE	`/api/v1/buckets` · `/api/v1/buckets/{name}`	Create (optional `quota_gb`) / delete
GET	`/api/v1/buckets/{name}/browse?prefix=`	Browse contents
POST	`/api/v1/buckets/{name}/objects?prefix=`	Simple upload (`multipart/form-data`)
POST	`/api/v1/buckets/{name}/upload/init` · `/upload/complete`	Multipart lifecycle
POST	`/api/v1/buckets/{dest}/objects/copy` · `/move`	Single copy / move
POST	`/api/v1/buckets/{dest}/objects/bulk-copy` · `/bulk-move`	Bulk copy / move

Method	Path	Auth	Notes
GET	`/api/v1/images/{bucket}/{key}`	JWT	Proxy + transforms (`w`,`h`,`format`,`q`,`fit`)
POST	`/api/v1/share/{bucket}/{key}`	JWT	Mint a share token (`expires_in`)
GET	`/api/v1/share` · DELETE `/api/v1/share/{id}`	JWT	List / revoke links
GET	`/api/v1/public/s/{token}`	none	Serve object; expired/revoked → 410

Policies, webhooks, users & audit

Method	Path	Notes
POST	`/api/v1/policies` · `/api/v1/policies/{id}/run`	Create policy / manual run
POST	`/api/v1/webhooks` · GET `/api/v1/webhooks/{id}/deliveries`	Register endpoint / inspect deliveries
GET / POST	`/api/v1/users/entra/search?q=` · `/api/v1/users/entra/import`	Entra search / import
GET	`/api/v1/audit?action=&bucket=&page=&page_size=`	Audit query (admin)

Authentication

Every authenticated endpoint accepts a Bearer credential — either a JWT from login or a Personal Access Token:

curl http://localhost:8200/api/v1/buckets \
  -H "Authorization: Bearer $TOKEN"

Related: Architecture · Authentication