> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dfns.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Governance architecture

> How Dfns combines authentication, permissions, policies, and MPC signing into a layered governance model for secure wallet operations.

This page explains how Dfns' governance layers work together to secure your digital assets.

## Overview

Every Dfns API request passes through multiple security layers before a blockchain transaction is signed:

```mermaid theme={null}
flowchart TB
    App[Your Application]

    subgraph Auth[1: Authentication]
        AuthCheck["Verify API token<br/>Verify user action signature"]
    end

    subgraph Authz[2: Authorization]
        PermCheck["Check user permissions<br/>e.g., Wallets:Sign"]
    end

    subgraph Policy[3: Policy Engine]
        PolicyEval["Evaluate matching policies"]
    end

    Blocked([Blocked])
    ApprovalRequired["Approval Required"]
    HumanApproval{"Human Review"}
    Rejected([Rejected])
    Approved["Approved"]

    subgraph MPC[4: MPC Signing]
        MPCSign["Distributed key shares<br/>sign collaboratively"]
    end

    subgraph Broadcast[5: Broadcast]
        BroadcastTx["Send to blockchain"]
    end

    App --> Auth
    Auth --> Authz
    Authz --> Policy
    Policy --> Blocked
    Policy --> ApprovalRequired
    Policy --> MPC
    ApprovalRequired --> HumanApproval
    HumanApproval -->|Reject| Rejected
    HumanApproval -->|Approve| Approved
    Approved --> MPC
    MPC --> Broadcast
```

## Layer 1: Authentication

Every API request must prove identity through two mechanisms:

### API Token

The `Authorization: Bearer <token>` header identifies who is making the request:

* **User tokens**: Short-lived, obtained through login flow
* **Service account tokens**: Long-lived, for server-to-server communication
* **Personal access tokens**: Long-lived user tokens for development

### User Action Signature

For state-changing operations (POST, PUT, DELETE), the `X-DFNS-USERACTION` header proves the caller controls a registered credential:

1. Client requests a challenge from Dfns
2. Client signs the challenge with their credential (passkey or asymmetric key)
3. Dfns verifies the signature matches a registered credential

This ensures that even if a token is stolen, an attacker cannot perform sensitive operations without the credential.

## Layer 2: Authorization (Permissions)

After authentication, Dfns checks if the user has permission to perform the requested action.

Permissions follow a whitelist model - users can only perform actions explicitly granted:

```mermaid theme={null}
flowchart LR
    User --> Permission --> Operations
```

Example: A user with `Wallets:Read` can view wallets but cannot transfer assets (requires `Wallets:Sign`).

See [Permissions](/core-concepts/roles-and-permissions) for the full list.

## Layer 3: Policy Engine

Even with valid authentication and permissions, the Policy Engine can add additional controls:

| Policy action     | Effect                                                   |
| ----------------- | -------------------------------------------------------- |
| `Block`           | Transaction is rejected                                  |
| `RequestApproval` | Transaction held until humans approve                    |
| `NoAction`        | Transaction proceeds (used with Chainalysis for logging) |

Policies evaluate rules like:

* Transaction amount limits
* Velocity limits (amount or count over time)
* Recipient whitelisting
* Chainalysis screening

**Important:** All matching policies are evaluated for every activity. If multiple policies apply:

* Any `Block` result immediately blocks the activity
* Multiple `RequestApproval` results require approvals from all triggered policies
* Policies cannot bypass or override each other

See [Policies](/core-concepts/policies) for details.

## Layer 4: MPC Signing

Once a transaction passes all checks, the MPC signing ceremony begins:

```mermaid theme={null}
flowchart TB
    subgraph MPC["Dfns MPC Network"]
        direction TB
        subgraph Signers[" "]
            direction LR
            S1["Signer Node<br/>Share 1"]
            S2["Signer Node<br/>Share 2"]
            S3["Signer Node<br/>Share 3"]
            S4["Signer Node<br/>Share 4"]
        end
        Threshold["Threshold Signature<br/>(k-of-n nodes collaborate)"]
        S1 --> Threshold
        S2 --> Threshold
        S3 --> Threshold
        S4 --> Threshold
    end
```

Key properties:

* **No complete key**: The private key never exists in one place
* **Threshold security**: Requires k-of-n shares to sign (not all shares needed)
* **Geographic distribution**: Nodes are in different data centers/regions
* **Audit trail**: Every signing ceremony is logged

## Layer 5: Broadcast

The signed transaction is broadcast to the blockchain network. Dfns monitors for confirmation and updates transaction status.

## Security model summary

| Layer               | What it protects against              |
| ------------------- | ------------------------------------- |
| Authentication      | Unauthorized access                   |
| User action signing | Token theft, replay attacks           |
| Permissions         | Privilege escalation                  |
| Policies            | Unauthorized transactions, fraud      |
| MPC                 | Key theft, single point of compromise |

## Separation of concerns

A critical security property: **credentials and keys are completely separate**.

| Credential (Authentication)                                 | Key (Signing)                 |
| ----------------------------------------------------------- | ----------------------------- |
| Proves identity                                             | Signs transactions            |
| Stored on user device (passkey) or server (service account) | Stored in MPC network         |
| Can be revoked/rotated                                      | Key shares are immutable      |
| Compromised credential ≠ stolen assets                      | Protected by all layers above |

Even if an attacker steals credentials, they still face:

* User action signing requirements
* Permission checks
* Policy enforcement
* MPC threshold requirements

## Related

<CardGroup cols={2}>
  <Card title="How MPC works" icon="lock" href="/core-concepts/how-mpc-wallets-work">
    Deep dive into MPC technology
  </Card>

  <Card title="Policies" icon="shield" href="/core-concepts/policies">
    Configuring transaction policies
  </Card>

  <Card title="Permissions" icon="user-shield" href="/core-concepts/roles-and-permissions">
    Understanding permission model
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/auth">
    Authentication flows
  </Card>
</CardGroup>