Server Administration API

Server configuration, monitoring, and system management endpoints for server administrators.

Authentication: All endpoints require admin authentication via JWT token obtained from the authentication endpoint.

Scope: System-wide configuration and monitoring.

Authenticate as a server administrator to obtain an admin JWT token.

Endpoint

POST /admin/v1/auth

Authentication Flow

Step 1: Request Challenge

GET /admin/v1/auth/challenge HTTP/1.1

Response

{
  "challenge": "a1b2c3d4e5f61728394a5b6c7d8e9f101234567890abcdef",
  "expires_at": 1759000300
}

Step 2: Sign Challenge and Authenticate

POST /admin/v1/auth HTTP/1.1
Content-Type: application/json

{
  "device_address": "a1b2c3d4e5f61728394a5b6c7d8e9f10@server.com",
  "challenge": "a1b2c3d4e5f61728394a5b6c7d8e9f101234567890abcdef",
  "challenge_signature": "ed25519_signature_of_challenge",
  "timestamp": 1759000000
}

Parameters:

device_address: Administrator’s device address (must be in server admin list)
challenge: Challenge from Step 1
challenge_signature: Ed25519 signature of challenge using device private key
timestamp: Current Unix timestamp (prevents replay attacks)

Response (200 OK)

{
  "admin_token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
  "expires_at": 1759003600,
  "permissions": [
    "view_metrics",
    "manage_config",
    "view_audit",
    "verify_devices",
    "block_federation",
    "modify_rate_limits"
  ],
  "admin_level": "admin"
}

Response Fields:

admin_token: JWT token for admin API access (use in Authorization: Bearer header)
expires_at: Token expiration timestamp (typically 1 hour)
permissions: List of granted admin permissions
admin_level: Admin role (admin, moderator, viewer)

Error Responses

401 Unauthorized

{
  "error": "INVALID_ADMIN",
  "message": "Device is not configured as admin",
  "code": 4009
}

403 Forbidden

{
  "error": "INVALID_SIGNATURE",
  "message": "Challenge signature verification failed",
  "code": 4001
}

410 Gone

{
  "error": "CHALLENGE_EXPIRED",
  "message": "Challenge has expired. Request a new one.",
  "code": 4010
}

Refresh Admin Token

Extend admin session without re-authentication.

Endpoint

POST /admin/v1/auth/refresh

Request

POST /admin/v1/auth/refresh HTTP/1.1
Authorization: Bearer {admin_token}

Response (200 OK)

{
  "admin_token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
  "expires_at": 1759007200
}

Admin Logout

Invalidate admin token (optional, tokens expire automatically).

Endpoint

POST /admin/v1/auth/logout

Request

POST /admin/v1/auth/logout HTTP/1.1
Authorization: Bearer {admin_token}

Response (200 OK)

{
  "message": "Admin token invalidated"
}

Get Server Configuration

Retrieve current server configuration.

Endpoint

GET /admin/v1/config

Request

GET /admin/v1/config HTTP/1.1
Authorization: Bearer {admin_token}

Response (200 OK)

{
    "server": {
        "server_name": "chat.example.com",
        "protocol_version": "1.0",
        "max_message_size": 10485760,
        "max_retention_days": 30
    },
    "registration": {
        "enabled": true,
        "require_proof_of_work": true,
        "proof_of_work_difficulty": 20,
        "allow_time_delay": true,
        "time_delay_seconds": 300,
        "accept_invites": true
    },
    "progressive_trust": {
        "enabled": true,
        "new_tier_duration_hours": 6,
        "established_tier_duration_hours": 24,
        "new_tier_limit": 10,
        "established_tier_limit": 60,
        "trusted_tier_limit": 300,
        "spam_report_block_threshold": 5
    },
    "federation": {
        "enabled": true,
        "allowlist_mode": false,
        "auto_block_threshold": 0.2,
        "publish_blocklist": true,
        "certificate_validation": true
    },
    "rate_limiting": {
        "enabled": true,
        "window_seconds": 3600,
        "burst_allowance": 10
    },
    "storage": {
        "message_queue_limit": 1000,
        "announcement_retention_hours": 24,
        "metadata_retention_days": 30
    }
}

Update Server Configuration

Modify server configuration (partial updates supported).

Endpoint

PATCH /admin/v1/config

Request

PATCH /admin/v1/config HTTP/1.1
Content-Type: application/json
Authorization: Bearer {admin_token}

{
    "progressive_trust": {
        "new_tier_limit": 15,
        "spam_report_block_threshold": 3
    },
    "registration": {
        "proof_of_work_difficulty": 22
    },
    "server": {
        "max_message_size": 20971520
    }
}

