Roles and permissions - Dfns documentation

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`

Record agreement acceptance ( – doc)

`Agreements:Acceptance:Read`

Get latest unaccepted agreement ( – doc)

`Allocations:Create`

Create allocation ( – doc)

`Allocations:Read`

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

`Allocations:Update`

Create allocation action ( – doc)

`Auth:Login:Delegated`

Delegated login ( – doc)

`Auth:Logs:Read`

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

`Auth:Pats:Create`

Create personal access token ( – doc)

`Auth:Recover:Delegated`

Create delegated recovery challenge ( – doc)

`Auth:Register:Delegated`

Create delegated registration challenge ( – doc)

`Auth:ServiceAccounts:Activate`

Activate service account ( – doc)

`Auth:ServiceAccounts:Create`

Create service account ( – doc)

`Auth:ServiceAccounts:Deactivate`

Deactivate service account ( – doc)

`Auth:ServiceAccounts:Delete`

Delete service account ( – doc)

`Auth:ServiceAccounts:Read`

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

`Auth:ServiceAccounts:Update`

Update service account ( – doc)

`Auth:Users:Activate`

Activate user ( – doc)

`Auth:Users:Create`

Create user ( – doc)

`Auth:Users:Deactivate`

Deactivate user ( – doc)

`Auth:Users:Delete`

Delete user ( – doc)

`Auth:Users:Read`

Get user ( – doc)
List users ( – doc)

`Auth:Users:Update`

Update user ( – doc)

`Exchanges:Create`

Create exchange ( – doc)

`Exchanges:Delete`

Delete exchange ( – doc)

`Exchanges:Deposits:Create`

Create exchange deposit ( – doc)

`Exchanges:Read`

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

`Exchanges:Withdrawals:Create`

Create exchange withdrawal ( – doc)

`FeeSponsors:Create`

Create fee sponsor ( – doc)

`FeeSponsors:Delete`

Delete fee sponsor ( – doc)

`FeeSponsors:Read`

List fee sponsors ( – doc)
Get fee sponsor ( – doc)
List sponsored fees ( – doc)

`FeeSponsors:Update`

Deactivate fee sponsor ( – doc)
Activate fee sponsor ( – doc)

`FeeSponsors:Use`

Sign and broadcast transaction ( – doc) Required if feeSponsorId is specified
Transfer asset ( – doc) Required if feeSponsorId is specified

`KeyStores:Read`

List key stores ( – doc)

`Keys:ChildKeys:Create`

Create key ( – doc) Required if deriveFrom is specified

`Keys:Create`

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

`Keys:Delegate`

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

`Keys:Delete`

Delete key ( – doc)

`Keys:Derive`

Derive key ( – doc)

`Keys:Export`

Export key ( – doc)

`Keys:Import`

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

`Keys:Read`

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

`Keys:Reuse`

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

`Keys:Signatures:Create`

Generate signature ( – doc)

`Keys:Signatures:Read`

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

`Keys:Update`

Update key ( – doc)

`Networks:CantonValidators:Create`

Create canton validator ( – doc)

`Networks:CantonValidators:Delete`

Delete canton validator ( – doc)

`Networks:CantonValidators:Read`

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

`Networks:CantonValidators:Update`

Update canton validator ( – doc)

`Payouts:Create`

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

`Payouts:Read`

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

`Payouts:Write`

Create payout action ( – doc)

`Permissions:Archive`

Archive permission ( – doc)

`Permissions:Assign`

Assign permission ( – doc)

`Permissions:Assignments:Read`

List permission assignments ( – doc)

`Permissions:Create`

Create permission ( – doc)

`Permissions:Read`

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

`Permissions:Revoke`

Revoke permission ( – doc)

`Permissions:Update`

Update permission ( – doc)

`Policies:Approvals:Approve`

Create approval decision ( – doc)

`Policies:Approvals:Read`

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

`Policies:Archive`

Delete policy ( – doc)

`Policies:Create`

Create policy ( – doc)

`Policies:Read`

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

`Policies:Update`

Update policy ( – doc)

`Signers:ListSigners`

List signers ( – doc)

`Stakes:Create`

Create stake ( – doc)

`Stakes:Read`

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

`Stakes:Update`

Create stake action ( – doc)

`Swaps:Create`

Create swap ( – doc)

`Swaps:Read`

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

`Wallets:Create`

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

`Wallets:Offers:Read`

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

`Wallets:Offers:Settle`

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

`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)

`Wallets:Tags:Add`

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

`Wallets:Tags:Delete`

Untag wallet ( – doc)

`Wallets:Transactions:Abort`

Abort transaction ( – doc)

`Wallets:Transactions:Create`

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

`Wallets:Transactions:Read`

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

`Wallets:Transfers:Abort`

Abort transfer ( – doc)

