# Policies Overview

A Policy acts as a "gate" for a given activity in Dfns system, which enforces a set of rules before the activity is executed. If triggered, a policy can either block the activity or launch an approval process before finalizing the activity.

A Policy is defined by:

* an [**Activity kind**](#activities): the type of activity that this policy should gate.
* a [**Rule**](#policy-rules): defines the rule being evaluated to know whether the policy should "activate" (aka "trigger") or not for a given activity happening in the system.
* an [**Action**](#policy-action): after rule was evaluated, if the policy is triggered, the action defines what action is taken as a consequence.
* optional [**Filters**](#policy-filters)**:** these can be used to reduce the scope upon which the policy applies.

Once evaluated for a given activity, a policy is either `Skipped` if the rule did not apply or is triggered executing the associated action. If the action is `RequestApproval`, an [**Approval**](#approval) process is initiated.

***

## Activities

"Activity" is a generic term describing some activity in the Dfns system. Supported activity kinds are: [`Wallets:Sign`](#wallets-sign-activity), [`Permissions:Assign`](#permissions-assign-activity), [`Permissions:Modify`](#permissions-modify-activity) , [`Policies:Modify`](#policies-modify-activity). 

### `Wallets:Sign` activity

A "`Wallets:Sign`" activity represents any activity which involves signing with a wallet. Currently, in our API, these can be:

* a Transfer Request (created using the endpoint [Transfer Asset from Wallet](/d/api-docs/wallets/transfer-asset.md))
* a Transaction Request (created using the endpoint [Broadcast Transaction from Wallet](/d/api-docs/wallets/broadcast-transaction.md))
* a Signature Request (created using the endpoint [Generate Signature from Wallet](/d/api-docs/wallets/generate-signature.md))

### `Wallets:IncomingTransaction` activity

A "`Wallets:IncomingTransaction`" activity represents when our indexers detected an incoming transaction into a wallet. This activity kind has to be used with the rule kind "`ChainalysisTransactionScreening`" (see more on [Chainalysis](/d/integrations/aml-kyt/chainalysis.md) integration page), and the action kind "`NoAction`", meaning that no actual action will be taken as a result of the Chainalysis screening, other than notifying you through a webhook event if the policy is triggered. The reason for that, is that the incoming transaction is already on-chain, so the funds are already in the wallet, we cannot block that transfer on chain.

### `Permissions:Modify` activity

A "`Permissions:Modify`" activity represents any activity which involves updating or archiving a permission. These activities are Permission change requests, created as a result of calling either:

* the endpoint [Update Permission](/d/api-docs/permissions/permissions/updatepermission.md)
* the endpoint [Archive Permission](/d/api-docs/permissions/permissions/archivepermission.md)

### `Permissions:Assign` activity

A "`Permissions:Assign`" activity represents any activity which involves assigning a permission (or revoking it, aka "deleting a permission assignment"). These activities are Assignment change requests, created as a result of calling either:

* the endpoint [Assign Permission](/d/api-docs/permissions/permissions/createassignment.md)
* the endpoint [Revoke Permission](/d/api-docs/permissions/permissions/revokeassignment.md)

### `Policies:Modify` activity

A "`Policies:Modify`" activity represents any activity which involves updating or archiving a policy. These activities are Policy change requests, created as a result of calling either:

* the endpoint [Update Policy](/d/api-docs/policy-engine/api-reference/update-policy.md)
* the endpoint [Archive Policy](/d/api-docs/policy-engine/api-reference/archive-policy.md)

Every policy requires a rule to be specified. Upon policy evaluation, the configuration specified in the rule will be used to determine whether the policy should trigger or not for a given activity.  

By exposing controls on permissions and policies, Dfns enables the specification of an admin quorum to approve sensitive actions which could change system governance.   Note Dfns does not expose a separate "admin quorum" concept like some of our competitors - we simply enable this use case as another configuration of the policy engine itself.   This was chosen to promote flexibility as not every customer will have the same requirements around creating and managing admin quorums. 

***

## Policy Rules

The policy rule is what gets evaluated to determine whether a given activity will "activate" (aka "trigger") the policy, therefore applying the policy "Action", or whether it will skip it.

Supported Policy Rule kinds are:[`AlwaysTrigger`](#alwaystrigger-policy-rule), [`TransactionAmountLimit`](#transactionamountlimit-policy-rule), [`TransactionAmountVelocity`](#transactionamountvelocity-policy-rule), [`TransactionCountVelocity`](#transactioncountvelocity-policy-rule), [`TransactionRecipientWhitelist`](#transactionrecipientwhitelist-policy-rule) . 

### `AlwaysTrigger` policy rule

This rule can be used on a policy of any `activityKind`. It will always be triggered, meaning that if this rule is defined on a policy, the policy will always trigger the policy action, regardless of the activity details.

```json
{
  "rule": {
    "kind": "AlwaysTrigger",
  }
}
```

### `TransactionAmountLimit` policy rule

This rule can be used on a policy of `activityKind` = `Wallets:Sign`. It will trigger if the wallet activity detected is transferring some value which amount is greater than a given limit.

{% hint style="info" %}
If the fiat amount of the wallet activity cannot be evaluated for any reason (eg. market prices are not available, or eg. the amount cannot be inferred from a wallet signature request, etc.), by default the rule will trigger the policy (this is called "failing closed" and is generally considered a security best practice).
{% endhint %}

```json
{
  "rule": {
    "kind": "TransactionAmountLimit",
    "configuration": {
      "limit": 1000,
      "currency": "USD",
    },
  }
}
```

**Configuration**

<table><thead><tr><th width="154">Property</th><th width="154">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>limit</code><mark style="color:red;">*</mark></td><td>Positive Integer</td><td>Amount limit in <code>currency</code></td></tr><tr><td><code>currency</code><mark style="color:red;">*</mark></td><td>String</td><td>Fiat currency, currently only  <code>USD</code></td></tr></tbody></table>

### `TransactionAmountVelocity` policy rule

This rule can be used on a policy of `activityKind` = `Wallets:Sign`. It will trigger if the cumulative amount transferred from a given wallet within a given timeframe is greater than a specified limit.  The aggregate amount evaluated is based only on the wallet that triggered the policy.&#x20;

{% hint style="info" %}
If the fiat amount of any wallet activity in the given timeframe cannot be evaluated for any reason (eg. market prices are not available, or eg. the amount cannot be inferred from a wallet signature request, etc.), by default the rule will trigger the policy (ie. will fail closed).
{% endhint %}

```json
{
  "rule": {
    "kind": "TransactionAmountVelocity",
    "configuration": {
      "limit": 1000,
      "currency": "USD",
      "timeframe": 60,
    },
  },
}
```

**Configuration**

<table><thead><tr><th width="154">Property</th><th width="154">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>limit</code><mark style="color:red;">*</mark></td><td>Positive Integer</td><td>Amount limit in <code>currency</code></td></tr><tr><td><code>currency</code><mark style="color:red;">*</mark></td><td>String</td><td>Fiat currency, currently only <code>USD</code></td></tr><tr><td><code>timeframe</code><mark style="color:red;">*</mark></td><td>Positive Integer</td><td>Time period in minutes. Minimum 1, Maximum 43,200.</td></tr></tbody></table>

### `TransactionCountVelocity` policy rule

This rule can be used on a policy of `activityKind` = `Wallets:Sign`. It will trigger if the number of wallet activities for a given wallet within a given timeframe, is greater than a specified limit.  The aggregate number of transactions evaluated is based only on the wallet that triggered the policy.&#x20;

```json
{
  "rule": {
    "kind": "TransactionCountVelocity",
    "configuration": {
      "limit": 5,
      "timeframe": 60,
    },
  },
}
```

**Configuration**

<table><thead><tr><th width="154">Property</th><th width="154">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>limit</code><mark style="color:red;">*</mark></td><td>Positive Integer</td><td>Amount limit in <code>currency</code></td></tr><tr><td><code>timeframe</code><mark style="color:red;">*</mark></td><td>Positive Integer</td><td>Time period in minutes. Minimum 1, Maximum 43,200.</td></tr></tbody></table>

### `TransactionRecipientWhitelist` policy rule

This rule can be used on a policy of `activityKind` = `Wallets:Sign`. It will trigger if the wallet activity transfers some value to a recipient *and the destination address is NOT whitelisted*.

{% hint style="warning" %}
Address comparison is case sensitive when evaluating the rule. For EVM addresses, make sure you use the canonical all lowercase address format, not the mixed-case checksum address format, in your policy rule configuration. Otherwise, the evaluation will fail and trigger the policy.
{% endhint %}

{% hint style="info" %}
If the wallet activity is not a value transfer, or the transaction recipient cannot be inferred from the wallet activity (eg if you use [Generate Signature](/d/api-docs/wallets/generate-signature.md)), by default the rule will trigger the policy (ie. fail closed).
{% endhint %}

If the specified whitelisted address list is empty, it basically means "no addresses are whitelisted", so the rule will trigger for any wallet activities.

```json
{
  "rule": {
    "kind": "TransactionRecipientWhitelist",
    "configuration": {
      "addresses": ["0x...1", "0x...2"],
    },
  }
}
```

**Configuration**

<table><thead><tr><th width="154">Property</th><th width="154">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>addresses</code><mark style="color:red;">*</mark></td><td>List of Positive Integer</td><td>Whitelisted recipient addresses</td></tr></tbody></table>

### `ChainalysisTransactionPrescreening`   policy rule

{% hint style="info" %}
This rule can only be used once the Chainalysis integration is activated from the Dfns dashboard settings. (see more on [Chainalysis](/d/integrations/aml-kyt/chainalysis.md) integration page)
{% endhint %}

This rule can be used on a policy of `activityKind` = `Wallets:Sign`. It's a rule based on [Chainalysis](/d/integrations/aml-kyt/chainalysis.md) KYT integration (Know-Your-Transaction). Upon transfer attempt, we will first register the transfer with Chainalysis (as a ["withdrawal attempt"](https://docs.chainalysis.com/api/kyt/#registration-register-a-withdrawal-attempt)), and fetch the screening results (alerts, exposures, addresses detected). Based on the results, and the configuration of this rule, the policy will be triggered.&#x20;

It's called "Pre"-screening, because the scanned transaction is not on chain yet, it's still a transaction attempt (before the transaction actually make it on chain).

```json
{
  "rule": {
    "kind": "ChainalysisTransactionPrescreening",
    "configuration": {
      "alerts": {
        "alertLevel": "LOW",
        "categoryIds": []
      },
      "exposures": {
        "direct": {
          "categoryIds": []
        }
      },
      "addresses": {
        "categoryIds": []
      },
      "fallbackBehaviours": {
        "skipUnscreenableTransaction": false,
        "skipUnsupportedNetwork": false,
        "skipUnsupportedAsset": false,
        "skipChainalysisFailure": false
      }
    }
  }
}
```

**Configuration**

<table><thead><tr><th width="229">Property</th><th width="154">Type</th><th>Description</th></tr></thead><tbody><tr><td><p><code>alerts</code></p><p> <code>.alertLevel</code><mark style="color:red;">*</mark></p></td><td><code>string</code></td><td>Minimum alert level above which the rule should trigger, if any <a href="https://docs.chainalysis.com/api/kyt/#withdrawal-attempts-get-alerts">alert is returned in Chainalysis results</a>. Can be <code>LOW</code>, <code>MEDIUM</code>, <code>HIGH</code>, or <code>SEVERE</code></td></tr><tr><td><p><code>alerts</code></p><p> <code>.categoryIds</code><mark style="color:red;">*</mark></p></td><td>list of integers</td><td>List of Chainalysis category IDs (see <a href="https://docs.chainalysis.com/api/kyt/#categories">here</a>). If you leave this list empty, alerts of any category will trigger the rule. Otherwise, if you only want the rule to trigger on specific categories, you can specify some in the list.</td></tr><tr><td><p><code>exposures</code></p><p> <code>.direct</code></p><p>  <code>.categoryIds</code><mark style="color:red;">*</mark></p></td><td>list of integers</td><td>List of Chainalysis category IDs (see <a href="https://docs.chainalysis.com/api/kyt/#categories">here</a>). If you leave this list empty, a <a href="https://docs.chainalysis.com/api/kyt/#withdrawal-attempts-get-direct-exposure">direct exposure</a> of any category detected by chainalysis will trigger the rule. Otherwise, if you only want the rule to trigger on specific categories, you can specify some in the list.</td></tr><tr><td><p><code>addresses</code></p><p> <code>.categoryIds</code><mark style="color:red;">*</mark></p></td><td>list of integers</td><td>List of Chainalysis category IDs (see <a href="https://docs.chainalysis.com/api/kyt/#categories">here</a>). If you leave this list empty, an <a href="https://docs.chainalysis.com/api/kyt/#withdrawal-attempts-get-address-identifications">address</a> of any category identified by chainalysis will trigger the rule. Otherwise, if you only want the rule to trigger on specific categories, you can specify some in the list.</td></tr><tr><td><p><code>fallbackBehaviours</code></p><p><code>.skipUnscreenableTransaction</code><mark style="color:red;">*</mark></p></td><td>boolean</td><td>Behaviour if the wallet activity is not screenable (eg. if it's a signature request of a hash). If true, a transaction which is "unscreenable" will just be skipped, and policy will not trigger</td></tr><tr><td><code>fallbackBehaviours.skipUnsupportedNetwork</code><mark style="color:red;">*</mark></td><td>boolean</td><td>Behaviour if the wallet activity is on a network not supported by chainalysis, or not yet supported in the dfns-chainalysis integration. If true, an unsupported network will just be skipped, and policy will not trigger</td></tr><tr><td><code>fallbackBehaviours.skipUnsupportedAsset</code><mark style="color:red;">*</mark></td><td>boolean</td><td>Behaviour if the wallet activity is with a asset not supported by chainalysis, or not yet supported in the dfns-chainalysis integration. If true, an unsupported asset will just be skipped, and policy will not trigger</td></tr><tr><td><code>fallbackBehaviours.skipChainalysisFailure</code><mark style="color:red;">*</mark></td><td>boolean</td><td>Behaviour if any issue with Chainalysis calls (timeout, results took too long, rate limiting errors, any error). If true, will skip if any error happens </td></tr></tbody></table>

### `ChainalysisTransactionScreening`   policy rule

{% hint style="info" %}
This rule can only be used once the Chainalysis integration is activated from the Dfns dashboard settings (see more on [Chainalysis](/d/integrations/aml-kyt/chainalysis.md) integration page)
{% endhint %}

This rule can be used on a policy of `activityKind` = `Wallets:IncomingTransaction`, and with the action kind `NoAction`. It's a rule based on Chainalysis KYT integration (Know-Your-Transaction). Upon an incoming transaction detectedby our indexers, we will [register the transfer with Chainalysis](https://docs.chainalysis.com/api/kyt/#registration-register-a-transfer), and fetch the results of the analysis (alerts & exposures detected). Based on the results, and the configuration of this rule, the policy will be triggered.

The shape of the rule is almost like the `ChainalysisTransactionPrescreening` rule, expect the the `address` property is not supported.

```json
{
  "rule": {
    "kind": "ChainalysisTransactionPrescreening",
    "configuration": {
      "alerts": {
        "alertLevel": "LOW",
        "categoryIds": []
      },
      "exposures": {
        "direct": {
          "categoryIds": []
        }
      },
      "fallbackBehaviours": {
        "skipUnscreenableTransaction": false,
        "skipUnsupportedNetwork": false,
        "skipUnsupportedAsset": false,
        "skipChainalysisFailure": false
      }
    }
  }
}
```

**Configuration**

See the above configuration for rule `ChainalysisTransactionPrescreening`

### `TravelRuleTransactionPrescreening` policy rule

{% hint style="info" %}
This rule can only be used once the Notabene integration is activated from the Dfns dashboard settings (see more on [Notabene](/d/integrations/travel-rule/notabene.md) integration page)
{% endhint %}

This rule can be used on a policy of `activityKind` = `Wallets:Sign,`and with the action kind `Block`. It's a rule based on [Notabene](/d/integrations/travel-rule/notabene.md) [TravelRule](/d/integrations/travel-rule.md) integration. It ***ONLY*** applies to Dfns [Transfer Asset](/d/api-docs/wallets/transfer-asset.md) Api Calls. It is NOT supported for Transfers initiated via the dashboard. Upon transfer attempt with an optional [TravelRule](/d/api-docs/wallets/transfer-asset.md) payload, we will call Notabene's APIs on your behalf to both confirm the validity of the travel rule message and submit it for processing. Dfns then waits for a response from the counterparty (for custodial transfers) or Notabene (for non-custodial transfers).

It's called "Pre"-screening, because the transaction is not on chain yet, it's still a transaction attempt (before the transaction actually make it on chain).

```json
{
  "kind": "TravelRuleTransactionPrescreening",
  "configuration": {
    "vendor": "Notabene",
    "autoTriggerTimeoutSeconds": 300,
    "autoClearAfterDeliveredTimeoutSeconds": 200
  }
}
```

\
**Configuration**

<table><thead><tr><th width="239.8828125">Property</th><th width="184.57421875">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>vendor</code></td><td><code>string</code></td><td>TravelRule vendor to use for the prescreening policy. At the moment we only support <strong><code>Notabene</code></strong>.</td></tr><tr><td><pre><code>autoTrigger
TimeoutSeconds
</code></pre></td><td><code>Positive Integer</code></td><td>If we do NOT receive any updates from Notabene regarding the status of the travel rule message we need to eventually time out and reject the transfer. This is the timeout, in seconds, we wait for a response from Notabene before rejecting the transfer.</td></tr><tr><td><p></p><pre class="language-json"><code class="lang-json">autoClearAfterDelivered
TimeoutSeconds
</code></pre></td><td><code>Positive Integer</code><br><code>(Optional)</code></td><td>This <code>OPTIONAL</code> setting allows you to proceed with a transfer that Notabene has delivered to a counterparty even if the recipient hasn't responded after delivery. </td></tr></tbody></table>

## Policy Action

An action specifies what should happen if a policy rule is triggered. Supported action kinds are: [`Block`](#block-policy-action)`and`[`RequestApproval`](#requestapproval-policy-action).

### `Block` policy action

This action means that the activity will be blocked if the policy is triggered.

```json
{
  "action": {
    "kind": "Block"
  }
}
```

### `RequestApproval` policy action

This action means that activity will first require an Approval process to be completed before it can  be executed (or be aborted if someone rejects it during the approval process).

One or several groups of approvers need to be specified. These groups define who is allowed to approve / reject an activity.

The activity will only be executed if all approver groups reach their "quorum" of approvals. Otherwise, if any one user within any approver group rejects, then the activity is aborted and the call is not executed.

The example below shows a `RequestApproval` action, configured with one approval group requiring 2 approvals amongst three specific users.&#x20;

```json
{
  "action": {
    "kind": "RequestApproval",
    "autoRejectTimeout": 60, // minutes
    "approvalGroups": [
      {
        "name": "Admins",
        "quorum": 2, // only 2 approvers required in that group 
        "approvers": {
          "userId": {
            "in": ["us-...1", "us-...2", "us-...3"],
          }
        }
      }
    ],

  }
}
```

{% hint style="danger" %}

### You **cannot approve your own requests**

Please make your policies won't require a requester to approve his/her own request so you don't get blocked.&#x20;

*Example:* Company has 3 users allowed to modify policies. They create a policy that requires approval from 3 out of the 3 users for any future policy modification. In this case, they get cannot modify policies anymore: whoever requests a modification cannot approve, and the policy is therefore always missing one approver. They need to invite a new user and give him the rights to update the policy, so he can lower the quorum and the 3 original users can approve the modification.
{% endhint %}

<table><thead><tr><th width="222">property</th><th width="170">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>approvalGroups</code><mark style="color:red;">*</mark></td><td>List of Object</td><td>List of approval groups. If multiple groups are defined, the approval is complete only when all groups have approved</td></tr><tr><td><p><code>approvalGroups[*]</code></p><p><code>.name</code></p></td><td>(Optional) String</td><td>Optional name of this group.</td></tr><tr><td><p><code>approvalGroups[*]</code></p><p><code>.quorum</code><mark style="color:red;">*</mark></p></td><td>Positive Integer</td><td>The quorum is the number of approvals required in this group to reach group consensus. The activity is executed only if all groups reached their approval quorum.</td></tr><tr><td><p><code>approvalGroups[*]</code></p><p><code>.approvers</code><mark style="color:red;">*</mark></p></td><td>Object</td><td>Defines all users that are allowed to approve in the group.<br><br>If set to an empty object  <code>{}</code>, it means that anyone within your organisation can be an approver.<br><br>Otherwise, you can specify an exact list of allowed approvers, by adding their user IDs in this object:  <code>{ userId: { in: [...] }}</code></td></tr><tr><td><code>autoRejectTimeout</code></td><td>(Optional) Positive Integer</td><td>Number of minutes after which, if the approval has not reach global consensus (all groups reached their consensus), the activity is automatically rejected.<br><br>If not specified, the activity will never be rejected automatically (the approval process doesn't "expire" / "times out").</td></tr></tbody></table>

### `NoAction` policy action

This action kind means that nothing will happen after policy rule evaluation. It's meant to be used with policy rules "`ChainalysisTransactionPrescreening`" or "`ChainalysisTransactionScreening`". This action is for when you just want the KYT analysis rule to be run, and then if triggered, those result returned in a `policy.triggered` [Webhook Event](/d/api-docs/webhooks.md#webhook-events).

```json
{
  "action": {
    "kind": "NoAction"
  }
}
```

***

## Policy Filters

Policy filters can reduce the scope on which the policy applies. If no filters are specifies, the policy applies to all activities happening in your organisation (all activities of the kind defined by the policy `activityKind`).

For example, you can use filters to setup a policy for activities happening on specific wallets or on groups of wallets. Some examples include:

* "All activities from wallets tagged '`group:treasury`' must first be approved by the CEO
* "All transfers from wallet ID 1 larger than $1k must first be approved by the CEO & the CFO"
* "All transfers from wallets tagged '`accounting:freeze`' must be blocked"

The filters that you can specify depend on the `activityKind` of your policy (`activityKind`)

### Filters for `"Wallets:Sign"` activity

<table><thead><tr><th width="158">key</th><th width="111">evaluator</th><th>Value</th></tr></thead><tbody><tr><td><code>walletId</code></td><td><code>in</code></td><td>List of wallet IDs. If the activity is from a wallet within one of these IDs, the policy applies to this wallet.</td></tr><tr><td><code>walletTags</code></td><td><code>hasAny</code></td><td>List of tags. If the activity is from a wallet that <strong>has any of these tags</strong>, the policy will apply to this wallet.</td></tr><tr><td><code>walletTags</code></td><td><code>hasAll</code></td><td>List of tags. If the activity is from a wallet that <strong>has all of these tags</strong>, the policy will apply to this wallet.</td></tr></tbody></table>

Some examples:

* The policy is scoped only to wallets with IDs `wa-1` or `wa-2`:

```json
{
  "filters": {
    "walletId": {
      "in": ["wa-1", "wa-2"]
    }
  }
}
```

* The policy is scoped only to wallets tagged either "`domain:accounting`" or "`sensitive`":

```json
{
  "filters": {
    "walletTags": {
      "hasAny": ["domain:accounting", "sensitive"]
    }
  }
}
```

* The policy is scoped only to wallets tagged with both "`domain:accounting`" and "`sensitive`":&#x20;

```json
{
  "filters": {
    "walletTags": {
      "hasAll": ["domain:accounting", "sensitive"]
    }
  }
}
```

* The policy is scoped only to wallets containing all these tags ("`domain:accounting`", "`zone:asia`") **AND** at least one of these tags ("`security:high`", "`security:medium`"):&#x20;

```json
{
  "filters": {
    "walletTags": {
      "hasAll": ["domain:accounting", "zone:asia"],
      "hasAny": ["security:high", "security:medium"]
    }
  }
}
```

Note the relationship between inclusion operators is always AND, not OR.&#x20;

### Filters for `"Policies:Modify"` activity

<table><thead><tr><th width="177">filter key</th><th width="111">evaluator</th><th>Value</th></tr></thead><tbody><tr><td><code>policyId</code></td><td><code>in</code></td><td>List of policy IDs. If the policy being modified is one of these IDs, the policy applies.</td></tr></tbody></table>

Some examples:

* The policy is scoped only to policies with IDs `plc-1` or `plc-2`

```json
{
  "filters": {
    "policyId": {
      "in": ["plc-1", "plc-2"]
    }
  }
}
```

### Filters for `"Permissions:Modify"` activity

<table><thead><tr><th width="177">filter key</th><th width="111">evaluator</th><th>Value</th></tr></thead><tbody><tr><td><code>permissionId</code></td><td><code>in</code></td><td>List of permission IDs. If the permission being modified is one of these IDs, the policy applies.</td></tr></tbody></table>

Some examples:

* The policy is scoped only to permissions with IDs `pm-1` or `pm-2`

```json
{
  "filters": {
    "permissionId": {
      "in": ["pm-1", "pm-2"]
    }
  }
}
```

### Filters for `"Permissions:Assign"` activity

<table><thead><tr><th width="177">filter key</th><th width="111">evaluator</th><th>Value</th></tr></thead><tbody><tr><td><code>permissionId</code></td><td><code>in</code></td><td>List of permission IDs. If the permission being assigned/revoked is one of these IDs, the policy applies.</td></tr></tbody></table>

Some examples:

* The policy is scoped only to permissions with IDs `pm-1` or `pm-2`

```json
{
  "filters": {
    "permissionId": {
      "in": ["pm-1", "pm-2"]
    }
  }
}
```

***

## Approval

When a policy is triggered and the action defined is `RequestApproval`, an Approval object is created containing:

* details about the activity that triggered this approval flow
* details on the different policy evaluations that happened for that activity and their result
* details about the decisions given by each approvers

When a new Approval object is created and an approval process is required, a [webhook event](/d/api-docs/webhooks.md#webhook-events) is emitted (event kind "`policy.approval.pending`"). You can subscribe to it to react to this event, eg. send notifications to the users that need to give their approval.

The Approval object can be queried using the `approvalId` returned from the endpoint that triggered the approval process, using the [Get Approval](/d/api-docs/policy-engine/api-reference/list-approvals.md) / [List Approvals](/d/api-docs/policy-engine/api-reference/list-approvals-1.md) endpoints.

Users can then call the [Create Approval Decision](/d/api-docs/policy-engine/api-reference/create-approval-decision.md) endpoint to either approve / reject this activity.  Of course this can also be done via the Dfns dashboard.&#x20;

A user can only give his approval / rejection if he is defined inside one of the approval groups defined on the policies that triggered.

A given user can only approve or reject once. If multiple approval groups exist, a decision from a single user will count as a decision for any of the groups this user belongs to.

A rejection from any user of any groups immediately rejects an activity.

The initiator is not allowed to approve their activity, but can deny it if they need to cancel it.

Here's an Approval object example

```json
{
  "id":"ap-...",
  "initiatorId":"us-...",
  "status":"Pending",
  "expirationDate":"2023-12-22T21:16:16.659Z",
  "dateCreated":"2023-12-22T20:56:16.662Z",
  "dateUpdated":"2023-12-22T20:56:16.662Z",
  "activity":{
    "kind": "Wallets:Sign",
    "transferRequest": { // the transfer request object from transfer endpoint
      "id": "xfr-...",
      ...
    },
  },
  "evaluatedPolicies":[
    {
      "policyId":"plc-...",
      "triggerStatus":"Triggered",
      "reason":"Number of transactions (2) is above limit (2)."
    },
    {
      "policyId":"plc-...",
      "triggerStatus":"Triggered",
      "reason":"Cumulative transfer amount (USD 20) is above limit (USD 2)."
    }
  ],
  "decisions":[
    {
      "userId":"us-...",
      "dateActioned":"2023-12-22T20:56:16.662Z",
      "value":"Approved"
    }
  ],
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs-legacy.dfns.co/d/api-docs/policy-engine/policies.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.