Commercetools User Management: Roles and Permissions

Manage teams, permissions, and API client scopes in commercetools. Covers the Merchant Center permission model, project-level access, and OAuth scope...

commercetools uses a project-based permission model managed through the Merchant Center and a separate OAuth-based system for API clients. User access is controlled through Teams that grant permission sets scoped to specific projects within an Organization.

Permission model overview

commercetools separates access into two layers:

Merchant Center access -- Human users log in to the Merchant Center UI. Access is controlled through Organization membership, Team assignment, and Permission Sets that define what the user can do within each project.
API Client access -- Machine-to-machine access via OAuth 2.0 client credentials. Each API client has specific scopes that control which resources and actions it can perform.

Organizations contain Projects, and Teams bridge users to projects with defined permissions.

Organization and team structure

The hierarchy works as follows:

Organization -- Top-level container. Managed by Organization Admins. Contains one or more projects and teams.
Teams -- Groups of users with a shared set of permissions applied to one or more projects. A user can belong to multiple teams.
Projects -- Individual commercetools environments (production, staging, etc.). Each project has its own data, API clients, and configuration.

Organization-level roles:

Organization Admin -- Full control over the organization: manage teams, members, projects, and billing. Can create and delete projects.
Organization Member -- Can view organization details but cannot manage teams or projects. Must be assigned to a Team to access any project.

Permission sets for teams

When creating or editing a team, you assign Permission Sets that control what team members can do within assigned projects. Key permission groups include:

Manage Project Settings -- Modify project-level configuration including currencies, languages, countries, and channel setup
View/Manage Products -- Access product catalog, product types, categories, and product variants
View/Manage Orders -- Access order data, create orders, process returns and refunds
View/Manage Customers -- Access customer accounts, groups, and customer-specific pricing
View/Manage Discounts -- Create and manage cart and product discounts
Manage API Clients -- Create, view, and delete API clients and their scopes (critical permission -- controls programmatic access)
View/Manage Types and Custom Fields -- Define and modify custom types used across resources
Manage Extensions and Subscriptions -- Configure API extensions (synchronous) and subscriptions (async messaging)
View Developer Tools -- Access the API playground and GraphQL explorer in the Merchant Center

Each permission is typically split into View (read-only) and Manage (read-write) variants.

Managing users in the Merchant Center

Adding a user:

Go to Organization Settings > Members
Click Add Member and enter the user's email
The user receives an invitation to create a commercetools account (or log in with an existing one)
Assign the member to one or more Teams under Organization Settings > Teams

Modifying access:

Navigate to Organization Settings > Teams
Select the team, then adjust its Permission Sets or the projects it applies to
Add or remove members from the team

Removing a user:

Go to Organization Settings > Members
Remove the member from all teams first, then remove them from the organization
Review and rotate any API clients the user created

API client management

API clients are created per-project and use OAuth 2.0 client credentials flow. Manage them under Settings > Developer settings > API clients within a project.

Each API client specifies:

Scopes -- Granular resource-level permissions following the pattern manage_products:{projectKey}, view_orders:{projectKey}, etc.
Client ID and Secret -- The secret is shown only once at creation
Token endpoint -- https://auth.{region}.commercetools.com/oauth/token

Common API scopes include:

manage_project:{projectKey} -- Full project access (use sparingly)
view_products:{projectKey} / manage_products:{projectKey}
view_orders:{projectKey} / manage_orders:{projectKey}
manage_api_clients:{projectKey} -- Can create other API clients (high-privilege)
view_audit_log:{projectKey} -- Access audit trail data

When offboarding a developer, delete any API clients they created and rotate credentials for shared API clients.

Analytics and tracking permissions

commercetools is a headless commerce platform, so analytics implementation happens in the frontend layer rather than in commercetools itself:

Event tracking (page views, add-to-cart, purchases) is implemented in your storefront application code, not in the Merchant Center
Order and conversion data can be pulled from the commercetools API for analytics pipelines -- this requires an API client with view_orders scope
Custom fields on orders and carts can carry UTM parameters or session IDs for attribution -- modifying custom field definitions requires manage_types permission
Subscriptions can push events (order created, payment received, etc.) to external analytics systems via Google Pub/Sub, AWS SQS, or Azure Service Bus -- configuring this requires manage_subscriptions permission

A team member who only needs to view sales data should be on a team with View Orders and View Customers permissions. Setting up analytics integrations requires Manage Extensions and Subscriptions plus Manage API Clients.

SSO and security

commercetools Merchant Center supports SSO via SAML 2.0 and OpenID Connect on Enterprise plans
SSO is configured at the Organization level under Organization Settings > SSO
When SSO is enforced, all organization members must authenticate through the configured identity provider
MFA is available for non-SSO accounts via the user's profile settings
Audit logs are available under Settings > Audit log within each project, tracking who changed what and when