# Custom Permissions

This guide documents all custom permissions in the Suger Salesforce App. Custom permissions control feature access and UI visibility for offers, referrals, and administrative functions.

## Overview

Suger uses Salesforce Custom Permissions to control granular access to specific features within the app. These permissions are assigned to users through Permission Sets (see [Permission Sets](/salesforce-app/salesforce-app-permission-sets)).

Custom permissions differ from Permission Sets in that they:

- Control specific **features** and **actions** (not object access)
- Enable/disable **UI elements** like buttons and menu items
- Follow a **hierarchical logic** where generic permissions override platform-specific ones

---

## Permission Hierarchy

The Suger permission model uses a hierarchical structure where **generic permissions override platform-specific permissions**:

```
GENERIC (applies to all platforms)
├─ Create_Offer ────────► Can create offers for ANY platform
├─ Read_Offer ──────────► Can read offers from ANY platform
├─ Create_Referral ─────► Can create referrals for ANY platform
└─ Read_Referral ───────► Can read referrals from ANY platform

PLATFORM-SPECIFIC (limited to one platform)
├─ AWS
│   ├─ Write_AWS_Offer
│   ├─ Read_AWS_Offer
│   ├─ Write_AWS_Referral
│   └─ Read_AWS_Referral
├─ Azure
│   ├─ Write_Azure_Offer
│   ├─ Read_Azure_Offer
│   ├─ Write_Azure_Referral
│   └─ Read_Azure_Referral
├─ GCP
│   ├─ Write_GCP_Offer
│   ├─ Read_GCP_Offer
│   ├─ Write_GCP_Referral
│   └─ Read_GCP_Referral
└─ Snowflake
    ├─ Write_SNOWFLAKE_Offer
    └─ Read_SNOWFLAKE_Offer
```

:::note
If a user has a **generic permission** (e.g., `Create_Offer`), they automatically have access to all platforms without needing platform-specific permissions.
:::

---

## Offer Permissions

### Generic Offer Permissions

| Permission | API Name | Description | UI Effect |
| ---------- | -------- | ----------- | --------- |
| Create Offer | `Create_Offer` | Create offers for any marketplace | Shows "New Offer" button, enables offer creation flows |
| Read Offer | `Read_Offer` | View offers from any marketplace | Shows offer records and list views for all platforms |

### Platform-Specific Write Permissions

These permissions allow creating and modifying offers for a specific cloud platform only.

| Permission | API Name | Description |
| ---------- | -------- | ----------- |
| Write AWS Offer | `Write_AWS_Offer` | Create/modify AWS marketplace offers |
| Write Azure Offer | `Write_Azure_Offer` | Create/modify Azure marketplace offers |
| Write GCP Offer | `Write_GCP_Offer` | Create/modify GCP marketplace offers |
| Write Snowflake Offer | `Write_SNOWFLAKE_Offer` | Create/modify Snowflake marketplace offers |

### Platform-Specific Read Permissions

These permissions allow viewing offers for a specific cloud platform only.

| Permission | API Name | Description |
| ---------- | -------- | ----------- |
| Read AWS Offer | `Read_AWS_Offer` | View AWS marketplace offers |
| Read Azure Offer | `Read_Azure_Offer` | View Azure marketplace offers |
| Read GCP Offer | `Read_GCP_Offer` | View GCP marketplace offers |
| Read Snowflake Offer | `Read_SNOWFLAKE_Offer` | View Snowflake marketplace offers |

---

## Referral (Co-Sell) Permissions

### Generic Referral Permissions

| Permission | API Name | Description | UI Effect |
| ---------- | -------- | ----------- | --------- |
| Create Referral | `Create_Referral` | Create referrals for any cloud partner | Shows referral creation buttons for all platforms |
| Read Referral | `Read_Referral` | View referrals from any cloud partner | Shows referral records and list views for all platforms |

### Platform-Specific Write Permissions

| Permission | API Name | Description |
| ---------- | -------- | ----------- |
| Write AWS Referral | `Write_AWS_Referral` | Create/modify AWS co-sell referrals |
| Write Azure Referral | `Write_Azure_Referral` | Create/modify Azure co-sell referrals |
| Write GCP Referral | `Write_GCP_Referral` | Create/modify GCP co-sell referrals |

### Platform-Specific Read Permissions

| Permission | API Name | Description |
| ---------- | -------- | ----------- |
| Read AWS Referral | `Read_AWS_Referral` | View AWS co-sell referrals |
| Read Azure Referral | `Read_Azure_Referral` | View Azure co-sell referrals |
| Read GCP Referral | `Read_GCP_Referral` | View GCP co-sell referrals |

