---
title: Administration Reference
path: reference/admin
status: published
---

# Administration Reference

Platform-admin-only endpoints for managing tenants, nameserver configuration, and cross-tenant state. For the audit log, see [Audit Log](./audit-log.md). For user and role management (tenant admin), see [Users, Groups, and Roles](./users-and-access.md).

**Base path:** `/api/v1/admin/`
**Required permission:** Platform admin unless otherwise stated.

## Platform configuration

### GET /admin/config

List all platform configuration settings.

**Response:**

```json
{
  "configs": [
    {
      "key": "validation.challenge_ttl",
      "value": "3600",
      "description": "TTL for TXT validation challenges",
      "updated_at": "...",
      "updated_by": "u_admin"
    }
  ]
}
```

### GET /admin/config/{key}

Get a specific config value.

### PATCH /admin/config/{key}

Update a config value.

**Request:** `{"value": "7200"}`

Changes take effect immediately for most settings; some require restart.

## Nameservers

ScaiDNS's authoritative nameservers are embedded in every zone's NS records and SOA. Changing them updates all zones.

### GET /admin/nameservers

Get the current nameserver list.

**Response:**

```json
{
  "nameservers": [
    "ns1.scaidns.scailabs.ai.",
    "ns2.scaidns.scailabs.ai."
  ]
}
```

### PUT /admin/nameservers

Update the nameserver list.

**Request:**

```json
{
  "nameservers": [
    "ns1.scaidns.scailabs.ai.",
    "ns2.scaidns.scailabs.ai.",
    "ns3.scaidns.scailabs.ai."
  ]
}
```

Writes the change to platform config and updates NS records across all zones. Impacts every zone globally — coordinate carefully.

## Authoritative domains

The list of domains for which this ScaiDNS instance is authoritative (used for zone transfer validation).

### GET /admin/authoritative-domains

### PUT /admin/authoritative-domains

**Request:** `{"domains": ["example.com", "example.net"]}`

## Partners

### GET /admin/partners

List ScaiKey partners (for multi-tenant platforms).

**Response:**

```json
{
  "data": [
    {
      "id": "p_abc",
      "scaikey_partner_id": "prt_...",
      "name": "ScaiLabs",
      "status": "active",
      "created_at": "..."
    }
  ],
  "total": 1
}
```

### GET /admin/partners/{partner_id}

Get a single partner.

## Tenants

### GET /admin/tenants

List all tenants across the platform.

**Query parameters:** `page`, `page_size`, `status`, `search`.

### GET /admin/tenants/{tenant_id}

Get a single tenant.

**Response:**

```json
{
  "id": "t_xyz",
  "scaikey_tenant_id": "tnt_...",
  "name": "BBinfra NL",
  "slug": "bbinfra-nl",
  "status": "active",
  "partner_id": "p_abc",
  "settings": {},
  "created_at": "...",
  "updated_at": "..."
}
```

### POST /admin/tenants

Create a tenant (normally synced from ScaiKey automatically via webhooks).

**Request:**

| Field | Type | Required |
|-------|------|---------|
| `name` | string | Yes |
| `slug` | string | Yes |
| `scaikey_tenant_id` | string | Yes |
| `partner_id` | string | No |
| `settings` | object | No |

### PATCH /admin/tenants/{tenant_id}

Update tenant metadata.

### POST /admin/tenants/{tenant_id}/suspend

Suspend a tenant. All API calls from the tenant's users start returning `403`. Zone data is preserved.

### POST /admin/tenants/{tenant_id}/activate

Reactivate a suspended tenant.

## Platform statistics

### GET /admin/stats

Get global counts.

**Response:**

```json
{
  "tenant_count": 42,
  "domain_count": 1247,
  "record_count": 18429,
  "user_count": 389,
  "active_api_key_count": 128
}
```

Useful for monitoring dashboards. Also see [Health and Monitoring](../operations/health-and-monitoring.md).

## Zone sync status

### GET /admin/sync-status

Get the PowerDNS sync state — which zones are in sync vs pending changes vs failed.

**Response:**

```json
{
  "zones": [
    {
      "domain_id": "d_abc",
      "domain_name": "example.com",
      "pdns_status": "in_sync",
      "last_synced_at": "..."
    },
    {
      "domain_id": "d_xyz",
      "domain_name": "broken.example.net",
      "pdns_status": "failed",
      "last_synced_at": "...",
      "error_message": "PowerDNS rejected SOA record"
    }
  ],
  "in_sync_count": 1246,
  "failed_count": 1
}
```

## Error codes

| Status | Meaning |
|--------|---------|
| `403` | Caller is not a platform admin |
| `404` | Resource not found |
| `409` | Conflict (e.g., creating a tenant that already exists) |

## Related

- [Audit Log](./audit-log.md) — admin-visible audit trail.
- [Users, Groups, and Roles](./users-and-access.md) — tenant-level admin.
- [Deployment](../operations/deployment.md) — running ScaiDNS.