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 implementation is currently limited to Cloudflare network, meaning DNS for the server must be managed through Cloudflare. If you need support for a different network setup, open an issue to request it.

curl -X GET "/_/api/4/config/traefik"

# /_/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"

# 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"

# 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"

# 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"

# 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 →