Declarative sharing — OWD, Role Hierarchy, Sharing Rules, Manual Sharing — covers most cases. Apex Managed Sharing is the escape hatch when business rules can't be expressed declaratively.
You write to the object's __Share table (e.g., Opportunity__Share, Account__Share) using Apex. Each share row has ParentId, UserOrGroupId, AccessLevel (Read or Edit), and a RowCause that you assign via an Apex Sharing Reason — a metadata-defined label that tells you and Salesforce why this share exists.
Reach for it when:
- Sharing logic depends on data in another object. "A user gets access to an Account if they're on the Account Team for any of its child Opportunities." Sharing Rules can't traverse parent-child for this; Apex can.
- Sharing must reflect a calculation, not a fixed criteria. "Grant access to the user listed in the custom Lookup field Deal Lawyer on this Opportunity." That's an inherited reference, not a rule the engine can express.
- You need temporary access with a deterministic expiry. Sharing Rules don't expire; you can put them in but you have to remove them. Apex Managed Sharing with a scheduled job that deletes share rows after N days gives you genuine TTL.
- You need access to survive owner changes. Manual Sharing is wiped on owner change. Apex shares created with a non-Manual
RowCausesurvive ownership changes and stick around until you delete them. - You're modeling complex teaming logic that isn't well-served by Account Team / Opportunity Team — for instance, role-specific access where a Deal Architect gets Read but a Deal Sponsor gets Edit, both inferred from custom fields.
Trade-offs to mention:
- It's code, so it needs maintenance, deployment, and unit tests.
- Sharing operations count against governor limits — bulk recalcs need careful design.
- You typically pair it with a Trigger plus a
@futureor Queueable for recalc on related-record changes. - The sharing recalculation built into Recalculate Sharing buttons doesn't recalculate Apex shares — that's your job.