API Configuration

Overview

Poweradmin includes a RESTful API that allows external applications to interact with DNS records and zones programmatically. The API supports both API key authentication and HTTP Basic Authentication.

Configuration Options

API settings can be configured in the config/settings.php file under the api section.

Setting	Default	Description
enabled	false	Enable API functionality (including API keys)
basic_auth_enabled	false	Enable HTTP Basic Authentication for public API endpoints
basic_auth_realm	Poweradmin API	Realm name for HTTP Basic Authentication
docs_enabled	false	Enable API documentation at /api/docs endpoint
max_keys_per_user	5	Maximum API keys per user (admin users unlimited)

Configuration Example

return [
    'api' => [
        'enabled' => true,
        'basic_auth_enabled' => true,
        'basic_auth_realm' => 'DNS Management API',
        'docs_enabled' => true,
        'max_keys_per_user' => 5,  // Admin users have no limit
    ],
];

Web Server Requirements

The API requires proper web server configuration to function correctly. The PHP router handles API path parsing from REQUEST_URI, so explicit per-endpoint rewrite rules are not needed - just route all /api/* requests to index.php.

Key Requirements

Requirement	Description
CORS Headers	Required for cross-origin API requests from browsers
Authorization Header	Must be forwarded to PHP for API key authentication
Clean URL Routing	Route non-file requests to index.php

Configuration Examples

Use the web server configuration examples from the Poweradmin repository:

Apache:

• The included .htaccess file handles everything automatically
• Ensure AllowOverride All and mod_rewrite are enabled
• Version links: 4.0.x .htaccess | 4.1.x+ .htaccess

Nginx:

• nginx.conf.example (4.0.x)
• nginx.conf.example (4.1.x+) - includes subfolder deployment support

Caddy:

• Caddyfile.example (4.0.x)
• caddy.conf.example (4.1.x+) - includes subfolder deployment support

Minimal Nginx Example

If you need a minimal configuration, ensure these key elements are present:

# CORS and API routing
location ~ ^/api {
    add_header Access-Control-Allow-Origin "*" always;
    add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
    add_header Access-Control-Allow-Headers "Content-Type, Authorization, X-API-Key" always;

    if ($request_method = 'OPTIONS') {
        return 204;
    }

    try_files $uri $uri/ /index.php$is_args$args;
}

# PHP handling - ensure Authorization header is forwarded
location ~ \.php$ {
    fastcgi_pass unix:/var/run/php/php-fpm.sock;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param HTTP_AUTHORIZATION $http_authorization;
    include fastcgi_params;
}

Authentication Methods

API Key Authentication

API keys provide secure, token-based authentication:

1. Generate API keys - Create keys for each application
2. Permissions - A key inherits its owner's permissions, and since v4.5.0 can be narrowed further by marking it read-only, ticking the operations it may perform (view, create, update, delete), or restricting it to selected zones
3. Revocation - Easily revoke compromised keys

See API Authentication for how each restriction is enforced.

Using API Keys

curl -H "X-API-Key: your-api-key-here" \
     -H "Content-Type: application/json" \
     https://your-domain.com/api/v2/zones

HTTP Basic Authentication

Traditional username/password authentication:

curl -u username:password \
     -H "Content-Type: application/json" \
     https://your-domain.com/api/v2/zones

API Endpoints

Poweradmin also exposes two health endpoints, /api/health and /ping, that take no credentials and are disabled by default. They sit outside the versioned API and the API key model, and answer regardless of api.enabled. See Health Checks.

API v2 (introduced in v4.1.0) is the current API and is recommended for every integration. API v1 was deprecated in 4.3.0 and removed in 4.5.0; on 4.2.x-4.4.x it is still available for backward compatibility.

API v2 Endpoints (v4.1.0+)

Zone Management

• GET /api/v2/zones - List all zones
• GET /api/v2/zones/{id} - Get zone details
• POST /api/v2/zones - Create new zone
• PUT /api/v2/zones/{id} - Update zone
• DELETE /api/v2/zones/{id} - Delete zone

Zone Owners (v4.2.0+)

• GET /api/v2/zones/{id}/owners - List zone owners
• POST /api/v2/zones/{id}/owners - Add zone owner (supports batch assignment via user_ids array)
• DELETE /api/v2/zones/{id}/owners/{user_id} - Remove zone owner

Record Management

• GET /api/v2/zones/{id}/records - List zone records
• POST /api/v2/zones/{id}/records - Create record
• PUT /api/v2/zones/{id}/records/{record_id} - Update record
• DELETE /api/v2/zones/{id}/records/{record_id} - Delete record
• POST /api/v2/zones/{id}/records/bulk - Bulk create records

When a POST request to any of the create endpoints omits the ttl field, the server applies the configured default, in this order: a per-type default from the record_type_defaults table (managed in the UI) for the submitted record type, then dns.ttl_reverse for PTR records in reverse zones (when set), then dns.ttl. A per-type default therefore wins over dns.ttl_reverse, including for PTR. See DNS settings for details. (4.5.0)

RRset Management

• GET /api/v2/zones/{id}/rrsets - List all RRsets in a zone
• GET /api/v2/zones/{id}/rrsets/{name}/{type} - Get specific RRset

User Management

• GET /api/v2/users - List users
• GET /api/v2/users/{id} - Get user details
• POST /api/v2/users - Create user
• PUT /api/v2/users/{id} - Update user
• DELETE /api/v2/users/{id} - Delete user

Permission Management

• GET /api/v2/permissions - List available permissions
• GET /api/v2/permissions/{id} - Get permission details

Permission Templates

• GET /api/v2/permission-templates - List permission templates
• GET /api/v2/permission-templates/{id} - Get permission template details
• POST /api/v2/permission-templates - Create permission template
• PUT /api/v2/permission-templates/{id} - Update permission template
• DELETE /api/v2/permission-templates/{id} - Delete permission template

Zone Templates (v4.2.0+)

• GET /api/v2/zone-templates - List zone templates
• GET /api/v2/zone-templates/{id} - Get zone template details
• POST /api/v2/zone-templates - Create zone template
• PUT /api/v2/zone-templates/{id} - Update zone template
• DELETE /api/v2/zone-templates/{id} - Delete zone template
• GET /api/v2/zone-templates/{id}/records - List template records
• POST /api/v2/zone-templates/{id}/records - Add template record
• PUT /api/v2/zone-templates/{template_id}/records/{id} - Update template record
• DELETE /api/v2/zone-templates/{template_id}/records/{id} - Delete template record

Group Management (v4.2.0+)

• GET /api/v2/groups - List groups
• GET /api/v2/groups/{id} - Get group details
• POST /api/v2/groups - Create group
• PUT /api/v2/groups/{id} - Update group
• DELETE /api/v2/groups/{id} - Delete group
• GET /api/v2/groups/{id}/members - List group members
• POST /api/v2/groups/{id}/members - Add member to group
• DELETE /api/v2/groups/{id}/members/{user_id} - Remove member from group
• GET /api/v2/groups/{id}/zones - List group zones
• POST /api/v2/groups/{id}/zones - Assign zone to group
• DELETE /api/v2/groups/{id}/zones/{zone_id} - Remove zone from group

API v1 Endpoints (Legacy, removed in 4.5.0)

API v1 is available on 4.2.x-4.4.x for backward compatibility. It was deprecated in 4.3.0 and removed in 4.5.0, where every /api/v1 path answers 410 Gone with a pointer to /api/v2. Migrate to v2 before upgrading.

• GET/POST /api/v1/zones - List / create zones
• GET/PUT/DELETE /api/v1/zones/{id} - Get / update / delete zone
• GET/POST /api/v1/zones/{id}/records - List / create records
• PUT/DELETE /api/v1/zones/{id}/records/{record_id} - Update / delete record
• GET/POST /api/v1/users - List / create users
• GET/PUT/DELETE /api/v1/users/{id} - Get / update / delete user
• GET/POST /api/v1/permission-templates - List / create templates
• GET/PUT/DELETE /api/v1/permission-templates/{id} - Get / update / delete template
• GET /api/v1/permissions - List permissions
• GET /api/v1/permissions/{id} - Get permission details

API Documentation

When docs_enabled is true, interactive API documentation is available at /api/docs. This provides:

• Interactive testing - Test API endpoints directly
• Request/response examples - See data formats
• Authentication guide - Learn how to authenticate
• Error codes - Understand error responses

Security Considerations

Production Setup

'api' => [
    'enabled' => true,
    'basic_auth_enabled' => false, // Use API keys only
    'docs_enabled' => false,       // Disable docs in production
],

Tip: To enable audit logging for API operations, use the audit logging settings (logging.database_enabled and logging.syslog_enabled) instead.

Security Best Practices

1. Use HTTPS only - Never expose API over HTTP
2. API key rotation - Regularly rotate API keys
3. Access control - Restrict API access by IP if possible
4. Audit logging - Log all API requests and responses

Request/Response Format

Request Format

{
    "name": "example.com",
    "type": "A",
    "content": "192.168.1.100",
    "ttl": 3600
}

Response Format

{
    "success": true,
    "data": {
        "record": {
            "id": 123,
            "zone_id": 42,
            "name": "www",
            "type": "A",
            "content": "192.168.1.100",
            "ttl": 3600,
            "priority": null,
            "disabled": false,
            "auth": true,
            "ptr_created": false
        }
    },
    "message": "Record created successfully"
}

Record responses nest under data.record, and list responses under the plural collection name (data.records, data.zones, data.users). Records carry no created_at or updated_at; those fields exist only on zones and groups.

Error Response

{
    "success": false,
    "data": null,
    "message": "Invalid record type"
}

The message is a plain string at the top level. There is no nested error object and no machine-readable error code, so branch on the HTTP status rather than on a code in the body.

Troubleshooting

Common Issues

1. 401 Unauthorized: Invalid API key or credentials
2. 403 Forbidden: Insufficient permissions
3. 500 Internal Server Error: Server configuration issue

Debugging

Enable diagnostic logging for troubleshooting:

'logging' => [
    'type' => 'native',
    'level' => 'debug',
],

This writes diagnostic messages to PHP's error_log. For audit logging of API operations, enable logging.database_enabled and/or logging.syslog_enabled - see Logging Configuration.

PowerDNS Metrics API (v4.0.3+)

Poweradmin can integrate with PowerDNS metrics endpoints for monitoring and status information.

Configuration

Everything lives in the pdns_api section. There is no separate pdns section and no metrics.enabled toggle - the status page is shown by interface.show_pdns_status.

'pdns_api' => [
    'url' => 'http://localhost:8081',
    'key' => 'your-powerdns-api-key',
    'server_name' => 'localhost',
    'timeout' => 10,
    'webserver_username' => '',
    'webserver_password' => '',
],

Basic Authentication for Metrics (v4.0.3+)

Starting with v4.0.3, Poweradmin supports Basic Authentication for accessing PowerDNS metrics endpoints (issue #800). This is useful when your PowerDNS webserver is protected with Basic Auth in addition to API keys. Set the credentials with webserver_username (usually #) and webserver_password:

'pdns_api' => [
    'webserver_username' => '#',
    'webserver_password' => 'secure_password',
],

Pagination (v4.0.1+)

Optional Pagination Parameters

Starting with v4.0.1, pagination is optional for zones and users endpoints (issue #803). You can now request all records without pagination limits.

Without pagination (returns all results):

GET /api/v2/zones
GET /api/v2/users

With pagination:

GET /api/v2/zones?page=1&per_page=50
GET /api/v2/users?page=2&per_page=25

Warning: The parameter is per_page, not limit. Unrecognised query parameters are ignored rather than rejected, so ?limit=50 silently returns every row.

page is only read when per_page is given, and per_page is capped at 10000.

Pagination Response

{
    "success": true,
    "data": {
        "zones": [...]
    },
    "pagination": {
        "current_page": 1,
        "per_page": 50,
        "total": 150,
        "last_page": 3
    }
}

Version History

v4.5.0

• Removed: API v1; its paths answer 410 Gone
• Added: Granular API keys - read-only, allowed operations, and per-zone scoping
• Added: Zone DNSSEC endpoints (API v2)
• Added: Dynamic DNS endpoint (POST /api/v2/dynamic-dns)
• Added: Per-request API logging via logging.api_request_logging

v4.3.0

• Added: Zone metadata endpoints (API v2)
• Added: Separate log_api table for API log entries

v4.2.0

• Added: Zone template CRUD endpoints (API v2)
• Added: Zone owners endpoints with batch assignment (API v2)
• Added: Group management endpoints - members and zones (API v2)

v4.1.0

• Added: API v2 with consistent response wrapping
• Added: Permission validation for API endpoints
• Added: RRset endpoints (API v2)
• Added: Bulk record creation endpoint (API v2)

v4.0.4

• Fixed: Basic Auth TypeError when LDAP authentication is enabled (issue #799)
  • Resolves compatibility issues between Basic Auth and LDAP
  • Properly handles authentication context

v4.0.3

• Added: Basic Auth support for PowerDNS metrics endpoint (issue #800)
  • Enables authentication for metrics API calls
  • Supports username/password in addition to API keys

v4.0.2

• Fixed: Routing and method validation issues (issue #767)
• Fixed: Graceful handling of missing optional fields (issue #818)

v4.0.1

• Added: Optional pagination for zones and users endpoints (issue #803)
  • Can now request all records without pagination
  • Backward compatible with paginated requests
• Fixed: SOA serial updates on all record operations (issue #804)
  • Ensures zone serial increments properly
  • Maintains DNS propagation consistency

v4.0.0

• Initial API implementation
• API key management system
• RESTful endpoints for zones, records, users
• Permission template management
• Interactive API documentation
• Request logging and audit trails

Related Documentation

• Security Policies - API authentication and authorization
• PowerDNS API - PowerDNS API configuration
• Logging Configuration - API request logging setup