Engine API Consumption with Postman Quickstart

This quickstart guide walks developers through authenticating with and consuming the Niksphere Engine API using Postman.

The fastest way to get started is a Personal Access Token (PAT) — a static Bearer token you generate once via the CLI and paste directly into Postman, with no OAuth 2.0 collection setup or browser login required. This is the path documented below.

If you specifically need to test the delegated OAuth 2.0 Authorization Code flow (for example, to validate consent screens or PKCE behavior for a custom client), see Alternative: OAuth 2.0 Authorization Code Flow at the end of this guide.

Prerequisites

Before starting, ensure you have:

The Niksphere CLI (nik) installed and authenticated against your Engine. If you haven't installed it yet, follow the CLI Installation & Setup Quickstart.
A Self-Hosted running Niksphere Engine (default: http://localhost:3000). If your Engine is not yet running, follow the Engine Installation & Setup Quickstart.
Postman desktop app or web client installed and ready.

TIP

If you use Postman Web (web.postman.co) instead of the desktop app, it sends requests through Postman's Cloud Agent by default, which cannot reach http://localhost:3000. Install the Postman Desktop Agent and switch the agent selector (bottom-right corner of the Postman Web window) from Cloud Agent to Desktop Agent before sending any request in this guide. The Postman desktop app does not need this — it always talks to localhost directly.

Step 1: Generate a Personal Access Token

1.1 Find Your Actor ID

Personal Access Tokens are issued to a specific Actor. List the actors in your environment to find the ID of the account you want to generate a token for:

bash

nik env actor list --json

1.2 Create the Token

bash

nik env actor identity pat create <actor-id> --name "Postman" --expiry-days 30 --json

Expected Output:

json

{
  "status": "success",
  "id": "<pat-id>",
  "name": "Postman",
  "token": "niksphere_pat_<random-hex>",
  "token_prefix": "niksphere_pat_<8-chars>",
  "scopes": [],
  "expires_at": "2026-09-26T18:07:36.4280386+02:00",
  "message": "Personal Access Token created successfully."
}

TIP

The token value is only ever shown once. Copy it immediately. If you lose it, delete the token (nik env actor identity pat delete <actor-id> <pat-id> --json) and create a new one.

Step 2: Configure Bearer Token Auth in Postman

2.1 Setup Collection Authorization

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

Parameter	Value	Description
Type	`Bearer Token`	Sends the token as `Authorization: Bearer <token>`
Token	`niksphere_pat_...`	Paste the PAT generated in Step 1

TIP

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

Step 3: List Application Packages (Admin API)

Create a request to list all application packages known to the Engine. This endpoint returns the full catalog with each package's installation state, so it works even if you haven't installed anything yet:

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

Expected Response (200 OK):

json

{
  "data": [
    {
      "id": "de.niksphere.businessfundamentals",
      "name": "Business Fundamentals",
      "publisher": "Niksphere Team",
      "developer": "Niksphere Team",
      "installed": false,
      "persisted": false,
      "version": "1.2.0",
      "availableVersions": "1.2.0"
    }
  ]
}

TIP

"installed": false just means the package hasn't been deployed to this Engine yet — the API call itself doesn't require it. To try the Runtime API (entity CRUD) and RPC Execution API (calling Pascal routines) shown in the Engine API Concept guide, install a package first via nik env app install <id> <version> --json.

Step 4: Manage Actors (Admin API)

Actors (users, services, and system accounts) exist independently of any installed application, making them a good next resource to explore both read and write operations.

4.1 List Actors (GET)

Add a new request in Postman:
- Method: GET
- URL: http://localhost:3000/api/v1/admin/actors
- Authorization: Inherit auth from parent
Click Send.

Expected Response (200 OK):

json

{
  "data": [
    {
      "id": "6d1e2b3a-...",
      "type": "USER",
      "name": "NikAdmin",
      "status": "ACTIVE",
      "created_at": "2026-08-24T10:15:00Z",
      "updated_at": "2026-08-24T10:15:00Z"
    }
  ]
}

4.2 Create a New Actor (POST)

Add a new request in Postman:
- Method: POST
- URL: http://localhost:3000/api/v1/admin/actors
- Authorization: Inherit auth from parent
- Body: Select raw and format JSON
Provide the JSON payload:

json

{
  "name": "Postman Test User",
  "type": "USER"
}

Click Send.

Expected Response (200 OK):

json

{
  "id": "9f4c7a10-...",
  "type": "USER",
  "name": "Postman Test User",
  "status": "ACTIVE",
  "created_at": "2026-08-27T10:15:00Z",
  "updated_at": "2026-08-27T10:15:00Z"
}

Step 5: Inspect Your Own Identities (Admin API)

As a final example, query the identities linked to the actor you generated your Personal Access Token for in Step 1 — this should show the PAT you are currently authenticating with.

Add a new request in Postman:
- Method: GET
- URL: http://localhost:3000/api/v1/admin/actors/<actor-id>/identities
- Authorization: Inherit auth from parent
Click Send.

Expected Response (200 OK):

json

{
  "password": {
    "id": "1a2b3c4d-...",
    "actor_id": "<actor-id>",
    "username": "NikAdmin",
    "must_change_password": false,
    "created_at": "2026-08-24T10:15:00Z",
    "updated_at": "2026-08-24T10:15:00Z"
  },
  "pats": [
    {
      "id": "<pat-id>",
      "actor_id": "<actor-id>",
      "name": "Postman",
      "token_prefix": "niksphere_pat_<8-chars>",
      "scopes": [],
      "expires_at": "2026-09-26T10:15:00Z",
      "created_at": "2026-08-27T10:15:00Z",
      "updated_at": "2026-08-27T10:15:00Z"
    }
  ],
  "external": []
}

Verification

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

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",...}
Verify OpenAPI Specification (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.

Alternative: OAuth 2.0 Authorization Code Flow

Personal Access Tokens are the recommended path for developer testing and Postman. Use the OAuth 2.0 Authorization Code flow instead if you need to validate the interactive, delegated login experience of a custom third-party client — for example, testing the consent screen or PKCE behavior before integrating a real application.

A.1 Register an OAuth Client for Postman

By default, the Engine only ships with its internal platform client. Register a dedicated OAuth client for Postman using the CLI's env client commands:

bash

nik env client add --client-id postman --client-name "Postman" --type PUBLIC --redirect-uris https://oauth.pstmn.io/v1/callback,https://oauth.pstmn.io/v1/browser-callback --grants authorization_code,refresh_token --json

Flag	Value	Description
`--client-id`	`postman`	Unique client identifier used in Postman's OAuth 2.0 configuration
`--client-name`	`Postman`	Display name of the client
`--type`	`PUBLIC`	Postman authenticates interactively via the browser and does not hold a confidential secret
`--redirect-uris`	`https://oauth.pstmn.io/v1/callback,https://oauth.pstmn.io/v1/browser-callback`	Both of Postman's OAuth callback URLs — which one is used depends on the Authorize using browser setting in Step A.2
`--grants`	`authorization_code,refresh_token`	Grant types required for the interactive Authorization Code flow and token refresh

Expected Response:

json

{
  "status": "success",
  "message": "Client 'postman' (Postman) successfully registered with ID: <generated-id>"
}

TIP

Use nik env client list --json to review all registered clients, or nik env client delete postman --json to remove the client again once you no longer need it.

A.2 Configure OAuth 2.0 in Postman

Instead of the Bearer Token authorization from Step 2, configure the collection's Authorization tab as follows:

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 (used when Authorize using browser is unchecked)
Authorize using browser	Checked / Unchecked	Use Postman's built-in webview (unchecked, `.../v1/callback`) or system browser (checked, `.../v1/browser-callback`) — both were registered in Step A.1, so either setting works
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	`postman`	The OAuth client registered in Step A.1
Client Secret	(leave empty)	Not required for a `PUBLIC` client
Scope	`openid`	OIDC standard scope
State	Any random value, at least 8 characters (for example `postman-test-1234`)	Required — the Engine rejects a missing/short `state` (see Troubleshooting)
Client Authentication	`Send client credentials in body`	Standard token endpoint parameter transmission

Scroll down and click Get New Access Token. An interactive login window opens showing the Niksphere Engine Login screen — sign in with your credentials, then click Use Token in the preview modal.

TIP

On a fresh Engine, the NikAdmin account's password and Personal Access Token are randomly generated on first startup and logged once at WARN level — see Default Admin Provisioning. To sign in with a specific, known password instead, set admin_username / admin_password before starting the Engine — see Configured Admin Provisioning.

Once the token is acquired, Step 3 through Step 5 work identically — each request just needs Authorization: Inherit auth from parent.

Troubleshooting

invalid_request: The 'redirect_uri' parameter does not match any of the OAuth 2.0 Client's pre-registered redirect urls.

The Engine's OAuth 2.0 authorization endpoint validates redirect_uri with an exact match — no wildcards. Postman sends .../v1/callback when Authorize using browser is unchecked (built-in webview), and .../v1/browser-callback when it's checked (system browser). If only one of them is registered, the other mode fails with this error. Fix: register both, as shown in Step A.1 — or run nik env client edit postman --redirect-uris https://oauth.pstmn.io/v1/callback,https://oauth.pstmn.io/v1/browser-callback on an existing client.

Error: invalid_state (web) or Error: [object Object] (desktop), browser window closes immediately

Postman leaves the State field empty by default and does not send a state parameter at all in that case. The Engine's authorization endpoint enforces the RFC 6819 CSRF-protection recommendation and requires state to be at least 8 characters long — an empty or missing state fails with invalid_state ("The state is missing or does not have enough characters..."). Fix: set State to any random value of at least 8 characters (for example postman-test-1234), as shown in Step A.2.

Next Steps

API Concept: Learn about the 4 API pillars and protocol boundaries in the Engine API Concept.
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.

Developer

Engine

CLI

VS Code Extension

Cloud

Website

Engine API Consumption with Postman Quickstart

Prerequisites

Step 1: Generate a Personal Access Token

1.1 Find Your Actor ID

1.2 Create the Token

Step 2: Configure Bearer Token Auth in Postman

2.1 Setup Collection Authorization

Step 3: List Application Packages (Admin API)

Step 4: Manage Actors (Admin API)

4.1 List Actors (GET)

4.2 Create a New Actor (POST)

Step 5: Inspect Your Own Identities (Admin API)

Verification

Alternative: OAuth 2.0 Authorization Code Flow

A.1 Register an OAuth Client for Postman

A.2 Configure OAuth 2.0 in Postman

Troubleshooting

Next Steps

Engine API Consumption with Postman Quickstart ​

Prerequisites ​

Step 1: Generate a Personal Access Token ​

1.1 Find Your Actor ID ​

1.2 Create the Token ​

Step 2: Configure Bearer Token Auth in Postman ​

2.1 Setup Collection Authorization ​

Step 3: List Application Packages (Admin API) ​

Step 4: Manage Actors (Admin API) ​

4.1 List Actors (GET) ​

4.2 Create a New Actor (POST) ​

Step 5: Inspect Your Own Identities (Admin API) ​

Verification ​

Alternative: OAuth 2.0 Authorization Code Flow ​

A.1 Register an OAuth Client for Postman ​

A.2 Configure OAuth 2.0 in Postman ​

Troubleshooting ​

Next Steps ​

Engine API Consumption with Postman Quickstart

Prerequisites

Step 1: Generate a Personal Access Token

1.1 Find Your Actor ID

1.2 Create the Token

Step 2: Configure Bearer Token Auth in Postman

2.1 Setup Collection Authorization

Step 3: List Application Packages (Admin API)

Step 4: Manage Actors (Admin API)

4.1 List Actors (GET)

4.2 Create a New Actor (POST)

Step 5: Inspect Your Own Identities (Admin API)

Verification

Alternative: OAuth 2.0 Authorization Code Flow

A.1 Register an OAuth Client for Postman

A.2 Configure OAuth 2.0 in Postman

Troubleshooting

Next Steps