Chevereto V4 Docs

# Tenants API

The Tenants API allows you to manage tenants in a multi-tenant Chevereto installation.

# Authorization

The Tenants API requires a key which can be generated using the Tenants CLI tool.

# Request signing

All requests to the Tenants API must include an X-Signature header containing an HMAC SHA256 signature of the request body.

X-Signature: your_hmac_sha256_signature

Generate the signature by hashing the raw request body (as a string) with CHEVERETO_TENANTS_API_REQUEST_SECRET using HMAC SHA256. The output must be in hexadecimal format.

# /_/api/4/auth/verify

# POST /_/api/4/auth/verify

200 Verify API key and signature.

curl -X POST "/_/api/4/auth/verify" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-Signature: request_signature"

# /_/api/4/config/traefik

# GET /_/api/4/config/traefik

200 Retrieve dynamic Traefik HTTP provider configuration.

Provides dynamic configuration for Traefik's HTTP provider (opens new window), enabling tenant-aware routing without custom glue code. This endpoint is internal and only accessible from localhost.

Note: This endpoint doesn't require X-Signature header.

curl -X GET "/_/api/4/config/traefik" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key"

{
    "http": {
        "routers": {
            "*": {
                "rule": "Host(`localhost`)",
                "service": "php",
                "entryPoints": [
                    "websecure"
                ],
                "middlewares": [
                    "allow-range"
                ]
            },
            "1": {
                "rule": "Host(`test.chevereto.app`)",
                "service": "php",
                "entryPoints": [
                    "websecure"
                ],
                "middlewares": [
                    "allow-range"
                ]
            }
        },
        "services": {
            "php": {
                "loadBalancer": {
                    "servers": [
                        {
                            "url": "http://php:8080"
                        }
                    ],
                    "passHostHeader": true
                }
            }
        },
        "middlewares": {
            "allow-range": {
                "ipAllowList": {
                    "sourceRange": [
                        "192.168.65.0/24",
                        "172.16.0.0/12",
                        "173.245.48.0/20",
                        "103.21.244.0/22",
                        "103.22.200.0/22",
                        "103.31.4.0/22",
                        "141.101.64.0/18",
                        "108.162.192.0/18",
                        "190.93.240.0/20",
                        "188.114.96.0/20",
                        "197.234.240.0/22",
                        "198.41.128.0/17",
                        "162.158.0.0/15",
                        "104.16.0.0/13",
                        "104.24.0.0/14",
                        "172.64.0.0/13",
                        "131.0.72.0/22",
                        "2400:cb00::/32",
                        "2606:4700::/32",
                        "2803:f800::/32",
                        "2405:b500::/32",
                        "2405:8100::/32",
                        "2a06:98c0::/29",
                        "2c0f:f248::/32"
                    ]
                }
            }
        }
    }
}

# /_/api/4/tenants

# GET /_/api/4/tenants

200 List all tenants.

curl -X GET "/_/api/4/tenants" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-Signature: request_signature"

[
  {
    "id": "1",
    "hostname": "test.chevereto.app",
    "is_enabled": true,
    "created_at": "2026-08-17 23:15:57",
    "updated_at": "2026-08-20 13:18:42",
    "plan_id": "plan_id",
    "limits": {},
    "env": {},
    "stats": {
      "tags": 1,
      "files": 4,
      "pages": 3,
      "users": 2,
      "admins": 1,
      "albums": 0,
      "managers": 0,
      "storages": 1,
      "cron_time": 0,
      "categories": 0,
      "file_likes": 0,
      "file_views": 14,
      "album_likes": 0,
      "album_views": 0,
      "storage_used": 348897934,
      "login_providers": 0
    },
    "last_job_at": "2026-08-20 13:18:42"
  }
]

# POST /_/api/4/tenants

201 Create a new tenant.

  • Request body (JSON):

    • id (required): Unique identifier for the tenant.
    • hostname (required): Hostname associated with the tenant.
    • is_enabled (required): Tenant enabled status (boolean).
    • plan_id (optional): ID of the tenant plan to assign.
    • limits (optional): Resource limits specific to the tenant.
    • env (optional): Environment variables specific to the tenant.
curl -X POST "/_/api/4/tenants" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-Signature: request_signature" \
  -d '{
        "id": "tenant123",
        "hostname": "tenant123.example.com",
        "is_enabled": true,
        "plan_id": "basic_plan",
        "limits": {"CHEVERETO_MAX_USERS":"2"},
        "env": {"CUSTOM_VAR": "value"}
      }'

# /_/api/4/tenants/{id}

# GET /_/api/4/tenants/{id}

200 Retrieve tenant details.

curl -X GET "/_/api/4/tenants/tenant123" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-Signature: request_signature"

