> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dfns.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up permission-based access

> Invite new users to your Dfns organization and configure roles, permissions, and assignments for fine-grained access management at scale.

export const Youtube = props => {
  return <iframe className="w-full aspect-video rounded-xl" src={`https://www.youtube.com/embed/${props.videoId}`} title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen>
      </iframe>;
};

Create roles, invite users, and assign roles to those users.

## From the Dashboard

<Youtube videoId="M1Y-6FlD4pQ" />

## With APIs

<Tip>
  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".
</Tip>

<Steps>
  <Step title="Create a new role">
    A [role](/core-concepts/roles-and-permissions) 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.

    <Info>
      As any other modification you make on your organization, this action needs to be signed as described in [User Action Signing](/api-reference/auth/signing-flows). That's what we will point you to below.
    </Info>

    1. Select a name for your role, and the permissions to whitelist. Here, only allowing assigned users read-only access to the wallets:

    ```sh theme={null}
    userActionPayload = {
      "name": "Wallet_Read_User",
      "operations": ["Wallets:Read"]
    }

    userActionHttpMethod = "POST"
    userActionHttpPath = "/permissions"
    ```

    2. Follow the process [here](/api-reference/auth/signing-flows) 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 theme={null}
    fetch(`${baseURL}${userActionHttpPath}`, {
      method: userActionHttpMethod,
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${token}`,
        "X-DFNS-USERACTION": userAction,
      },
      body: JSON.stringify(userActionHttpMethod),
    })
    ```

    <Info>
      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.
    </Info>

    <Check>
      That's it! You have created a new role! Now, let's get it assigned to a new user.
    </Check>
  </Step>

  <Step title="Invite a New User">
    We will invite a new [User](/api-reference/auth/users) 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](/api-reference/auth/registration-flows#delegated-users-registration-flow).

    <Info>
      As any other modification you make on your organization, this action needs to be signed as described in [User Action Signing](/api-reference/auth/signing-flows). That's what we will point you to below.
    </Info>

    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:

    ```js theme={null}
    userActionPayload = {
      "email": "jdoe@example.co",
      "kind": "CustomerEmployee"
    }

    userActionHttpMethod = "POST"
    userActionHttpPath = "/auth/users"
    ```

    2. Follow the process [here](/api-reference/auth/signing-flows) 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 theme={null}
    fetch(`${baseURL}${userActionHttpPath}`, {
      method: userActionHttpMethod,
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${token}`,
        "X-DFNS-USERACTION": userAction,
      },
      body: JSON.stringify(userActionHttpMethod),
    })
    ```

    <Info>
      In the response, keep a note of the `userId`, you will need it to assign the role in the next step.
    </Info>

    <Check>
      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!
    </Check>
  </Step>

  <Step title="Assign the role">
    Final step! Let's give our user the rights they deserve! We will use the [assign permission](/api-reference/permissions/assign-permission) endpoint to link the role to the user we just created

    <Info>
      As any other modification you make on your organization, this action needs to be signed as described in [User Action Signing](/api-reference/auth/signing-flows). That's what we will point you to below.
    </Info>

    1. Not much choice here, just input the ids gathers above:

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

    2. Follow the process [here](/api-reference/auth/signing-flows) 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 assign the role:

    ```javascript theme={null}
    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 that is already assigned to the user returns a `409 Conflict` error.
    </Note>

    <Check>
      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.
    </Check>
  </Step>
</Steps>