The Central server (artica-edgeguard-central) is the management plane of the EdgeGuard system. It hosts the PostgreSQL database, the REST API v2, the React dashboard, and manages all agent connections.
| Aspect |
Detail |
| Binary |
artica-edgeguard-central |
| Database |
PostgreSQL (multi-tenant, multi-org) |
| API |
REST API v2 — JWT with optional MFA for people, API keys for scripts |
| Dashboard |
React + TypeScript + Tailwind CSS (served as static files) |
| Agent Auth |
Mutual TLS (mTLS) + API key |
| Default Port |
:8082 (HTTPS) |
📷 Image: Central server architecture — to be added.
When the central binary starts, it launches the following services:
| Service |
Default Port |
Description |
| API v2 Server |
:8082 |
REST API + dashboard static files (TLS required) |
| Health Server |
:8080 |
/health and /ready endpoints |
| Metrics Server |
:9090 |
Prometheus-compatible /metrics endpoint |
| Feed Updater |
(background) |
Auto-fetches security rulesets and OWASP CRS mappings |
| Staleness Checker |
(background) |
Marks agents offline after 90s without heartbeat |
{
"mode": "central",
"health_addr": ":8080",
"metrics_addr": ":9090",
"central_db": {
"host": "localhost",
"port": 5432,
"database": "artica_edgeguard",
"username": "artica_edgeguard",
"password": "secret",
"ssl_mode": "require",
"max_conns": 10,
"min_conns": 2
},
"api_v2": {
"enabled": true,
"listen_addr": ":8082",
"jwt_secret": "long-random-string",
"token_expiry_hours": 24,
"refresh_expiry_hours": 168,
"cors_origins": ["https://dashboard.example.com"],
"tls_enabled": true,
"tls_cert_file": "/path/to/server.crt",
"tls_key_file": "/path/to/server.key",
"mtls_enabled": true,
"mtls_ca_cert_file": "/path/to/ca.crt",
"mtls_ca_key_file": "/path/to/ca.key"
}
}
📷 Image: Central config.json example — to be added.
¶ Bootstrap Commands
Before first use, the central server needs initial setup:
# Generate TLS certificates (CA + server cert)
artica-edgeguard-central --generate-cert /path/to/certs
# Create initial admin user
artica-edgeguard-central --bootstrap-admin \
--admin-email="admin@example.com" \
--admin-password="secure-password"
# Create organization
artica-edgeguard-central --bootstrap-org \
--org-name="MyOrg" \
--org-slug="myorg"
# Fix database ownership (after schema migration)
artica-edgeguard-central --fix-db
Three ways to authenticate, for three different callers.
POST /api/v2/auth/login with email and password returns an access token
(24 hours by default) and a refresh token (7 days). Send the access token as
Authorization: Bearer <token>. When the account has MFA enabled, the login
answers mfa_required and a short-lived MFA token instead; verify it at
/api/v2/auth/mfa/verify to get the real pair.
Keys are issued in the console under API Keys and sent either way — the
header is explicit, the bearer form is what most client libraries reach for
first:
curl -H "X-API-Key: eg_…" https://central.example.com:8082/api/v2/tenants
curl -H "Authorization: Bearer eg_…" https://central.example.com:8082/api/v2/tenants
A key is recognised by its eg_ prefix, looked up by SHA-256 hash, and
authenticates as the person who created it: same role, same organisation,
the same sites and groups that account can see. There is no separate permission
model — if a script should only read, issue its key from an account that can only
read.
Keys can expire (30 days, 90, a year, or never — chosen at creation), can be
revoked at any moment, and stop working if the account that owns them is deleted.
Every refusal answers the same 401, whatever the reason: telling a caller
whether a key is unknown, revoked or expired tells an attacker the same thing.
Anything a key does appears in the audit trail naming the key beside its owner:
ana@example.com (api key: CI/CD Pipeline).
API keys authenticate the management API from central 2.4.25. Before that
the middleware only understood JWTs, so every key ever issued was refused on
its first request.
¶ An agent: mTLS and an agent key
Agents authenticate with two layers, and they are not the same thing as an API
key — an agent key pulls configuration and ships events, and authorises nothing
on the management API:
- mTLS — a client certificate issued during enrolment (mandatory).
- Agent key — the
X-Agent-Key header, SHA-256 hashed on the server, never
stored in plaintext.
TOTP (Google Authenticator, Authy and the like), set up from the dashboard with a
QR code, with recovery codes issued once. An administrator can reset another
user's MFA; a platform administrator can reset anyone's.
| Status |
Meaning |
401 |
no credential, or one that is invalid, expired, revoked, or whose owner no longer exists |
403 — role |
the account's role is not allowed here (adminOnly, editorOnly, platform admin required) |
403 — quota |
the organisation is at its limit; the message names the limit, the current count and where to raise it |
403 — suspended |
the organisation is suspended. Applies to sessions and API keys too, not only to the login form (central 2.4.34) |
404 |
not found, or found in another organisation — the two are deliberately indistinguishable |
409 |
a name or slug already in use |
A platform administrator can read the console as one organisation or as all of
them: POST /api/v2/auth/switch-org with {"org_slug": "acme"} returns a new
token scoped to it, and an empty body returns one scoped to none — which means
all. An organisation that does not exist answers 404.
| Method |
Endpoint |
Description |
POST |
/api/v2/auth/login |
Login with email/password, returns JWT |
POST |
/api/v2/auth/refresh |
Refresh access token |
POST |
/api/v2/auth/logout |
Logout / invalidate session |
POST |
/api/v2/auth/mfa/setup |
Generate TOTP secret + QR code |
POST |
/api/v2/auth/mfa/confirm |
Confirm TOTP setup |
POST |
/api/v2/auth/mfa/verify |
Verify TOTP code on login |
DELETE |
/api/v2/auth/mfa |
Disable MFA |
PUT |
/api/v2/auth/password |
Change password |
POST |
/api/v2/auth/switch-org |
Switch organization context |
GET |
/api/v2/auth/me |
Get current user info |
| Method |
Endpoint |
Description |
GET |
/api/v2/hierarchy/global |
Get global security settings |
PUT |
/api/v2/hierarchy/global |
Update global settings |
GET |
/api/v2/hierarchy/groups |
List all groups |
POST |
/api/v2/hierarchy/groups |
Create a group |
GET |
/api/v2/hierarchy/groups/:id |
Get group details |
PUT |
/api/v2/hierarchy/groups/:id |
Update group |
DELETE |
/api/v2/hierarchy/groups/:id |
Delete group |
GET |
/api/v2/hierarchy/groups/:id/nodes |
List nodes in group |
GET |
/api/v2/hierarchy/groups/:id/effective-settings |
Get group effective settings |
| Method |
Endpoint |
Description |
GET |
/api/v2/tenants |
List all tenants |
POST |
/api/v2/tenants |
Create a tenant |
GET |
/api/v2/tenants/:id |
Get tenant details + effective settings |
PUT |
/api/v2/tenants/:id |
Update tenant |
DELETE |
/api/v2/tenants/:id |
Delete tenant |
GET |
/api/v2/tenants/:id/stats |
Tenant event statistics |
| Method |
Endpoint |
Description |
GET |
/api/v2/hierarchy/tenants/:id/path-rules |
List path rules for tenant |
POST |
/api/v2/hierarchy/tenants/:id/path-rules |
Create path rule |
GET |
/api/v2/hierarchy/tenants/:id/path-rules/:ruleId |
Get path rule |
PUT |
/api/v2/hierarchy/tenants/:id/path-rules/:ruleId |
Update path rule |
DELETE |
/api/v2/hierarchy/tenants/:id/path-rules/:ruleId |
Delete path rule |
| Method |
Endpoint |
Description |
GET |
/api/v2/rulesets |
List all rulesets |
POST |
/api/v2/rulesets |
Create a ruleset |
GET |
/api/v2/rulesets/:id |
Get ruleset with rules |
PUT |
/api/v2/rulesets/:id |
Update ruleset |
DELETE |
/api/v2/rulesets/:id |
Delete ruleset |
POST |
/api/v2/rulesets/validate-pattern |
Validate regex pattern |
GET |
/api/v2/tenants/:id/rulesets |
Get tenant ruleset assignments |
POST |
/api/v2/tenants/:id/rulesets/:rulesetId |
Assign ruleset to tenant |
DELETE |
/api/v2/tenants/:id/rulesets/:rulesetId |
Remove ruleset from tenant |
| Method |
Endpoint |
Description |
GET |
/api/v2/ip-lists |
List IP entries (block/allow) |
POST |
/api/v2/ip-lists |
Add IP entry |
PUT |
/api/v2/ip-lists/:id |
Update IP entry |
DELETE |
/api/v2/ip-lists/:id |
Delete IP entry |
| Method |
Endpoint |
Description |
GET |
/api/v2/response-templates |
List templates |
POST |
/api/v2/response-templates |
Create template |
GET |
/api/v2/response-templates/defaults |
Get built-in default templates |
GET |
/api/v2/response-templates/:id |
Get template |
PUT |
/api/v2/response-templates/:id |
Update template |
DELETE |
/api/v2/response-templates/:id |
Delete template |
| Method |
Endpoint |
Description |
GET |
/api/v2/events |
Get events (paginated, filterable) |
GET |
/api/v2/analytics/summary |
Event counts by action |
GET |
/api/v2/analytics/timeseries |
Events over time |
GET |
/api/v2/analytics/top-attacks |
Top attack types |
GET |
/api/v2/analytics/top-ips |
Top attacking IPs |
GET |
/api/v2/analytics/top-countries |
Top countries (GeoIP) |
| Method |
Endpoint |
Description |
GET |
/api/v2/compliance/reports |
List compliance reports |
POST |
/api/v2/compliance/reports |
Generate a report |
GET |
/api/v2/compliance/reports/:id |
Get report details |
DELETE |
/api/v2/compliance/reports/:id |
Delete report |
GET |
/api/v2/compliance/reports/:id/download |
Download PDF/HTML |
GET |
/api/v2/compliance/schedules |
List report schedules |
POST |
/api/v2/compliance/schedules |
Create schedule |
PUT |
/api/v2/compliance/schedules/:id |
Update schedule |
DELETE |
/api/v2/compliance/schedules/:id |
Delete schedule |
| Method |
Endpoint |
Description |
GET |
/api/v2/users |
List users (admin) |
POST |
/api/v2/users |
Create user |
GET |
/api/v2/users/:id |
Get user |
PUT |
/api/v2/users/:id |
Update user |
DELETE |
/api/v2/users/:id |
Delete user |
POST |
/api/v2/users/:id/mfa/reset |
Admin MFA reset |
GET |
/api/v2/api-keys |
List API keys |
POST |
/api/v2/api-keys |
Create API key |
POST |
/api/v2/api-keys/:id/revoke |
Revoke API key |
| Method |
Endpoint |
Description |
GET |
/api/v2/agents |
List agents |
POST |
/api/v2/agents |
Create agent (returns enrollment bundle) |
GET |
/api/v2/agents/:id |
Get agent details |
PUT |
/api/v2/agents/:id |
Update agent |
DELETE |
/api/v2/agents/:id |
Delete agent |
POST |
/api/v2/agents/:id/commands |
Send command to agent |
| Method |
Endpoint |
Description |
POST |
/api/v2/agent/heartbeat |
Agent heartbeat with status + perf metrics |
GET |
/api/v2/agent/config |
Pull configuration bundle |
POST |
/api/v2/agent/events |
Ship event batches |
| Method |
Endpoint |
Description |
GET |
/api/v2/system/stats |
System statistics (tenant/user counts, agent perf) |
GET |
/api/v2/system/cluster |
Cluster node status |
GET |
/api/v2/audit-logs |
Audit trail (admin) |
| Method |
Endpoint |
Description |
GET |
/api/v2/organizations |
List organizations |
POST |
/api/v2/organizations |
Create organization |
GET |
/api/v2/organizations/:id |
Get organization |
PUT |
/api/v2/organizations/:id |
Update organization |
DELETE |
/api/v2/organizations/:id |
Delete organization |
GET |
/api/v2/organizations/:id/stats |
Organization stats |
| Method |
Endpoint |
Description |
GET |
/api/v2/country-groups |
List the named country groups |
POST |
/api/v2/country-groups |
Create one (name, description, countries) |
PUT |
/api/v2/country-groups/:id |
Edit one, built-in groups included |
DELETE |
/api/v2/country-groups/:id |
Delete one — rules naming it then match nothing |
| Method |
Endpoint |
Description |
GET |
/api/v2/digests |
The per-day, per-site summaries |
GET |
/api/v2/digests/export |
The week as CSV, PDF or HTML (?format=) |
| Method |
Endpoint |
Description |
GET |
/api/v2/audit-logs |
The administrative trail, filtered by actor, action, resource or period |
GET |
/api/v2/audit-logs/export |
The same filtered set as CSV or PDF, stating its own scope |
GET |
/api/v2/audit-logs/resource/:type/:id |
Everything done to one object |
¶ Compliance and monitoring
| Method |
Endpoint |
Description |
GET |
/api/v2/compliance/attack-surface |
The discovered endpoint inventory |
GET |
/api/v2/compliance/incidents |
Incidents, filterable by status and severity |
GET |
/api/v2/compliance/incidents/:id |
One incident with its requests |
PATCH |
/api/v2/compliance/incidents/:id/status |
Resolve or close one |
GET |
/api/v2/compliance/contained-ips |
Addresses blocked by incident response |
DELETE |
/api/v2/compliance/contained-ips/:tenantId/:ip |
Release one — this reaches the agents |
GET |
/api/v2/compliance/drift-events |
Configuration drift detected on the agents |
POST |
/api/v2/compliance/generate |
Generate a report now |
GET |
/api/v2/compliance/schedules |
Recurring report schedules |
POST |
/api/v2/compliance/schedules |
Schedule one (weekly, monthly, quarterly) |
| Method |
Endpoint |
Description |
GET |
/api/v2/analytics/latency |
Decision latency over time (p90, p95, p99) |
GET |
/api/v2/analytics/score-distribution |
Anomaly scores by band |
GET |
/api/v2/analytics/attack-evolution |
Attack categories over time |
GET |
/api/v2/analytics/by-site |
Volume and disposition per site |
GET |
/api/v2/analytics/top-targets |
The endpoints taking the most |
GET |
/api/v2/analytics/top-asns |
The networks behind the traffic |
GET |
/api/v2/analytics/rule-coverage |
Which rules fired, and which stayed silent |
GET |
/api/v2/analytics/false-positive-rates |
Per-rule false-positive estimate |
GET |
/api/v2/analytics/bot-human-analysis |
Bot versus human classification |
GET |
/api/v2/analytics/challenge-solve-times |
How long challenges take to solve |
GET |
/api/v2/analytics/rate-limit-insights |
Most rate-limited addresses and paths |
| Method |
Endpoint |
Description |
POST |
/api/v2/agents/:id/revoke |
Stop trusting an agent; it wipes its local cache |
POST |
/api/v2/agents/:id/reactivate |
Trust it again |
GET |
/api/v2/agents/:id/enrollment |
The enrolment material for mTLS |
| Method |
Endpoint |
Description |
POST |
/api/v2/events/:id/mark-fp |
Record a decision as a false positive, with a scope |
POST |
/api/v2/events/:id/unmark-fp |
Take that back |
GET |
/api/v2/events/ray/:rayId |
Open one request by its EdgeGuard ID |
¶ Configuration and backup
| Method |
Endpoint |
Description |
GET |
/api/v2/config/export |
Export the configuration |
POST |
/api/v2/config/import |
Import it |
POST |
/api/v2/backup/full |
A full backup |
POST |
/api/v2/backup/restore |
Restore one |
This reference covers the endpoints a caller usually wants. The console uses the same API for everything else — 225 routes in total — so anything not listed here can be read off the browser's network tab while using the page that does it.
The Central serves a React dashboard at the API v2 port. See the Dashboard Reference for complete page-by-page documentation of all 20 dashboard pages.
Key sections:
- Dashboard — Real-time metrics, charts, top attackers
- WAF — Rules, IP lists, path rules, response templates
- Monitoring — Events, analytics, attack chains, threat intel, performance
- Configuration — Global settings, groups, tenants, agents, API keys
- Compliance — Reports (17 standards), audit log, log connectors
| Table |
Description |
organizations |
Multi-org support |
users |
Dashboard users with roles + MFA |
sessions |
Active user sessions |
global_settings |
Organization-wide WAF defaults |
hierarchy_groups |
Server groups / clusters |
group_nodes |
Nginx nodes per group (with heartbeat) |
tenants |
Protected websites/domains |
path_rules |
URL-specific security overrides |
rulesets |
Managed detection rulesets |
ip_lists |
IP blocklists/allowlists (scoped) |
allowed_bots |
Bot allowlist per hierarchy level |
response_templates |
Custom HTML response pages |
events |
Security events from agents |
agents |
Registered agent nodes |
api_keys |
API authentication keys |
audit_log |
Configuration change audit trail |
threat_feeds |
Threat intelligence feed configs |
threat_indicators |
IOCs from threat feeds |
compliance_reports |
Generated compliance reports |
compliance_schedules |
Recurring report schedules |
| View |
Description |
v_tenant_effective_settings |
Computed inherited settings (Global → Group → Tenant) |
v_active_ip_blocks |
Currently active IP blocks (not expired) |
v_active_allowed_bots |
Active bot allowlist entries |
- TLS is mandatory for the API v2 server
- mTLS is mandatory for agent connections — agents must present a client certificate issued during enrollment
- API keys are hashed with SHA-256 before storage — never stored in plaintext
- JWT secrets should be at least 32 random characters
- CORS can be restricted to specific dashboard origins
- Role-based access — super_admin, admin, editor, viewer
📷 Image: Central deployment diagram — to be added.