Child organizations¶

A child organization is an organization below yours: one of your customers, if you are a partner, or a department of your own organization. This page shows how to find them, create a new one, with or without a plan, and how to suspend, resume or delete one. What organizations and partners are is explained in People and organisations.

You work in a child organization with the roles you hold in your own organization with reach descendants, without having to be a member there (Partners). You open it like any organization: everything inside it, such as its settings, theme, members and plans, you manage on its own pages.

Who may do what¶

You only see the Create child organization button when you may create one. A row's menu only shows what you may do with that organization.

The list¶

Open Organization management and then Child organizations. The entry is in the menu as soon as your organization has child organizations you see, or as soon as you may create one.

• Search by name keeps the organizations whose name contains your text, in any case.
• Every level below also shows the organizations below your child organizations, down to the deepest level. That way you find a customer by name without opening its partner first.
• Switch to this organization in a row's menu, or a click on the name, opens that organization.

Create a child organization¶

1. Choose Create child organization.
2. Fill in the Name. It is unique below your organization.
3. Choose who becomes the first administrator. Tick I will be the first administrator myself to be that yourself, or fill in the Email address of the first administrator. They get the role org-admin with reach descendants.
4. Choose the Data separation: Shared, kept apart per organization (the default) or A schema of its own. It is fixed once the organization exists.
5. Add Labels if you like: one label and value per row. Rules about organizations read them (Rules).
6. If you may give plans, choose a Plan and, for a trial, the date it ends (Trial ends on). Without a plan the organization gets your own organization's service.
7. If you may give plans and want a demo, fill in Demo until. After that day the organization is suspended, and erased thirty days later unless you convert it. Leave it empty for a regular organization.
8. Choose Create child organization.

OS creates the organization, the invitation and the plan at once: if the plan is refused, nothing is created. If you are the first administrator yourself, there is no invitation: you are a member and administrator as soon as the organization is set up. Typing your own address works the same, if it is verified on your account. Any other address gets an invitation, and becomes a member only when that person accepts it. The new organization is listed as Being set up until it is ready, and is Active after that.

Suspend, resume and delete¶

• Suspend this organization stops it, with every organization below it: requests in them are refused until you resume it.
• Resume this organization starts a suspended organization again.
• Delete this organization asks for confirmation first. An organization with child organizations of its own can only be deleted once those are gone. It is then erased and listed as Being deleted until that is done.

Become a member and leave¶

You need no membership to work in a child organization, but you can become a member of one: then it is on your own list of organizations, you work in it with its own rights, and its administrators see you among its members.

• Become a member of this organization in a row's menu makes you a member, with the role member and nothing more. Your roles from above keep applying; anything more in that organization its own administrators give you. Its administrators are told that you joined.
• Leave this organization in the menu of a row where you are a member asks for confirmation, then ends your membership. What you made in it is kept. The last administrator of an organization cannot leave; give another member org-admin first.

You cannot become a member again this way while an administrator has deactivated your membership, nor during a support session. An organization that requires its company login only takes you in when you signed in through that login. If an invitation to the organization waits for you, Become a member of this organization accepts it at once, with what it holds; your address must be verified on your account for that.

Settings per child organization¶

On a wide screen you set a few things for each organization in its row, as in Artific Platform. Whoever may not change a value sees it as a label.

• Demo: choose another end date, or remove it with the cross. Removing it converts the demo into a regular organization (A demo's end date).
• Cost insight: the furthest the organization may show costs and token usage. It still chooses who sees them, but never beyond this, and that holds for the organizations below it too. Set it to Nobody and nobody there sees costs, even if its administrators chose otherwise; their choice is kept for when you widen it again.
• Session logs: off means nobody in that organization, its administrators included, can read someone else's chats with an assistant, whatever its rules say. Everyone then sees only their own chats in the session logs. This holds for the organizations below it too, and for whoever calls Core directly. While it is off, OS refuses a rule or role that would open it again.
• Plans: tick a plan to give it from now on, untick it to take it back. A plan an organization above you gave stays ticked and locked: only that organization can take it back. A trial shows its end date.
• Restrictions for administrators in a row's menu: what that organization's own administrators may not do, namely View usage, View the audit trail and Manage keys. OS reads the current value when you open the dialog.

Every change goes on that organization's audit trail, with who made it, and never with the value.

Through the API¶

The examples use $OS, $TOKEN and $ORG as in Manage groups.

curl -s "$OS/api/v1/organisations/$ORG/organisations?scope=descendants&q=acme" \
    -H "Authorization: Bearer $TOKEN"

{"items": [{"id": "org_...", "name": "Acme", "parent_id": "org_...", "status": "active",
            "child_count": 2, "reach": "from_above", "plans": ["Basic"],
            "primary_colour": "#287deb", "may_join": true,
            "parent_allowed_actions": ["see", "write", "delete"],
            "child_allowed_actions": ["see", "write", "delete"]}],
 "next_cursor": null}

• scope is children (the default: only those directly below) or descendants (every level).
• q keeps the names that contain the text; status keeps one status.
• The list is sorted by name and comes in pages: pass next_cursor as cursor for the next one. A page may hold fewer rows than limit while next_cursor continues.
• reach is member or from_above; plans is empty when you may not see that organization's service. parent_allowed_actions says whether you may suspend and resume it (write) and delete it (delete).
• child_allowed_actions is on every organization: when it holds write, you may create an organization below it.
• primary_colour is the color shown in the list, null for the platform's own color; may_join says whether you may become a member of it.

Create an organization, with a plan for a trial:

curl -s -X POST "$OS/api/v1/organisations/$ORG/organisations" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d '{"name": "Acme", "first_admin_email": "admin@acme.example",
         "plan_id": "pln_...", "plan_ends_at": "2026-12-31T00:00:00Z"}'

Send "first_admin_self": true instead of first_admin_email to be the first administrator yourself; one of the two is required. isolation (shared or schema) and labels are optional. Which plans you can give is read with GET /api/v1/organisations/$ORG/assignable-plans (Plans and exceptions). Suspending, resuming and deleting are POST …/organisations/{id}/suspend, POST …/resume and DELETE /api/v1/organisations/{id}. Becoming a member is POST …/organisations/{id}/join and leaving POST …/organisations/{id}/leave.

To create a demo, send "demo_ends_at": "2027-01-31T00:00:00Z" when creating. Every row of the list also has demo_ends_at, cost_visibility_limit, session_logs_readable, plan_assignments (each plan with id, ends_at and may_take_back) and service_parent_actions. Cost insight and session logs are read with GET /api/v1/organisations/{id}/limits and changed with PATCH, beside the cost cap and admin_restrictions:

curl -s -X PATCH "$OS/api/v1/organisations/$CUSTOMER/limits" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d '{"cost_visibility_limit": "off", "session_logs_readable": false}'

When OS refuses¶