title	Admin API
description	Reference for SynapS3 health, metrics, dashboard, settings, wallet, task, and S3 user endpoints.

Admin API

The Admin API is used by the dashboard and CLI. Admin authentication is enabled by default. Keep the listener on loopback for local access; use an HTTPS reverse proxy or SSH tunnel for remote access.

Default base URL:

http://127.0.0.1:9090

Setup Mode

When /healthz returns {"status":"setup"}, the Admin endpoint exposes only the surfaces needed to finish configuration:

/healthz, Admin login, session, refresh, and logout;
the dashboard shell;
GET /api/v1/settings, PUT /api/v1/settings, and POST /api/v1/settings/validate;
POST /api/v1/filecoin/readiness/preflight.

Runtime metrics, buckets, objects, tasks, wallet operations, storage health, and S3 user management are unavailable in setup mode. Save valid settings, restart SynapS3, and verify that /healthz returns {"status":"ok"} before using the full API.

Auth Model

/healthz is public so process health checks can run without credentials. The dashboard shell and static assets can load before login, but dashboard data and write operations require Admin auth.

Surface	Required auth
`/healthz`	None.
`/api/v1/auth/login`, `/api/v1/auth/session`	Login and session endpoints. Session returns `401` when no valid browser session exists.
`/api/v1/auth/refresh`, `/api/v1/auth/logout`	Require a valid browser session and CSRF header; HTTP Basic auth is not accepted.
`/api/v1/*`	Browser session cookie with CSRF for unsafe methods, or HTTP Basic auth.
`/metrics`	Browser session cookie or HTTP Basic auth.
`/admin/exhausted-tasks*`	Browser session cookie with CSRF for unsafe methods, or HTTP Basic auth.

Browser Sessions

Browser login sets the synaps3_admin_session HttpOnly cookie and returns a CSRF token. Cookie-authenticated POST, PUT, PATCH, and DELETE requests must include X-SynapS3-CSRF. Refresh and logout only accept browser sessions.

The optional remember boolean in the login request defaults to false. A standard login uses a browser-session cookie and the configured admin.auth.session_ttl. When remember is true, the cookie persists for the greater of 30 days or the configured session TTL. Some browsers can restore browser-session cookies when restoring a previous browsing session.

Login, session, and refresh responses contain username, csrf_token, expires_at, and refresh_after. After refresh_after, the official dashboard requests renewal on the next trusted pointer, click, keyboard, or wheel interaction. Dashboard polling and returning to a visible tab do not trigger renewal. The server does not verify user activity: any client holding the valid session cookie and matching CSRF token can request renewal after refresh_after. The login has no absolute lifetime cap. If no client requests renewal, the token expires at expires_at.

Refresh preserves the session lifetime, CSRF token, and login family. Logout revokes the whole family, including tokens issued before the latest refresh. Revocations are kept in memory; restarting SynapS3 clears them, although the browser cookie is still removed during a normal logout.

CLI and Basic Auth

CLI and script calls can use HTTP Basic auth and do not need a CSRF header. Browser Basic-auth requests are rejected when Sec-Fetch-Site, Origin, or Referer show a cross-site origin. Requests without browser-origin headers still work for CLI and scripts.

Failed password checks are rate-limited by resolved client IP; additional login attempts are rejected while the limit is active.

Reverse Proxies

When SynapS3 is behind a reverse proxy, forwarded client, scheme, and host headers are used only when admin.trusted_proxies contains the proxy IP or CIDR. Keep it empty unless the proxy removes untrusted X-Forwarded-For, X-Real-IP, X-Forwarded-Proto, and X-Forwarded-Host headers.

Admin Credentials

Admin credentials are created by synaps3 init. Interactive init prints the password once. Non-interactive and Docker init write it to admin-initial-password in the runtime data directory with file mode 0600. Local synaps3 admin commands locate config through --config, SYNAPS3_CONFIG, then the default path; they use SYNAPS3_ADMIN_PASSWORD first, then admin-initial-password next to the config file, then the prompt.

Resetting the password also rotates admin.auth.session_secret, invalidating existing browser sessions. Reset it offline with:

synaps3 admin-auth reset-password --config /var/lib/synaps3/config.toml

Auth Endpoints

