DocsDocsStart

Teams, apps, and environments

Learn how workspace, app, route context, and runtime stage fit together before choosing SDK or API docs.

Start here when you know the storefront, integration, or operational surface you are working on, but still need to choose the right team, app, and runtime context.

The short model

A team is the top-level workspace: the business or organization boundary that owns related apps, people, configuration, and operational work.

An app is one concrete business surface inside that workspace, such as a public storefront, B2B portal, campaign experience, internal commerce tool, or another runtime that needs separate context.

An environment is the stage where that app is running or being tested. It usually means development, preview, or production configuration. Environment is important for safety, but it is not a replacement for team or app context.

Use this order when you are unsure:

  1. Pick the team that owns the work.
  2. Pick the app surface inside that team.
  3. Pick the environment or credential set you intend to use.
  4. Pick the API, SDK, Search, Media, Event, or integration surface for the job.

How context appears in APIs

You will see app context in two common forms:

  • Team slug and app slug identify a human-readable workspace/app pair.
  • App ID identifies one app directly, usually as a UUID.

The current public API surfaces use those forms differently:

SurfaceRoute contextUse it for
Management APIteam_slug and app_slugApp-owned operational records such as catalog, channels, markets, store groups, warehouses, orders, publishing rules, and DAM share-link administration.
Shopper APIapp_id, store_group, market, and localeStorefront reads where the same app needs shopper-facing catalog, redirect, facet, brand, series, or variant responses for a specific selling context.
Auth and account APIapp_idCustomer auth, user profile work, carts, organizations, wishlists, files, order lookup, and customer-group price lookup.
DAM APIapp_idFolder reads, media reads, media search, facets, and read-only shareable-link token routes.
Integrations APIapp_idConnector records, app-level stats, per-integration stats, sync jobs, sync status, cancellation, and verification.

This route shape follows the caller. Management work often starts from the workspace and app slug that operators recognize. Customer, media, shopper, and integration work often starts from the app ID that the calling runtime or token already knows.

Contract facts to keep in mind

Use these facts before copying an endpoint into code or an agent task.

  • Use team_slug and app_slug when the route manages the app through the workspace/app pair. A matching app slug in another team is not the same app.
  • Use app_id when the route is scoped directly to one app, such as Auth, DAM public reads, Integrations, and Shopper routes.
  • Shopper API responses depend on app_id, store_group, market, and locale. The route shape is /api/v1/omni/:app_id/:store_group/:market/:locale/....
  • Environment is the runtime stage you are calling, not the business surface itself. Public API paths select team/app or app/store-group/market/locale context; environment usually comes from the deployment, credential set, or connector configuration.
  • Keep development, preview, and production app IDs, tokens, OAuth clients, webhook secrets, and integration credentials separate.

Common mistakes to avoid

  • Treating team and app as interchangeable.
  • Using team_slug and app_slug for APIs that expect app_id.
  • Calling shopper routes with only app context.
  • Treating environment as a public API selector.

Where to go next

Teams, apps, and environments

# Teams, apps, and environments Start here when you know the storefront, integration, or operational surface you are working on, but still need to choose the right team, app, and runtime context. ## The short model A **team** is the top-level workspace: the business or organization boundary that owns related apps, people, configuration, and operational work. An **app** is one concrete business surface inside that workspace, such as a public storefront, B2B portal, campaign experience, internal commerce tool, or another runtime that needs separate context. An **environment** is the stage where that app is running or being tested. It usually means development, preview, or production configuration. Environment is important for safety, but it is not a replacement for team or app context. Use this order when you are unsure: 1. Pick the team that owns the work. 2. Pick the app surface inside that team. 3. Pick the environment or credential set you intend to use. 4. Pick the API, SDK, Search, Media, Event, or integration surface for the job. ## How context appears in APIs You will see app context in two common forms: - **Team slug and app slug** identify a human-readable workspace/app pair. - **App ID** identifies one app directly, usually as a UUID. The current public API surfaces use those forms differently: | Surface | Route context | Use it for | | --- | --- | --- | | Management API | `team_slug` and `app_slug` | App-owned operational records such as catalog, channels, markets, store groups, warehouses, orders, publishing rules, and DAM share-link administration. | | Shopper API | `app_id`, `store_group`, `market`, and `locale` | Storefront reads where the same app needs shopper-facing catalog, redirect, facet, brand, series, or variant responses for a specific selling context. | | Auth and account API | `app_id` | Customer auth, user profile work, carts, organizations, wishlists, files, order lookup, and customer-group price lookup. | | DAM API | `app_id` | Folder reads, media reads, media search, facets, and read-only shareable-link token routes. | | Integrations API | `app_id` | Connector records, app-level stats, per-integration stats, sync jobs, sync status, cancellation, and verification. | This route shape follows the caller. Management work often starts from the workspace and app slug that operators recognize. Customer, media, shopper, and integration work often starts from the app ID that the calling runtime or token already knows. ## Contract facts to keep in mind Use these facts before copying an endpoint into code or an agent task. - Use `team_slug` and `app_slug` when the route manages the app through the workspace/app pair. A matching app slug in another team is not the same app. - Use `app_id` when the route is scoped directly to one app, such as Auth, DAM public reads, Integrations, and Shopper routes. - Shopper API responses depend on `app_id`, `store_group`, `market`, and `locale`. The route shape is `/api/v1/omni/:app_id/:store_group/:market/:locale/...`. - Environment is the runtime stage you are calling, not the business surface itself. Public API paths select team/app or app/store-group/market/locale context; environment usually comes from the deployment, credential set, or connector configuration. - Keep development, preview, and production app IDs, tokens, OAuth clients, webhook secrets, and integration credentials separate. ## Common mistakes to avoid - Treating team and app as interchangeable. - Using `team_slug` and `app_slug` for APIs that expect `app_id`. - Calling shopper routes with only app context. - Treating environment as a public API selector. ## Where to go next - Need selling context next? Read [Store groups and markets](/start/concepts/store-groups-and-markets). - Need storefront implementation guidance for a specific app? Start with [React SDK latest](/react-sdk/latest). - Need REST contracts for a specific API area? Start with [APIs](/apis) and [Reference](/reference). - Need media routes? Start with [Media/DAM latest](/media/latest). - Need integration setup and sync behavior? Start with [Integrations](/integrations). - Need agent or MCP setup? Start with [AI](/ai).