Organisations and customers¶

Say you are a partner serving ten customers. Each customer needs its own users, agents, knowledge and data, and no customer may see anything of another. In Core you set that up with organisations: your own organisation, and one organisation per customer beneath it.

flowchart TB
    partner["Your organisation"]
    partner --> a["Customer A"]
    partner --> b["Customer B"]
    partner --> c["Customer C"]
    b --> b1["Customer B, Care department"]

Your operator creates your own organisation for you. Your operator is Artific: the party that runs the installation. Everything beneath it you create yourself: one organisation per customer, and another layer below where a customer needs one.

What each customer organisation has of its own¶

A key of customer A reaches only what belongs to customer A. When that key asks about your organisation or about customer B, Core answers 404, the same answer as for something that does not exist.

What you can do as the organisation above¶

You administer every organisation beneath yours. That means:

• creating, renaming, suspending and deleting an organisation;
• inviting its administrators and registering, rotating and withdrawing its keys;
• setting the capability ceiling: which features its keys may switch on;
• setting a monthly cost cap, in euro;
• reading its usage and audit trail, and adding up the usage of a whole branch;
• setting a markup on what it pays for usage (Models and routing);
• reserving parts, so the customer's own administrators cannot reach them:
  • Usage figures: the organisation's usage;
  • Audit trail: the events of calls. The trail of management changes stays the customer's;
  • Key management: changing keys, routing configurations and routers. Reading stays.

In the console you open a customer organisation from Organisations and work in its sections the way its own administrators do. You also see the customer's content there: knowledge, files, datastores and traces. Take that into account in your agreements with the customer.

With an API key the line is different. A key with the management capability administers organisations and does not read their content through the ordinary routes: no knowledge, prompts, files or conversations of the customer. Such a key can request and download an archive of a customer organisation, and that archive holds that content (Take your data with you). When your application needs to work inside a customer organisation, it registers a key there and calls as that key (Work inside an organisation below you).

You cannot suspend or delete your own organisation, and you do not set your own ceiling or cost cap. The organisation above does that, and for your organisation that is your operator. Where an organisation sits in the tree is changed only by your operator, also for an organisation below you.

The capability ceiling¶

A capability is a feature that is on or off, such as knowledge or tooling. Every organisation has a ceiling: the capabilities its keys may switch on. A new organisation starts with everything its parent may have; you take away what a customer should not have.

Core checks the ceiling when it is set: what you give a customer organisation must fall within the ceiling of the organisation directly above it. When you later narrow the ceiling of a parent organisation, the narrowing holds for every organisation beneath it from the next call: a capability is in force only where the organisation and every organisation above it permit it. The ceilings stored beneath it do not change, so widening the parent again gives each of them back what its own ceiling holds, as far as every organisation above it permits it.

Switching a capability off in the ceiling takes effect on the next call for every key of that organisation and of every organisation below it. The routes behind it answer 404. See Keys, capabilities and policy.

A policy works differently from the ceiling: the policy of an organisation above binds every organisation below it on each call, for the kinds of thing it holds a rule about, and nothing has to be adjusted below (Policy).

The terms¶

Multi-tenancy means one installation of Core serves several customers and keeps their data apart. In the API an organisation is called a tenant; its id starts with ten_.

Isolation is how an organisation's data is kept apart in the database. You choose one of two when you create the organisation, and the choice is fixed after that:

For your application the choice makes no difference: the API and the console work the same with both. Each organisation chooses for itself, whatever the organisation above chose.

Database is a separate fact. An organisation lives on the same database as the organisation above by default. Only your operator can give an organisation a database of its own; everything you then create beneath that organisation lives on that database too. When a customer needs its own database, ask your operator before you create the organisation.

How administrators sign in¶

An organisation's administrators sign in to the console with a password by default. An organisation can also let them sign in with its own identity provider -- OpenID Connect, Google Workspace or Microsoft Entra ID -- so its people use the account and second factor they already have at work.

Such a provider never creates an account. It signs in only people the organisation has already invited as administrators, matched on the email address the provider has verified, and only addresses in an email domain the organisation has proved it owns. It belongs to that one organisation: organisations below it do not inherit it, and someone who administers more than one organisation keeps signing in with a password. An administrator shares a sign-in link that leads straight to the provider, because the ordinary sign-in page lists no organisation's providers.

This is separate from the Identity providers an organisation registers for the people who use its applications through a key (Building for people): those tokens identify a subject on a call, never a person in the console.

Set one up in the console or with a key; what the administrator then sees is in Sign in.

How it fits together¶

A customer organisation inherits no library and no routing: no agents, prompts, skills or tools, and no routing configurations or routers from the organisation above. What you want to use at several customers, you share with a publication.

Five things do work from the top down:

• the capability ceiling bounds what you can give a customer organisation;
• a markup on everything below decides the price a customer sees (Models and routing);
• a new organisation lives on the database of the organisation above by default;
• a publication with Install automatically is installed in every new organisation beneath it (Sharing and reuse);
• an organisation without a notification address of its own uses that of the nearest organisation above that has one (Notification mail).

What a key reaches inside an organisation is in Keys, capabilities and policy; what you see of a customer organisation, in Insight.

Create a customer organisation¶

There are two ways, with the same result:

• In the console: Create an organisation on the Organisations screen.
• With a key: Create an organisation below you with POST /organisations. Your key needs the management capability.

A new organisation has the status Being provisioned until Core is done. You can already register keys in that time; they work once the status is Active.

Read on¶

Tutorial: Set up a new customer organisation.

• Manage organisations in the console: the tree, statuses, creating and deleting.
• Manage organisations through the API: the same actions through the API.
• An organisation's settings: ceiling, cap, retention, policy and reservations.
• An organisation's administrators and Keys.
• Sign in with your own provider: an organisation's own identity provider for its administrators.
• Sharing and reuse: installing the same thing at several customers.