Method	Path	Purpose
`POST`	`/api/v1/auth/login`	Validate username and password, accept optional `remember`, set the browser cookie, and return the session.
`GET`	`/api/v1/auth/session`	Return the current browser session.
`POST`	`/api/v1/auth/refresh`	Require session and CSRF, then renew an eligible browser session. Early requests return the current session without changing the cookie.
`POST`	`/api/v1/auth/logout`	Require session and CSRF, end the current browser session, and clear the cookie.

After logout or a 401 API response, the dashboard returns to the login page.

Security Headers

Admin responses include Content-Security-Policy, X-Content-Type-Options: nosniff, X-Frame-Options: DENY, and Referrer-Policy: strict-origin-when-cross-origin. The default content policy keeps dashboard resources on the same origin.

High-Risk Operations

Treat these endpoints as change-window operations. They can change data, credentials, wallet payment state, or background state.

Area	Endpoints	Risk
Settings	`PUT /api/v1/settings`	Changes can require restart or move the node to a different Filecoin network. Validate settings and Filecoin readiness before saving.
Wallet	`POST /api/v1/wallet/fund`, `POST /api/v1/wallet/withdraw`, `POST /api/v1/wallet/approve`	Creates on-chain payment operations.
S3 users	`POST /api/v1/s3-users`, `PUT /api/v1/s3-users/{accessKey}`, `POST /api/v1/s3-users/{accessKey}/secret`, `DELETE /api/v1/s3-users/{accessKey}`	Changes client access or invalidates credentials.
Buckets and objects	bucket create, owner/copy-policy updates, object upload/download/delete/restore/permanent-delete	Changes or exposes user-visible S3 data and metadata.
Tasks and storage health	task retry, diagnostic refresh, storage provider and data set refresh	Requeues work or refreshes operational status.

Health and Metrics

Method	Path	Purpose
`GET`	`/healthz`	Health status for database, cache, and background tasks.
`GET`	`/metrics`	Prometheus metrics. Requires Admin auth.
`GET`	`/api/v1/system/info`	Version and runtime information.
`GET`	`/api/v1/workers`	Background task activity and health.
`GET`	`/api/v1/cache/stats`	Cache usage and capacity.

Dashboard Data

Method	Path	Purpose
`GET`	`/api/v1/overview`	Dashboard summary.
`GET`	`/api/v1/events`	Dashboard event stream.
`GET`	`/api/v1/buckets`	List buckets.
`POST`	`/api/v1/buckets`	Create a bucket.
`GET`	`/api/v1/buckets/{name}`	Read bucket detail.
`PUT`	`/api/v1/buckets/{name}/owner`	Update bucket owner.
`PUT`	`/api/v1/buckets/{name}/copy-policy`	Update default copy policy.
`DELETE`	`/api/v1/buckets/{name}`	Not supported. Returns `501 Not Implemented`.
`GET`	`/api/v1/buckets/{name}/objects`	List objects.
`DELETE`	`/api/v1/buckets/{name}/objects`	Create an object delete marker.
`POST`	`/api/v1/buckets/{name}/objects/upload`	Upload an object through the dashboard.
`GET`	`/api/v1/buckets/{name}/objects/download`	Download an object through the dashboard.
`GET`	`/api/v1/buckets/{name}/objects/versions`	List object versions and return the current version token.
`POST`	`/api/v1/buckets/{name}/objects/versions/restore`	Create a new current version from an existing data version.
`GET`	`/api/v1/buckets/{name}/objects/provenance`	Inspect object storage provenance.
`GET`	`/api/v1/buckets/{name}/objects/status-detail`	Read detailed object state.
`GET`	`/api/v1/buckets/{name}/objects/deleted`	List deleted objects.
`GET`	`/api/v1/buckets/{name}/objects/deletions`	List object delete markers.
`POST`	`/api/v1/buckets/{name}/objects/restore`	Restore an object from a delete marker.
`POST`	`/api/v1/buckets/{name}/objects/permanent-delete`	Permanently delete an object version.
`POST`	`/api/v1/buckets/{name}/objects/deleted/permanent-delete`	Permanently delete a deleted object version.
`GET`	`/api/v1/buckets/{name}/storage-health/affected-versions`	List versions affected by storage health issues.

For object upload, the HTTP Content-Type is the uploaded object's content type. It is not a JSON request marker.

Restore an Object Version

GET /api/v1/buckets/{name}/objects/versions includes current_version_id on every page when the object has version history. Pass that value when confirming a restore:

{
  "key": "path/file.txt",
  "version_id": "source-version-id",
  "expected_current_version_id": "current-version-id"
}

