# Organisations and access

> How access is organised on a server: personal vaults, organisations, permissions, teams, spaces, access tokens and the instance admin panel

Notes live in spaces, and spaces belong to organisations. Whether someone can see a note depends on their place in the organisation and in the space. As an operator you mostly need this to answer questions and to set `allowed_orgs` on [publish targets](../running-a-server/publish-targets.md). The user-facing side is in [Sharing and permissions](../using-kribble/sharing-and-permissions.md).

## Personal vaults

Every account gets a personal vault when it is created: an organisation of its own, shown as **Personal**, with one space called **My Notes**.

- Its internal name is generated, like `vault-3f9a1c0b7d2e`. The owner can rename it once, before publishing any site from it. You need this name to allow a vault in a publish target's `allowed_orgs`. The admin panel's Organizations tab shows it.
- Sites published from a personal vault are served at `/p/~<username>/<slug>/`.
- The owner can invite people into their vault and then share individual spaces with them. Member permissions can't be changed in a personal vault.

## Organisations

Any signed-in user can create an organisation and becomes its **owner**. The name, used in URLs, is 1 to 63 characters of lowercase letters, digits and hyphens, and some names are reserved.

The owner can do everything in the organisation, sees every space, and is the only one who can change its profile and theme, manage its PDF templates and delete it. The owner can't be removed and their permissions can't be changed.

Other people join through an invitation (by email, valid 7 days), are added directly by someone with **Invite members**, or are added by an LDAP group mapping ([Authentication](../running-a-server/authentication.md)). Each member has a set of permissions:

| Permission | Bit | Allows |
| --- | --- | --- |
| Invite members | 1 | Inviting people and adding existing users to the organisation |
| Remove members | 2 | Removing members |
| Create teams | 4 | Creating teams |
| Manage own teams | 8 | Changing teams the member belongs to (whoever created a team can always change it) |
| Manage all teams | 16 | Seeing and changing every team, and changing members' permissions |
| Create spaces | 32 | Creating spaces |
| Manage own spaces | 64 | Managing spaces the member can access |
| Manage all spaces | 128 | Seeing and managing every space in the organisation |
| Manage access tokens | 256 | Seeing and revoking everyone's access tokens in the organisation |

The organisation settings offer two presets: **Admin** (all permissions) and **Member** (none). Members added by an invitation get the permissions chosen in the invitation. Members added by LDAP group sync get none.

:::callout{type="warning"}
**Manage all teams** also lets a member change other members' permissions, within their own: they can't change their own, grant a permission they don't have, or change someone who has one they lack. Only the owner is unrestricted.
:::

Removing a member from an organisation also revokes the access tokens they created in it, and takes away their access to its published sites limited to space members.

## Teams

A team is a named group of organisation members. Teams are used to give a group access to a space in one step. They are also the target of LDAP group sync (`[[ldap.team_map]]`), which only adds people to teams that already exist and never removes them.

## Spaces

A space is a tree of folders and notes. Someone can open a space if they are:

- the organisation's owner,
- a member with **Manage all spaces**,
- a direct member of the space, or
- in a team that is a member of the space.

Each direct or team membership can be marked **admin**. Space admins manage the space's members and settings, and can publish the space and its notes as sites. Members with **Manage own spaces** can manage spaces they can access, and the person who created a space can always manage it.

Search only returns notes from spaces the person can open.

## Access tokens

Access tokens let the CLI, CI jobs, the desktop app's synced folders and AI agents (over MCP) act for a person. A token:

- looks like `kb_` followed by 64 hex characters. Kribble stores only its SHA-256 hash, so it is shown once, when it is created.
- belongs to one organisation and acts with its creator's permissions there. It can't do more than its creator.
- can be limited to some spaces.
- can instead reach **all of the creator's organisations**, including ones they join later. `kribble login` creates these when the person picks **All my organizations**. They are listed under the personal vault.
- never expires, or expires after 30 days, 90 days or 1 year (any number of days through the API).
- records when it was last used.

Tokens are created in the organisation settings under **Access Tokens**, or by `kribble login` ([Authentication](../running-a-server/authentication.md)). Everyone sees and revokes their own tokens there. Members with **Manage access tokens** see and revoke everyone's.

| Scope | Allows |
| --- | --- |
| `read` | Reading notes and comments over MCP and the CLI, `kribble pull` and exports, and reading sites limited to space members with the CLI |
| `write` | Creating and editing notes and comments over MCP and the CLI, `kribble push`, and deploying and rebuilding sites from the CLI or MCP |
| `import` | Importing markdown into a space (`POST /api/v1/spaces/{spaceId}/import`) and `kribble push` |
| `publish` | Publishing or rebuilding a space's site (`POST /api/v1/spaces/{spaceId}/publish`), and deploying from the CLI or MCP |

The scope choices in the web app are **Publish + Import** (the default), **Publish only**, **Import only**, **Read only (MCP)**, **Read + Write (MCP agents)** and **All scopes**. `kribble login` asks for `read,write`, which the person can narrow to `read`. The MCP endpoint `/mcp` needs at least `read`.

A request with a revoked or expired token gets `401`. A token without the needed scope gets `403`.

## The instance admin panel

Instance admins open **Instance admin** in the user menu (`/admin`). [Authentication](../running-a-server/authentication.md) explains how someone becomes one. The panel has four tabs:

| Tab | Shows | Actions |
| --- | --- | --- |
| Users | Every account: email, username, display name, sign-in source (local or the `[[ldap]]` name), admin status (marked when it comes from `[admin].emails`), created date. Searchable. | Promote to instance admin, demote. Nobody can demote themselves. |
| Organizations | Every organisation: name, display name, owner's email, member, space, team and published-site counts, created date. Searchable; personal vaults can be hidden. | None |
| Auth Sources | The loaded `[[ldap]]` sources with all their settings and team mappings. Bind passwords are never shown, only whether one is set. | None. Edit `config.toml` and restart. |
| System | Version, mode, uptime, the number of site builds `queued` or `building`, the storage backend, whether Redis and Meilisearch are configured, and counts of users, admins, organisations, spaces, notes and LDAP sources. | Refresh, and **Rebuild index**, which rebuilds the search index from the database (see [Troubleshooting](../running-a-server/troubleshooting.md)) |

An instance admin can't read notes, change organisation membership, reset passwords or delete accounts from the panel. Admin status gives no access to organisations; an admin sees only what their own memberships allow. People delete their own account in their profile.