{
  "id": "{id}",
  "hostname": "test.chevereto.app",
  "is_enabled": true,
  "created_at": "2026-08-17 23:15:57",
  "updated_at": "2026-08-20 13:18:42",
  "plan_id": "plan_id",
  "limits": {},
  "env": {},
  "stats": {
    "tags": 1,
    "files": 4,
    "pages": 3,
    "users": 2,
    "admins": 1,
    "albums": 0,
    "managers": 0,
    "storages": 1,
    "cron_time": 0,
    "categories": 0,
    "file_likes": 0,
    "file_views": 14,
    "album_likes": 0,
    "album_views": 0,
    "storage_used": 348897934,
    "login_providers": 0
  },
  "last_job_at": "2026-08-20 13:18:42"
}

# PATCH /_/api/4/tenants/{id}

204 Edit tenant information.

  • Request body (JSON):

    • is_enabled (optional): New enabled status (boolean).
    • hostname (optional): New hostname for the tenant.
    • plan_id (optional): New tenant plan ID. Use empty string to remove plan.
    • limits (optional): New resource limits.
    • env (optional): New environment variables.
curl -X PATCH "/_/api/4/tenants/tenant123" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-Signature: request_signature" \
  -d '{
        "hostname": "new-tenant123.example.com",
        "plan_id": "premium_plan",
        "limits": {"CHEVERETO_MAX_USERS":"5"},
        "env": {"CUSTOM_VAR": "new_value"}
      }'

# DELETE /_/api/4/tenants/{id}

204 Delete a tenant.

  • Request body (JSON):

    • drop_tables (optional): Whether to drop tenant database tables [default: false] (boolean).
curl -X DELETE "/_/api/4/tenants/tenant123" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-Signature: request_signature" \
  -d '{
      "drop_tables": true
    }'

# /_/api/4/tenants/{id}/install

# POST /_/api/4/tenants/{id}/install

201 Install Chevereto for a tenant. 404 Tenant not found. 409 Tenant already installed.

curl -X POST "/_/api/4/tenants/tenant123/install" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-Signature: request_signature" \
  -d '{
        "username": "admin",
        "email": "admin@example.com",
        "password": "mypassword"
      }'

# /_/api/4/tenants/{id}/user-password-reset

# PATCH /_/api/4/tenants/{id}/user-password-reset

200 Reset a user's password for a tenant. Returns the new password. 404 Tenant or user not found.

  • Request body (JSON):

    • username (required): Username of the user to reset the password for.
    • password (optional): New password. If not provided, a random password will be generated.
curl -X PATCH "/_/api/4/tenants/tenant123/user-password-reset" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-Signature: request_signature" \
  -d '{
        "username": "rodolfo",
        "password": "mypassword"
      }'

# /_/api/4/tenants-plans

# GET /_/api/4/tenants-plans

200 List all tenant plans.

curl -X GET "/_/api/4/tenants-plans" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-Signature: request_signature"

[
  {
    "id": "1",
    "limits": {
      "CHEVERETO_MAX_TAGS": "500",
      "CHEVERETO_MAX_FILES": "10000",
      "CHEVERETO_MAX_PAGES": "3",
    },
    "env": null,
    "created_at": "2026-08-17 01:02:31",
    "updated_at": "2026-08-17 01:02:31"
  }
]

# POST /_/api/4/tenants-plans

201 Create a new tenant plan.

  • Request body (JSON):

    • id (required): Unique identifier for the tenant plan.
    • limits (optional): Resource limits specific to the tenant plan.
    • env (optional): Environment variables specific to the tenant plan.
curl -X POST "/_/api/4/tenants-plans" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-Signature: request_signature" \
  -d '{
        "id": "basic_plan",
        "limits": {"CHEVERETO_MAX_USERS":"2"}
      }'

# /_/api/4/tenants-plans/{id}

# GET /_/api/4/tenants-plans/{id}

200 Retrieve tenant plan details.

curl -X GET "/_/api/4/tenants-plans/basic_plan" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-Signature: request_signature"

{
    "id": "{id}",
    "limits": {
      "CHEVERETO_MAX_TAGS": "500",
      "CHEVERETO_MAX_FILES": "10000",
      "CHEVERETO_MAX_PAGES": "3",
    },
    "env": null,
    "created_at": "2026-08-17 01:02:31",
    "updated_at": "2026-08-17 01:02:31"
  }

# PATCH /_/api/4/tenants-plans/{id}

204 Edit tenant plan information.

  • Request body (JSON):

    • limits (optional): New resource limits.
    • env (optional): New environment variables.
curl -X PATCH "/_/api/4/tenants-plans/basic_plan" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-Signature: request_signature" \
  -d '{
        "limits": {"CHEVERETO_MAX_USERS":"3"}
      }'

# DELETE /_/api/4/tenants-plans/{id}

204 Delete a tenant plan.

curl -X DELETE "/_/api/4/tenants-plans/basic_plan" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-Signature: request_signature"

← Authorization →