Admin API

The Admin API provides HTTP endpoints for managing users, credentials, and system information. All endpoints (except login) require a JWT token with SuperUser role.

Authentication

First, obtain a JWT token:

TOKEN=$(curl -s -k -X POST https://localhost:9000/api/admin/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"root","password":"password12345"}' | jq -r '.token')

Use the token in subsequent requests:

curl -s -k https://localhost:9000/api/admin/users \
  -H "Authorization: Bearer $TOKEN"

Endpoints

Login

POST /api/admin/login

No authentication required.

curl -s -k -X POST https://localhost:9000/api/admin/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"root","password":"password12345"}'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2026-02-11T10:00:00Z"
}

List Users

GET /api/admin/users

curl -s -k https://localhost:9000/api/admin/users \
  -H "Authorization: Bearer $TOKEN"

Response: Array of user objects (password hashes and secret keys are never returned).

Create User

POST /api/admin/users

curl -s -k -X POST https://localhost:9000/api/admin/users \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"username":"alice","password":"alice123","role":"Writer"}'

Request body:

Get User

GET /api/admin/users/{id}

curl -s -k https://localhost:9000/api/admin/users/<user-id> \
  -H "Authorization: Bearer $TOKEN"

Update User

PUT /api/admin/users/{id}

curl -s -k -X PUT https://localhost:9000/api/admin/users/<user-id> \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"role":"Reader"}'

Request body (all fields optional):

Delete User

DELETE /api/admin/users/{id}

curl -s -k -X DELETE https://localhost:9000/api/admin/users/<user-id> \
  -H "Authorization: Bearer $TOKEN"

Response: 204 No Content

Generate S3 Credentials

POST /api/admin/users/{id}/credentials

curl -s -k -X POST https://localhost:9000/api/admin/users/<user-id>/credentials \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "access_key": "S4AKxxxxxxxxxxxxxxxxxxxx",
  "secret_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Important: The secret_key is shown only once. Store it securely — it cannot be retrieved again.

Delete S3 Credentials

DELETE /api/admin/users/{id}/credentials

curl -s -k -X DELETE https://localhost:9000/api/admin/users/<user-id>/credentials \
  -H "Authorization: Bearer $TOKEN"

Response: 204 No Content

Create Bucket

PUT /api/admin/buckets/{name}

curl -s -k -X PUT https://localhost:9000/api/admin/buckets/my-bucket \
  -H "Authorization: Bearer $TOKEN"

Response:

{ "name": "my-bucket" }

Delete Bucket

DELETE /api/admin/buckets/{name}

Deletes a bucket. By default the bucket must be empty (returns 400 otherwise).

curl -s -k -X DELETE https://localhost:9000/api/admin/buckets/my-bucket \
  -H "Authorization: Bearer $TOKEN"

Force delete — recursively deletes all objects in the bucket first:

curl -s -k -X DELETE "https://localhost:9000/api/admin/buckets/my-bucket?force=true" \
  -H "Authorization: Bearer $TOKEN"

Response: 204 No Content

List Bucket Objects

GET /api/admin/buckets/{name}/objects

curl -s -k "https://localhost:9000/api/admin/buckets/my-bucket/objects?max-keys=100" \
  -H "Authorization: Bearer $TOKEN"

Query parameters:

Bucket Stats

GET /api/admin/bucket-stats

Returns storage statistics for all buckets.

curl -s -k https://localhost:9000/api/admin/bucket-stats \
  -H "Authorization: Bearer $TOKEN"

Error Responses