A Salesforce namespace is the short, permanent prefix that Salesforce puts in front of every packaged component's API name, so your app's Invoice__c becomes acme__Invoice__c in every customer org. Salesforce's 1GP packaging guide calls it "a one to 15-character alphanumeric identifier that distinguishes your package and its contents from packages of other developers on AppExchange." The part that matters for a SaaS company is permanence. The Apex Developer Guide says "Once namespaces are assigned, they cannot be changed."
So the namespace is a product decision for founders and CTOs shipping the native integration enterprise customers asked for, not a setup step. You pick it before your first managed package, every customer's reports, flows and integrations reference it, and it decides which of your future packages can share code or even install side by side. If you'd rather not learn this on your first package, Appnigma's marketplace apps team builds "A Salesforce managed package or HubSpot app built around your product and customer workflows," namespace setup included.
Updated October 2026. Checked against the 1GP and 2GP packaging guides, the Salesforce DX Developer Guide, the Apex Developer Guide and the REST API Developer Guide. The earlier version was a short definition with no sources. This version adds the naming rules and how 1GP and 2GP differ. It also covers registering and linking a namespace, what it changes in a customer org, and the collisions that block installs.
What a namespace changes inside a customer's org
The prefix shows up everywhere your package touches a customer org, and each surface uses a different syntax. Salesforce "automatically prepends your namespace, followed by two underscores ("__"), to all unique component names" (Register a Namespace for a First-Generation Managed Package). Unique components are things like custom objects, custom fields, custom links and validation rules.
| Where | What the customer org sees with namespace acme | Source |
|---|---|---|
| Custom object or field API name | acme__Invoice__c, acme__Amount__c | Namespaces for 2GP |
| Calling your Apex from the customer's code | acme.InvoiceService.post(args), global methods only | Namespace Prefix |
| Your Apex referring to your own fields | Amount__c, no prefix needed | Namespace Prefix |
| Your Lightning web components in your own code | Always c, as in c-invoice-tile | Component Namespaces |
| REST queries from your SaaS backend | acme__Amount__c, or Amount__c with a default namespace header | Call Options Header |
Two rows trip up SaaS teams. Inside your package, Apex assumes your own namespace, because "the parser assumes that the namespace of the current object is the namespace of all other objects and fields unless otherwise specified." Outside the package it doesn't. Your backend's REST calls into a customer org must use the full acme__Amount__c name, unless you set defaultNamespace=acme in the Sforce-Call-Options header. With that header, "the request resolves field names in managed packages without specified namespaces." The same REST guide says that field is not supported in Bulk API and is ignored for describe calls. A sync that also runs Bulk API jobs, or maps fields from describe results, needs the full names anyway, so most teams store the prefixed names and skip the header.
LWC is the other surprise. Salesforce's guidance is "To reference your own components, always code with the c namespace prefix," even inside a namespaced package. Customers who use your components from outside the package reference them by your namespace instead.
Namespace rules, and why you can't change a prefix
Most "how do I change my namespace prefix" questions have the same answer. You can't, and you can't reuse one either. Link a Namespace to a Dev Hub Org warns "After you associate a namespace with an org, you can't change it or reuse it." A new prefix means a new package and new API names. Salesforce's AppExchange Object Prefixes and the API page shows what renamed API names cost a customer. They have to "export your data" and uninstall the old package before installing the new one. It also resets your security review, since a resubmission "qualifies for a follow-up review" only "If the package ID and namespace don’t change" (Submit Your Solution for a Follow-Up Security Review). That is why the format rules deserve five minutes before you register.
The 1GP registration page allows one to 15 alphanumeric characters starting with a letter, with no two underscores in a row. It is case-insensitive, so ABC and abc collide, and it "must be globally unique across all Salesforce orgs." Salesforce also asks you not to "name a namespace after a person."
Shorter is better than clever. Customers type the prefix in SOQL and formula fields and read it in every error your package throws, and every packaged field name carries it plus two underscores. A product codename you might drop in a rebrand is the worst choice, since the prefix outlives it. If you only need one to experiment, the Dev Hub page says to "choose a disposable namespace" and never one you'll want for a production package.
How 1GP and 2GP treat namespaces differently
A namespace holds one package in first-generation packaging (1GP) and many in second-generation packaging (2GP). Salesforce's comparison of 1GP and 2GP sets out the differences.
| First-generation managed package (1GP) | Second-generation managed package (2GP) | |
|---|---|---|
| Where the namespace lives | "The namespace of the managed package is created in the packaging org" | Created in a namespace org and linked to the Dev Hub, which can hold "multiple namespaces" |
| Packages per namespace | "A namespace can be associated with only one package" | "Multiple packages can use the same namespace" |
| Sharing Apex between your packages | "Global Apex is the only way to share code across packages" | Public Apex with @NamespaceAccessible |
| How a package gets its namespace | Set in the packaging org | Read from sfdx-project.json when you run sf package create |
The difference shows up the day you ship a second product. Take a base app plus two add-ons, a common shape for SaaS vendors with paid tiers. In 1GP that is three namespaces, three sets of prefixed API names for customers to learn, and every method the add-ons call on the base has to be global. In 2GP it is one namespace, and the add-ons call the base through public classes marked @NamespaceAccessible. Salesforce notes you can add or remove that annotation "at any time, even on managed and released Apex code" (Namespace-Based Visibility for Apex Classes in 2GP). Global methods can't be taken back that way.
The 2GP rule has a hard edge. "A single managed 2GP package can't be associated with more than one namespace," and "After a namespace is associated with a managed 2GP, the association can't be changed" (Namespaces for 2GP).
Unlocked packages are the exception to "namespace required." The Salesforce DX guide says "You can choose to create unlocked packages with or without a specific namespace." That suits internal teams. A product you sell to customers belongs in a managed package, which needs one. If you're still choosing the packaging model, our guide to managed packages covers the trade-offs.
One namespace or several for your packages?
For most SaaS companies, one namespace for every managed 2GP package is the right default. Salesforce recommends it because "sharing of code is much easier if your package shares the same namespace" (Create and Register Your Namespace for 2GP). The cost of sharing is that every package in the namespace draws from one pool of API names, so two teams can't both ship an Invoice__c. Code sharing usually wins that trade, because the alternative is making shared Apex global. Salesforce's global Apex best practices say you can't delete a released global class or method, or change its signature.
Split when a product could change owners. Salesforce's own example is that "having a unique namespace for that package enables you to transfer the namespace with the package." If two products share one namespace, you can't hand a buyer half of it, so anything you might sell, spin off or license to a partner gets its own prefix from day one. The mechanics exist. Salesforce supports moving a managed 2GP to another company's Dev Hub through a Support case, which "provides a way to sell a managed 2GP package to a different company" (Transfer a 2GP Managed Package to a Different Dev Hub). The same page limits it to packages that "have passed AppExchange security review" and rules out 2GP packages converted from 1GP. So the namespace split is a question for the founders and the board, answered before the first sf package create, not during diligence.
A 1GP package already in market also forces the issue. Its namespace belongs to that one package, so a new 2GP product either gets its own namespace or waits until you convert the 1GP package. Converting keeps the namespace you have. The 1GP to 2GP conversion steps start by linking "the namespace of your managed 1GP to the Dev Hub in your Partner Business Org (PBO)." Customers keep the same API names, so their reports and integrations don't break. Our 1GP to 2GP migration guide walks through the rest.
How to create, register and link a namespace for 2GP
A 2GP namespace is created in one org and used from another, and the org that holds it matters more than the clicks. Per Create and Register Your Namespace for 2GP, you sign up for a new Developer Edition org and reserve the prefix in its Package Manager. Check Availability in Namespace Settings tells you whether anyone else holds it. That Developer Edition org is the namespace org, and Link a Namespace to a Dev Hub Org says it must be "separate from the Dev Hub or scratch orgs."
Next, in your Dev Hub (for AppExchange partners, usually the Partner Business Org), open Namespace Registries and click Link Namespace. The pop-up asks you to log in to the namespace org "using the org's System Administrator's credentials." That login is the detail to plan for. Sign up the namespace org under a shared company admin account, not an engineer's personal email, because whoever controls it controls your ability to link the namespace to a new Dev Hub later. The link itself is a NamespaceRegistry record, and "You can’t create this object with the API," so it can't be scripted into CI.
Last, name the prefix in sfdx-project.json. Packages created with sf package create from that project take it, and so do scratch orgs created from the project.
{
"packageDirectories": [{ "path": "force-app", "default": true }],
"namespace": "acme",
"sourceApiVersion": "68.0"
}Install conflicts a namespace can cause
Namespaces decide which packages can share an org, and the failures show up at install time in a customer org or a test org. The rules below are from Avoid Namespace Collisions in 2GP unless noted.
- Same API name in two packages. "If two packages include a component with the same API name, you can’t install these packages into the same org." With one shared namespace, keep a single list of component names across every package.
- 1GP and 2GP on one namespace. "If the 1GP and 2GP share a namespace, you can’t install them in the same org." Moving a product to 2GP means converting the 1GP package, not shipping a second package beside it.
- 2GP into a namespaced Developer Edition org. Salesforce blocks "the installation of 2GP packages in Developer Edition (DE) orgs that have an associated namespace, unless it’s a DE scratch org." Your namespace org can't double as a test org.
- Scratch org snapshots. "You can't use a namespaced scratch org to create a snapshot" (Create a Snapshot for Use with Namespaced Scratch Orgs). Build the source org with
--no-namespace. - The customer's own field with your name. If a customer creates a local
Amount__cnext to youracme__Amount__c, dynamic SOQL in your package can fail with a duplicate field error. The current Apex Developer Guide (Winter '27) handles this withDatabase.QueryOptionsandexplicitNamespaceset totrue(Prevent Field Name Collisions in Managed SOQL Queries). Unqualified names then resolve to the customer's field and prefixed names to yours. - Expecting `@NamespaceAccessible` everywhere. It can't be used on
@AuraEnabledor@InvocableMethodmethods (Namespace-Based Visibility for Apex Classes in 2GP). Put shared logic in a service class and call it from each package's own controller.
Frequently Asked Questions
Can you change a namespace prefix in Salesforce?
No. It can't be changed or reused once assigned, so a new prefix means a new package and a data migration for every customer.
Is a namespace required for a managed package?
Yes, for 1GP and 2GP alike. Only unlocked packages, which suit internal teams more than products, can skip it.
Can multiple managed packages share a namespace?
With 2GP, yes, and Salesforce recommends one namespace for all of them. With 1GP, each namespace belongs to exactly one package.
Can a Salesforce namespace be transferred to another company?
Yes, with its package. A managed 2GP that has passed security review can move to another company's Dev Hub through a Salesforce Support case, but 1GP packages and 2GPs converted from 1GP can't.
Does my SaaS backend need the namespace in API calls?
Yes, for your packaged fields. Use the full acme__Field__c names, or set defaultNamespace in the Sforce-Call-Options header for REST queries, which Bulk API doesn't support.
Can Appnigma set up our namespace and managed package?
Yes. Appnigma's marketplace apps team builds the managed package and helps you "Get a native app, marketplace listing preparation, and review support." For integrations that run outside a package, its done-for-you team builds and maintains them.
Related Articles
- What is a managed package in Salesforce?
- Salesforce managed package guide
- What is Dev Hub in a Partner Business Org?
- 1GP to 2GP managed package migration
- What are Salesforce objects and fields?
- License checks for LWC in managed packages
Sources
- Namespaces for Second-Generation Managed Packages, 2GP Developer Guide
- Create and Register Your Namespace for Second-Generation Managed Packages
- Link a Namespace to a Dev Hub Org, 2GP Developer Guide
- Comparison of First- and Second-Generation Managed Packages
- Avoid Namespace Collisions in Second-Generation Managed Packages
- Namespace-Based Visibility for Apex Classes in Second-Generation Managed Packages
- Register a Namespace for a First-Generation Managed Package
- Convert Your Managed 1GP Package to 2GP
- Understanding Namespaces, Salesforce DX Developer Guide
- Create a Snapshot for Use with Namespaced Scratch Orgs
- Namespace Prefix, Apex Developer Guide
- Prevent Field Name Collisions in Managed SOQL Queries, Apex Developer Guide
- Component Namespaces, Lightning Web Components Developer Guide
- Call Options Header, REST API Developer Guide
- NamespaceRegistry, Object Reference
- Best Practices for Using Global Apex in Managed Packages, Apex Developer Guide
- AppExchange Object Prefixes and the API, Object Reference
- Transfer a Second-Generation Managed Package to a Different Dev Hub
- Submit Your Solution for a Follow-Up Security Review, ISVforce Guide
