Roles and permissions

Roles enable you to control access to the platform on a granular basis (following the principle of least privilege). As an example, if you have an employee who needs to initiate payments, but shouldn’t be able to manipulate policies, you can create a role for that. Start by creating a role, selecting which permissions to include, and assigning it to a user.

Terminology

Role: a role is a named collection of permissions that can be assigned to users or service accounts. When assigned, a role allows the user to perform those actions in the platform. Each role has a unique name and ID. A role can be assigned to one or multiple users, depending on what you need.
Permission: a permission grants access to one action in the API (e.g. Wallets:Create). There is a fixed list of permissions (see below) that you can include in roles. Every API endpoint requires one or more permissions to use it.
Assignment: the act of granting a role to a user or service account. A role can be assigned (aka “granted”) or unassigned (aka “revoked”).

In the API, roles are called “permissions” and permissions are called “operations”. When you see POST /permissions in the API reference, it means “create a role”. The dashboard uses the more intuitive terminology.

Dfns-managed roles

When your Dfns organization is created, some roles already exist in it. They are special: some of them are automatically assigned, and some of them are immutable (cannot be updated or archived).

`ManagedFullAdminAccess`

This role is automatically assigned to the first user of the organization. It includes all existing (and future) permissions available in the Dfns API. It’s immutable, so you cannot update it or archive it. You can only assign it or revoke it.

`ManagedDefaultEndUserAccess`

This role is assigned by default to any new EndUser in your organization, and comes with an initial set of permissions (which you can update at any time) allowing any EndUser to use the wallet delegated to them by default.

Regardless of roles, an EndUser can only access wallets delegated to them. This role does not allow end-users to access your organization’s wallets. See Wallet Visibility below.

This role is meant to facilitate end-user access management. Since all your end users have this role assigned by default, you don’t necessarily need to explicitly grant them other roles to allow them to use their wallets, and you only need to modify this one role to affect all your end users at once. This role is not immutable, and you can still modify it or revoke it.

User types

Dfns supports three types of identities, each designed for different use cases:

Type	Description	Typical use
`CustomerEmployee`	Your team members	Dashboard access, wallet management
`EndUser`	Your end customers	Delegated wallets (user holds signing authority)
Service Account	Machine identity	Automation, server-to-server API calls

Comparison matrix

Capability	CustomerEmployee	EndUser	Service Account
Wallet visibility	All org wallets	Only delegated wallets	All org wallets
Dashboard access	Yes	No	No
Policy coverage	Yes	No (bypassed)	Yes
Can hold credentials	Yes (passkeys, keys)	Yes (passkeys, keys)	Yes (keys only)
Created via	Dashboard or API	Delegated registration	Service Account API

Wallet visibility

The wallets a user can see depends on their user type:

User Type	Wallet Visibility
`CustomerEmployee`	All wallets in the organization
`EndUser`	Only wallets delegated to them
Service Account	All wallets in the organization

CustomerEmployee users are your team members who access the Dfns dashboard and manage wallets on behalf of your organization. When granted Wallets:Read, they can see all org-managed wallets. This enables shared visibility across your team for operational purposes. EndUser accounts are for your end customers using delegated wallets. Each EndUser can only access wallets that have been delegated to them - they cannot see other users’ wallets or your organization’s wallets. This isolation is enforced at the platform level, regardless of permissions. Service Accounts are machine identities for server-to-server API calls. They can access all organization wallets (when granted appropriate permissions) and are commonly used for automation workflows.

Delegated wallets strictly belong to the EndUser they are delegated to. No one else in the organization can access or manage them - this includes policies, which do not apply to delegated wallets. Only the EndUser can sign transactions for their wallets.

Need per-user wallet isolation? CustomerEmployee users always see all organization wallets. This cannot be restricted with permissions. Two approaches:

Delegated wallets: Use EndUser accounts with delegated wallets. Each user can only access wallets delegated to them. Isolation is enforced at the platform level.
Proxy through your backend: Manage all Dfns wallets via a service account, and handle user-to-wallet mapping in your own backend. Your app controls which wallets each user sees, without registering users in Dfns.

Role assignment

To assign roles to users, you need the Permissions:Assign permission. You can also create policies on Permissions:Assign activity to require approval for role changes.

List of permissions

Agreements

Acceptance:Create: Allows accepting legal agreements on behalf of the organization

API permission: Agreements:Acceptance:Create

Record agreement acceptance ( – doc)

Acceptance:Read: Allows viewing agreement acceptance records

API permission: Agreements:Acceptance:Read

Get latest unaccepted agreement ( – doc)

Allocations

Create: Allows creating allocations

API permission: Allocations:Create

Create allocation ( – doc)

Read: Allows viewing allocations

API permission: Allocations:Read

