Skip to content

Engine API ​

insider 2026-10-02 JSON ↗

Management API for Niksphere applications and core data.

Server & Base URL ​

All REST API endpoints documented below are relative to the Engine base URL:

http
http://localhost:3000/api/v1

NOTE

For custom host/port setups or production deployments, configure NIKSPHERE_ENGINE_HTTP_BASE_URL (or http_base_url in config.yaml). See the Engine Configuration Reference for all options.

Endpoints Overview ​

MethodEndpointSummary
GET/api/v1/admin/actorsList all actors
POST/api/v1/admin/actorsCreate a new actor
GET/api/v1/admin/actors/{id}Get actor details
PUT/api/v1/admin/actors/{id}Update an actor
DELETE/api/v1/admin/actors/{id}Delete an actor
GET/api/v1/admin/actors/{id}/identitiesList actor identities
DELETE/api/v1/admin/actors/{id}/identities/external/{ext_id}Delete an external SSO identity link
POST/api/v1/admin/actors/{id}/identities/passwordSet or update actor password
POST/api/v1/admin/actors/{id}/identities/patCreate a Personal Access Token
DELETE/api/v1/admin/actors/{id}/identities/pat/{pat_id}Delete a Personal Access Token
GET/api/v1/admin/appsList all applications
POST/api/v1/admin/apps/publishPublish an application package
POST/api/v1/admin/apps/uploadUpload an application package
DELETE/api/v1/admin/apps/{id}/dataDrop application database tables
POST/api/v1/admin/apps/{id}/install/{version}Install an application version
POST/api/v1/admin/apps/{id}/uninstallUninstall an application
DELETE/api/v1/admin/apps/{id}/versions/{version}Delete an application version
GET/api/v1/admin/apps/{id}/versions/{version}/packageDownload an application package
GET/api/v1/admin/clientsList all clients
POST/api/v1/admin/clientsRegister a new client
GET/api/v1/admin/clients/{id}Get client details
PUT/api/v1/admin/clients/{id}Update client details
DELETE/api/v1/admin/clients/{id}Delete a client
PUT/api/v1/admin/clients/{id}/toggleEnable or disable client
GET/api/v1/admin/dapDAP debug control connection
GET/api/v1/admin/idps/externalList all external IdPs
POST/api/v1/admin/idps/externalCreate a new external IdP
PUT/api/v1/admin/idps/external/{id}Edit an external IdP
DELETE/api/v1/admin/idps/external/{id}Delete an external IdP
GET/api/v1/admin/monitorLive log and telemetry streaming
GET/api/v1/admin/sessionsList active client runtime sessions
DELETE/api/v1/admin/sessions/{id}Terminate an active client runtime session
GET/api/v1/admin/tasksList background tasks
GET/api/v1/admin/tasks/{id}Get task status
DELETE/api/v1/admin/tasks/{id}Cancel a task
GET/api/v1/admin/tasks/{id}/streamStream task events
GET/api/v1/clientClient runtime WebSocket connection
GET/api/v1/healthService health check
GET/api/v1/openapi.jsonOpenAPI specification

Admin ​

GET /api/v1/admin/actors ​

List all actors

Retrieves a list of all registered actors

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
401Unauthorizedresponse.Response
500Internal Server Errorresponse.Response

POST /api/v1/admin/actors ​

Create a new actor

Registers a new user, system, or service actor

Parameters:

NameLocated inTypeRequiredDescription
requestbodyActorAddRequestyesActor creation payload

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
400Bad Requestresponse.Response
401Unauthorizedresponse.Response
500Internal Server Errorresponse.Response

GET /api/v1/admin/actors/{id} ​

Get actor details

Retrieves details of a specific actor by ID

Parameters:

NameLocated inTypeRequiredDescription
idpathstringyesActor ID

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
401Unauthorizedresponse.Response
404Not Foundresponse.Response
500Internal Server Errorresponse.Response

PUT /api/v1/admin/actors/{id} ​

Update an actor

Updates an actor's display name or status

Parameters:

NameLocated inTypeRequiredDescription
idpathstringyesActor ID
requestbodyActorEditRequestyesActor edit payload

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
400Bad Requestresponse.Response
401Unauthorizedresponse.Response
404Not Foundresponse.Response
500Internal Server Errorresponse.Response

DELETE /api/v1/admin/actors/{id} ​

Delete an actor

Removes an actor from the system

Parameters:

NameLocated inTypeRequiredDescription
idpathstringyesActor ID

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
400Bad Requestresponse.Response
401Unauthorizedresponse.Response
404Not Foundresponse.Response
500Internal Server Errorresponse.Response

