Skip to content

Organisation and users

Organisation

An organisation is the tenant in xTool. All data (documents, API keys, integrations) is scoped to an organisation.

Organisation data

  • Name, address (street, postal code, city, country), customer number, and other profile fields.
  • Organisations can have various identifiers (e.g. for participation in exchange networks). For Peppol, the organisation has Peppol-related configuration — it must be set up to receive and send documents via Peppol. See Receive by Peppol and Peppol.

Multi-tenancy and organisation hierarchy

Organisations can form a tree: an organisation can have a parent and subsidiary (child) organisations. One “top” organisation and its subsidiaries form a tree.

A user belongs to one organisation (their source organisation). Their capabilities (view, create, update, delete, send documents, etc.) apply in the context of the active organisation and all its subsidiary organisations (all subsidiaries in the subtree). The active organisation can be the source organisation or any of its descendants. So when a user selects organisation A as active in the web app, they see and can work with data for A and all organisations for which A is an ancestor.

1
2
3
4
graph TD
    A[Organisation A] --> B[Subsidiary B]
    A --> C[Subsidiary C]
    B --> D[Subsidiary D]

If a user belongs to organisation A (source organisation is A), they can choose A as active and then see data for A, B, C and D; if they choose B as active — they see data for B and D.

Source organisation and active organisation

In the context of xTool (and the API) two terms are used:

  • Source organisation — The organisation to which the account entity belongs: an API key is created under one organisation and is “bound” to it; a user is also bound to one organisation. This is the organisation that owns the key or the account.
  • Active organisation — The organisation in whose context the current action is performed. It can be the same as the source organisation or one of its descendants (a subsidiary in the tree).

When using the API: you call the API with a key belonging to the source organisation and act on behalf of the active organisation — either the source (by default) or one of its subsidiaries (only if you specify it explicitly). Requests (documents, settings, integrations, etc.) are executed in the context of the active organisation. For authentication and headers, see API Reference.

In the web app: the user is bound to one organisation (the source); the organisation selected in the switcher is the active one — either their source organisation or one of its subsidiaries. All actions and displayed data refer to the active organisation and its subsidiaries.

Switching organisation (web)

The web app has an organisation switcher (in the header or sidebar): the selected organisation is set as the active organisation; all actions and displayed data refer to it and its subsidiary organisations. See Web overview and Organisation UI.

Users

Users are accounts for signing in to the web app. Each user is bound to one organisation (their source organisation) and has one of three roles, which define their capabilities. Rights apply in the context of the active organisation (source or one of its subsidiaries).

Roles

  • Viewer — View data within their organisation (and its subsidiaries): documents, settings, usage. Cannot change settings or create/delete entities.
  • Member — View and actively work with documents and allowed entities: create, edit, send documents, etc. within the organisation and subsidiaries.
  • Administrator — Full management within the organisation and subsidiaries: organisation settings, users, API keys, integrations, documents, etc.

Roles define different access levels; exact capabilities may be refined as the product evolves.

Where to manage users

Users and their roles are configured in the web app (sections for organisation and users). See Organisation UI.