Skip to main content

Permit.io Best Practices

Plan your Permit.io rollout and fit it into your software development lifecycle (SDLC). This page is for engineering leads and architects who own the authorization rollout. None of these practices is required, and each one saves rework later.

Define the project scope​

  • Before you integrate anything, write down your use case and user stories. For example: "a support agent can read a customer's tickets, but only in the customer's tenant". The stories show the priorities, scale, and data volume your authorization layer needs to handle.
  • Decide which policy authoring interface each stakeholder needs. Developers can use the API, SDKs, or policy as code. Product managers and security teams can use the Policy Editor. End users can use Permit Elements.

Model your policies​

After you know what your authorization layer needs to do and who operates it, model the policies:

Map your authorization layer

Follow the step-by-step guide to planning an RBAC implementation to map roles, resources, and actions before you build.

Start with a small proof of concept​

  • After you pick a model, apply Permit to one part of your application first, such as a single service. That part gets fine-grained enforcement while the rest of your setup stays the same.
  • If you already have an in-house authorization system, run Permit alongside it. For example, call permit.check() next to your existing check, log both decisions, and compare them before you switch enforcement to Permit.
  • Run the first proof of concept in a development or staging environment before you deploy to a larger part of your application.

Map deployments to projects, environments, and tenants​

Projects and environments​

Use projects and environments to keep deployments separate. Each environment has its own policy, data, and API key.

Example mapping

Create one Permit project for each application or major service. Inside the project, create one environment for each deployment stage: development, staging, user acceptance testing (UAT), and production.

Tenants​

Use tenants to isolate users and resources that belong together. Role assignments are scoped to a tenant, so a role in one tenant grants nothing in another tenant.

Tenants for B2B accounts

In a B2B application, create one tenant for each customer account.

Policy decision points (PDPs)​

  • Policy decision points (PDPs) answer permission checks. Teams usually start by running PDPs as sidecars, or as load-balanced containers on services such as AWS Fargate, Google Cloud Run, or Kubernetes (for example Amazon EKS). See Deploy Permit to production.
  • Start each PDP with the API key of the environment it serves. A PDP started with the staging API key answers checks with the staging policy, even when production traffic reaches it.

Manage policy changes in your SDLC and CI/CD​

Control who changes policy at each stage​

Use project and environment member roles to control who can change policy at each deployment stage. For example, a product manager can edit policy in the staging environment, while only a developer or DevOps engineer can edit the production environment.

Automate environments in CI/CD​

  • Call the create environment API from your CI/CD pipeline to create a preview environment for each pull request. Limit access to the preview environment during review, for example to the developer who opened the pull request.
  • Call the copy environment API to promote changes from one environment to another, so environments stay consistent. See Copy and merge environments.
  • Use the Permit Terraform provider to manage environment baselines and policy changes as code.
  • Use GitOps to review, merge, and roll out policy changes the same way you manage code.

Give each stakeholder the right interface​

  • Grant Policy Editor access to stakeholders based on their role, so non-technical staff can make the policy changes they own without a code release.
  • Give the broader developer team access to the Permit API and the Terraform provider for day-to-day operations.
  • Limit GitOps and direct policy-as-code access to the developers who own the policy code.
  • Use Permit Elements, embeddable UI components, to let your end users manage users and approve access requests in their own tenant.

Get help​

Contents

Edit this page

Need help?