GET /api/v1/admin/actors/{id}/identities ​

List actor identities

Retrieves all linked credentials (password, PATs, external SSO links) for an actor

Parameters:

NameLocated inTypeRequiredDescription
idpathstringyesActor ID

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
401Unauthorizedresponse.Response
404Not Foundresponse.Response
500Internal Server Errorresponse.Response

DELETE /api/v1/admin/actors/{id}/identities/external/{ext_id} ​

Delete an external SSO identity link

Unlinks and deletes an external SSO identity provider link from an actor

Parameters:

NameLocated inTypeRequiredDescription
idpathstringyesActor ID
ext_idpathstringyesExternal Identity ID

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
401Unauthorizedresponse.Response
404Not Foundresponse.Response
500Internal Server Errorresponse.Response

POST /api/v1/admin/actors/{id}/identities/password ​

Set or update actor password

Sets or resets the embedded password credentials for an actor

Parameters:

NameLocated inTypeRequiredDescription
idpathstringyesActor ID
requestbodySetPasswordRequestyesPassword payload

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
400Bad Requestresponse.Response
401Unauthorizedresponse.Response
404Not Foundresponse.Response
500Internal Server Errorresponse.Response

POST /api/v1/admin/actors/{id}/identities/pat ​

Create a Personal Access Token

Generates a new Personal Access Token (PAT) for an actor

Parameters:

NameLocated inTypeRequiredDescription
idpathstringyesActor ID
requestbodyCreatePATRequestyesPAT creation payload

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
400Bad Requestresponse.Response
401Unauthorizedresponse.Response
404Not Foundresponse.Response
500Internal Server Errorresponse.Response

DELETE /api/v1/admin/actors/{id}/identities/pat/{pat_id} ​

Delete a Personal Access Token

Revokes and deletes a specific Personal Access Token belonging to an actor

Parameters:

NameLocated inTypeRequiredDescription
idpathstringyesActor ID
pat_idpathstringyesPersonal Access Token ID

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
401Unauthorizedresponse.Response
404Not Foundresponse.Response
500Internal Server Errorresponse.Response

GET /api/v1/admin/apps ​

List all applications

Retrieves a detailed list of all applications and their available versions

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
401Unauthorizedresponse.Response
500Internal Server Errorresponse.Response

POST /api/v1/admin/apps/publish ​

Publish an application package

Uploads and automatically installs/activates a Niksphere App package (.nikapp) on the server in a single request

Parameters:

NameLocated inTypeRequiredDescription
fileformDatafileyesNiksphere App Package
allow_dropsquerybooleannoAllow drops

Responses:

Status CodeDescriptionSchema / Content
202Acceptedresponse.Response
400Bad Requestresponse.Response
401Unauthorizedresponse.Response
409Conflictresponse.Response
500Internal Server Errorresponse.Response

POST /api/v1/admin/apps/upload ​

Upload an application package

Uploads a new Niksphere App package (.nikapp) to the server

Parameters:

NameLocated inTypeRequiredDescription
fileformDatafileyesNiksphere App Package

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
400Bad Requestresponse.Response
401Unauthorizedresponse.Response
500Internal Server Errorresponse.Response

DELETE /api/v1/admin/apps/{id}/data ​

Drop application database tables

Drops all physical database tables and associated data for an uninstalled application

Parameters:

NameLocated inTypeRequiredDescription
idpathstringyesApplication ID

Responses:

Status CodeDescriptionSchema / Content
202Acceptedresponse.Response
400Bad Requestresponse.Response
401Unauthorizedresponse.Response
404Not Foundresponse.Response
409Conflictresponse.Response
500Internal Server Errorresponse.Response

POST /api/v1/admin/apps/{id}/install/{version} ​

Install an application version

Installs and activates a specific version of an application as a background operation

Parameters:

NameLocated inTypeRequiredDescription
idpathstringyesApplication ID
versionpathstringyesVersion string
allow_dropsquerybooleannoAllow drops

Responses:

Status CodeDescriptionSchema / Content
202Acceptedresponse.Response
400Bad Requestresponse.Response
401Unauthorizedresponse.Response
404Not Foundresponse.Response
409Conflictresponse.Response
500Internal Server Errorresponse.Response

POST /api/v1/admin/apps/{id}/uninstall ​

Uninstall an application

Deactivates the currently installed version of an app

Parameters:

NameLocated inTypeRequiredDescription
idpathstringyesApplication ID

Responses:

Status CodeDescriptionSchema / Content
202Acceptedresponse.Response
400Bad Requestresponse.Response
401Unauthorizedresponse.Response
404Not Foundresponse.Response
409Conflictresponse.Response
500Internal Server Errorresponse.Response

