---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/production/projects-and-namespaces
markdown_url: https://steel.dev/docs/production/projects-and-namespaces.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Projects and namespaces
description: An organization holds projects, and a project holds namespaces. Learn what each one isolates and how API key scopes follow them.
summary: An organization holds projects, and a project holds namespaces.
type: concept
reviewed: 2026-11-12
prerequisites: []
related:
  - https://steel.dev/docs/production/checklist.md
  - https://steel.dev/docs/production/run-sessions-at-scale.md
  - https://steel.dev/docs/production/make-sessions-faster-and-cheaper.md
  - https://steel.dev/docs/production/session-cost.md
  - https://steel.dev/docs/production/track-cost-per-customer.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# Projects and namespaces

Steel groups your work by organization, project and namespace. An organization is your account. A project is a group inside the organization. It has its own sessions, profiles, credentials and API keys. A namespace is a label inside a project that selects which stored credentials a session uses. Use projects to keep apps or environments apart. Use namespaces to keep your own users' logins apart inside one app.

## Organization, project, namespace

```text nocopy
organization
  members, billing, files, extensions
  project (one is the default project)
    sessions, profiles, API keys
    namespace "default"
      credentials
    namespace "example:jane"
      credentials
```

- The organization is what you sign up for. It has the members, the plan and the bill. [Organizations and members](https://steel.dev/docs/account/organizations-and-members) covers it.
- A project belongs to one organization. Every organization has a default project, and you can add more. Each project has an `id`, a `name` and a `slug`. [Projects](https://steel.dev/docs/account/projects) shows how to create and use them.
- A namespace is a name that a session and its credentials share. Namespaces need no setup. A session that names none uses `default`. A namespace name can use letters, digits, `_`, `.`, `:` and `-`, and it cannot be `.` or `..`.

## What a project isolates

A project holds these, and they do not reach across projects:

| Resource | How it follows the project |
| - | - |
| Sessions | A session runs in one project. A key for one project sees and releases only that project's sessions. |
| Profiles | A profile belongs to one project. A session can load only a profile from its own project. |
| Credentials | A credential belongs to one project, and to one namespace in it. |
| API keys | A project key works in its project only. |
| Quick actions | Each request runs in a project. |

Uploaded extensions belong to the organization, not to a project, and so do the files that you upload to the organization's file storage.

A project limits what its keys can reach. Give each app or each environment its own project and its own key. A key that leaks then exposes one project, not the whole organization.

## What a namespace isolates

A namespace selects credentials. A session uses only the credentials stored in its own project and its own namespace, for the page's origin. The match is exact. No namespace inherits from another, and there is no wildcard.

Namespaces let you store a login for each of your users on the same site. Store Fred's login under `example:fred` and Jane's under `example:jane`. A session created with `namespace: "example:fred"` fills in Fred's login only.

A namespace is not an access control. Any key that can create a session in the project can name any namespace. Your backend decides which namespace each request may use. Do not use a namespace from an untrusted client without checking it. [Credentials](https://steel.dev/docs/logins/credentials) shows how to store a login and use it in a session.

## API key scopes

A project key reaches one project, and an organization key reaches every project in the organization. [Choose a scope](https://steel.dev/docs/account/api-keys#choose-a-scope) lists what each key can do and who can create it.

When you create a session, Steel picks its project in this order:

1. A project key: the key's project.
2. An organization key: the project in `projectId`. Without `projectId`, the request fails with `400`. The same holds for Quick actions, profiles and credentials.
3. A sign-in to the dashboard: the project in `projectId`, or the default project.

The session's namespace is the one in `namespace`. Without `namespace`, the session uses the project's namespace, which is `default` for a new project.

The MCP server follows the same rules. When a client signs in, you pick one project, and the sessions that the agent creates run there. A client that sends an API key works in the key's project, so it needs a project key.
