Admin API

APISystem APIAdmin API

API:Pryv Lab: ${username}.pryv.meDNS-less: ${hostname}/${username}Own domain: ${username}.${domain}

Format:REST payloadBatch blockcURLcURL authSocket.IO

Admin API

The admin (or “system”) API is the operator-facing surface of a Pryv.io core. In v2 it is a set of token-authenticated /system/* HTTP routes served by the core itself, complemented by the bin/*.js operator CLIs.

This replaces the v1 admin service entirely: there is no config-leader, no admin-panel GUI, and no JWT admin login. Platform-wide settings now live in the platform database and are managed through the CLIs and the routes below.

All /system/* routes are always mounted; access is purely key-gated (there is no enable/disable switch).

Authentication

Every /system/* request carries the operator admin key verbatim in the Authorization header:

curl -i -H 'Authorization: <adminAccessKey>' \
  "https://{username}.pryv.me/system/admin/cores"

The key is the auth.adminAccessKey config value, which is required at boot and must be identical across every core in a cluster. On a missing or wrong key the core answers 404 unknown-resource. The one exception is POST /system/admin/cores/ack, which authenticates with a one-time join token in the request body instead.

Cluster and cores

List cores

idlist-coresHTTPGET /system/admin/cores

Lists the cluster’s cores with a per-core user count. Requires the operator admin key in the Authorization header (the raw auth.adminAccessKey value, not a Bearer token). A missing or invalid key returns 404 unknown-resource (deliberately, to avoid confirming the endpoint exists).

Result

HTTP200 OK

cores	array of objects One entry per core: id, url, hosting (or null), available (boolean), userCount.

Acknowledge a core (bootstrap)

idack-coreHTTPPOST /system/admin/cores/ack

Called by a freshly bootstrapped core to acknowledge joining the cluster. Flips the core to available: true and returns a cluster snapshot. Authenticated by a one-time join token in the request body, not the admin key. Operators normally trigger this indirectly via bin/bootstrap.js.

Result

HTTP200 OK

Cluster snapshot from the bootstrap handler.

TLS certificates

List certificates

idlist-certsHTTPGET /system/admin/certs

Lists TLS certificate metadata. Never returns certificate or key material. Requires the operator admin key in the Authorization header (the raw auth.adminAccessKey value, not a Bearer token). A missing or invalid key returns 404 unknown-resource (deliberately, to avoid confirming the endpoint exists).

Result

HTTP200 OK

certs	array of objects One entry per certificate: hostname, issuedAt, expiresAt, daysUntilExpiry (integer or null).

Force certificate renewal

idforce-renewHTTPPOST /system/admin/certs/force-renew

Triggers an operator-initiated ACME certificate rollover on the renewer core. Requires the operator admin key in the Authorization header (the raw auth.adminAccessKey value, not a Bearer token). A missing or invalid key returns 404 unknown-resource (deliberately, to avoid confirming the endpoint exists).

Parameters

hostname	stringoptional The host to renew; defaults to the core’s primary host.

Result

HTTP200 OK

ok	boolean
hostname	string
issuedAt	timestamp
expiresAt	timestamp

Specific errors

invalid-request	HTTP400 hostname must be a string when provided.
renewal-failed	HTTP400 { ok: false, error } when this core is not the renewer, Let’s Encrypt is disabled, or ACME fails.

Users

List users

idlist-usersHTTPGET /system/admin/users

Lists all users. Requires the operator admin key in the Authorization header (the raw auth.adminAccessKey value, not a Bearer token). A missing or invalid key returns 404 unknown-resource (deliberately, to avoid confirming the endpoint exists).

Result

HTTP200 OK

users	array of objects Per user: username, id, email, language, and core (only on multi-core).

Create user

idcreate-userHTTPPOST /system/create-user

Registers a new user. Requires the operator admin key in the Authorization header (the raw auth.adminAccessKey value, not a Bearer token). A missing or invalid key returns 404 unknown-resource (deliberately, to avoid confirming the endpoint exists).

Parameters

username	string
password	string
email	string
appId	string

Result

HTTP201 Created

id	string The new user id.

Get user info

iduser-infoHTTPGET /system/user-info/{username}

Per-user usage statistics and storage. Requires the operator admin key in the Authorization header (the raw auth.adminAccessKey value, not a Bearer token). A missing or invalid key returns 404 unknown-resource (deliberately, to avoid confirming the endpoint exists).

Parameters

username	string

Result

HTTP200 OK

userInfo	object username, storageUsed, lastAccess, callsTotal, callsDetail, callsPerAccess.

Specific errors

unknown-resource	HTTP404 Unknown user.

Deactivate a user's MFA

iddeactivate-mfaHTTPDELETE /system/users/{username}/mfa

Clears the user’s multi-factor authentication. Requires the operator admin key in the Authorization header (the raw auth.adminAccessKey value, not a Bearer token). A missing or invalid key returns 404 unknown-resource (deliberately, to avoid confirming the endpoint exists).

Parameters

username	string

Result

HTTP204 No Content

Update user platform fields

idupdate-userHTTPPUT /system/users

Updates a user’s indexed / unique platform fields. The username cannot be changed. Requires the operator admin key in the Authorization header (the raw auth.adminAccessKey value, not a Bearer token). A missing or invalid key returns 404 unknown-resource (deliberately, to avoid confirming the endpoint exists).

Parameters

username	string
user	object Fields to set.
fieldsToDelete	objectoptional

Result

HTTP200 OK

user	boolean

Reserve a user (pre-registration)

idvalidate-userHTTPPOST /system/users/validate

Reserves a username and unique fields ahead of registration, verifying an invitation token. Requires the operator admin key in the Authorization header (the raw auth.adminAccessKey value, not a Bearer token). A missing or invalid key returns 404 unknown-resource (deliberately, to avoid confirming the endpoint exists).

Parameters

username	string
invitationToken	string
uniqueFields	objectoptional
core	stringoptional

Result

HTTP200 OK

reservation	boolean

Specific errors

reservation-refused	HTTP400 { reservation: false, error } with id invitationToken-invalid or item-already-exists.

Delete a user's platform fields

idregistry-deleteHTTPDELETE /system/users/{username}

Deletes only the platform-side unique / indexed fields for a user (NOT their stored data). Requires the operator admin key in the Authorization header (the raw auth.adminAccessKey value, not a Bearer token). A missing or invalid key returns 404 unknown-resource (deliberately, to avoid confirming the endpoint exists).

Parameters

username	string
onlyReg	boolean Required (?onlyReg=true); this route never touches base storage.
dryRun	booleanoptional

Result

HTTP200 OK

result	object dryRun, deleted.

Specific errors

invalid-operation	HTTP400 Missing onlyReg=true.
unknown-resource	HTTP404 Unknown user.

Delete a user (full)

idfull-deleteHTTPDELETE /users/{username}

Full cascading delete of a user on their home core: base storage, attachments, high-frequency series, audit, sessions, platform and index entries. Served on the user’s core (not under /system). Accepts either the admin key or the user’s own personal token in the Authorization header (when user-account.delete includes adminToken, the default).

Parameters

username	string

Result

HTTP200 OK

Resolve an access

idget-accessHTTPGET /system/accesses/{accessId}

Resolves an access id to its owning user and metadata (used for breach scoping). Requires the operator admin key in the Authorization header (the raw auth.adminAccessKey value, not a Bearer token). A missing or invalid key returns 404 unknown-resource (deliberately, to avoid confirming the endpoint exists).

Parameters

accessId	string

Result

HTTP200 OK

accessIndex	object Owning user and access metadata; includes deleted for deleted accesses.

Specific errors

unknown-resource	HTTP404 Access not found.

Mail templates

Manage the in-core email templates stored in the platform database. The CLI complement is bin/mail.js.

List templates

idlist-templatesHTTPGET /system/admin/mail/templates

Requires the operator admin key in the Authorization header (the raw auth.adminAccessKey value, not a Bearer token). A missing or invalid key returns 404 unknown-resource (deliberately, to avoid confirming the endpoint exists).

Result

HTTP200 OK

templates	array of objects type, lang, part, length.

Get a template

idget-templateHTTPGET /system/admin/mail/templates/{type}/{lang}/{part}

Returns the raw Pug of one template as text/plain. Requires the operator admin key in the Authorization header (the raw auth.adminAccessKey value, not a Bearer token). A missing or invalid key returns 404 unknown-resource (deliberately, to avoid confirming the endpoint exists).

Result

HTTP200 OK

Specific errors

unknown-resource	HTTP404 Unknown template.

Upsert a template

idput-templateHTTPPUT /system/admin/mail/templates/{type}/{lang}/{part}

Creates or replaces a template. Requires the operator admin key in the Authorization header (the raw auth.adminAccessKey value, not a Bearer token). A missing or invalid key returns 404 unknown-resource (deliberately, to avoid confirming the endpoint exists).

Parameters

pug	string The template source.

Result

HTTP204 No Content

Specific errors

invalid-request-structure	HTTP400 Body must be { pug }.

Delete a template

iddelete-templateHTTPDELETE /system/admin/mail/templates/{type}/{lang}/{part}

Requires the operator admin key in the Authorization header (the raw auth.adminAccessKey value, not a Bearer token). A missing or invalid key returns 404 unknown-resource (deliberately, to avoid confirming the endpoint exists).

Result

HTTP204 No Content

Send a test mail

idsend-testHTTPPOST /system/admin/mail/send-test

Sends a test email using a template. Requires SMTP to be configured. Requires the operator admin key in the Authorization header (the raw auth.adminAccessKey value, not a Bearer token). A missing or invalid key returns 404 unknown-resource (deliberately, to avoid confirming the endpoint exists).

Parameters

type	string
lang	string
recipient	string | object An email string, or { name, email }.

Result

HTTP200 OK

sent	boolean

Integrity

Check platform integrity

idcheck-platform-integrityHTTPGET /system/check-platform-integrity

Runs the platform and user-index integrity checks. Requires the operator admin key in the Authorization header (the raw auth.adminAccessKey value, not a Bearer token). A missing or invalid key returns 404 unknown-resource (deliberately, to avoid confirming the endpoint exists).

Result

HTTP200 OK

checks	array The platform and users-index check results.

Operator CLIs

The bin/*.js scripts complement the HTTP surface (they open the storages / platform database directly). Key ones:

• bootstrap.js - cluster bootstrap: new-core, init-ca-holder, list-tokens, revoke-token, promote-core.
• dns-records.js - manage persistent DNS records: list, load, delete, export.
• observability.js - OpenTelemetry posture: show, enable, disable, set-endpoint, set-header, set-interval, set-app-name.
• mail.js - mail templates: templates list|get|set|delete|seed, send-test.
• oauth-client.js - OAuth2 app-account management: create, list, show, update, revoke, key revocation.
• backup.js / migrate.js / migrate-platform.js - backup/restore and database/platform migrations.
• integrity-check.js, backfill-access-index.js, breach-scope.js, reconcile-user-cores.js - maintenance.
• check-config.js, config-to-env.js, init.js - configuration and install.

Run each with --help for its full options.