# Organizations & projects

Organizations are tenant boundaries. Projects are the workspaces that own agent resources, credentials, and production evidence.

## Organizations

An **organization** is the tenant root. Its members, projects, GitHub
integration, and Data Plane deployments are isolated from every other
organization.

Organization roles such as `owner`, `admin`, and `member` control what people
can change. Members sign in through the dashboard or CLI.

### Adding a teammate

Membership is organization-wide: a member reaches every project in the
organization, so there is no per-project invite.

An owner or admin invites someone by email from
[organization settings](https://app.introspection.dev/organization/settings),
with a role of `owner`, `admin`, or `member`. Only an owner can grant `owner`.
An email domain already claimed by another organization is rejected.

To remove access, disable the member rather than deleting them. Disabling
revokes access, keeps their name on work they already did, and can be reversed;
deleting is for a member created in error.

## Projects

An **Introspection project** is the resource and authorization boundary inside
an organization. Recipes, runtimes, bindings, tasks, conversations, files,
judges, and experiments all resolve to one project. An organization can use
separate projects for different products, teams, or isolation requirements.

Do not map every product workspace to an Introspection project. A full-stack
application normally runs one project and passes the authenticated product user
as the runner identity. Product organization or workspace IDs remain
application metadata unless they represent a deliberate Introspection resource
boundary.

## Principals

People and applications act within a project through different principals:

| Principal | Role |
| --- | --- |
| **Member** | A person using the dashboard or CLI. |
| **Agent member** | The stable agent identity an API key or application acts as when it runs work. It also owns that agent's local development overlay. |
| **API key** | A project and environment-scoped credential linked to an agent member for trusted backend automation. |
| **Application** | A service-account or federated caller linked to an agent member for a full-stack or B2B2C application. |
| **End-user identity** | The user, anonymous visitor, or conversation that the runner's durable work belongs to. |

See [Authentication & Identity](/platform/authentication) for how each caller
authenticates and how Introspection establishes an end user's identity.

## Which project a command acts on

Every project-scoped CLI command resolves a project before it runs. The order is:

1. an explicit `--project` (`-p`) on the command,
2. otherwise `INTROSPECTION_PROJECT` from the environment,
3. otherwise the project selected when you logged in.

Run `introspection whoami` to see the active login and its project, and
`introspection login` again to select a different one.

**`bindings` and `api-keys` are the exception.** Both always act on the
project you logged in to and ignore `INTROSPECTION_PROJECT`. If the variable
is set to a different project they print a note on stderr and continue against
the login project — so a binding or key you believed you had scoped elsewhere
may have landed in the login project. Neither family accepts `--project`
either: changing project for them means a new login, not a per-command
selector. When working across projects, log in to the intended project before
running them, and treat that stderr note as a signal to stop rather than
something to override.

## How it fits together

```text
Organization
├── Members
└── Projects
    ├── API keys and applications
    ├── Recipes, runtimes, and bindings
    ├── Tasks, conversations, and files
    └── Judges and experiments
```

## Related

- [Authentication & Identity](/platform/authentication)
- [Runtimes & environments](/platform/runtimes)
- [Security & Data](/platform/security)

Organizations & projects

Organizations are tenant boundaries. Projects are the workspaces that own agent resources, credentials, and production evidence.

Organizations

An organization is the tenant root. Its members, projects, GitHub integration, and Data Plane deployments are isolated from every other organization.

Organization roles such as owner, admin, and member control what people can change. Members sign in through the dashboard or CLI.

Adding a teammate

Membership is organization-wide: a member reaches every project in the organization, so there is no per-project invite.

An owner or admin invites someone by email from organization settings , with a role of owner, admin, or member. Only an owner can grant owner. An email domain already claimed by another organization is rejected.

To remove access, disable the member rather than deleting them. Disabling revokes access, keeps their name on work they already did, and can be reversed; deleting is for a member created in error.

Projects

An Introspection project is the resource and authorization boundary inside an organization. Recipes, runtimes, bindings, tasks, conversations, files, judges, and experiments all resolve to one project. An organization can use separate projects for different products, teams, or isolation requirements.

Do not map every product workspace to an Introspection project. A full-stack application normally runs one project and passes the authenticated product user as the runner identity. Product organization or workspace IDs remain application metadata unless they represent a deliberate Introspection resource boundary.

Principals

People and applications act within a project through different principals:

Principal	Role
Member	A person using the dashboard or CLI.
Agent member	The stable agent identity an API key or application acts as when it runs work. It also owns that agent’s local development overlay.
API key	A project and environment-scoped credential linked to an agent member for trusted backend automation.
Application	A service-account or federated caller linked to an agent member for a full-stack or B2B2C application.
End-user identity	The user, anonymous visitor, or conversation that the runner’s durable work belongs to.

See Authentication & Identity for how each caller authenticates and how Introspection establishes an end user’s identity.

Which project a command acts on

Every project-scoped CLI command resolves a project before it runs. The order is:

an explicit --project (-p) on the command,
otherwise INTROSPECTION_PROJECT from the environment,
otherwise the project selected when you logged in.

Run introspection whoami to see the active login and its project, and introspection login again to select a different one.

bindings and api-keys are the exception. Both always act on the project you logged in to and ignore INTROSPECTION_PROJECT. If the variable is set to a different project they print a note on stderr and continue against the login project — so a binding or key you believed you had scoped elsewhere may have landed in the login project. Neither family accepts --project either: changing project for them means a new login, not a per-command selector. When working across projects, log in to the intended project before running them, and treat that stderr note as a signal to stop rather than something to override.

How it fits together


Organization
├── Members
└── Projects
    ├── API keys and applications
    ├── Recipes, runtimes, and bindings
    ├── Tasks, conversations, and files
    └── Judges and experiments