Admin API

The Admin API is served by control_plane_app under the /admin/v1 prefix. It provides full management capabilities for the AuthNexus platform including agent (admin) accounts, applications, users, card keys, nodes, PKI, security, and reporting.

General Information

Base URL

http://127.0.0.1:9090/admin/v1

The admin API listens on loopback by default. In production, expose it through a reverse proxy with TLS termination.

Authentication

Most endpoints require a valid admin session token in the Authorization header:

Authorization: Bearer <access_token>

Tokens are obtained via the login endpoint and refreshed via the refresh endpoint.

Response Format

All responses use JSON. Successful responses include the resource data directly. Error responses follow a consistent structure:

{
    "error": "error_code",
    "message": "Human-readable description"
}

Pagination

List endpoints support pagination via query parameters:

Parameter	Type	Description
page	integer	Page number (1-based)
page_size	integer	Items per page

Responses include pagination metadata where applicable.

Authentication Endpoints

Method	Path	Description
POST	/auth/login	Authenticate with username and password
GET	/auth/me	Get current agent profile
POST	/auth/logout	Invalidate current session
POST	/auth/refresh	Refresh access token

Setup (First Run)

Method	Path	Description
GET	/setup/status	Check initialization state (PKI, root admin)
POST	/setup/initialize	Complete first-run setup (requires console token)

The setup endpoints are available before authentication is configured. After the root admin is created, /setup/status returns requires_setup: false with no PKI details exposed.

Applications

Method	Path	Description
GET	/applications	List all applications
POST	/applications	Create application
PATCH	/applications/:app_id	Update application
DELETE	/applications/:app_id	Soft-delete (recycle bin)
POST	/applications/:app_id/restore	Restore from recycle bin
POST	/applications/:app_id/purge	Permanently delete

Agents (Admin Accounts)

Method	Path	Description
GET	/agents	List agents
POST	/agents	Create agent
PATCH	/agents/:id	Update agent
DELETE	/agents/:id	Soft-delete (recycle bin)
POST	/agents/:id/restore	Restore from recycle bin
DELETE	/agents/:id/purge	Permanently delete
POST	/agents/:id/move	Move agent in hierarchy
GET	/agents/:id/subtree	Get agent subtree
GET	/agents/:id/timeline	Agent activity timeline
GET	/agents/:id/stats	Agent statistics
POST	/agents/:id/reset-password	Reset agent password

Agent Permissions & Grants

Method	Path	Description
GET	/agents/:id/permissions	Get agent permissions
PATCH	/agents/:id/permissions	Update permissions
GET	/agents/:id/app-grants	Get application grants
PUT	/agents/:id/app-grants	Set application grants
GET	/agents/:id/card-type-grants	Get card type grants
PUT	/agents/:id/card-type-grants	Set card type grants
GET	/agents/:id/card-type-prices	Get card type prices
PUT	/agents/:id/card-type-prices	Set card type prices
GET	/agents/:id/bindings	Get agent bindings
GET	/permission-defs	List permission definitions

Agent Wallet

Method	Path	Description
GET	/agents/:id/wallet	Get wallet balance
POST	/agents/:id/wallet/adjust	Adjust balance
POST	/wallet/transfer	Transfer between agents
GET	/agents/:id/ledger	Transaction ledger

Agent Billing Mode

Method	Path	Description
POST	/agents/:id/billing-mode/preview	Preview billing mode change
POST	/agents/:id/billing-mode/apply	Apply billing mode change

Settlement

Method	Path	Description
GET	/agents/:id/commission-rules	Get commission rules
PUT	/agents/:id/commission-rules	Set commission rules
DELETE	/agents/:id/commission-rules/:childId	Delete rule
POST	/settlement/report	Generate settlement report

Users

Method	Path	Description
GET	/users	List users (with filtering)
PATCH	/users/:id	Update user
DELETE	/users/:id	Delete user
GET	/users/:id/timeline	User activity timeline
GET	/users/:id/ledger	User transaction ledger
POST	/users/:id/recharge-by-card	Recharge by card key
POST	/users/:id/reset-password	Reset password
POST	/users/:id/add-time	Add service time
GET	/users/:id/bindings	User-agent bindings
POST	/agent-user-bindings	Create binding
DELETE	/agent-user-bindings/:user_id	Delete binding

Batch User Operations

Method	Path	Description
POST	/users/batch/active	Batch activate/deactivate
POST	/users/batch/expire-at	Batch set expiration
POST	/users/batch/add-time	Batch add time
POST	/users/batch/delete	Batch delete

Card Keys

Method	Path	Description
GET	/card-keys	List card keys
GET	/card-key-batches	List generation batches
PATCH	/card-keys/:id	Update card key
DELETE	/card-keys/:id	Delete card key
POST	/card-keys/generate	Generate new card keys
POST	/card-keys/batch/patch	Batch update
POST	/card-keys/batch/delete	Batch delete

