Apex-Managed Sharing
Apex Managed Sharing is the Salesforce sharing mechanism that lets Apex code create, modify, and delete share records programmatically, applying access grants that standard sharing rules cannot express.
Definition
Apex Managed Sharing is the Salesforce sharing mechanism that lets Apex code create, modify, and delete share records programmatically, applying access grants that standard sharing rules cannot express. Every shareable object (standard or custom) has a parallel __Share object that holds one row per access grant. The __Share row stores the parent record ID, the user or group receiving access, the access level (Edit, Read, or All), and the row cause (Manual, Rule, Owner, Team, or a developer-defined Apex Sharing Reason). Apex Managed Sharing is the only mechanism that can use Apex Sharing Reasons; the others reserve a fixed set of row causes.
The technique exists for orgs whose sharing requirements outgrow declarative tools. Standard sharing handles owner-based, role-hierarchy, and rule-based access. Teams, queues, and territories add a few more options. Beyond those, complex business rules (a custom approver gets read access when a deal reaches a particular stage, sales engineers get edit access only on opportunities matching their product specialty) require Apex. The mechanism is powerful enough to grant arbitrary access patterns, but it inherits the same governor limits and bulkification concerns as any other Apex code. Production orgs reach for Apex Managed Sharing only after exhausting the declarative options.
How Apex Managed Sharing actually grants access
The __Share object schema
Every custom object whose Sharing Model is Private or Public Read Only gets an auto-generated __Share object with the same name plus the __Share suffix. The schema includes ParentId (the record being shared), UserOrGroupId (the recipient), AccessLevel (Edit, Read, All), and RowCause (the system reason for the share). For standard objects like Account, the equivalents are AccountShare, OpportunityShare, CaseShare, and similar. Inserting a __Share row grants access; deleting it revokes.
Apex Sharing Reasons
Apex Sharing Reasons are admin-defined RowCause values that identify shares created by Apex code. Setup, Object Manager, open the custom object, then Apex Sharing Reasons, create a reason like Specialty_Engineer or Compliance_Reviewer. The corresponding __Share row's RowCause uses that label. Reasons matter because share rows are typically recalculated; the platform deletes and re-inserts only the rows with the developer's reason and leaves Manual and Rule shares intact.
The standard objects use fixed row causes
Only custom objects support Apex Sharing Reasons. Standard objects (Account, Opportunity, Case) use built-in row causes, with Manual being the most common for Apex-managed shares. The trade-off is that recalculation is harder on standard objects because the same RowCause is used by manual shares, so the developer must distinguish carefully when deciding what to delete.
Granting access in triggers
The most common pattern is a trigger that creates __Share rows when a record changes. On insert of an Opportunity tagged with a specific product, the trigger looks up the matching sales engineers and inserts OpportunityShare rows with AccessLevel Edit and RowCause Manual. On stage change, the trigger could grant compliance reviewers Read access. The trigger must be bulkified: collect all the share rows first, then a single Database.insert call at the end.
Recalculation on data change
When the data that drove the share changes, the share has to change. A specialty change reassigning an opportunity from one engineer to another means deleting the old __Share rows and inserting new ones. Most production implementations centralise this in a sharing service class invoked from triggers on every relevant object. Forgetting to handle the recalculation is a classic source of stale access (the previous engineer can still see the deal long after reassignment).
Recalculation batches and the platform's role
Salesforce can run a sharing recalculation on a custom object when its sharing model or rules change. Apex Sharing Recalculation classes implement the standard interface and are registered on the object. The platform calls the class during recalculation events. The Recalculate Sharing button on Setup, Sharing Settings triggers the platform run. Apex Sharing Recalculation is the supported way to fix drifted share rows in bulk.
Governor limits and bulkification
Inserts into __Share count against DML row limits. Large reassignments can exceed 10,000-row limits if not handled in batches. Triggers must collect shares across all records in Trigger.new before any DML, and operations that touch tens of thousands of parent records belong in batch jobs, not synchronous triggers. The patterns are identical to bulkified DML on any object.
Maintenance over time
Apex Managed Sharing is a long-running commitment. The rules that drive shares change as business processes evolve. The code paths are easy to miss in code review because share-granting logic often lives inside a handler called only from triggers. Most teams maintain a single Sharing service class with a documented contract; spreading sharing logic across many handlers is a recipe for stale grants and audit findings.
How to implement Apex Managed Sharing safely
Apex Managed Sharing is the most complex part of Salesforce sharing. Take the implementation in three deliberate steps: create the Apex Sharing Reason, write the granting code, then write the recalculation code that keeps shares accurate as data changes.
- Create an Apex Sharing Reason
Setup, Object Manager, open the custom object, then Apex Sharing Reasons. Create a reason with a clear name (e.g. Specialty_Engineer_Access). The reason becomes the RowCause on every __Share row your code creates.
- Write a trigger or service class that creates shares
On the right trigger event (insert, update of the driving field), collect the eligible record-user pairs, instantiate __Share rows with the right AccessLevel and RowCause, and insert them in bulk. Run with FOR UPDATE locking or sharing.share() inside SOQL when concurrent edits are likely.
- Handle revocation on data change
When the data driving the share changes (specialty reassignment, stage rollback), delete the existing share rows with the Apex Sharing Reason and re-insert the new set. Test that no orphan share rows survive a change.
- Implement Apex Sharing Recalculation
Create a class that implements the sharing recalculation interface and register it on the object. The platform calls it during recalculation events, including manual triggers from Sharing Settings.
- Audit and monitor
Build a SOQL query that compares expected shares to actual __Share rows for a sample of records. Schedule it weekly. Drift is the most common failure mode of long-lived Apex Managed Sharing implementations.
The auto-generated sharing object for the target object.
The record being shared.
The recipient user, public group, role, or queue.
Edit, Read, or All.
Manual on standard objects, or the Apex Sharing Reason on custom objects.
Admin-defined RowCause for custom objects; required for safe recalculation.
- Standard objects do not support custom Apex Sharing Reasons. Manual is the only practical RowCause, which complicates safe recalculation.
- Forgetting to revoke shares when the driving data changes leaves stale access in place; this is the most common audit finding.
- Apex Managed Sharing share rows count against DML and storage. Mass grant patterns can blow row limits at scale.
- Recalculation triggered from Sharing Settings runs synchronously and can time out on large orgs. Plan to test recalculation against full-volume sandboxes before relying on the button.
Trust & references
Cross-checked against the following references.
- Understanding Apex Managed SharingApex Developer Guide
- Creating Sharing with ApexApex Developer Guide
Straight from the source - Salesforce's reference material on Apex-Managed Sharing.
- Apex Managed SharingSalesforce Help
Hands-on resources to go deeper on Apex-Managed Sharing.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What field on a share record identifies it as Apex-Managed?
Q2. What happens to Apex-Managed Sharing records during sharing recalculations?
Q3. Why would you use Apex-Managed Sharing instead of criteria-based sharing rules?
Discussion
Loading discussion…