Core API Integration

As a rule, plugins should be self-contained within their own tables (Data model, niyase.data). Use niyase.core only when you need to read core business data (employees, departments). You cannot access the database directly or fetch an arbitrary server — all data access goes through the useNiyase() bridge.

Two kinds of data API

The data APIs available to a plugin split by purpose:

API	Purpose	Bridge
/nplg/:pluginId/:table	Generic CRUD on your own plg_* tables	niyase.data (Data model)
/nplg-core/v1/:pluginId/*	Read-only access to core data (employees, departments)	niyase.core (this page)

The /nplg prefix is a leftover implementation detail from the retired name "network plugin." It is not specific to any one connection pattern — it's the generic data API shared by every plugin, standalone or PROVIDER-CLIENT alike, for reading and writing their own tables. It is not a "network-only" API.

The niyase.core API

const niyase = useNiyase();

await niyase.core.employees({ limit: 200 }); // { items, total } — name, email, employment status only
await niyase.core.employee(id);
await niyase.core.departments(); // { items } — id, name, and parent department only

niyase.core.grantedScopes; // Scopes granted at activation (for conditional UI)

Internally this calls the in-app proxy /nplg-core/v1/:pluginId/*. What it returns is a minimal projection (employees return only name, email, and employment status — never sensitive fields like My Number).

About niyase.core.workspace(): it exists in the type definitions, but cloud-connected spaces (the shared execution path used by cloud, desktop, and mobile alike) don't serve it through this route — calling it returns NOT_FOUND. Basic space information (workspaceId / workspaceType / spaceId) is always available from niyase.context with no scope required, so use that when you just need to know which space you're in.

Granted scopes (grantedScopes)

Core data can only be read within the scope the space's owner granted at activation.

Scope	Contents
core:employee:read	Employee list and individuals
core:department:read	Departments

For features that are not granted, the server returns 403 SCOPE_DENIED. By inspecting niyase.core.grantedScopes you can adapt the UI without waiting for a 403.

if (niyase.core.grantedScopes.includes("core:employee:read")) {
  // Show the assignee-selection UI
}

Current limitation (beta): the plugin management UI in space settings doesn't yet have a screen for approving individual scopes at activation time. Because of that, grantedScopes defaults to empty, so activating a plugin in production today leaves every niyase.core.* call returning SCOPE_DENIED (the activation API itself already accepts grantedScopes, so this will start working as soon as the approval UI ships). To exercise the scoped path while developing, use niyase-plugin dev (its MOCK backend grants core:employee:read by default) or set scopes explicitly with the test helper createTestHost({ context: { grantedScopes: [...] } }) (Reference).

What you can read never exceeds the calling user

grantedScopes is a ceiling — the most a plugin is allowed to read. The actual call runs scoped to the intersection of that ceiling and the calling user's own effective permissions. Even inside a plugin the owner activated, a request made while viewing as a regular employee only returns what that employee could see anyway. Widening the number of access paths doesn't widen what any one user can reach, because the boundary isn't a static field allowlist — it's enforced per caller.

Handling errors

Bridge errors are normalized to a stable set of codes (NiyaseErrorCode, see Reference). The ones you'll actually run into when calling the core API:

Code	Meaning
SCOPE_DENIED	Missing grantedScopes (403)
NOT_FOUND	The target doesn't exist, or isn't served through this route (404)
VALIDATION	The request was invalid (400)
MAINTENANCE	Temporarily unavailable for maintenance (503)

try {
  await niyase.core.employees();
} catch (e) {
  const err = e as { code: string; status: number };
  if (err.code === "SCOPE_DENIED") {
    // Missing grantedScopes — check whether the UI branch was skipped
  }
}