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

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