Admin API

Overview

The Admin API provides administrative operations for system administrators.

Warning

Admin endpoints require elevated privileges. These operations are restricted to users with the SADM (system admin) role.

Endpoints

List Tenants

GET /api/admin/tenants

List all tenants (identities) managed by this server.

Authentication: Required (admin role)

Query Parameters:

  • limit - Maximum results (default: 20)
  • offset - Skip N results for pagination

Response:

{
  "data": [
    {
      "tnId": 12345,
      "idTag": "alice.cloudillo.net",
      "name": "Alice",
      "type": "person",
      "profilePic": "b1~abc123",
      "createdAt": "2025-01-01T00:00:00Z"
    },
    {
      "tnId": 12346,
      "idTag": "bob.cloudillo.net",
      "name": "Bob",
      "type": "person",
      "createdAt": "2025-01-02T00:00:00Z"
    }
  ],
  "time": "2025-01-15T10:30:00Z"
}

Example:

curl -H "Authorization: Bearer $ADMIN_TOKEN" \
  "https://cl-o.admin.cloudillo.net/api/admin/tenants?limit=50"

Send Password Reset

POST /api/admin/tenants/{id_tag}/password-reset

Send a password reset email to a tenant.

Authentication: Required (admin role)

Path Parameters:

  • id_tag - Identity tag of the tenant

Response:

{
  "data": {
    "sent": true
  },
  "time": "2025-01-15T10:30:00Z"
}

Example:

curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
  "https://cl-o.admin.cloudillo.net/api/admin/tenants/alice.cloudillo.net/password-reset"

Send Test Email

POST /api/admin/email/test

Send a test email to verify SMTP configuration.

Authentication: Required (admin role)

Request Body:

{
  "to": "admin@example.com"
}

Response:

{
  "data": {
    "sent": true
  },
  "time": "2025-01-15T10:30:00Z"
}

Example:

curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to":"admin@example.com"}' \
  "https://cl-o.admin.cloudillo.net/api/admin/email/test"

Update Profile (Admin)

PATCH /api/admin/profiles/{id_tag}

Admin update of a profile (roles, status, ban metadata).

Authentication: Required (admin role)

Path Parameters:

  • id_tag - Identity tag of the profile to update

Request Body:

{
  "name": "Updated Name",
  "status": "Suspended",
  "roles": ["user", "moderator"],
  "banExpiresAt": "2025-02-01T00:00:00Z",
  "banReason": "Terms of service violation"
}

Profile Status Values:

Status Description
Active Normal active account
Trusted Verified/trusted account
Blocked Blocked from interactions
Muted Content hidden from feeds
Suspended Account suspended (temporary)
Banned Account banned (permanent)

Response:

{
  "data": {
    "idTag": "user.cloudillo.net",
    "name": "Updated Name",
    "status": "Suspended",
    "roles": ["user", "moderator"]
  },
  "time": "2025-01-15T10:30:00Z"
}

Proxy Site Management

Manage reverse proxy sites for hosting custom domains.

List Proxy Sites

GET /api/admin/proxy-sites

List all configured proxy sites.

Authentication: Required (admin role)

Response:

{
  "data": [
    {
      "siteId": 1,
      "domain": "docs.example.com",
      "backendUrl": "http://localhost:8080",
      "status": "A",
      "type": "basic",
      "certExpiresAt": "2025-06-01T00:00:00Z",
      "config": {},
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    }
  ],
  "time": "2025-01-15T10:30:00Z"
}

Create Proxy Site

POST /api/admin/proxy-sites

Create a new proxy site configuration.

Authentication: Required (admin role)

Request Body:

{
  "domain": "docs.example.com",
  "backendUrl": "http://localhost:8080",
  "type": "basic",
  "config": {}
}
Field Type Required Description
domain string Yes Domain name for the proxy site
backendUrl string Yes Backend URL to proxy requests to
type string No Proxy type: basic (default) or advanced
config object No Additional proxy configuration

Response (201 Created): Returns the created ProxySite object.

Get Proxy Site

GET /api/admin/proxy-sites/{site_id}

Get details of a specific proxy site.

Authentication: Required (admin role)

Path Parameters:

  • site_id - The proxy site ID

Update Proxy Site

PATCH /api/admin/proxy-sites/{site_id}

Update a proxy site configuration.

Authentication: Required (admin role)

Path Parameters:

  • site_id - The proxy site ID

Request Body:

{
  "backendUrl": "http://localhost:9090",
  "status": "A",
  "config": {}
}
Field Type Description
backendUrl string Updated backend URL
status string A (active) or D (disabled)
type string Proxy type
config object Updated configuration

Delete Proxy Site

DELETE /api/admin/proxy-sites/{site_id}

Delete a proxy site configuration.

Authentication: Required (admin role)

Path Parameters:

  • site_id - The proxy site ID

Response: 204 No Content

Renew Proxy Site Certificate

POST /api/admin/proxy-sites/{site_id}/renew-cert

Trigger TLS certificate renewal for a proxy site.

Authentication: Required (admin role)

Path Parameters:

  • site_id - The proxy site ID

Community Invite

Invite Community

POST /api/admin/invite-community

Send an invitation to a community to join the server.

Authentication: Required (admin role)

Request Body:

{
  "targetIdTag": "community.example.com",
  "expiresInDays": 30,
  "message": "Join our platform!"
}
Field Type Required Description
targetIdTag string Yes Identity tag of the community to invite
expiresInDays number No Invitation expiry in days (default: 30)
message string No Optional invitation message

Response:

{
  "data": {
    "refId": "ref_abc123",
    "inviteUrl": "https://example.com/invite/ref_abc123",
    "targetIdTag": "community.example.com",
    "expiresAt": 1740000000
  },
  "time": "2025-01-15T10:30:00Z"
}

Client SDK Usage

import { createApiClient } from '@cloudillo/core'

const api = createApiClient({ idTag: 'admin.cloudillo.net', authToken: adminToken })

// List all tenants
const tenants = await api.admin.listTenants({ limit: 100 })

// Search tenants
const results = await api.admin.listTenants({ q: 'alice' })

// Send password reset
await api.admin.sendPasswordReset('alice.cloudillo.net')

// Send test email
await api.admin.sendTestEmail('admin@example.com')

// Suspend a user
await api.profiles.adminUpdate('baduser.cloudillo.net', {
  status: 'S',
  ban_reason: 'Spam'
})

Security Considerations

  • Admin endpoints require admin role authentication
  • All admin actions are logged for audit purposes
  • Password reset emails are rate-limited
  • Suspension requires a reason for accountability

See Also