# Permission-Based Access Control In this tutorial you will learn how to create permissions, how to invite users and finally how to assign permissions to users. ## From the Dashboard {% embed url="" %} ## With APIs {% stepper %} {% step %} ### Create a new Permission A [permission](/d/api-docs/permissions.md) is a whitelist of all operations a user is allowed to take. Permissions are designed to be assigned to users to help secure your organization by enforcing the principle of least privilege. {% hint style="info" %} As any other modification you make on your organization, this action needs to be signed as described in [User Action Signing](/d/api-docs/authentication/user-action-signing.md). That's what we will point your to bellow. {% endhint %} 1. Select a name for your Permission, and the operations to whitelist. Here, only allowing assigned users read-only access to the wallets: ```sh userActionPayload = { "name": "Wallet_Read_User", "operations": ["Wallets:Read"] } userActionHttpMethod = "POST" userActionHttpPath = "/permissions" ``` 2. Follow the process [here](/d/api-docs/authentication/user-action-signing.md) to authorize the action request a get a `userAction` token that you can include in your request as the `X-DFNS-USERACTION` header. 3. Call the permission creation endpoint: `POST /permissions` ```javascript fetch(`${baseURL}${userActionHttpPath}`, { method: userActionHttpMethod, headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}`, "X-DFNS-USERACTION": userAction, }, body: JSON.stringify(userActionHttpMethod), }) ``` {% hint style="info" %} In the response, keep a note of the permission `id`, you will need it to assign it to the user in the last step of this tutorial. {% endhint %} {% hint style="success" %} That's it! You have created a new permission! Now, let's get it assigned to a new user. {% endhint %} {% endstep %} {% step %} ### Invite a New User We will invite a new [User](/d/api-docs/authentication/user-management.md) 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](/d/api-docs/authentication/delegated-auth/delegatedregistration.md). {% hint style="info" %} As any other modification you make on your organization, this action needs to be signed as described in [User Action Signing](/d/api-docs/authentication/user-action-signing.md). That's what we will point your to bellow. {% endhint %} 1. When you invite a user, he will receive a registration email with a code allowing him to register to your organization. That user will be created without any permission. Just input his email: ``` userActionPayload = { "email": "jdoe@example.co", "kind": "CustomerEmployee" } userActionHttpMethod = "POST" userActionHttpPath = "/auth/users" ``` 2. Follow the process [here](/d/api-docs/authentication/user-action-signing.md) to authorize the action request a get a `userAction` token that you can include in your request as the `X-DFNS-USERACTION` header. 3. Call the user creation endpoint: `POST /auth/users` to initiate the registration process. ```javascript fetch(`${baseURL}${userActionHttpPath}`, { method: userActionHttpMethod, headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}`, "X-DFNS-USERACTION": userAction, }, body: JSON.stringify(userActionHttpMethod), }) ``` {% hint style="info" %} In the response, keep a note of the `userId`, you will need it to assign his permission in the next step. {% endhint %} {% hint style="success" %} The new user has been created and has received instructions to create his own credentials. We don't need to wait for him to complete his registration, let's go ahead and assign him our permission! {% endhint %} {% endstep %} {% step %} ### Assign Permissions Final step! Let's give our user the rights he deserves! We will the [assign permission](/d/api-docs/permissions/permissions/createassignment.md) endpoint to link it to the user we just created {% hint style="info" %} As any other modification you make on your organization, this action needs to be signed as described in [User Action Signing](/d/api-docs/authentication/user-action-signing.md). That's what we will point your to bellow. {% endhint %} 1. Not much choice here, just input the ids gathers above: ``` userActionPayload = { "identityId": "{userId}" } userActionHttpMethod = "POST" userActionHttpPath = "/permissions/{permission id}/assignments" ``` 2. Follow the process [here](/d/api-docs/authentication/user-action-signing.md) to authorize the action request a get a `userAction` token that you can include in your request as the `X-DFNS-USERACTION` header. 3. Call the permission assignment endpoint: `POST /permissions/{permission id}/assignments` to grant the permission: ```javascript fetch(`${baseURL}${userActionHttpPath}`, { method: userActionHttpMethod, headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}`, "X-DFNS-USERACTION": userAction, }, body: JSON.stringify(userActionHttpMethod), }) ``` {% hint style="success" %} Contrats! You have built the base of a taylored identity management policy, you can now keep refining and assign to your complete user base. {% endhint %} {% endstep %} {% endstepper %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs-legacy.dfns.co/d/guides/permission-based-access-control.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.