---

## Funding Permissions

These permissions control access to **AWS Funding** features (MDF/POC funding applications and the funding approval workflow). Because they are evaluated as Salesforce custom permissions, they apply whether the permission set is assigned directly or through a permission set group.

| Permission | API Name | Description | UI Effect |
| ---------- | -------- | ----------- | --------- |
| Read Funding | `Read_Funding` | View funding applications | Shows funding records and list views on the Funding tab |
| Write Funding | `Write_Funding` | Create and modify funding applications | Enables funding creation and edit actions |

`Read_Funding` is granted by the **Suger Funding** and **Suger Funding (Read Only)** permission sets; `Write_Funding` is granted by **Suger Funding**.

:::note
Funding approval reuses the shared **Approve Cosell** (`Approve_Cosell`) permission.
:::

---

## Approval Permissions

These permissions control access to approval workflows for offers and co-sell referrals.

| Permission | API Name | Description | UI Effect |
| ---------- | -------- | ----------- | --------- |
| Approve Offer | `Approve_Offer` | Approve/reject offers in approval workflow | Shows approval section and actions on offer records |
| Approve Cosell | `Approve_Cosell` | Approve/reject co-sell referrals | Shows approval actions on referral records |

:::note
The **Approve Offer** permission only functions when the **Enable Approval Process** toggle is active in Suger Settings.
:::

---

## Contact Management Permissions

These permissions control the ability to manage contacts on offer records.

| Permission | API Name | Description | UI Effect |
| ---------- | -------- | ----------- | --------- |
| Modify Offer Contacts | `Modify_Offer_Contacts` | Add/remove contacts from offers | Shows "Add Contact" button on offer records |
| Notify Offer Contacts | `Notify_Offer_Contacts` | Send notifications to offer contacts | Shows "Notify Contacts" button on offer records |

:::tip
Users with the **Create Offer** permission automatically have access to contact management features, even without these specific permissions.
:::

---

## Administrative Permissions

| Permission | API Name | Description | UI Effect |
| ---------- | -------- | ----------- | --------- |
| Modify Settings | `Modify_Settings` | Access and modify Suger settings | Shows Settings tab and allows configuration changes |

:::note
**System Administrators** automatically have `Modify_Settings` capabilities regardless of whether this permission is explicitly assigned.
:::

---

## Permission Checking Logic

The Suger app uses the following logic to determine user access:

### For Offer Creation

1. Check if user has `Create_Offer` → Grant access to **all** platforms
2. If not, check platform-specific permission (e.g., `Write_AWS_Offer`)
3. If neither, access is denied

### For Offer Reading

1. Check if user has `Create_Offer` → Writers can read (grant access)
2. If not, check if user has `Read_Offer` → Grant access to **all** platforms
3. If not, check platform-specific permission (e.g., `Read_AWS_Offer`)
4. If none, access is denied

### For Product Filtering

When creating offers, the product list is filtered based on the user's write permissions:

- If user has `Create_Offer` → Show products for **all** platforms
- If user has only `Write_AWS_Offer` → Show only AWS products
- Multiple platform permissions combine (e.g., `Write_AWS_Offer` + `Write_GCP_Offer` shows both)

---

## UI Elements Controlled by Permissions

### Tab Visibility

| Tab | Required Permission(s) |
| --- | ---------------------- |
| Products | Any marketplace offer permission |
| Offers | Any marketplace offer permission |
| Entitlements | Any marketplace offer permission |
| Buyers | Any marketplace offer permission |
| Referrals | Any co-sell referral permission |
| Funding | `Read_Funding` or `Write_Funding` |
| Settings | `Modify_Settings` or System Administrator |

### Action Buttons

| Button/Action | Required Permission(s) |
| ------------- | ---------------------- |
| Create Offer | `Create_Offer` OR any `Write_*_Offer` |
| Edit Offer | Platform-specific write permission for the offer's partner |
| Approve/Reject Offer | `Approve_Offer` |
| Add Contact | `Modify_Offer_Contacts` OR `Create_Offer` |
| Notify Contacts | `Notify_Offer_Contacts` OR `Create_Offer` |
| Create Referral | `Create_Referral` OR any `Write_*_Referral` |
| Edit Referral | Platform-specific write permission for the referral's partner |
| Approve/Reject Referral | `Approve_Cosell` |
| Delete Referral | Uses native Salesforce object permissions (`isDeletable()`) |

---

## Permission Set Assignments

The following table shows which custom permissions are included in each permission set:

### Suger User (Full Access)

The **Suger User** permission set grants access to ALL custom permissions across all platforms:

