Skip to main content

Documentation Index

Fetch the complete documentation index at: https://devzone.nayax.com/llms.txt

Use this file to discover all available pages before exploring further.

Nayax Core has a role management system that lets administrators control what users can see and do based on their role. You can connect your Core Extension to this system so that specific UI elements in your app (tabs, buttons, widgets, settings sections) are automatically shown or hidden based on the logged-in user’s role. Your app fetches the list of hidden elements from Nayax at startup, then applies visibility throughout your UI.

​
Prerequisites

  • Your Core Extension is registered with Nayax and has a model name (for example, Apps/YourAppName)
  • You have identified the UI elements in your app that should be role-controllable
1

Define your UI element IDs

Assign a string ID to each UI element you want to make role-controllable. Use this naming convention:
{category}.{name}
  • Category: one of tab, widget, action, settings, sidebar, topMenu
  • Name: camelCase identifier for the element
Examples:
tab.overview
tab.settings
action.restartDevice
action.exportReport
widget.salesSummary
settings.notifications
Keep a list of all element IDs you define. You will provide this list to Nayax so administrators can configure role permissions for each one.
Element IDs are case-sensitive. Use consistent casing throughout your app and in the list you submit to Nayax.
2

Fetch hidden elements at startup

When your app loads, call the Nayax UI elements endpoint to get the list of elements that should be hidden for the current user:
GET /core/apps/ui-elements?model=Apps/YourAppName
The endpoint returns a JSON object with a hide array:
{
  "hide": [
    "action.restartDevice",
    "tab.settings",
    "widget.communication"
  ]
}
Store the result as a set for fast lookup:
async function fetchHiddenElements(model: string): Promise<Set<string>> {
  try {
    const response = await fetch(
      `/core/apps/ui-elements?model=${model}`,
      { credentials: "include" }
    );

    if (!response.ok) {
      return new Set();
    }

    const data: { hide: string[] } = await response.json();
    return new Set(data.hide);
  } catch {
    return new Set();
  }
}
The endpoint returns an empty hide array for users who can see everything (for example, administrators). An empty array is a valid response, not an error.
3

Apply visibility in your UI

Create a helper function that checks whether an element should be visible, then use it throughout your UI before rendering each role-controllable element:
let hiddenElements: Set<string> = new Set();

function isVisible(elementId: string): boolean {
  return !hiddenElements.has(elementId);
}
Call fetchHiddenElements at app startup and store the result before rendering:
hiddenElements = await fetchHiddenElements("Apps/YourAppName");
Then apply visibility checks in your UI:
// Filter a tab list
const visibleTabs = allTabs.filter(tab => isVisible(tab.elementId));

// Conditionally render a widget
{isVisible("widget.salesSummary") && <SalesSummaryWidget />}

// Filter an actions dropdown
const visibleActions = allActions.filter(action => isVisible(action.elementId));
4

Handle the loading state

The API call takes time. Decide how your app behaves while permissions are loading. The safest approach is to render nothing until the API call resolves, then apply visibility:
let permissionsLoaded = false;

async function initApp() {
  hiddenElements = await fetchHiddenElements("Apps/YourAppName");
  permissionsLoaded = true;
  renderApp();
}
Alternatively, you can render all elements immediately and re-render after permissions load. Either approach is valid, but the first avoids a flash of visible content.
5

Provide your element IDs to Nayax

Nayax administrators configure role permissions using your element IDs. You must provide Nayax with the complete list of element IDs your app exposes so they can be added to the role management system.

​
Element ID naming reference

Use these categories when defining your element IDs:
CategoryUse for
tabTabs in a tabbed view (for example, tab.overview, tab.reports)
actionButtons or menu items that trigger an operation (for example, action.export, action.delete)
widgetDashboard cards or data panels (for example, widget.salesChart)
settingsSections within a settings screen (for example, settings.notifications)
sidebarSidebar navigation items (for example, sidebar.filters)
topMenuItems in a top navigation bar (for example, topMenu.userMenu)

​
Error handling

The UI elements endpoint is designed to fail open. If the request fails for any reason (network error, authentication issue, server error), your app should show all elements rather than hiding everything. Hiding elements when you cannot confirm permissions would lock users out of your app. The example in Step 2 implements this behavior by returning an empty Set on any error.

​
Troubleshooting

If role-based visibility is not behaving as expected, use the table below to identify the cause.
SymptomLikely causeFix
All elements visible despite role configurationAPI returned empty array or request failedCheck browser DevTools network tab for the /core/apps/ui-elements response
Specific element not hidingElement ID not in the hide arrayVerify your element ID matches exactly what Nayax configured (case-sensitive)
API returns 404App not served through reverse proxyAccess your app through Nayax Core, not directly
Element IDs not available in role managementIDs not submitted to NayaxProvide your element ID list to Nayax for registration

​
What’s next

Translations

Expose your UI strings for multi-language support.

Authentication

Understand the JWT token your app receives from Nayax.