DELETE /api/v1/admin/apps/{id}/versions/{version} ​

Delete an application version

Permanently removes a specific version of an app from the system

Parameters:

NameLocated inTypeRequiredDescription
idpathstringyesApplication ID
versionpathstringyesVersion string

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
400Bad Requestresponse.Response
401Unauthorizedresponse.Response
404Not Foundresponse.Response
500Internal Server Errorresponse.Response

GET /api/v1/admin/apps/{id}/versions/{version}/package ​

Download an application package

Downloads the compiled Niksphere App package (.nikapp) for a specific version

Parameters:

NameLocated inTypeRequiredDescription
idpathstringyesApplication ID
versionpathstringyesVersion string

Responses:

Status CodeDescriptionSchema / Content
200The Niksphere App Packagefile
401Unauthorizedresponse.Response
404Not Foundresponse.Response
500Internal Server Errorresponse.Response

GET /api/v1/admin/clients ​

List all clients

Retrieves a list of all registered OAuth clients

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
401Unauthorizedresponse.Response
500Internal Server Errorresponse.Response

POST /api/v1/admin/clients ​

Register a new client

Registers a new OAuth 2.0 / OIDC client in the system

Parameters:

NameLocated inTypeRequiredDescription
requestbodyClientAddRequestyesClient creation payload

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
400Bad Requestresponse.Response
401Unauthorizedresponse.Response

GET /api/v1/admin/clients/{id} ​

Get client details

Retrieves details of a specific OAuth client by ID

Parameters:

NameLocated inTypeRequiredDescription
idpathstringyesClient ID

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
401Unauthorizedresponse.Response
404Not Foundresponse.Response
500Internal Server Errorresponse.Response

PUT /api/v1/admin/clients/{id} ​

Update client details

Updates an existing client's display name, redirect URIs, or allowed grants

Parameters:

NameLocated inTypeRequiredDescription
idpathstringyesClient ID
requestbodyClientEditRequestyesClient edit payload

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
400Bad Requestresponse.Response
401Unauthorizedresponse.Response
404Not Foundresponse.Response
500Internal Server Errorresponse.Response

DELETE /api/v1/admin/clients/{id} ​

Delete a client

Removes a third-party OAuth client from the system

Parameters:

NameLocated inTypeRequiredDescription
idpathstringyesClient ID

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
400Bad Requestresponse.Response
401Unauthorizedresponse.Response
404Not Foundresponse.Response
500Internal Server Errorresponse.Response

PUT /api/v1/admin/clients/{id}/toggle ​

Enable or disable client

Activates or deactivates an OAuth client

Parameters:

NameLocated inTypeRequiredDescription
idpathstringyesClient ID
requestbodyClientToggleRequestyesToggle payload

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
400Bad Requestresponse.Response
401Unauthorizedresponse.Response
404Not Foundresponse.Response
500Internal Server Errorresponse.Response

GET /api/v1/admin/dap ​

DAP debug control connection

Control-plane WebSocket used by the Niksphere CLI's DAP proxy to arm, break, step, and inspect the next Client Runtime session created via the Engine's API

Parameters:

NameLocated inTypeRequiredDescription
ticketquerystringyesSingle-use WebSocket Ticket

Responses:

Status CodeDescriptionSchema / Content
101Switching Protocols to WebSocketstring
401Unauthorizedresponse.Response

GET /api/v1/admin/idps/external ​

List all external IdPs

Retrieves a list of all configured external identity providers

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
401Unauthorizedresponse.Response
500Internal Server Errorresponse.Response

POST /api/v1/admin/idps/external ​

Create a new external IdP

Creates a new external identity provider configuration

Parameters:

NameLocated inTypeRequiredDescription
requestbodyExternalIdpAddRequestyesIdP creation data

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
400Bad Requestresponse.Response
401Unauthorizedresponse.Response

PUT /api/v1/admin/idps/external/{id} ​

Edit an external IdP

Modifies an existing external IdP

Parameters:

NameLocated inTypeRequiredDescription
idpathstringyesIdP ID to edit
requestbodyExternalIdpEditRequestyesUpdated fields

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
400Bad Requestresponse.Response
401Unauthorizedresponse.Response
404Not Foundresponse.Response
500Internal Server Errorresponse.Response

DELETE /api/v1/admin/idps/external/{id} ​

Delete an external IdP

Removes an external IdP from the system

Parameters:

NameLocated inTypeRequiredDescription
idpathstringyesIdP ID to delete

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
400Bad Requestresponse.Response
401Unauthorizedresponse.Response
404Not Foundresponse.Response
500Internal Server Errorresponse.Response

