Permission-based Access Control

Using APIs

Create a New Role

A role is a whitelist of permissions a user can access. Roles enforce the principle of least privilege by restricting users to only the actions they require.

Note: As with any modification to your organization, this action must be signed. For more information, see User Action Signing

1. Select a name for your role and the permissions to whitelist, for example, read-only wallet access.

   
   userActionPayload = {
     "name": "Wallet_Read_User",
     "operations": ["Wallets:Read"]
   }
   
   userActionHttpMethod = "POST"
   userActionHttpPath = "/permissions"
    

2. Follow the signing process to obtain a userAction token. Include it in your request as the X-DFNS-USERACTION header.
3. 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),
   })

   Record the role id. You will need it to assign the user .

You have created a new role. Next, invite a user.

Invite a New User

Invite a new user as an employee. Employees can access both the dashboard and APIs. For inviting end users, see Delegated Registration. This action must also be signed.

1. Provide the user’s email. They will receive a registration email with a code. The user is created without a role.

   userActionPayload = {
     "email": "jdoe@example.co",
     "kind": "CustomerEmployee"
   }
   
   userActionHttpMethod = "POST"
   userActionHttpPath = "/auth/users"

2. Follow the signing process to obtain a userAction token.
3. Call the user creation endpoint: POST /auth/users.

   fetch(`${baseURL}${userActionHttpPath}`, {
     method: userActionHttpMethod,
     headers: {
       "Content-Type": "application/json",
       Authorization: `Bearer ${token}`,
       "X-DFNS-USERACTION": userAction,
     },
     body: JSON.stringify(userActionHttpMethod),
   })

   Record the role id. You will need it to assign the user .

The new user has been created and received instructions to register. You can assign their role immediately.

Assign the Role

Use the assign permission endpoint to link the role to the user. This action must also be signed.

1. Provide the IDs gathered above:

   userActionPayload = {
     "identityId": "{userId}"
   }
   userActionHttpMethod = "POST"
   userActionHttpPath = "/permissions/{permission id}/assignments"

2. Follow the signing process to obtain a userAction token.
3. Call the permission assignment endpoint: POST /permissions/{permission id}/assignments.

   fetch(`${baseURL}${userActionHttpPath}`, {
     method: userActionHttpMethod,
     headers: {
       "Content-Type": "application/json",
       Authorization: `Bearer ${token}`,
       "X-DFNS-USERACTION": userAction,
     },
     body: JSON.stringify(userActionHttpMethod),
   })

Note: This endpoint is not idempotent. Assigning a role already assigned to a user returns a 409 Conflict error.

You have now established a tailored identity management setup. Continue refining this setup by assigning roles across your user base.