Note: Only include fields you want to change. Omitted fields remain unchanged.

Response (200 OK)

{
    "config_updated_at": 1759000000,
    "updated_by": "a1b2c3d4e5f61728394a5b6c7d8e9f10@server.com",
    "updated_fields": [
        "progressive_trust.new_tier_limit",
        "progressive_trust.spam_report_block_threshold",
        "registration.proof_of_work_difficulty",
        "server.max_message_size"
    ],
    "requires_restart": false
}

Response Fields:

config_updated_at: Timestamp of update
updated_by: Device address of the admin who made the change
updated_fields: List of changed configuration keys
requires_restart: Whether a server restart is needed (typically false)

Error Responses

400 Bad Request

{
    "error": "INVALID_CONFIG",
    "message": "Invalid configuration value: progressive_trust.new_tier_limit must be between 1 and 1000",
    "code": 4012
}

403 Forbidden

{
    "error": "INSUFFICIENT_PERMISSIONS",
    "message": "Admin does not have 'manage_config' permission",
    "code": 4011
}

Get Server Statistics

Retrieve aggregate server metrics and statistics.

Endpoint

GET /admin/v1/metrics

Request

GET /admin/v1/metrics?period=24h HTTP/1.1
Authorization: Bearer {admin_token}

Query Parameters:

period: Time period for metrics (1h, 24h, 7d, 30d). Defaults to 24h.

Response (200 OK)

{
    "period": "24h",
    "timestamp": 1759000000,
    "server": {
        "uptime_seconds": 2592000,
        "version": "1.0.0",
        "cpu_usage_percent": 35.2,
        "memory_usage_mb": 2048,
        "storage_used_gb": 125.5
    },
    "devices": {
        "total": 1500,
        "active_last_24h": 850,
        "new_last_24h": 25,
        "verified": 120,
        "blocked": 15,
        "by_trust_tier": {
            "new": 45,
            "established": 320,
            "trusted": 1115,
            "verified": 120
        }
    },
    "messages": {
        "sent_last_24h": 45000,
        "received_last_24h": 48000,
        "queued": 120,
        "expired_last_24h": 5,
        "average_size_bytes": 8192
    },
    "spam": {
        "reports_last_24h": 12,
        "auto_blocked_devices_last_24h": 3,
        "rate_limited_requests_last_24h": 450
    },
    "federation": {
        "active_peers": 25,
        "blocked_peers": 2,
        "messages_sent_last_24h": 15000,
        "messages_received_last_24h": 18000,
        "failed_deliveries_last_24h": 8
    },
    "performance": {
        "average_delivery_latency_ms": 45,
        "p95_delivery_latency_ms": 120,
        "p99_delivery_latency_ms": 250,
        "websocket_connections": 650
    }
}

Get Time-Series Metrics

Retrieve metrics over time for graphing and analysis.

Endpoint

GET /admin/v1/metrics/timeseries

Request

GET /admin/v1/metrics/timeseries?metric=messages_sent&period=7d&interval=1h HTTP/1.1
Authorization: Bearer {admin_token}

Query Parameters:

metric: Metric name (e.g., messages_sent, active_devices, spam_reports)
period: Time period (1h, 24h, 7d, 30d)
interval: Data point interval (5m, 1h, 1d)

Response (200 OK)

{
    "metric": "messages_sent",
    "period": "7d",
    "interval": "1h",
    "data_points": [
        {
            "timestamp": 1758400000,
            "value": 1850
        },
        {
            "timestamp": 1758403600,
            "value": 1920
        },
        {
            "timestamp": 1758407200,
            "value": 2100
        }
    ],
    "aggregate": {
        "min": 850,
        "max": 3200,
        "avg": 1875,
        "total": 314250
    }
}

Export Metrics

Export metrics in Prometheus format for monitoring intergration.

Endpoint

GET /admin/v1/metrics/export

Request

GET /admin/v1/metrics/export?format=prometheus HTTP/1.1
Authorization: Bearer {admin_token}

Query Parameters:

format: Export format (prometheus, json, csv). Defaults to prometheus.

Response (200 OK)

# HELP cryptid_devices_total Total number of registered devices
# TYPE cryptid_devices_total gauge
cryptid_devices_total 1500

# HELP cryptid_devices_active_24h Devices active in last 24 hours
# TYPE cryptid_devices_active_24h gauge
cryptid_devices_active_24h 850

# HELP cryptid_messages_sent_total Total messages sent
# TYPE cryptid_messages_sent_total counter
cryptid_messages_sent_total 45000