POST /api/v1/buckets/{name}/objects/versions/restore copies a historical data version to a new version of the same bucket and key. It does not modify or remove existing data versions or delete markers. The selected version must differ from the readable current object representation. Selecting the current version, or an equivalent historical version, is rejected without changing the object. A failed or unavailable current version can still be restored from a readable historical version.

Successful response:

{
  "key": "path/file.txt",
  "source_version_id": "source-version-id",
  "version_id": "new-current-version-id"
}

The request returns 409 Conflict when the selected version is a delete marker or expected_current_version_id is no longer current. Refresh the version list and confirm again with the new token. When the selected version already matches the current object, the response uses a stable code so clients can treat it as a no-op:

{
  "error": "selected version already matches the current object",
  "code": "object_version_already_current"
}

A missing or permanently deleted source returns 404 Not Found; insufficient cache capacity returns 507 Insufficient Storage; invalid input returns 400 Bad Request; source read and internal failures return 500 Internal Server Error.

The restore streams synchronously for up to one hour and requires enough cache capacity for the new destination version.

Tasks

Method	Path	Purpose
`GET`	`/api/v1/tasks`	List background tasks. Supports filters such as `type`, `stage`, `status`, `limit`, and `offset`.
`GET`	`/api/v1/tasks/stats`	Count tasks by status.
`GET`	`/api/v1/tasks/{id}/ref-detail`	Resolve the object or storage operation related to a task.
`GET`	`/api/v1/tasks/{id}/diagnostic`	Read task diagnostics.
`POST`	`/api/v1/tasks/{id}/diagnostic/refresh`	Refresh diagnostics.
`POST`	`/api/v1/tasks/{id}/retry`	Retry an exhausted task.
`GET`	`/admin/exhausted-tasks`	List exhausted tasks. Supports `limit` up to `1000`.
`POST`	`/admin/exhausted-tasks/{id}/retry`	Retry an exhausted task (legacy path).

Wallet and Filecoin

Method	Path	Purpose
`GET`	`/api/v1/wallet`	Wallet identity, balances, contract state, and business counters.
`POST`	`/api/v1/wallet/fund`	Create a wallet funding operation.
`POST`	`/api/v1/wallet/withdraw`	Create a wallet withdrawal operation.
`POST`	`/api/v1/wallet/approve`	Create an explicit FWSS approval operation. Payload only accepts `client_request_id`.
`GET`	`/api/v1/wallet/operations`	List wallet operations.
`GET`	`/api/v1/filecoin/readiness`	Check Filecoin readiness.
`POST`	`/api/v1/filecoin/readiness/preflight`	Validate pending Filecoin settings.
`GET`	`/api/v1/observability/providers`	Provider health data.
`POST`	`/api/v1/observability/providers/refresh`	Refresh provider health.
`GET`	`/api/v1/observability/data-sets`	Local data set health data.
`POST`	`/api/v1/observability/data-sets/refresh`	Refresh data set health.

Settings and S3 Users

Method	Path	Purpose
`GET`	`/api/v1/settings`	Read effective settings and metadata.
`PUT`	`/api/v1/settings`	Persist settings changes.
`POST`	`/api/v1/settings/validate`	Validate a settings payload without saving.
`GET`	`/api/v1/s3-users`	List S3 users.
`POST`	`/api/v1/s3-users`	Create an S3 user.
`PUT`	`/api/v1/s3-users/{accessKey}`	Update an S3 user role.
`POST`	`/api/v1/s3-users/{accessKey}/secret`	Rotate an S3 secret key.
`DELETE`	`/api/v1/s3-users/{accessKey}`	Delete an S3 user.

Cache settings expose eviction_policy, lru_high_watermark_percent, and lru_low_watermark_percent under cache. Valid policies are lru, after_upload, and none. Watermarks must satisfy 0 <= low < high <= 100 and only affect lru.

After saving settings, restart SynapS3, check /healthz, and read settings again to confirm the effective values.

Write Example

curl -X POST http://127.0.0.1:9090/api/v1/s3-users \
  -u admin \
  -H 'Content-Type: application/json' \
  -d '{"role":"user"}'

Enter the Admin password at curl's no-echo prompt. The response contains an access key, secret key, and role. The secret is shown only once; save it in a credential file protected with 0600 and rotate it immediately if exposed.

FilesExpand file tree

admin-api.md

Latest commit

History