Concepts

Authorization and hierarchy

How a key's scope, role, purchased app, company and hierarchy combine to decide what it can access.

An API key is not a super-user. It acts as a dedicated, non-login "integration user" with a normal NEXTOREx role, placed at one point in your organisation tree. Everything that limits a person in NEXTOREx limits the key too.

The access model

effective access =
    API key scope
  ∩ assigned role and its permissions
  ∩ purchased application
  ∩ company
  ∩ hierarchy

A request succeeds only when all of these allow it. Removing any one of them is enough to block it.

Layer	What it controls
Key scope	The broad areas the key was issued for, for example `crm:read`.
Role and permissions	The same role permissions your staff have, for example "view leads" or "create customers". A tenant-wide permission ceiling still applies.
Purchased application	Whether your subscription includes the app (ERP / POS, CRM or Education).
Company	The key belongs to one company and can never see another.
Hierarchy	The key's place in your organisation tree (see below).

Applications are separate

NEXTOREx sells three business applications, each as its own plan inside one subscription:

Application	Scopes
ERP / POS	`erp:read`, `erp:write`
CRM	`crm:read`, `crm:write`
Education	`education:read`, `education:write`

Owning one application does not give you another. A CRM-only customer calling an Education endpoint receives a 403 (plan_not_entitled or forbidden), even with a valid key and scope.

Developer API is a platform feature, not a fourth application. It does not appear in the catalog's apps list and it does not change what your applications include.

Hierarchy

NEXTOREx organisations can be a tree: a company with groups, entities and units beneath it. When a key is created it is bound to one node of that tree and acts from there.

A key can read and write records belonging to its own node and every node below it (its descendants).
A key issued for a leaf node cannot see its parent or its siblings.
A key issued at a higher node can reach the descendants it is permitted to, and can narrow a request to one descendant with filter[node], or place a new record under one descendant with the node field on create.
Records that belong only to a higher level of the tree are not visible to a lower key, even where the NEXTOREx screens show them to staff. The API is deliberately stricter.
Anything outside the key's reach returns 404 resource_not_found, exactly like a record that does not exist, so a key cannot be used to discover what exists elsewhere.

Node references

Nodes are referred to by safe public references that start with nd_. Use GET /hierarchy/nodes to list the nodes your key can reach and their references. You never send, and never receive, internal tree paths or database identifiers.

{
  "data": [
    { "id": "nd_0123456789abcdef01234567", "name": "Head Office", "level": "company", "parent_id": null, "is_self": true },
    { "id": "nd_89abcdef0123456789abcdef", "name": "Lahore Branch", "level": "le", "parent_id": "nd_0123456789abcdef01234567", "is_self": false }
  ],
  "pagination": { "limit": 25, "has_more": false, "next_cursor": null }
}

The level codes (company, bg, le, ou, su) show how deep a node sits in the tree.

Context is fixed by the key

Tenant, company, hierarchy node and role come from the key and nothing else. If a request contains fields such as tenant_id, company_id, hierarchy_node_id or role_id (or headers such as X-Tenant-Id), it is rejected with 422 reserved_context_field. To act somewhere else, use a different key.