## Permission Policies Overview

You can create _Permission Policies_ for your Users and assign these Permission Policies to them. There are two types of Permission Policies you can assign to Users:

- **Custom**. The policies you create yourself for controlling access to your Organization.
- **Managed**. System generated policies which you can assign to Users but which you cannot edit to change the access to resources they are configured to allow or deny.

When you create a Custom Permission Policy, you can add _statements_ to the policy that _allow or deny actions_ for specific _resources_. This allows you to control very precisely what a User who has been given access to your Organization can and cannot do. For example, you might want to create a Permissions Policy that denies Users the ability to retrieve Meters. This section explains the m3ter permissions model, lists the actions and resources you can use when adding statements to create Permission Policies, and how to create and manage your Custom Permissions Policies:

- [Understanding the m3ter Permissions Model](https://docs.m3ter.com/guides/organization-and-access-management/creating-and-managing-permissions#understanding-the-m3ter-permissions-model)
- [Permission Policy Statements - Actions and Resources](https://docs.m3ter.com/guides/organization-and-access-management/creating-and-managing-permissions#permission-policy-statements-available-actions-and-resources)
- [Creating Custom Permission Policies](https://docs.m3ter.com/guides/organization-and-access-management/creating-and-managing-permissions#creating-custom-permission-policies)
- [Permissions Exceptions](https://docs.m3ter.com/guides/organization-and-access-management/creating-and-managing-permissions#permissions-exceptions)

**Warning - Check for Exceptions!** There are instances where exceptions to the general permissions framework might occur as a result of shared data. See the [Permissions Exceptions](https://docs.m3ter.com/guides/organization-and-access-management/creating-and-managing-permissions#permissions-exceptions) section below for more details.

## Understanding the m3ter Permissions Model

The m3ter Permissions model is implemented using a three-fold framework of _Effect_, _Action_, and _Resource_:

- **Def**: A Permission is defined as imposing an _effect_ of either allowing or denying access to a specific _resource_ to perform a specific _action_ on that resource.

In JSON format, the general schema for a Permission is:

```json
{
  "Effect": {effect},
  "Action": [{action}],
  "Resource": [{resource}]
}
```

### Resources

Resources are defined as _m3ter Resource Identifiers_ (MRIs) in the format:

> `service:resource-type/item-type/id`

Where:

- _service_ is a distinct part of the overall m3ter system, and which forms a natural functional grouping, such as “config” or “billing”.
- _resource-type_ is the resource type item accessed - for example: “Plan”, “Meter”, “Bill”
- _item-type_ is one of:
  - “item” - to specify an individual item.
  - “group” - to specify a resource group.
- _id_ is the resource group id or the resource item id

For example:

- To denote as resource a specific _Plan_ with an _id = 12345_ in the _config_ service, the MRI would be:

> `config:plan/item/12345`

- To denote as resource a _Plan Resource Group_ with _id= 987_ (that is, applying to all Plans that are contained within the resource group) the MRI would be:

> `config:plan/group/987`

#### Use of Wildcards for Resources

The use of wildcards when denoting resources is allowed. For example, to denote all Plans as the resource in a permission statement, you can use:

> `config:plan/*`

**Tip: Available Resources?** Please see the [following section](https://docs.m3ter.com/guides/organization-and-access-management/creating-and-managing-permissions#permission-policy-statements-available-actions-and-resources) for a full list of available resources by service you can use in statements when creating your Permission Policies.

### Actions

Actions define what a User is either allowed or not allowed to do with respect to a resource. For example, you can use a `config:create` and `config:retrieve` action to create a statement for a Permission Policy that allows Users to create or retrieve any Plan in your Organization. But if this is the only Permission Policy assigned to a User, they will not be able to update or delete any Plans:

```json
{
  "effect": "allow",
  "action": [
    "config:create",
    "config:retrieve"
  ],
  "resource": [
    "config:plan/*"
  ]
}
```

Please see the [following section](https://docs.m3ter.com/guides/organization-and-access-management/creating-and-managing-permissions#permission-policy-statements-available-actions-and-resources) for full details and explanation on using actions against resources when creating statements for your Permission Policies.

### Effects and Evaluation Logic

The effect for a Permission Policy is either _to allow_ or _to deny_:

- **Allow** - indicates the policy is allowing access to the resource(s) for the given action(s).
- **Deny** - indicates the policy is denying access to the resource(s) for the given action(s).

If you create a Permission Policy with multiple statements this is how evaluation of access to a resource for a given action is applied:

- There is an implicit denial - the order of evaluation is:
  - We check to see if there is a statement that denies access to a resource for a given action. If there is, the access is denied.
  - We check to see if there is a statement that allows access to a resource for a given action. If there is, the access is allowed.
  - If there is no statement that explicitly denies and no statement that explicitly allows, the access is denied.
- In the case of a conflict of deny/allow, denial takes precedence:
  - If there is a statement that denies access to a resource for a given action and there is a statement that allows access to a resource for the same action, the access is denied.

### Permission Policy Statements - Available Actions and Resources

This section lists the actions and resources available for compiling statements you add to your custom Permission Policies.

### Statements - Available Actions

When creating statements for Permission Policies, actions _always require_ a resource-type to operate against.

Some actions also require a resource path - either a specific item or group to be defined or a wildcard `‘*'` to indicate all items of the resource-type. For a `config:create` action, no resource path is required and we use a wildcard to apply denial of meter creation to all meters:

```json
{
  "effect": "deny",
  "action": ["config:create"],
  "resource": ["config:meter/*"]
}
```

However, for a `config:retrieve` action, a resource path is required:

```json
{
  "effect": "deny",
  "action": ["config:retrieve"],
  "resource": ["config:meter/item/456"]
}
```

For actions that don’t require a path, paths in associated MRIs will be ignored, and only the resource-type will be used. You can use the following actions when creating Permission Policy statements:

| Action                      | MRI Path Required?  |
| --------------------------- | --------------------|
| config:create               | No                   |
| config:retrieve             | Yes                  |
| config:update               | Yes                  |
| config:delete               | Yes                  |
| measurements:upload         | Yes                  |
| measurements:fileUpload      | Yes                  |
| measurements:retrieve       | Yes                  |
| exports:download            | Yes                  |
| ALL                         | *                    |

### Which Actions can I use with which Resources?

For the resources listed in the [following section](https://docs.m3ter.com/guides/organization-and-access-management/creating-and-managing-permissions#statements-available-resources), the Actions you can use when creating Permission Policy Statements are determined by Resource type:

- Measurements data:
  - `measurements:retrieve`
  - `measurements:upload`
  - `measurements:fileUpload`
- Exports data:
  - `exports:download`
- Other Resource types:
  - `config:create`
  - `config:retrieve`
  - `config:update`
  - `config:delete`

##### Examples

- **Billing Operations**. Suppose you want to set up a Permission Policy that you’ll assign to Users of your Organization that belong to the Billing Operations Team. You want them to have full access to work with a specific collection of Bill, Account, AccountPlan, and Bill Statement resources. You can use the four `config` actions with the relevant resources to build the required Permission Policy statement:

```json
{
  "effect": "allow",
  "action": [
    "config:create",
    "config:retrieve",
    "config:update",
    "config:delete"
  ],
  "resource": [
    "billing:bill/*",
    "billing:balance/*",
    "billing:billjob/*",
    "billing:credit/*",
    "billing:creditAdjustment/*",
    "config:account/*",
    "config:accountPlan/*",
    "config:commitment/*",
    "config:contract/*",
    "config:plan/*",
    "config:planGroup/*",
    "config:planGroupLink/*",
    "statement:statement/*",
    "statementjob:statementjob/*"
  ]
}
```

This means that all members of the Billing Operations Team will have full CRUD access to all resources of the type specified.

- **Measurements Data**. For a Permission Policy statement you want to use to define User permissions for the `measurements:data` resource, you _cannot use_ any of the `config` actions. If you want to create a Permission Policy to allow a User full access to work with measurements data, you must use the `measurements` actions:

```json
{
  "effect": "allow",
  "action": [
    "measurements:upload",
    "measurements:fileUpload",
    "measurements:retrieve"
  ],
  "resource": [
    "measurements:data/*"
  ]
}
```

- **Data Exports**. For a Permission Policy granting Users full working access to create, manage and run data exports, you can create a Permission Policy with two statements. To create and manage data exports:

```json
{
  "effect": "allow",
  "action": [
    "config:create",
    "config:delete",
    "config:retrieve",
    "config:update"
  ],
  "resource": [
    "config:exportDestination/*",
    "config:exportSchedules/*",
    "config:exportStatus/*"
  ]
}
```

- To run data exports:

```json
{
  "effect": "allow",
  "action": [
    "exports:download"
  ],
  "resource": [
    "exports:data/*"
  ]
}
```

### Statements - Available Resources

You can use the following resources when creating Permission Policy statements:

| Resource                         | Policy Statement Format  |
| -------------------------------- | -------------------------|
| ALL                              | *                         |
| action                           |                           |
| ACTION_PERFORMED                | action:actionPerformed    |
| analytics                        |                           |
| USAGE                            | analytics:usage           |
| billing                          |                           |
| BALANCE                          | billing:balance           |
| BILL                             | billing:bill              |
| BILL_JOB                         | billing:billjob           |
| CHARGE                           | billing:charge            |
| BILL_CONFIG                      | billing:config            |
| COUNTER_ADJUSTMENT              | billing:counterAdjustment  |
| CREDIT                           | billing:credit            |
| CREDIT_ADJUSTMENT               | billing:creditAdjustment  |
| BILL_LOCK                        | billing:lock             |
| SCHEDULED_VALIDATION            | billing:validation        |
| config                           |                           |
| ACCOUNT                          | config:account            |
| ACCOUNT_PLAN                     | config:accountPlan        |
| ACTION                           | config:action            |
| ACTION_TRIGGER                   | config:actionTrigger      |
| AGGREGATION                      | config:aggregation        |
| ALERT                            | config:alert              |
| ANALYTICS_JOB                   | config:analyticsJob        |
| COMMITMENT                       | config:commitment        |
| CONTRACT                         | config:contract          |
| COUNTER                          | config:counter           |
| PICKLIST_CREDIT_REASON           | config:creditReason      |
| CREDIT_TYPE                       | config:creditType        |
| PICKLIST_CURRENCY                | config:currency          |
| CUSTOM_FIELD                     | config:customField       |
| DATA_EXPLORER_SELECTION          | config:dataExplorerSelection|
| PICKLIST_DEBIT_REASON            | config:debitReason       |
| EVENT                            | config:event             |
| EXTERNAL_MAPPING                 | config:externalMapping    |
| INTEGRATION                      | config:integration       |
| METER                            | config:meter             |
| METER_GROUP                      | config:metergroup        |
| NOTIFICATION                     | config:notification      |
| ORGANIZATION_CONFIG              | config:organizationConfig |
| OUTGOING_INTEGRATION            | config:outgoingIntegration|
| PERMISSION_POLICY                | config:permissionPolicy  |
| PRINCIPAL_PERMISSION             | config:principalPermission|
| PLAN                             | config:plan              |
| PLAN_GROUP                       | config:planGroup        |
| PLAN_GROUP_LINK                  | config:planGroupLink     |
| PLAN_TEMPLATE                    | config:planTemplate      |
| PRODUCT                          | config:product           |
| REPORT_SELECTION                 | config:reportSelection   |
| RESOURCE_GROUP                   | config:resourceGroup     |
| SERVICE_USER                     | config:serviceUser       |
| SUPPORT_USERS                    | config:supportUsers      |
| TEMPLATE                         | config:template          |
| PICKLIST_TRANSACTION_TYPE        | config:transactionType   |
| ORG_USER                         | config:user              |
| ORG_USER_INVITATION              | config:orgUserInvitation |
| EXPORT_DESTINATION               | config:exportDestination  |
| EXPORT_SCHEDULES                 | config:exportSchedules    |
| EXPORT_STATUS                    | config:exportStatus      |
| SCHEDULED_EVENT                  | config:scheduledEvent     |
| USAGE_SAVED_QUERY                | config:usageSavedQuery   |
| integration                      |                           |
| INTEGRATION_CONFIG               | integration:integrationConfig|
| INTEGRATION_CREDENTIALS          | integration:integrationCredentials|
| INTEGRATION_DESTINATION          | integration:integrationDestination|
| INTEGRATION_RUN                  | integration:integrationRun|
| INTEGRATION_MARKETPLACE_USAGE    | integration:marketplaceUsage|
| measurements                     |                           |
| MEASUREMENTS                     | measurements:data        |
| MEASUREMENTS_VALIDATION_ERRORS    | measurements:validationErrors|
| statement                         |                           |
| STATEMENT                        | statement:statement      |
| statement definition              |                           |
| STATEMENT_DEFINITION              | statementdefinition:statementdefinition|
| statement job                     |                           |
| STATEMENT_JOB                    | statementjob:statementjob|
| exports                          |                           |
| EXPORTS_JOB                      | exports:data             |

## Creating Custom Permission Policies

In the Settings area of the Console, you can quickly create and manage Custom Permission Policies.

**Important: Access to Console!** To enable any Users who are assigned **Custom** Permission Policies to access the m3ter Console, please ensure that one of their Permission Policies includes a Statement that allows them to **Retrieve** two Resources:
- `config:organizationConfig`
- `billing:config`

Without these permissions Users will be unable to access the Console - see step 9 in the following procedure.

**To create and manage Permission Policies:**

1. Select **Settings**:
2. Select **Access settings**:
3. Select the **Permission policies** tab:
4. Select **Create permission policy**. The **Create** page opens.
5. Under **Permission policy details**, enter a descriptive **Name** for the new Permission Policy.
6. Under **Permission policy statements**, you have the option to use either a **Simple** or **Advanced** editor to add Statements to the Permission Policy.
7. Leave the **Simple** editor selected. Here’s an example of how to compile Statements using the **Advanced editor** to allow all actions for all Meters:
8. Select **Advanced** if you want to add JSON formatted Statements. 
9. If you want to add another JSON formatted Statement, select **Add**. A new Statement text editor window is shown:
10. When you have finished adding all of the required Statements for the Permission Policy, select **Create permission policy**. 
11. Select **Edit** to edit the new policy.
12. If you want to delete a Permission Policy, return to the **Permission policies** tab and select the delete icon for the Policy:

**Tip: Using API Call to Create Permission Policy?** You can use the [Create Permission Policy](https://docs.m3ter.com/api/permissionpolicy/create-permission-policy) config API call.

## Permissions Exceptions

There are instances where exceptions to the general permissions framework can occur as a result of shared data:
- For example, if a user has been assigned a Permission Policy that denies them access to Products but grants them access to Bills, when they open a Bill, some Product data referenced by the Bill’s line items will be shown for the user.