GET /api/v1/admin/monitor ​

Live log and telemetry streaming

Establishes a WebSocket connection for real-time engine logs and system metrics

Parameters:

NameLocated inTypeRequiredDescription
ticketquerystringyesSingle-use WebSocket Ticket

Responses:

Status CodeDescriptionSchema / Content
101Switching Protocols to WebSocketstring
401Unauthorizedresponse.Response

GET /api/v1/admin/sessions ​

List active client runtime sessions

Retrieves a snapshot of all currently active client runtime WebSocket sessions

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
401Unauthorizedresponse.Response

DELETE /api/v1/admin/sessions/{id} ​

Terminate an active client runtime session

Forces the WebSocket connection backing the given session id to close

Parameters:

NameLocated inTypeRequiredDescription
idpathstringyesSession ID

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
401Unauthorizedresponse.Response
404Not Foundresponse.Response

Tasks ​

GET /api/v1/admin/tasks ​

List background tasks

Returns a list of all tracked background tasks

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
401Unauthorizedresponse.Response

GET /api/v1/admin/tasks/{id} ​

Get task status

Returns status, title, message, percent, and timestamps for a task

Parameters:

NameLocated inTypeRequiredDescription
idpathstringyesTask ID

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
401Unauthorizedresponse.Response
404Not Foundresponse.Response

DELETE /api/v1/admin/tasks/{id} ​

Cancel a task

Cancels a task if it has not yet started execution

Parameters:

NameLocated inTypeRequiredDescription
idpathstringyesTask ID

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
401Unauthorizedresponse.Response
404Not Foundresponse.Response
409Conflictresponse.Response

GET /api/v1/admin/tasks/{id}/stream ​

Stream task events

Streams live newline-delimited JSON events for a task until completion

Parameters:

NameLocated inTypeRequiredDescription
idpathstringyesTask ID

Responses:

Status CodeDescriptionSchema / Content
200OKresponse.Response
401Unauthorizedresponse.Response
404Not Foundresponse.Response

Client ​

GET /api/v1/client ​

Client runtime WebSocket connection

Establishes a bidirectional WebSocket connection for interactive UI state synchronization and push events

Parameters:

NameLocated inTypeRequiredDescription
ticketquerystringyesSingle-use WebSocket Ticket

Responses:

Status CodeDescriptionSchema / Content
101Switching Protocols to WebSocketstring
401Unauthorizedresponse.Response

System ​

GET /api/v1/health ​

Service health check

Inspects the running service status and database connectivity

Responses:

Status CodeDescriptionSchema / Content
200OKHealthResponse
503Service UnavailableHealthResponse

GET /api/v1/openapi.json ​

OpenAPI specification

Retrieves the complete OpenAPI JSON specification for the Niksphere Engine API

Responses:

Status CodeDescriptionSchema / Content
200OKobject
401Unauthorizedresponse.Response
404Not Foundresponse.Response

Data Models & Schemas ​

github_com_niksphere_niksphere-idpbroker-go.ActorType ​

github_com_niksphere_niksphere-idpbroker-go.ClientType ​

ActorAddRequest ​

PropertyTypeDescription
namestring
typeany

ActorEditRequest ​

PropertyTypeDescription
namestring
statusstring

ClientAddRequest ​

PropertyTypeDescription
actor_idstring
allowed_grantsArray<string>
client_idstring
client_namestring
client_secretstring
client_typeany
redirect_urisArray<string>

ClientEditRequest ​

PropertyTypeDescription
allowed_grantsArray<string>
client_namestring
redirect_urisArray<string>

ClientToggleRequest ​

PropertyTypeDescription
is_activeboolean

CreatePATRequest ​

PropertyTypeDescription
expiry_daysinteger
namestring
scopesArray<string>

ExternalIdpAddRequest ​

PropertyTypeDescription
auto_provisionboolean
client_idstring
client_secretstring
is_activeboolean
issuer_urlstring
namestring
scopesstring

ExternalIdpEditRequest ​

PropertyTypeDescription
auto_provisionboolean
client_idstring
client_secretstring
is_activeboolean
issuer_urlstring
namestring
scopesstring

HealthResponse ​

PropertyTypeDescription
databasestring
servicestring
statusstring
timestampstring

SetPasswordRequest ​

PropertyTypeDescription
passwordstring
usernamestring

response.Response ​

PropertyTypeDescription
actor_idstring
actor_namestring
dataany
finalboolean
messagestring
message_codestring
percentinteger
statusstring
task_idstring
titlestring

Release v1.0.0-build.67-channel.insider