`Wallets:Transfers:Create`

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

`Wallets:Transfers:Read`

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

`Wallets:Update`

Update wallet ( – doc)

`Webhooks:Create`

Create webhook ( – doc)

`Webhooks:Delete`

Delete webhook ( – doc)

`Webhooks:Events:Read`

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

`Webhooks:Ping`

Ping webhook ( – doc)

`Webhooks:Read`

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

`Webhooks:Update`

Update webhook ( – doc)

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:Acceptance:Create

​Agreements:Acceptance:Read

​Allocations:Create

​Allocations:Read

​Allocations:Update

​Auth:Login:Delegated

​Auth:Logs:Read

​Auth:Pats:Create

​Auth:Recover:Delegated

​Auth:Register:Delegated

​Auth:ServiceAccounts:Activate

​Auth:ServiceAccounts:Create

​Auth:ServiceAccounts:Deactivate

​Auth:ServiceAccounts:Delete

​Auth:ServiceAccounts:Read

​Auth:ServiceAccounts:Update

​Auth:Users:Activate

​Auth:Users:Create

​Auth:Users:Deactivate

​Auth:Users:Delete

​Auth:Users:Read

​Auth:Users:Update

​Exchanges:Create

​Exchanges:Delete

​Exchanges:Deposits:Create

​Exchanges:Read

​Exchanges:Withdrawals:Create

​FeeSponsors:Create

​FeeSponsors:Delete

​FeeSponsors:Read

​FeeSponsors:Update

​FeeSponsors:Use

​KeyStores:Read

​Keys:ChildKeys:Create

​Keys:Create

​Keys:Delegate

​Keys:Delete

​Keys:Derive

​Keys:Export

​Keys:Import

​Keys:Read

​Keys:Reuse

​Keys:Signatures:Create

​Keys:Signatures:Read

​Keys:Update

​Networks:CantonValidators:Create

​Networks:CantonValidators:Delete

​Networks:CantonValidators:Read

​Networks:CantonValidators:Update

​Payouts:Create

​Payouts:Read

​Payouts:Write

​Permissions:Archive

​Permissions:Assign

​Permissions:Assignments:Read

​Permissions:Create

​Permissions:Read

​Permissions:Revoke

​Permissions:Update

​Policies:Approvals:Approve

​Policies:Approvals:Read

​Policies:Archive

​Policies:Create

Terminology

Dfns-managed roles

`ManagedFullAdminAccess`

`ManagedDefaultEndUserAccess`

User types

Comparison matrix

Wallet visibility

Role assignment

List of permissions

`Agreements:Acceptance:Create`

`Agreements:Acceptance:Read`

`Allocations:Create`

`Allocations:Read`

`Allocations:Update`

`Auth:Login:Delegated`

`Auth:Logs:Read`

`Auth:Pats:Create`

`Auth:Recover:Delegated`

`Auth:Register:Delegated`

`Auth:ServiceAccounts:Activate`

`Auth:ServiceAccounts:Create`

`Auth:ServiceAccounts:Deactivate`

`Auth:ServiceAccounts:Delete`

`Auth:ServiceAccounts:Read`

`Auth:ServiceAccounts:Update`

`Auth:Users:Activate`

`Auth:Users:Create`

`Auth:Users:Deactivate`

`Auth:Users:Delete`

`Auth:Users:Read`

`Auth:Users:Update`

`Exchanges:Create`

`Exchanges:Delete`

`Exchanges:Deposits:Create`

`Exchanges:Read`

`Exchanges:Withdrawals:Create`

`FeeSponsors:Create`

`FeeSponsors:Delete`

`FeeSponsors:Read`

`FeeSponsors:Update`

`FeeSponsors:Use`

`KeyStores:Read`

`Keys:ChildKeys:Create`

`Keys:Create`

`Keys:Delegate`

`Keys:Delete`

`Keys:Derive`

`Keys:Export`

`Keys:Import`

`Keys:Read`

`Keys:Reuse`

`Keys:Signatures:Create`

`Keys:Signatures:Read`

`Keys:Update`

`Networks:CantonValidators:Create`

`Networks:CantonValidators:Delete`

`Networks:CantonValidators:Read`

`Networks:CantonValidators:Update`

`Payouts:Create`

`Payouts:Read`

`Payouts:Write`

`Permissions:Archive`

`Permissions:Assign`

`Permissions:Assignments:Read`

`Permissions:Create`

`Permissions:Read`

`Permissions:Revoke`

`Permissions:Update`

`Policies:Approvals:Approve`

`Policies:Approvals:Read`

`Policies:Archive`

`Policies:Create`

`Policies:Read`

`Policies:Update`

`Signers:ListSigners`

`Stakes:Create`

`Stakes:Read`

`Stakes:Update`

`Swaps:Create`

`Swaps:Read`