List allocations ( – doc)
List allocation actions ( – doc)
Get allocation ( – doc)

Update: Allows updating allocations

API permission: Allocations:Update

Create allocation action ( – doc)

Analytics

Read: Allows viewing analytics and usage metrics

Dashboard only — no public API endpoint.

Authentication

Logs:Read: Allows reading authentication and access audit logs

API permission: Auth:Logs:Read

List audit logs ( – doc)
Get audit log ( – doc)

Pats:Create: Allows creating Personal Access Tokens (PATs)

API permission: Auth:Pats:Create

Create personal access token ( – doc)

Recover:Delegated: Allows initiating account recovery via delegated authentication

API permission: Auth:Recover:Delegated

Create delegated recovery challenge ( – doc)

API permission: Auth:Register:Delegated

Create delegated registration challenge ( – doc)

ServiceAccounts:Activate: Allows activating a service account

API permission: Auth:ServiceAccounts:Activate

Activate service account ( – doc)

ServiceAccounts:Create: Allows creating service accounts for programmatic access

API permission: Auth:ServiceAccounts:Create

Create service account ( – doc)

ServiceAccounts:Deactivate: Allows deactivating a service account

API permission: Auth:ServiceAccounts:Deactivate

Deactivate service account ( – doc)

ServiceAccounts:Delete: Allows deleting a service account

API permission: Auth:ServiceAccounts:Delete

Delete service account ( – doc)

ServiceAccounts:Read: Allows viewing service accounts and their configuration

API permission: Auth:ServiceAccounts:Read

List service accounts ( – doc)
Get service account ( – doc)

ServiceAccounts:Update: Allows updating service account details

API permission: Auth:ServiceAccounts:Update

Update service account ( – doc)

Users:Activate: Allows activating a user account

API permission: Auth:Users:Activate

Activate user ( – doc)

Users:Create: Allows creating new user accounts within the organization

API permission: Auth:Users:Create

Create user ( – doc)

Users:Deactivate: Allows deactivating a user account

API permission: Auth:Users:Deactivate

Deactivate user ( – doc)

Users:Delete: Allows permanently deleting a user account

API permission: Auth:Users:Delete

Delete user ( – doc)

Users:Read: Allows viewing user profiles and user-related metadata

Users:Update: Allows updating user information and settings

API permission: Auth:Users:Update

Update user ( – doc)

Billing

Read: Allows viewing billing and usage information

Dashboard only — no public API endpoint.

Write: Allows managing billing configuration

Dashboard only — no public API endpoint.

Events

Read: Allows reading system and product events

Dashboard only — no public API endpoint.

Exchanges

Create: Allows creating exchange integrations

API permission: Exchanges:Create

Create exchange ( – doc)

Delete: Allows removing exchange integrations

API permission: Exchanges:Delete

Delete exchange ( – doc)

Deposits:Create: Allows initiating deposits from exchanges

API permission: Exchanges:Deposits:Create

Create exchange deposit ( – doc)

Read: Allows viewing configured exchanges

API permission: Exchanges:Read

Get exchange ( – doc)
List exchanges ( – doc)
List accounts ( – doc)
List account assets ( – doc)
List asset withdrawal networks ( – doc)

Withdrawals:Create: Allows initiating withdrawals to exchanges

API permission: Exchanges:Withdrawals:Create

Create exchange withdrawal ( – doc)

Fee Sponsors

Create: Allows creating fee sponsor configurations

Delete: Allows deleting fee sponsors

API permission: FeeSponsors:Delete

Delete fee sponsor ( – doc)

Read: Allows viewing fee sponsor configurations

Update: Allows updating fee sponsor settings

Use: Allows using a fee sponsor to pay transaction fees

Key Stores

Read: Allows viewing key store configurations

API permission: KeyStores:Read

List key stores ( – doc)

Keys

ChildKeys:Create: Allows creating child keys

API permission: Keys:ChildKeys:Create

Create key ( – doc) Required if deriveFrom is specified

Create: Allows creating cryptographic keys

API permission: Keys:Create

Create key ( – doc)
Create wallet ( – doc) Required if wallet creation also creates a new Key entity. This is the default behavior

Delegate: Allows delegating key usage

API permission: Keys:Delegate

Create key ( – doc) Required if delegateTo is specified
Delegate key ( – doc)
Create wallet ( – doc) Required if delegateTo is specified

Delete: Allows deleting keys

API permission: Keys:Delete

Delete key ( – doc)

Derive: Allows deriving new keys from a parent key

API permission: Keys:Derive

Derive key ( – doc)

Export: Allows exporting keys (if permitted by policy)

API permission: Keys:Export

Export key ( – doc)

Import: Allows importing externally generated keys

