Consuming the Engine API with Postman Quickstart

This quickstart guide walks developers through authenticating with and consuming the Niksphere Engine API using Postman's native OAuth 2.0 integration.

Prerequisites

Before starting, ensure you have:

• A running Niksphere Engine instance (default: http://localhost:3000). If your Engine is not yet running, follow the Engine Installation & Setup Quickstart.
• Administrative or user credentials (default embedded administrator: username: NikAdmin, password: Nik€AdmIn78).
• At least one installed application package on your Engine (such as de.niksphere.businessfundamentals at version 1.2.0) for App Runtime and entity operations.
• Postman desktop app or web client installed and ready.

Step 1: Configure OAuth 2.0 in Postman

The Niksphere Engine protects its API routes using OpenID Connect (OIDC) via its embedded IDP Broker. Postman natively supports the OAuth 2.0 Authorization Code flow, handling the browser login dialog, authorization code capture, and token exchange automatically.

1.1 Setup Collection Authorization

1. In the top navigation bar of Postman, click Workspaces and select an existing workspace (such as My Workspace) or create a new one.
2. In the left sidebar of the workspace, select Collections (the stacked layers icon).
3. Click the + icon (or Create collection) and name it Niksphere Engine API.
4. Select the newly created collection, navigate to the Authorization tab in the main editor area, and configure the following parameters:

Parameter	Value	Description
Type	OAuth 2.0	Postman's built-in OAuth engine
Add authorization data to	Request Headers	Automatically sends Authorization: Bearer <token>
Grant Type	Authorization Code	Standard interactive OIDC authorization flow
Callback URL	https://oauth.pstmn.io/v1/callback	Postman's standard OAuth callback
Authorize using browser	Checked / Unchecked	Use Postman's built-in webview or system browser
Auth URL	http://localhost:3000/auth/authorize	IDP Broker authorization endpoint
Access Token URL	http://localhost:3000/auth/token	IDP Broker token exchange endpoint
Client ID	niksphere	Default platform OAuth client identifier
Client Secret	(leave empty)	Not required for the default public client
Scope	openid	OIDC standard scope
Client Authentication	Send client credentials in body	Standard token endpoint parameter transmission

1.2 Acquire the JWT Access Token

1. Scroll down in the Authorization tab and click Get New Access Token.
2. An interactive login window will open showing the Niksphere Engine Login screen.
3. Enter your administrator credentials:
   • Username: NikAdmin
   • Password: Nik€AdmIn78
4. Click Log In. The IDP Broker validates your credentials and redirects back to Postman.
5. In the Postman token preview modal, click Use Token.

TIP

By configuring OAuth 2.0 at the Collection level, all individual requests in the collection automatically inherit this authentication when set to Inherit auth from parent.

Step 2: Access the Admin API

Create a request to list all registered and installed application packages on the Engine:

1. Inside your Postman collection, add a new request:
   • Method: GET
   • URL: http://localhost:3000/api/v1/admin/apps
   • Authorization: Inherit auth from parent
2. Click Send.

Expected Response (200 OK):

{
  "status": "success",
  "data": [
    {
      "id": "de.niksphere.businessfundamentals",
      "name": "Business Fundamentals",
      "author": "Niksphere Team",
      "installed": true,
      "persisted": true,
      "version": "1.2.0",
      "availableVersions": "1.2.0"
    }
  ]
}

Step 3: Query & Insert Application Entity Data (Runtime API)

The Niksphere Engine dynamically exposes REST CRUD endpoints for entities defined in installed apps via /api/{appId}/v{appVersion}/{entityName}. Physical database column names are translated to and from logical semantic field names on-the-fly.

3.1 Query Records (GET)

Retrieve existing entity records (for example, the Partner entity in de.niksphere.businessfundamentals):

1. Add a new request in Postman:
   • Method: GET
   • URL: http://localhost:3000/api/de.niksphere.businessfundamentals/v1.2.0/Partner
   • Authorization: Inherit auth from parent
2. Click Send.

Expected Response (200 OK):

{
  "data": [
    {
      "system_id": "ce2de807-9b7f-45ff-b718-b3250cdf3327",
      "system_created_at": "2026-08-24T10:15:00Z",
      "FirstName": "Tino",
      "LastName": "Teuber",
      "EmailAddress": "tino.teuber@niksphere.de",
      "Number": 10001
    }
  ]
}

3.2 Insert a Record (POST)

Insert a new record into the entity table:

1. Add a new request in Postman:
   • Method: POST
   • URL: http://localhost:3000/api/de.niksphere.businessfundamentals/v1.2.0/Partner
   • Authorization: Inherit auth from parent
   • Body: Select raw and format JSON
2. Provide the JSON record payload:

{
  "FirstName": "Max",
  "LastName": "Mustermann",
  "EmailAddress": "max.mustermann@example.com",
  "Number": 10002
}

3. Click Send.

Expected Response (201 Created):

{
  "data": {
    "system_id": "8f3b6a12-d9e4-4c2b-8a5e-1c7f9e8a0b2d",
    "FirstName": "Max",
    "LastName": "Mustermann",
    "EmailAddress": "max.mustermann@example.com",
    "Number": 10002
  }
}

Step 4: Execute Pascal Routines (RPC Execution API)

The Niksphere Engine allows direct Remote Procedure Calls (RPC) on top-level Pascal procedures and functions exported by installed application units.

• Route Pattern: POST /api/v1/{appId}/{unitRelativePath}/{symbolName}

1. Add a new request in Postman:
   • Method: POST
   • URL: http://localhost:3000/api/v1/de.niksphere.businessfundamentals/Source/Globalization/Languages/LanguageEntity.pas/AddNumbers
   • Authorization: Inherit auth from parent
   • Body: Select raw and format JSON
2. Provide the ordered parameter arguments:

{
  "args": [15, 30]
}

3. Click Send.

Expected Response (200 OK):

{
  "result": 45
}

Verification

To verify that your API setup and authentication are functioning properly:

1. Verify Health Probe (Public / Unauthenticated):

   • Method: GET
   • URL: http://localhost:3000/api/v1/health
   • Authorization: No Auth
   • Expected Response (200 OK): {"status":"ok","service":"niksphere-engine","database":"up",...}

2. Verify OpenAPI Specification (OIDC Authenticated):

   • Method: GET
   • URL: http://localhost:3000/api/v1/openapi.json
   • Authorization: Inherit auth from parent
   • Expected Response (200 OK): Full OpenAPI 3.0 JSON specification describing all Admin routes and schemas.

Next Steps

• API Architecture: Learn about the 4 API pillars and protocol boundaries in the Engine API Architecture.
• Authentication Deep Dive: Review token lifespans, grant types, and IdP federation in Engine Authentication.
• OpenAPI Reference: Explore all administrative endpoints in the Engine API Reference.
• Client SDKs: Consume the Engine API programmatically with official SDKs for Go and TypeScript.