# HELP cryptid_spam_reports_24h Spam reports in last 24 hours
# TYPE cryptid_spam_reports_24h gauge
cryptid_spam_reports_24h 12

# HELP cryptid_federation_peers_active Active federation peers
# TYPE cryptid_federation_peers_active gauge
cryptid_federation_peers_active 25

Query Audit Log

Retrieve audit log of administative actions.

Endpoint

GET /admin/v1/audit

Request

GET /admin/v1/audit?since=1758000000&action=device_verified&limit=50 HTTP/1.1
Authorization: Bearer {admin_token}

Query Parameters:

since: Unix timestamp (default: 24 hours ago)
until: Unix timestamp (default: now)
action: Filter by action type (e.g., device_verified, config_updated)
admin: Filter by admin device address
target: Filter by target (device address, server domain, etc.)
limit: Max results (default: 100, max: 1000)
offset: Pagination offset

Response (200 OK)

{
    "entries": [
        {
            "id": "audit_550e8400e29b41d4a716446655440000",
            "timestamp": 1759000000,
            "action": "device_verified",
            "admin": "a1b2c3d4e5f61728394a5b6c7d8e9f10@server.com",
            "target": "f1e2d3c4b5a6978869504132e1f2d3c4@server.com",
            "details": {
                "reason": "Known community member",
                "previous_tier": "New",
                "new_tier": "Verified"
            },
            "ip_address": "192.168.1.100",
            "user_agent": "CryptidAdmin/1.0"
        },
        {
            "id": "audit_550e8400e29b41d4a716446655440001",
            "timestamp": 1758999000,
            "action": "federation_blocked",
            "admin": "a1b2c3d4e5f61728394a5b6c7d8e9f10@server.com",
            "target": "spam-factory.com",
            "details": {
                "reason": "Excessive spam reports",
                "expires_at": null,
                "auto_blocked": false
            },
            "ip_address": "192.168.1.100",
            "user_agent": "CryptidAdmin/1.0"
        },
        {
            "id": "audit_550e8400e29b41d4a716446655440002",
            "timestamp": 1758998000,
            "action": "config_updated",
            "admin": "a1b2c3d4e5f61728394a5b6c7d8e9f10@server.com",
            "target": "server_config",
            "details": {
                "updated_fields": [
                    "progressive_trust.new_tier_limit",
                    "progressive_trust.spam_report_block_threshold"
                ],
                "old_values": {
                    "progressive_trust.new_tier_limit": 10,
                    "progressive_trust.spam_report_block_threshold": 5
                },
                "new_values": {
                    "progressive_trust.new_tier_limit": 15,
                    "progressive_trust.spam_report_block_threshold": 3
                }
            },
            "ip_address": "192.168.1.100",
            "user_agent": "CryptidAdmin/1.0"
        }
    ],
    "total_count": 3,
    "has_more": false,
    "next_offset": null
}

Audit Action Types

device_verified: Admin verified a device
verification_revoked: Admin revoked verification
rate_limit_modified: Admin set a custom rate limit
federation_blocked: Admin blocked a server
federation_unblocked: Admin unblocked a server
config_updated: Server configuration changed
admin_login: Admin authenticated
admin_logout: Admin logged out

Export Audit Log

Export audit log for compliance or analysis.

Endpoint

GET /admin/v1/audit/export

Request

GET /admin/v1/audit/export?since=1758000000&format=csv HTTP/1.1
Authorization: Bearer {admin_token}

Query Parameters:

since: Start timestamp
until: End timestamp
format: csv or json
action: Filter by action type
admin: Filter by admin device address

Response (200 OK)

id,timestamp,action,admin,target,details,ip_address
audit_550e8400...,1759000000,device_verified,a1b2c3d4...@server.com,f1e2d3c4...@server.com,"Known community member",192.168.1.100
audit_550e8401...,1758999000,federation_blocked,a1b2c3d4...@server.com,spam-factory.com,"Excessive spam",192.168.1.100

Server Health Check

Check server operational status.

Endpoint

GET /admin/v1/health

Request

GET /admin/v1/health HTTP/1.1
Authorization: Bearer {admin_token}

Response (200 OK)

{
    "status": "healthy",
    "timestamp": 1759000000,
    "version": "1.0.0",
    "uptime_seconds": 2592000,
    "components": {
        "database": {
            "status": "healthy",
            "latency_ms": 5,
            "details": "Connected to PostgreSQL 15.2"
        },
        "message_queue": {
            "status": "healthy",
            "queue_size": 120,
            "details": "Redis 7.0.5"
        },
        "federation": {
            "status": "healthy",
            "active_connections": 25,
            "details": "All peers reachable"
        },
        "websocket": {
            "status": "healthy",
            "active_connections": 650,
            "details": "650 active WebSocket connections"
        }
    },
    "warnings": []
}