Card Types & Configuration

Method	Path	Description
GET	/card-types	List card types
POST	/card-types	Create card type
PATCH	/card-types/:id	Update card type
DELETE	/card-types/:id	Delete card type

Cloud Functions

Method	Path	Description
GET	/cloud-functions	List cloud functions
GET	/cloud-functions/:name	Get function detail
POST	/cloud-functions	Create function
PUT	/cloud-functions/:name	Update function
DELETE	/cloud-functions/:name	Delete function
PATCH	/cloud-functions/:name/toggle	Toggle enabled state

Variables

Method	Path	Description
GET	/variables	List cloud variables
POST	/variables	Create variable
PATCH	/variables/:id	Update variable
DELETE	/variables/:id	Delete variable

Versions & Announcements

Method	Path	Description
GET	/versions	List app versions
POST	/versions	Create version
PATCH	/versions/:id	Update version
DELETE	/versions/:id	Delete version
GET	/announcements	List announcements
POST	/announcements	Create announcement
PATCH	/announcements/:id	Update announcement
POST	/announcements/reorder	Reorder announcements
DELETE	/announcements/:id	Delete announcement

Nodes

Method	Path	Description
GET	/nodes/overview	Node statistics overview
GET	/nodes	List nodes
POST	/nodes	Create node (triggers PKI onboard)
GET	/nodes/:nid	Node detail
PUT	/nodes/:nid	Update node
POST	/nodes/:nid/disable	Disable node
POST	/nodes/:nid/enable	Enable node
DELETE	/nodes/:nid	Hard delete node
POST	/nodes/:nid/enrollment-token	Generate enrollment token
GET	/nodes/:nid/enrollment-tokens	List enrollment tokens
GET	/nodes/:nid/deploy-packages	List deploy packages
POST	/nodes/:nid/deploy-packages	Generate deploy package
GET	/nodes/:nid/deploy-packages/:pid/download	Download package
POST	/nodes/:nid/reissue-package	Reissue deploy package

Node Certificates

Method	Path	Description
GET	/nodes/:nid/certs	List node certificates
POST	/nodes/:nid/certs/issue	Issue certificate (async, 202)
POST	/nodes/:nid/certs/:cid/revoke	Revoke certificate
POST	/nodes/:nid/certs/rotate	Rotate certificates (async, 202)

PKI

Method	Path	Description
GET	/pki/cas	List CAs
POST	/pki/cas	Create CA
GET	/pki/cas/:id	CA detail
GET	/pki/certs	List all certificates
GET	/pki/certs/:id	Certificate detail
POST	/pki/certs/:id/revoke	Revoke certificate
GET	/pki/jobs	List PKI jobs
GET	/pki/jobs/:id	Job detail
POST	/pki/jobs/:id/retry	Retry failed job
POST	/pki/jobs/:id/cancel	Cancel pending job
GET	/pki/audit-logs	PKI audit trail
GET	/pki/expiring	Certificates nearing expiry
GET	/pki/revocations	Revocation list
POST	/pki/bundles/publish	Publish trust bundle
GET	/pki/bundles	List trust bundles

App Certificate Packages

Method	Path	Description
GET	/apps/:app_id/cert-packages	List app cert packages
POST	/apps/:app_id/cert-packages	Create cert package
GET	/apps/:app_id/cert-packages/:pid/download	Download package

Security

Method	Path	Description
GET	/login-logs	User login logs
GET	/audit-logs	User audit logs
GET	/agent-login-logs	Agent login logs
GET	/agent-audit-logs	Agent audit logs
GET	/agent-tokens	Active agent tokens
DELETE	/agent-tokens/:agent_id	Revoke agent tokens
GET	/tokens	User token overview
DELETE	/tokens/user/:user_id	Bump user auth epoch
GET	/blacklist	Server blacklist
POST	/blacklist	Add blacklist entry
PATCH	/blacklist/:id	Update entry
DELETE	/blacklist/:id	Remove entry
POST	/blacklist/batch/remove	Batch remove
GET	/control-blacklist	Control plane blacklist
POST	/control-blacklist	Add entry
PATCH	/control-blacklist/:id	Update entry
DELETE	/control-blacklist/:id	Remove entry
POST	/control-blacklist/batch/remove	Batch remove

Reports

Method	Path	Description
GET	/reports/login-daily	Daily login statistics
GET	/reports/card-generated-daily	Daily card generation
GET	/reports/card-activated-daily	Daily card activation
GET	/reports/agent-login-daily	Daily agent login activity

Next Steps

• Getting Started -- setting up your first deployment
• Security Model -- blacklist and epoch mechanisms
• SDK Integration -- client-side API usage