| Permission Category | Permissions Included |
| ------------------- | -------------------- |
| Generic Offer | `Create_Offer`, `Read_Offer` |
| AWS Offer | `Write_AWS_Offer`, `Read_AWS_Offer` |
| Azure Offer | `Write_Azure_Offer`, `Read_Azure_Offer` |
| GCP Offer | `Write_GCP_Offer`, `Read_GCP_Offer` |
| Snowflake Offer | `Write_SNOWFLAKE_Offer`, `Read_SNOWFLAKE_Offer` |
| Generic Referral | `Create_Referral`, `Read_Referral` |
| AWS Referral | `Write_AWS_Referral`, `Read_AWS_Referral` |
| Azure Referral | `Write_Azure_Referral`, `Read_Azure_Referral` |
| GCP Referral | `Write_GCP_Referral`, `Read_GCP_Referral` |
| Contact Management | `Modify_Offer_Contacts`, `Notify_Offer_Contacts` |

:::note
**Suger User** is the standard permission set for human users requiring full access to the Suger app across all cloud platforms. Use platform-specific permission sets for restricted access.
:::

### Marketplace Permission Sets

| Permission | Marketplace Read Only | Marketplace AWS | Marketplace Azure | Marketplace GCP | Marketplace Snowflake |
| ---------- | :------------------: | :-------------: | :---------------: | :-------------: | :-------------------: |
| Read_Offer | ✓ | | | | |
| Write_AWS_Offer | | ✓ | | | |
| Read_AWS_Offer | | ✓ | | | |
| Write_Azure_Offer | | | ✓ | | |
| Read_Azure_Offer | | | ✓ | | |
| Write_GCP_Offer | | | | ✓ | |
| Read_GCP_Offer | | | | ✓ | |
| Write_SNOWFLAKE_Offer | | | | | ✓ |
| Read_SNOWFLAKE_Offer | | | | | ✓ |
| Modify_Offer_Contacts | | ✓ | ✓ | ✓ | |
| Notify_Offer_Contacts | | ✓ | ✓ | ✓ | |

### Co-Sell Permission Sets

| Permission | Cosell | Cosell AWS | Cosell Azure | Cosell GCP | Cosell Read Only |
| ---------- | :---------------: | :--------: | :----------: | :--------: | :--------------: |
| Create_Referral | ✓ | | | | |
| Read_Referral | ✓ | | | | ✓ |
| Write_AWS_Referral | ✓ | ✓ | | | |
| Read_AWS_Referral | ✓ | ✓ | | | ✓ |
| Write_Azure_Referral | ✓ | | ✓ | | |
| Read_Azure_Referral | ✓ | | ✓ | | ✓ |
| Write_GCP_Referral | ✓ | | | ✓ | |
| Read_GCP_Referral | ✓ | | | ✓ | ✓ |

### Administrative Permission Sets

| Permission | Suger Integrator | Suger Approver | Suger Approval Cosell |
| ---------- | :--------------: | :------------: | :-------------------: |
| All Offer Permissions | ✓ | | |
| All Referral Permissions | ✓ | | |
| Approve_Offer | ✓ | ✓ | |
| Approve_Cosell | ✓ | | ✓ |
| Modify_Settings | ✓ | | |
| Modify_Offer_Contacts | ✓ | | |
| Notify_Offer_Contacts | ✓ | | |

:::note
**Suger Approver** grants Approve_Offer only (marketplace offers). **Suger Approval Cosell** grants Approve_Cosell only (co-sell referrals). Assign both if a user needs to approve both kinds.
:::

:::note
**Suger Integrator** is dedicated for integration/API users (not human users). It has the same custom permissions as **Suger User**, plus `Approve_Offer`, `Approve_Cosell`, and `Modify_Settings` for full system access.
:::

---

## Best Practices

### Principle of Least Privilege

Assign the most restrictive permission set that meets the user's needs:

- For human users who need full access to the Suger app, use `Suger_User`
- For users who only work with one cloud platform, use platform-specific permission sets
- Reserve `Suger_Integrator` for integration/API users only (not human users)

### Permission Set Groups

Consider creating Permission Set Groups to combine multiple permissions:

- **AWS Power User**: `Suger_User_Marketplace_AWS` + `Suger_User_Cosell_AWS`
- **Multi-Cloud Viewer**: `Suger_User_Marketplace_Read` + `Suger_User_Cosell_Read`

### Testing Permissions

Before deploying permission changes to production:

1. Create a test user with the target permission set
2. Verify tab visibility matches expectations
3. Confirm action buttons appear/hide correctly
4. Test actual CRUD operations to verify object-level access