API permission: Keys:Import

Import key ( – doc)
Import wallet ( – doc)

Read: Allows viewing key metadata

API permission: Keys:Read

List keys ( – doc)
Get key ( – doc)

Reuse: Allows reusing existing keys

API permission: Keys:Reuse

Create wallet ( – doc) Required if signingKey.id is specified. Wallet will reuse an existing key instead of creating a new one

Signatures:Create: Allows generating digital signatures

API permission: Keys:Signatures:Create

Generate signature ( – doc)

Signatures:Read: Allows viewing signature requests and results

API permission: Keys:Signatures:Read

List signatures ( – doc)
Get signature ( – doc)

Update: Allows updating key settings

API permission: Keys:Update

Update key ( – doc)

Networks

CantonValidators:Create: Allows creating Canton validator configurations

API permission: Networks:CantonValidators:Create

Create canton validator ( – doc)

CantonValidators:Delete: Allows deleting Canton validators

API permission: Networks:CantonValidators:Delete

Delete canton validator ( – doc)

CantonValidators:Read: Allows viewing Canton validators

API permission: Networks:CantonValidators:Read

Get canton validator ( – doc)
List canton validators ( – doc)

CantonValidators:Update: Allows updating Canton validators

API permission: Networks:CantonValidators:Update

Update canton validator ( – doc)

Organization

Read: Allows viewing organization details

Dashboard only — no public API endpoint.

Settings:Read: Allows viewing organization settings

Dashboard only — no public API endpoint.

Settings:Update: Allows updating organization settings

Dashboard only — no public API endpoint.

Update: Allows updating organization information

Dashboard only — no public API endpoint.

Payouts

Create: Allows creating a payout and payout quotes

API permission: Payouts:Create

Create payout ( – doc)
Request payout quote ( – doc)

Read: Allows viewing the status of payouts

API permission: Payouts:Read

List payouts ( – doc)
Get payout status ( – doc)

Write: Allows performing an action on a payout

API permission: Payouts:Write

Create payout action ( – doc)

Permissions

Archive: Allows archiving permissions or roles

API permission: Permissions:Archive

Archive permission ( – doc)

Assign: Allows assigning permissions to users or service accounts

API permission: Permissions:Assign

Assign permission ( – doc)

Assignments:Read: Allows viewing permission assignments

API permission: Permissions:Assignments:Read

List permission assignments ( – doc)

Create: Allows creating new permissions or roles

API permission: Permissions:Create

Create permission ( – doc)

Read: Allows viewing permissions and roles

API permission: Permissions:Read

List permissions ( – doc)
Get permission ( – doc)

Revoke: Allows revoking assigned permissions

API permission: Permissions:Revoke

Revoke permission ( – doc)

Update: Allows updating permissions or roles

API permission: Permissions:Update

Update permission ( – doc)

Policies

Approvals:Approve: Allows approving or rejecting policies

API permission: Policies:Approvals:Approve

Create approval decision ( – doc)

Approvals:Read: Allows viewing pending and historical policy approvals

API permission: Policies:Approvals:Read

Get approval ( – doc)
List approvals ( – doc)

Archive: Allows archiving policies

API permission: Policies:Archive

Delete policy ( – doc)

Create: Allows creating policies

API permission: Policies:Create

Create policy ( – doc)

Read: Allows viewing policies

API permission: Policies:Read

Get policy ( – doc)
List policies ( – doc)

Update: Allows updating policies

API permission: Policies:Update

Update policy ( – doc)

Registry

Addresses:Create: Allows creating new addresses in the address registry

Dashboard only — no public API endpoint.

Addresses:Delete: Allows removing addresses from the registry

Dashboard only — no public API endpoint.

Addresses:Read: Allows viewing registered addresses and their metadata

Dashboard only — no public API endpoint.

Addresses:Update: Allows updating metadata or aliases for registered addresses

Dashboard only — no public API endpoint.

ContractSchemas:Create: Allows registering new smart contract schemas (ABIs)

Dashboard only — no public API endpoint.

ContractSchemas:Delete: Allows removing contract schemas from the registry

Dashboard only — no public API endpoint.

ContractSchemas:Read: Allows viewing registered contract schemas

Dashboard only — no public API endpoint.

Signers

ListSigners: Allows listing available signing entities

API permission: Signers:ListSigners

List signers ( – doc)

Staking

Create: Allows creating staking operations

API permission: Stakes:Create

Create stake ( – doc)

Read: Allows viewing staking positions

API permission: Stakes:Read

List stakes ( – doc)
List stake actions ( – doc)
Get stakes ( – doc)
Get stake rewards ( – doc)

Update: Allows updating staking configurations

API permission: Stakes:Update

Create stake action ( – doc)

Swaps

