Category: Uncategorized

  • Salesforce Sharing and Visibility Explained Simply with Real-World Examples

    One of the most confusing topics in Salesforce is sharing and visibility.

    I have seen this many times. A user says, “I cannot see the record.” Another says, “I can open it, but I cannot edit it.” Someone else says, “I can see the record, but one important field is missing.” That is usually the point where terms like OWD, role hierarchy, sharing rules, and Apex sharing start coming up, and for many people it begins to feel more complicated than it actually is.

    But the truth is, the concept becomes much easier once we understand it in the correct order.

    In this post, I want to explain Salesforce sharing and visibility in a very simple way, using one practical example throughout, so that even a beginner can understand:

    • who can see what
    • why they can see it
    • and when each option should be used

    The simplest way to understand Salesforce visibility

    I usually explain Salesforce access in layers.

    Think of it like entering a building:

    • Object access decides whether you can enter the building at all
    • Field access decides which rooms inside the building you can open
    • Record access decides which specific cabin, flat, or apartment you can enter

    That is the key idea.

    Before Salesforce even checks sharing, it first checks whether the user has access to the object and the fields.

    That is why I always say this first:

    Object-level and field-level visibility always come before record sharing.


    The access flow at a glance

    You can use this simple diagram to remember the order:

    Object Access

    Field Access

    OWD / Baseline Record Access

    Grant Access Using Hierarchies

    Sharing Rules

    Teams / Manual Sharing / Apex Sharing

    Territory Sharing (when business model needs it)

    If this order is clear in your mind, Salesforce security becomes much easier to design and troubleshoot.


    A simple business example

    Let us take a fictional company called NovaRay GridWorks.

    This is not a real company. Let us assume they sell and implement energy management systems for commercial buildings across different regions.

    Here are a few people in the company:

    • Rohit – Sales Executive
    • Neha – Sales Manager
    • Priya – Finance Executive
    • Aman – Support Agent
    • Karan – Regional Head
    • Meera – Partner Operations Lead

    Now Rohit creates:

    • an Account: Skyline Habitat Developers
    • an Opportunity: Building Energy Optimization Project
    • Opportunity Amount: ₹28,00,000

    Now the business starts asking questions like:

    • Can Neha see this Opportunity?
    • Can Priya see it?
    • Can Aman see it?
    • Can Meera see it?
    • Can regional leadership see it?
    • Can some people only see it after the deal is won?

    That is exactly where Salesforce sharing and visibility design comes in.


    1) Why object and field visibility get the highest priority

    Before we talk about OWD or sharing rules, we need to understand one very important rule.

    If a user does not have access to the object, then sharing the record will not help.

    And if a user can access the record but does not have access to a field, then that field will still remain hidden.

    This is why the first layer of visibility is always:

    • Object-level access
    • Field-level security

    Object-level access

    Object access is controlled through Profiles and Permission Sets.

    It decides whether a user can:

    • Read
    • Create
    • Edit
    • Delete

    records for objects such as:

    • Account
    • Opportunity
    • Contact
    • Case

    Example

    Suppose Aman works in Support.

    He has access to:

    • Accounts
    • Contacts
    • Cases

    But he does not have access to Opportunity.

    Now even if someone tries to share Rohit’s Opportunity with Aman, he still will not be able to see it.

    Why?

    Because Salesforce first checks:

    “Does Aman even have access to the Opportunity object?”

    If the answer is no, record sharing does not matter.

    That is why I call object access the first gate.


    Field-level security

    Now let us say Priya from Finance can access the Opportunity object, but NovaRay GridWorks does not want every finance user to edit certain sensitive fields like:

    • Discount %
    • Margin %
    • Internal Pricing Notes

    This is where Field-Level Security (FLS) comes in.

    Field-Level Security decides whether a user can:

    • see a field
    • edit a field

    Example

    Priya can open the Opportunity record, but:

    • she can see Amount
    • she can see Stage
    • she cannot edit Internal Pricing Notes

    So even though she can access the record, she does not automatically get access to every field on it.

    That is why sharing alone never tells the full story.


    2) OWD: the baseline of record access

    Once object and field access are in place, Salesforce then checks the baseline record-level access.

    This is decided by Organization-Wide Defaults, usually called OWD.

    OWD answers this question:

    “By default, how open or how private should records be for this object?”

    You can think of OWD as the starting point of record visibility.


    Common OWD options

    Depending on the object, common OWD options include:

    • Public Read/Write
    • Public Read Only
    • Private
    • Controlled by Parent

    Public Read/Write

    Everyone with object access can view and edit all records.

    Public Read Only

    Everyone with object access can view all records, but not everyone can edit them.

    Private

    Only the owner and users who get access through some other mechanism can see the record.

    Controlled by Parent

    The child record follows the visibility of the parent record.


    Example

    At NovaRay GridWorks, let us say the company keeps:

    • Account OWD = Private
    • Opportunity OWD = Private

    This means if Rohit creates the Account and Opportunity, then by default:

    • Rohit can see them because he owns them
    • others cannot automatically see them
    • additional access must come from hierarchy, sharing rules, teams, manual sharing, Apex sharing, or territory-based access

    This is a very common setup when business data like customers, pipeline, and revenue is sensitive.


    3) Sharing settings also include “Grant Access Using Hierarchies”

    This is one of those settings people often see, but many do not fully understand.

    Grant Access Using Hierarchies means users higher in the role hierarchy can get access to records owned by users below them.

    In simple words:

    Managers can see their team’s records.

    Example

    Rohit is a Sales Executive.
    Neha is his manager.
    Karan is above Neha as the Regional Head.

    If Grant Access Using Hierarchies is enabled, then:

    • Rohit owns the Opportunity
    • Neha can see it because she is above him in the role hierarchy
    • Karan can also see it because he is higher up in the hierarchy

    This access is not coming from a sharing rule.

    It is coming from the company’s role structure.

    That makes hierarchy a very natural solution when the business expectation is:

    “Managers should be able to see their team’s work.”


    Important difference: hierarchy vs sharing rules

    This is where many beginners get confused.

    • Hierarchy gives access upward based on reporting structure
    • Sharing Rules give access sideways or outward based on ownership or criteria

    So if a Finance user needs access, and they are not above the Sales user in hierarchy, hierarchy will not help. That is where sharing rules become useful.


    4) Sharing Rules: when records should open automatically

    Sometimes hierarchy alone is not enough.

    For example, Priya from Finance is not Rohit’s manager. She is in a different function. Still, the business may want her to access certain Opportunities.

    This is where Sharing Rules come in.

    Sharing Rules are used to automatically share records based on:

    • who owns the record
    • or what values the record contains

    There are two common types.


    A) Owner-based sharing rules

    An owner-based sharing rule says:

    “If records are owned by this group of users, share them with that group of users.”

    Example

    NovaRay GridWorks wants this:

    All Opportunities owned by the North Region Sales Team should be visible to the North Region Finance Team.

    Now if Rohit belongs to North Region Sales and owns an Opportunity, Priya and her finance group can automatically get access.

    This is useful when sharing depends on ownership by:

    • team
    • department
    • business unit
    • role

    The easiest way to think about owner-based sharing is:

    If the record belongs to users from this bucket, share it with users from that bucket.


    B) Criteria-based sharing rules

    A criteria-based sharing rule says:

    “If a record meets certain conditions, share it with a group.”

    Example

    NovaRay GridWorks wants Finance to access only deals that are already won.

    So they create a rule like this:

    • If Stage = Closed Won
    • Share Opportunity with Finance Team

    This means:

    • Finance does not need to see every deal from day one
    • Finance gets access only when their process needs to begin

    Another example could be:

    • If Region = North
    • Share Account with North Support Team

    This is a very practical use of criteria-based sharing.


    When should Sharing Rules be used?

    Sharing Rules are best when:

    • the logic is stable
    • the access pattern is predictable
    • the rule is broad and repeatable
    • admins should be able to manage it without code

    They work really well when the requirement sounds like this:

    • share all west region accounts with west support users
    • share all closed won opportunities with finance
    • share all enterprise customers with the enterprise service team

    If the rule can be described clearly and applies consistently, a sharing rule is often the right choice.


    5) Apex-Based Sharing: when standard sharing is not enough

    Now let us move to the more advanced scenario.

    Sometimes the access requirement is too dynamic or too specific for standard sharing rules.

    Examples:

    • share the Opportunity with the Implementation Manager mentioned on that record
    • share the Account with users mapped through a custom junction object
    • share the record only when multiple conditions across related records are true

    These are the kinds of situations where Apex-Based Sharing becomes useful.

    In simple words:

    Apex sharing means the system grants access through custom code.


    Real-world example of Apex sharing

    Let us assume NovaRay GridWorks has a custom field on Opportunity:

    Implementation_Manager__c

    Now the business wants this behavior:

    • when Opportunity reaches Proposal Accepted
    • the user in Implementation_Manager__c
    • should automatically get Edit access

    This is record-specific and dynamic.

    A normal sharing rule may not be the cleanest way to handle it.

    So a developer can write Apex logic to create a sharing entry and grant the required access to that user.

    That is Apex-based sharing.


    Another practical example

    Suppose there is a custom object called Partner Assignment.

    Whenever an Account is mapped to a partner through this custom object, Meera from Partner Operations should get access to that Account.

    Because this access depends on a custom relationship and may vary record by record, Apex sharing is usually a better fit.


    When should Apex sharing be used?

    Apex sharing should be used when:

    • standard sharing rules cannot handle the business logic
    • access is dynamic and record-specific
    • access depends on custom objects or custom relationships
    • the system must automatically add or remove access based on business logic

    But my advice is always the same:

    Use standard Salesforce sharing first. Use Apex only when it is genuinely required.

    Because once code gets involved, maintenance, testing, and long-term support also come into the picture.


    6) Account and Opportunity Sharing: when to use them specifically

    A very common question is this:

    “If we already have sharing settings, why do we separately talk about Account and Opportunity sharing?”

    The reason is simple.

    Accounts and Opportunities are core CRM objects, and in real business implementations they usually have more layered access requirements than many other objects.


    Why Account sharing matters

    Accounts represent customers or businesses.

    Different teams may need Account access for different reasons:

    • Sales needs ownership of the relationship
    • Support needs customer context
    • Finance may need billing-related visibility
    • Leadership may need strategic access
    • Partner teams may need access on selected records

    If Account OWD is Private, then access needs to be opened thoughtfully.

    Example

    At NovaRay GridWorks:

    • Sales owns the account
    • managers see it through hierarchy
    • support sees some accounts based on region
    • partner operations sees selected accounts through custom assignment logic

    That is why Account sharing design matters so much.


    Why Opportunity sharing matters even more

    Opportunities usually contain highly sensitive information such as:

    • amount
    • stage
    • forecast
    • probability
    • negotiation details
    • discounting strategy

    Because of this, many organizations keep Opportunity OWD = Private.

    Example

    At NovaRay GridWorks:

    • Rohit owns the Opportunity
    • Neha sees it through hierarchy
    • Finance sees it only after Closed Won using a criteria-based sharing rule
    • a Sales Engineer is added only on selected deals through Opportunity Team
    • the Implementation Manager gets access through Apex sharing when needed

    This is very realistic, and it is also why Opportunity sharing needs careful thought.


    When to use Account Teams and Opportunity Teams

    Sometimes access is not broad enough to justify a general sharing rule.

    You do not want to say:

    All finance users should see all such records.

    Instead, you want to say:

    On this specific record, these exact people should collaborate.

    That is where Account Teams and Opportunity Teams help a lot.

    Example

    Rohit is working on a large deal and needs these people involved:

    • Neha – Manager
    • Sales Engineer
    • Legal Reviewer
    • Meera – Partner Operations

    He can add them to the Opportunity Team.

    Now the right people get access to that one Opportunity without opening access more broadly than needed.


    So when should each approach be used?

    Use standard sharing settings when:

    • access rules are broad and repeatable
    • hierarchy and sharing rules can solve the need
    • admins should manage access centrally

    Use Account Teams / Opportunity Teams when:

    • access is collaboration-based
    • the users differ from record to record
    • business users need flexibility on specific accounts or deals

    Use Apex sharing when:

    • the access logic is dynamic
    • it depends on custom processes or custom objects
    • standard options are not enough

    The way I usually summarize it is:

    Standard where possible, teams where practical, Apex where necessary.


    7) Territory Sharing: when visibility should follow business geography

    Now let us talk about Territory Sharing.

    This becomes useful when business is structured not only by ownership, but also by:

    • geography
    • market
    • sales region
    • industry segment
    • territory-led account planning

    Ownership answers this question:

    Who is responsible for the record?

    Territory answers this question:

    Which region or sales coverage model should also have visibility into the record?


    Real-world example of Territory Sharing

    At NovaRay GridWorks, Rohit owns an Account in the North Region.

    But the company also wants:

    • North Region sales leadership
    • territory-aligned account managers
    • regional planners

    to have visibility because that customer belongs to the North Commercial Territory.

    Now ownership stays with Rohit, but visibility can also follow the territory structure.

    This is where Territory Management becomes valuable.


    When should Territory Sharing be used?

    Territory sharing is useful when:

    • the sales model is region-based or segment-based
    • multiple users need access due to territory coverage
    • account planning is done by territory
    • ownership alone does not represent how the business works

    When should it not be used?

    Territory Management should not be used just because it is available.

    If hierarchy, sharing rules, and teams can already solve your access model well, then adding Territory Management may only make things more complex.

    Territory sharing is best used when the business genuinely operates in a territory-led model.


    Bringing everything together with one final example

    Let us go back to our Opportunity:

    Account: Skyline Habitat Developers
    Opportunity: Building Energy Optimization Project
    Owner: Rohit

    Now let us see who gets access and why.

    Rohit

    He owns the record, so he can see it.

    Neha

    She is Rohit’s manager, so she gets access through hierarchy.

    Karan

    He is above Neha, so he also gets visibility through hierarchy.

    Priya

    She does not get access by default.
    But once the Opportunity becomes Closed Won, a criteria-based sharing rule can give her access.

    Aman

    Even if someone wants him to see the record, he still cannot access it if he does not have Opportunity object permission.

    Meera

    If her access depends on a custom partner assignment process, Apex sharing can grant her access to the selected record.

    Sales Engineer

    If Rohit adds the Sales Engineer to the Opportunity Team, that user gets access to that specific Opportunity.

    Territory-aligned leader

    If the Account belongs to a defined territory, users aligned to that territory may also get access through Territory Management.

    Once you see all of this in one flow, Salesforce sharing starts becoming logical instead of confusing.


    A simple checklist I follow for designing access

    Whenever I review or design record access in Salesforce, I usually go in this order:

    1. Does the user have access to the object?
    2. Does the user have access to the required fields?
    3. What is the OWD for the object?
    4. Does hierarchy already solve manager visibility?
    5. Can a sharing rule solve it without code?
    6. Would Teams be better for record-specific collaboration?
    7. Is Apex sharing really needed?
    8. Is Territory Management a real business requirement?

    This sequence helps avoid unnecessary complexity.


    Common mistakes I see people make

    1. Thinking sharing overrides object access

    It does not. If object permission is missing, record sharing will not help.

    2. Thinking Sharing Rules can solve every scenario

    They solve many scenarios, but not all dynamic custom ones.

    3. Using Apex too early

    Apex sharing is powerful, but it should not be the first option.

    4. Confusing hierarchy with Sharing Rules

    Hierarchy is based on reporting structure. Sharing Rules are based on ownership or record criteria.

    5. Overcomplicating Account and Opportunity access

    Often a cleaner design comes from using OWD, hierarchy, sharing rules, and teams correctly before moving to custom code.


    Final thoughts

    Salesforce sharing and visibility can look intimidating at first, but the core question is actually very simple:

    Who should see what data, and under what conditions?

    Once that question is answered layer by layer, the design becomes much easier.

    If I had to summarize the entire topic in one line, it would be this:

    Object Access → Field Access → OWD → Hierarchy → Sharing Rules → Teams / Apex → Territory

    That is the sequence I find most helpful for both learning and designing a secure access model.

    At the end of the day, good Salesforce security is not about hiding everything from everyone.

    It is about making sure the right people get the right access at the right time.


    Conclusion

    If you are learning Salesforce sharing and visibility, my suggestion is simple:

    • start with object and field access
    • keep OWD as your secure baseline
    • use hierarchy for manager visibility
    • use Sharing Rules for predictable access
    • use Teams for collaboration on specific records
    • use Apex sharing for truly dynamic business logic
    • use Territory sharing only when the business model genuinely needs it

    Once these layers become clear, Salesforce visibility stops feeling confusing and starts feeling structured and logical.

    And that is when designing security becomes much easier.

  • Salesforce Spring ’26: A Quiet Release That Changes How We Work

    Salesforce Spring ’26 is not loud.

    There are no dramatic UI overhauls, no “this changes everything” moments, and no features that force you to rewrite your architecture overnight.

    And yet, as someone working deeply with Salesforce Core, automation, metadata, and multi-org setups, I believe Spring ’26 is one of the most important releases in recent years.

    Not because of what it adds —
    but because of what it improves.

    This Release Is About Reducing Friction, Not Adding Features

    Most Salesforce orgs today don’t struggle because they lack features.
    They struggle because of:

    • Too many configurations spread across Setup
    • Automations that work but are hard to debug
    • Errors that surface only after users complain
    • Deployments that take longer than they should

    Spring ’26 quietly targets these exact problems.

    It’s a release focused on operational maturity.


    Setup Is No Longer Just for Power Users

    One of the most noticeable shifts in Spring ’26 is how Salesforce is rethinking Setup itself.

    Instead of assuming admins remember:

    • where a setting lives,
    • which permission controls what,
    • or which toggle affects which feature,

    Salesforce is moving toward a goal-driven setup experience.

    The idea is simple:

    You explain what you want to achieve, and Salesforce helps you get there.

    This doesn’t replace admin knowledge — it reduces unnecessary mental load.
    For experienced admins, it means less time navigating Setup and more time designing solutions.


    Automation Is Finally Easier to Maintain (Not Just Build)

    Flow has been powerful for years.
    But anyone working in real orgs knows the problem was never building flows — it was understanding them later.

    Spring ’26 improves:

    • Flow execution visibility
    • Runtime diagnostics
    • Post-deployment troubleshooting

    This matters a lot in enterprise environments where:

    • multiple teams touch automation,
    • ownership changes over time,
    • and issues are investigated weeks or months later.

    Salesforce is acknowledging something important:

    Automation success is measured after deployment, not at save time.


    Developers Get Practical Wins (Not Shiny Toys)

    For developers, Spring ’26 is refreshingly practical.

    Instead of introducing entirely new paradigms, Salesforce focuses on:

    • cleaner UI building blocks,
    • smarter test execution,
    • better separation between configuration and code.

    These changes may not look exciting in demos, but they:

    • speed up CI/CD pipelines,
    • reduce deployment fatigue,
    • and make large codebases easier to manage.

    If you work across multiple orgs or managed packages, you will feel this release.


    Errors Are Treated as Signals, Not Accidents

    Historically, Salesforce errors were:

    • scattered,
    • inconsistent,
    • and often invisible to admins.

    Spring ’26 changes that mindset.

    Errors are now something you:

    • monitor,
    • analyze,
    • and act on proactively.

    Centralized visibility into Lightning errors means:

    • fewer “it suddenly stopped working” tickets,
    • faster root-cause analysis,
    • better confidence in production changes.

    This is not a flashy feature — but it’s one of the most valuable ones.


    Security Tightening You Should Take Seriously

    Some Spring ’26 changes won’t break anything today — but they will break things if ignored.

    Salesforce is tightening:

    • certificate lifecycles,
    • connected app governance,
    • and permission granularity.

    This aligns Salesforce with modern security standards, even if it feels restrictive.

    If you manage:

    • integrations,
    • CI/CD users,
    • or third-party tools,

    this is the right time to review your setup — not when something fails unexpectedly.


    What Spring ’26 Intentionally Does Not Do

    Equally important is what Salesforce chose not to change:

    • Apex is not being replaced
    • Flow is not being forced into AI-only territory
    • Existing architectures are not being disrupted
    • Admins and developers are not being sidelined

    Spring ’26 respects existing investments.

    It evolves the platform instead of rewriting it.


    Why Spring ’26 Feels Different

    This release doesn’t chase buzzwords.

    It focuses on:

    • clarity over complexity,
    • stability over novelty,
    • and long-term maintainability over short-term excitement.

    For mature Salesforce orgs — especially those working on Core platform, automation at scale, and multi-org governance — Spring ’26 delivers real value.

    Sometimes the best releases are the ones that don’t shout.

  • Introducing SmartBulk: A Free, Salesforce-Native Bulk Utility

    If you’ve ever had to clean up data or update hundreds of records in Salesforce, you know how painful it can get—especially when you want to stay fully native and avoid relying on external utilities.

    I’m excited to share SmartBulk, a 100% free Salesforce admin utility that helps teams perform bulk view, bulk update, and bulk delete operations directly inside Salesforce.

    Status: SmartBulk is currently under AppExchange review.
    🔗 The AppExchange listing link will be available soon.


    What SmartBulk does

    SmartBulk helps you:

    • View records in bulk based on predefined configurations
    • Update records in bulk, including inline edits where applicable
    • Delete selected records in bulk, only when the user has required permissions
    • Work faster on common admin tasks like cleanup, standardization, and maintenance

    Typical use cases include:

    • Pre-deployment cleanup
    • Fixing incorrect field values across many records
    • Removing invalid/test records safely
    • Standardizing picklists/fields across a dataset

    Built for “native-first” admins (no external tools)

    SmartBulk is designed to be fully Salesforce-native:

    • No Tooling API
    • No Salesforce Inspector
    • No browser extensions
    • No external services or integrations
    • No data stored outside Salesforce

    Everything runs within the Salesforce platform, under the logged-in user’s access.


    Who should use SmartBulk?

    SmartBulk is useful for:

    • Salesforce Admins
    • Release / DevOps teams
    • Teams doing ongoing data hygiene
    • Orgs that prefer secure, compliant, platform-native solutions

    Availability

    SmartBulk is currently submitted for AppExchange review.
    I’ll share the official AppExchange link once it’s approved and live.


    Final note

    My goal with SmartBulk is simple:
    Make bulk operations faster for admins—without relying on external tooling—and keep it free forever.

    More updates soon. 🚀

  • 🔍 Metadata Explorer Is Now Live on Salesforce AppExchange!

    I’m excited to share that Metadata Explorer is now officially live on the Salesforce AppExchange.

    What started as a simple internal utility to help me navigate metadata across Salesforce orgs has now evolved into a complete Lightning application designed to make metadata exploration faster, clearer, and developer/admin-friendly.


    🌟 Why I Built Metadata Explorer

    Working across multiple orgs at UNICEF and various packages, I frequently needed a quick way to:

    • Inspect metadata structures
    • Explore Apex classes, triggers, profiles, and permission sets
    • Find and review custom fields
    • Analyze model tables and related objects
    • Speed up impact analysis before deployments

    Most existing tools were:

    • slow
    • outdated
    • or required external setup

    So I built Metadata Explorer — a native, LWC-powered app that allows instant metadata exploration directly inside Salesforce.


    ✨ Key Features

    🔎 Explore 14+ Metadata Types

    View and analyze many important Salesforce components, including:

    • Apex Classes
    • Apex Triggers
    • Profiles
    • Permission Sets
    • Record Types
    • Custom Fields
    • Custom Objects
    • Page Layouts
    • And more

    Everything is visible in one clean interface for quick understanding of an org’s metadata structure.

    ⚡ Lightning-Fast LWC Interface

    Built entirely with Lightning Web Components for a clean, responsive, and modern UI.

    📄 Export Support

    Export metadata details for:

    • documentation
    • DevOps reviews
    • impact analysis
    • technical scoping

    🧭 Simple, Intuitive Navigation

    Switch between metadata types effortlessly without writing a single line of SOQL or using external tools.


    🧩 Who Is Metadata Explorer For?

    • Salesforce Admins
    • Developers
    • Architects
    • DevOps / Release Engineers
    • Consultants handling multiple orgs

    If you need quick visibility into any part of an org’s metadata, this tool saves time and improves analysis accuracy.


    🔗 Install Metadata Explorer

    You can install the app directly from the Salesforce AppExchange:

    👉 https://appexchange.salesforce.com/appxListingDetail?listingId=d011486b-88ac-4000-9bb7-37a5f6c7f945


    🙏 Thank You

    A huge thank you to everyone who supported this project throughout the build and review process.
    Seeing Metadata Explorer pass Salesforce’s Security Review and go live on AppExchange is a proud milestone in my ISV journey.

    More enhancements, metadata coverage, and new utilities are coming soon!

    #CloudWithAbhi

  • 🧩 Client Credentials Flow: New Invalid Scope Error

    Salesforce has updated the OAuth 2.0 Client Credentials flow in the Winter ’26 Release to return a clear error when a token request has no valid scopes. This makes debugging integration issues much simpler.


    🔐 The Change

    When a token request is made using grant_type=client_credentials and Salesforce finds that none of the effective scopes are supported, it now returns the following descriptive error:

    {
      "error": "invalid_grant",
      "error_description": "no valid scopes defined"
    }
    
    

    What It Means

    • Applies only to the Client Credentials flow — other OAuth 2.0 flows are unaffected.
    • If a request includes both supported and unsupported scopes, Salesforce drops the unsupported ones and issues a token for the valid scopes.
    • If all scopes are unsupported, Salesforce rejects the request with the error above.

    Unsupported scopes (examples):

    • full → Full access
    • refresh_token / offline_access → Perform requests at any time

    Typical supported scope for integrations:

    • api → Manage user data via APIs

    🧊 Release Timeline

    This update is part of Salesforce Winter ’26, with production rollouts starting September 19, 2025.


    ❓ Why You Might See This Error

    Many integrations using the Client Credentials flow don’t send the scope parameter — and that’s fine.
    In such cases, Salesforce uses the scopes configured in the Connected App’s Selected OAuth Scopes section.

    If that Connected App contains only unsupported scopes, the request resolves to no valid scopes, resulting in:

    invalid_grant: no valid scopes defined
    
    

    Fix: Ensure at least one supported scope (like Manage user data via APIs (api)) is selected in your Connected App, even if your integration doesn’t explicitly send a scope.


    🧭 How to Find and Fix

    Step 1: Inventory

    • Identify all integrations using grant_type=client_credentials (e.g., Named Credentials, middleware, background jobs).
    • Locate the corresponding Connected Apps.
    • Review their Selected OAuth Scopes.

    Step 2: Remediate

    1. Go to Setup → App Manager → Manage Connected Apps → [App Name] → Edit Policies
    2. Under Selected OAuth Scopes, add:
      • Manage user data via APIs (api)
    3. Remove unsupported scopes (full, refresh_token, etc.).
    4. Ensure the Run As user has:
      • API Enabled
      • Required object CRUD/FLS permissions

    Step 3: Add Guardrails

    • Don’t send scope in the request — rely on Connected App scopes.
    • Monitor for token errors containing invalid_grant and “no valid scopes defined.”
    • Document your Connected App scope policy and integration user permissions.

    🧠 Summary

    AreaDetails
    Applies ToOnly OAuth 2.0 Client Credentials Flow
    ChangeNew descriptive error for missing valid scopes
    ReleaseWinter ’26 (starts Sep 19, 2025)
    ImpactToken requests with unsupported scopes now fail clearly
    FixAdd Manage user data via APIs (api) to Connected App scopes
    Best PracticeRely on Connected App configuration instead of sending scope

    💡 Pro Tip

    If you’re using Azure Logic Apps, MuleSoft, Boomi, or Postman collections with grant_type=client_credentials, review your Connected Apps now and ensure at least one supported scope is configured before Winter ’26 rolls out.


    🏁 Final Thought

    This update impacts only the Client Credentials flow, improving clarity for integration developers.
    By ensuring every Connected App includes the api scope, you’ll keep your machine-to-machine integrations running smoothly through Winter ’26 and beyond.