Status Values:

healthy: All systems operational
degraded: Operational with issues
unhealthy: Critical issues

Response (503 Service Unavailable)

{
    "status": "unhealthy",
    "timestamp": 1759000000,
    "version": "1.0.0",
    "uptime_seconds": 2592000,
    "components": {
        "database": {
            "status": "unhealthy",
            "latency_ms": null,
            "error": "Connection timeout",
            "details": "Unable to connect to database"
        },
        "message_queue": {
            "status": "healthy",
            "queue_size": 120,
            "details": "Redis 7.0.5"
        }
    },
    "warnings": [
        "Database connection failed",
        "Message delivery may be delayed"
    ]
}

Get System Alerts

Retrieve active system alerts and warnings.

Endpoint

GET /admin/v1/alerts

Request

GET /admin/v1/alerts HTTP/1.1
Authorization: Bearer {admin_token}

Response (200 OK)

{
    "active_alerts": [
        {
            "id": "alert_high_cpu",
            "severity": "warning",
            "component": "server",
            "message": "CPU usage above 80% for 5 minutes",
            "started_at": 1758999700,
            "details": {
                "cpu_usage": 85.3,
                "threshold": 80
            }
        },
        {
            "id": "alert_spam_spike",
            "severity": "info",
            "component": "moderation",
            "message": "Spam reports increased 200% in last hour",
            "started_at": 1759000000,
            "details": {
                "current_rate": 30,
                "average_rate": 10
            }
        }
    ],
    "total_count": 2
}

Severity Levels:

critical: Immediate action required
warning: Attention needed
info: Informational only

Important Notes

Admin Permissions

Different operations require different permissions:

Permission	Operations
`view_metrics`	View server metrics, statistics
`manage_config`	Update server configuration
`view_audit`	View audit logs
`verify_devices`	Manage device trust (see Moderation API)
`block_federation`	Manage federation blocklists (see Moderation API)
`modify_rate_limits`	Set custom rate limits (see Moderation API)
`all`	All permissions

Configuration Example

[server.admins]
# Full device address format: device_id_hex@server_domain
"a1b2c3d4e5f61728394a5b6c7d8e9f10@server.com" = ["all"]
"f1e2d3c4b5a6978869504132e1f2d3c4@server.com" = ["verify_devices", "block_federation", "view_metrics"]
"c4b5a6978869504132e1f2d3c4b5a697@server.com" = ["view_metrics", "view_audit"]

Rate Limiting

Admin endpoints have generous rate limits.

Metrics queries: 1000/hour
Configuration updates: 100/hour
Audit log queries: 1000/hour

Security Considerations

Audit Everything

All admin actions are logged with:

Timestamp
Admin device address who performed the action
Target of action
Action details
IP address and user agent

Token Security

Admin tokens expire after 1 hour
Use refresh endpoint to extend sessions
Tokens are invalidated on logout
No refresh tokens (re-authenticate after expiry)

Configuration Safety

Configuration changes are validated before applying
Invalid changes are rejected with detailed error messages
Critical changes may require server restart (flagged in response)
Previous configuration is preserved in audit log

Server Administration API

Admin Login

Endpoint

Authentication Flow

Step 1: Request Challenge

Response

Step 2: Sign Challenge and Authenticate

Refresh Admin Token

Endpoint

Request

Response (200 OK)

Admin Logout

Endpoint

Request

Response (200 OK)

Get Server Configuration

Endpoint

Request

Response (200 OK)

Update Server Configuration

Endpoint

Request

Response (200 OK)

Error Responses

400 Bad Request

403 Forbidden

Get Server Statistics

Endpoint

Request

Response (200 OK)

Get Time-Series Metrics

Endpoint

Request

Response (200 OK)

Export Metrics

Endpoint

Request

Response (200 OK)

Query Audit Log

Endpoint

Request

Response (200 OK)

Audit Action Types

Export Audit Log

Endpoint

Request

Response (200 OK)

Server Health Check

Endpoint

Request

Response (200 OK)

Response (503 Service Unavailable)

Get System Alerts

Endpoint

Request

Response (200 OK)

Important Notes

Admin Permissions

Configuration Example

Rate Limiting

Security Considerations

Audit Everything

Token Security

Configuration Safety