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

# Core Concepts

> The primitives VaultGraph is built around

VaultGraph is a multi-tenant MCP gateway for e-commerce merchants. Everything is organized around a tenant hierarchy, a commerce backend per deployment, and API-key authentication.

## Organization

An **organization** is a merchant's tenant — the top-level workspace. It owns team members, billing, and one or more shops. All access is scoped to an organization.

## Shop

A **shop** is a storefront that belongs to an organization. An organization can have multiple shops.

## Deployment

A **deployment** is an environment of a shop — for example `dev`, `staging`, or `production`. A shop can have several deployments. Each deployment is one MCP endpoint and holds its own API keys and commerce backend configuration.

## Commerce backend

A **commerce backend** is what fulfills the catalog, cart, checkout, and order tools exposed on a deployment's MCP endpoint. Each deployment has at most one. Two kinds:

* **Custom** — your own storefront, reached over the [remote adapter protocol](/remote-adapter-protocol). Configure an HTTPS endpoint and a shared signing secret in the portal; the gateway calls your endpoint on every tool invocation. Implement the methods with [`@vaultgraph/sdk/adapter`](/sdk).
* **Demo** — an ephemeral built-in backend used by the showcase widget. Useful for evaluation; not for production.

A deployment without a configured backend returns `commerce_backend_not_configured` on every commerce call.

## API keys

VaultGraph uses API keys for authentication. There are two kinds:

| Kind                 | Prefix | Scope                  | Use                                                         |
| -------------------- | ------ | ---------------------- | ----------------------------------------------------------- |
| Organization API key | `vk_`  | The whole organization | Org-wide operations, such as listing shops                  |
| Deployment API key   | `dk_`  | A single deployment    | Authenticates an agent's MCP session against the deployment |

A deployment can have multiple deployment API keys at once, which makes key rotation straightforward. Both kinds of key carry coarse-grained `scopes` that determine what the key is allowed to do.

Keep API keys server-side only. Never expose them in browser or client code.