> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blobhub.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Organizations & access

> Who can reach what: organizations, visibility, members and roles, API keys, and the perimeter only a person may change.

export const Shot = ({src, alt, caption}) => <Frame caption={caption}>
    <img className="block dark:hidden" src={src} alt={alt} />
    <img className="hidden dark:block" src={src.replace(/\.(png|svg)$/, '.dark.$1')} alt={alt} />
  </Frame>;

An organization is where a team's work lives, and where every access decision starts. Everything you build, such
as a workflow, a schedule or a model, belongs to one organization for its whole life, and whether someone may read
it, change it or decide who else may is settled by their standing there.

## Organizations

An organization is the first thing that has to exist, since nothing you build can be created outside one.
Whoever creates one holds `owner` over it automatically, with nothing to configure, and anyone else who needs access
is added as a member. Only a person can create one: an anonymous reader creates nothing, and a
[service account](/general/service-accounts) can never own an organization.
[Create Organization](/rest-api/orgs/create-org) is the route.

An organization is the product's access boundary, not a company. A company may hold several, one per team or
product, each with its own blobs, members, API keys, credentials and limits. Nothing sits above the organization:
there is no company record that groups them, and a grant in one organization says nothing about another.

## Visibility

An organization is public or private, and so is each blob in it. A private organization can be seen only by its
owner, its members and a key that reaches it. A public organization can be seen by anyone, signed in or anonymous,
but that alone opens none of its content: its owner and members see every blob in it, and everyone else reads only
the blobs that are public too. An outsider therefore reads a blob only when the blob and its organization are both
public. A public blob in a private organization stays out of reach, and so does a private blob in a public one.

Visibility grants read and nothing more: being public lets no outsider change anything. It is a floor for a caller
with no standing at all, and an API key scoped to an organization or a blob never falls back on it, so such a key
reads nothing outside its own target, public or not. Changing visibility is publishing, one of the changes on
[the access perimeter](#the-access-perimeter).

## Members and roles

Standing on an organization or a blob is a role, on a ladder of four, each rung including the ones below it:

* **`read`** sees the target and what it holds.
* **`write`** also changes it and its content.
* **`admin`** also governs its boundary: its members, its API keys, whether it exists at all and, on an
  organization, the blobs created in it.
* **`owner`** is never granted. An organization's creator holds it, and a blob has none of its own: the owner of its
  organization stands there.

A member is a person or a service account given `read`, `write` or `admin` on one organization or one blob. There is
no invitation: an admin adds the member directly, with [Add Member](/rest-api/shared/add-member) or the **Access**
section of the organization's or the blob's settings, and removing the membership takes the access away.

Standing on an organization reaches every blob in it, so organization membership is the common case. A membership on
a single blob is the exception: it gives someone that one blob, at its role, without the rest of the organization.

<Shot src="/general/images/organizations-and-access/members.png" alt="An organization's members and their roles" caption="Access is granted by membership, the same way for a person and a service account." />

## API keys

An API key lets a program call the API without anyone signing in. It is minted for one target, an organization, a
blob or a user, with one role, `read`, `write` or `admin`, and neither changes afterwards. Minting a key takes `admin`
on its target, and its secret is returned once, when it is minted, and never again:
[Create API Key](/rest-api/shared/create-api-key) is the route, and the **API Keys** section of an organization's, a
blob's or your own settings does the same.

A key scoped to an organization or a blob carries its answer with it. It reaches that target at its role and nothing
else, never through a membership looked up later, and it never reaches public content outside its scope. A key
scoped to a user resolves the way that user's sign-in does, memberships and public content included, capped at the
key's own role. That is how a service account authenticates, with a key of its own.
[Authentication](/rest-api/authentication) covers every way a request can authenticate.

A key minted for an organization or a blob writes under the name of the person who minted it, so everything a
pipeline does with it is attributed to that person. A service account gives automation an author of its own.

<Shot src="/general/images/organizations-and-access/api-keys.png" alt="The form that creates an organization's API key: a role and an optional description" caption="A key is scoped to one target with one role, fixed when it is created." />

## The access perimeter

A few changes decide who else can get in: minting and revoking API keys, storing and removing
[credentials](/general/credentials), granting and revoking membership, creating and retiring accounts, and
publishing. Together they are the access perimeter, and each one needs a person behind the request. A person passes,
whether signed in, on a key that authenticates as them, or [acting as a service account](/rest-api/auth/impersonate).
A service account's own key is refused, whatever role its memberships give it, so a key left on a CI runner or a
worker can do the work it was given and cannot change who can reach what.

Publishing is the one perimeter change gated at `write` rather than `admin`. Reads are never on the perimeter:
listing members, keys or credentials is ordinary work for a caller with the standing to see them.
[The access perimeter](/general/service-accounts#the-access-perimeter) on Service accounts lists every operation on
it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.