Safebucket API
REST API for Safebucket, a self-hosted secure file sharing platform where file uploads/downloads go directly to the storage backend via presigned URLs.
Authentication is provider-based (local, oidc, ldap). Access, refresh, MFA, and public-share tokens are JWTs carried either as a Bearer header or as HttpOnly cookies (safebucket_access_token, safebucket_refresh_token, safebucket_mfa_token, safebucket_share_token). Endpoints that accept a restricted-audience token (MFA login, password reset, invite acceptance) are noted in their description; regular BearerAuth/CookieAuth schemes are shown for illustration only in those cases since OpenAPI has no way to express JWT audience restrictions.
Error responses always have the shape {"status": <int>, "error": [<string>, ...]} (see the Error schema). Error code strings are stable identifiers (e.g. BUCKET_NOT_FOUND, INVALID_MFA_CODE) intended for programmatic handling; only a representative subset of codes is called out per endpoint below, not an exhaustive enumeration.
Authentication failures: a request with a missing or invalid token is rejected with 403 FORBIDDEN (not 401). 401 SESSION_REVOKED is returned when the token is valid but its session has been revoked, and 403 FORBIDDEN is also used when a restricted-audience token is used on a route it does not allow or when the caller's role/group is insufficient.
Authentication
- HTTP: Bearer Auth
- API Key: CookieAuth
- API Key: CookieRefreshAuth
- API Key: CookieMFAAuth
- API Key: CookieShareAuth
Full access token (app:* audience), sent as Authorization Bearer <token>.
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |
Bearer format: | JWT |
Full access token (app:* audience) stored in an HttpOnly cookie.
Security Scheme Type: | apiKey |
|---|---|
Cookie parameter name: | safebucket_access_token |
Refresh token (auth:refresh audience), only valid for /auth/refresh and /auth/logout.
Security Scheme Type: | apiKey |
|---|---|
Cookie parameter name: | safebucket_refresh_token |
Restricted token issued mid-flow (auth:mfa:login or auth:mfa:password-reset audience). Only valid for MFA verify/device-management and password-reset completion endpoints.
Security Scheme Type: | apiKey |
|---|---|
Cookie parameter name: | safebucket_mfa_token |
Share-scoped access token issued by POST /shares/{shareId}/auth. Only enforced for password-protected shares; shares without a password are accessible without it.
Security Scheme Type: | apiKey |
|---|---|
Cookie parameter name: | safebucket_share_token |
License Apache 2.0