Skip to main content
In this tutorial you will learn how to create roles, how to invite users and finally how to assign roles to users.

​
From the Dashboard

​
With APIs

In the API, a role is called a permission, and the action of assigning a role to a user is called “assigning a permission”. So, when you see “permission” in the API reference, just think “role”.
1

Create a new role

A role is a whitelist of all permissions a user is allowed to use. Roles are designed to be assigned to users to help secure your organization by enforcing the principle of least privilege.
As any other modification you make on your organization, this action needs to be signed as described in User Action Signing. That’s what we will point your to bellow.
  1. Select a name for your role, and the permissions to whitelist. Here, only allowing assigned users read-only access to the wallets:
userActionPayload = {
  "name": "Wallet_Read_User",
  "operations": ["Wallets:Read"]
}

userActionHttpMethod = "POST"
userActionHttpPath = "/permissions"
  1. Follow the process here to authorize the action request a get a userAction token that you can include in your request as the X-DFNS-USERACTION header.
  2. Call the permission creation endpoint: POST /permissions
fetch(`${baseURL}${userActionHttpPath}`, {
  method: userActionHttpMethod,
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${token}`,
    "X-DFNS-USERACTION": userAction,
  },
  body: JSON.stringify(userActionHttpMethod),
})
In the response, keep a note of the role id, you will need it to assign it to the user in the last step of this tutorial.
That’s it! You have created a new role! Now, let’s get it assigned to a new user.
2

Invite a New User

We will invite a new User as an employee from your company. Employees can also access the dashboard and use the APIs. If you want to invite your End users then look at Delegated Registration.
As any other modification you make on your organization, this action needs to be signed as described in User Action Signing. That’s what we will point your to bellow.
  1. When you invite a user, they will receive a registration email with a code allowing them to register to your organization. That user will be created without any role. Just input their email:
userActionPayload = {
  "email": "jdoe@example.co",
  "kind": "CustomerEmployee"
}

userActionHttpMethod = "POST"
userActionHttpPath = "/auth/users"
  1. Follow the process here to authorize the action request a get a userAction token that you can include in your request as the X-DFNS-USERACTION header.
  2. Call the user creation endpoint: POST /auth/users to initiate the registration process.
fetch(`${baseURL}${userActionHttpPath}`, {
  method: userActionHttpMethod,
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${token}`,
    "X-DFNS-USERACTION": userAction,
  },
  body: JSON.stringify(userActionHttpMethod),
})
In the response, keep a note of the userId, you will need it to assign the role in the next step.
The new user has been created and has received instructions to create their own credentials. We don’t need to wait for them to complete their registration, let’s go ahead and assign them our role!
3

Assign the role

Final step! Let’s give our user the rights they deserve! We will use the assign permission endpoint to link the role to the user we just created
As any other modification you make on your organization, this action needs to be signed as described in User Action Signing. That’s what we will point your to bellow.
  1. Not much choice here, just input the ids gathers above:
userActionPayload = {
  "identityId": "{userId}"
}
userActionHttpMethod = "POST"
userActionHttpPath = "/permissions/{permission id}/assignments"
  1. Follow the process here to authorize the action request a get a userAction token that you can include in your request as the X-DFNS-USERACTION header.
  2. Call the permission assignment endpoint: POST /permissions/{permission id}/assignments to assign the role:
fetch(`${baseURL}${userActionHttpPath}`, {
  method: userActionHttpMethod,
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${token}`,
    "X-DFNS-USERACTION": userAction,
  },
  body: JSON.stringify(userActionHttpMethod),
})
This endpoint is not idempotent. Assigning a role that is already assigned to the user returns a 409 Conflict error.
Congrats! You have built the base of a tailored identity management setup, you can now keep refining and assign roles to your complete user base.
Last modified on March 2, 2026