Create: Allows creating asset swap operations

API permission: Swaps:Create

Create swap ( – doc)

Read: Allows viewing swap history and details

API permission: Swaps:Read

List swaps ( – doc)
Get swap ( – doc)

Wallets

Create: Allows creating wallets

API permission: Wallets:Create

Activate wallet ( – doc)
Create wallet ( – doc)
Import wallet ( – doc)

Offers:Read: Allows viewing settlement offers

API permission: Wallets:Offers:Read

Get offer ( – doc)
List offers ( – doc)

Offers:Settle: Allows settling offers

API permission: Wallets:Offers:Settle

Accept offer ( – doc)
Reject offer ( – doc)

Read: Allows viewing wallet details

API permission: Wallets:Read

List wallets ( – doc)
Get wallet ( – doc)
Get wallet assets ( – doc)
Get wallet history ( – doc)
Get wallet nfts ( – doc)
List org wallet history ( – doc)

Tags:Add: Allows adding tags to wallets

API permission: Wallets:Tags:Add

Create wallet ( – doc) Required if tags are specified
Tag wallet ( – doc)

Tags:Delete: Allows removing wallet tags

API permission: Wallets:Tags:Delete

Untag wallet ( – doc)

Transactions:Abort

API permission: Wallets:Transactions:Abort

Abort transaction ( – doc)

Transactions:Create: Allows creating transactions

API permission: Wallets:Transactions:Create

Sign and broadcast transaction ( – doc)
Cancel transaction ( – doc)
Cancel transfer ( – doc)
Speed up transaction ( – doc)
Speed up transfer ( – doc)

Transactions:Read: Allows viewing wallet transactions

API permission: Wallets:Transactions:Read

List transactions ( – doc)
Cancel transaction ( – doc)
Speed up transaction ( – doc)
Get transaction ( – doc)

Transfers:Abort

API permission: Wallets:Transfers:Abort

Abort transfer ( – doc)

Transfers:Create: Allows creating wallet transfers

API permission: Wallets:Transfers:Create

Create exchange deposit ( – doc)
Transfer asset ( – doc)

Transfers:Read: Allows viewing wallet transfers

API permission: Wallets:Transfers:Read

Cancel transfer ( – doc)
Speed up transfer ( – doc)
Get transfer ( – doc)
List transfers ( – doc)

Update: Allows updating wallet configuration

API permission: Wallets:Update

Update wallet ( – doc)

Webhooks

Create: Allows creating webhooks

API permission: Webhooks:Create

Create webhook ( – doc)

Delete: Allows deleting webhooks

API permission: Webhooks:Delete

Delete webhook ( – doc)

Events:Read: Allows viewing webhook event history

API permission: Webhooks:Events:Read

Get webhook event ( – doc)
List webhook events ( – doc)

Ping: Allows testing webhook endpoints

API permission: Webhooks:Ping

Ping webhook ( – doc)

Read: Allows viewing webhooks

API permission: Webhooks:Read

List webhooks ( – doc)
Get webhook ( – doc)

Update: Allows updating webhook configuration

API permission: Webhooks:Update

Update webhook ( – doc)

Introduction

Core Concepts

Platform Features

Networks

Solutions

Guides

Advanced

Terminology

Dfns-managed roles

`ManagedFullAdminAccess`

`ManagedDefaultEndUserAccess`

User types

Comparison matrix

Wallet visibility

Role assignment

List of permissions

Agreements

Allocations

Analytics

Authentication

Billing

Events

Exchanges

Fee Sponsors

Key Stores

Keys

Networks

Organization

Payouts

Permissions

Policies

Registry

Signers

Staking

Swaps

Wallets

Webhooks

Introduction

Core Concepts

Platform Features

Networks

Solutions

Guides

Advanced

Documentation Index

​Terminology

​Dfns-managed roles

​ManagedFullAdminAccess

​ManagedDefaultEndUserAccess

​User types

​Comparison matrix

​Wallet visibility

​Role assignment

​List of permissions

​Agreements

​Allocations

​Analytics

​Authentication

​Billing

​Events

​Exchanges

​Fee Sponsors

​Key Stores

​Keys

​Networks

​Organization

​Payouts

​Permissions

​Policies

​Registry

​Signers

​Staking

​Swaps

​Wallets

​Webhooks

Terminology

Dfns-managed roles

`ManagedFullAdminAccess`

`ManagedDefaultEndUserAccess`

User types

Comparison matrix

Wallet visibility

Role assignment

List of permissions

Agreements

Allocations

Analytics

Authentication

Billing

Events

Exchanges

Fee Sponsors

Key Stores

Keys

Networks

Organization

Payouts

Permissions

Policies

Registry

Signers

Staking

Swaps

Wallets

Webhooks