Configuring Orgs, Roles, and Permissions

We now have our frontend and backend setup, including an authenticated request between our frontend and backend. In this guide, we'll setup our hierarchy of orgs, roles, and permissions, as well as set up a route in our backend that only users with a specific permission can access.

Configuring Organizations

Organizations are groups of your users that will use your product together. These are also referred to as companies, tenants, teams, workspaces, or shared accounts.

Let's start configuring your organization settings by navigating to the Organization Settings page in your PropelAuth dashboard. Here, we can enable orgs, allow users to create their own, require that users belong to at least one org, and more.

Creating an org

Let's create an org that our users can join. There are multiple ways to do this - the easiest being our users creating them themselves! Another option is to create orgs programmatically using the Create Org backend API request.

Navigate to the Organizations page in PropelAuth and click on the + Create Organization button.

Add an org name as well as the domain of the org. We can then allow any users with that domain to join. For now, let's create a new user, add them to the org, and set them as the org Owner.

Configuring Roles and Permissions

Let's move onto configuring the roles and permissions our users will have within their organizations.

• Roles: Define what users within an organization can do, like "Admin" or "Member". These are the labels users see.
• Permissions (Behind the scenes): Control what actions users with a specific role can take, like "view billing information." Users won't see these directly.

PropelAuth's default role structure includes Owner, Admin, and Member. However, you can add, delete, and rename any role as you'd like.

Let's start by navigating to the Roles and Permissions page within your PropelAuth dashboard. Next, we can create a custom permission called "can_view_billing". Click on Configure Permissions followed by + Add Permission. We can then add that permission to the Owner and Admin roles. Since the user we created earlier was an Owner, this user will now have the "can_view_billing" permission.

Making an Authorized Request

Let's now protect a route by requiring that the user has the "can_view_billing" permission that we created earlier. We can make a request to an exposed endpoint in our backend with an access token, generated by our frontend, set as an authorization header.

With FastAPI, we can use the require_org_member_with_permission() function to validate that the user belongs to the org we passed in the URL, as well as having the required permission.

auth = init_auth("auth_url", "auth_api_key")

@app.get("/api/org/{org_id}/billing")
async def billing(org_id: str, current_user: User = Depends(auth.require_user)):
  org = auth.require_org_member_with_permission(current_user, org_id, "can_view_billing")
  pass