Organization template
The organization template in Logto defines a consistent set of roles and permissions available to every organization (tenant) in your SaaS product. By centralizing these definitions, you can enforce security, enable scalable onboarding, and ensure an excellent user experience across all organizations.
If you are not building a multi-tenant application or do not need organization-specific roles/permissions, you can skip this section. Logto's global roles and permissions are sufficient for single-tenant or non-organization-based applications.
What is the organization template?
An organization template is a blueprint that specifies which roles and permissions are available in each organization. Every organization created in your Logto tenant automatically inherits the template, guaranteeing a consistent authorization model across all tenants.
- Why use a template?
- Enforces uniform access control policies for every organization.
- Simplifies onboarding for new tenants and team members.
- Makes role-based access control (RBAC) updates and audits easier as your product grows.
Core concepts
- Organization roles: Collections of permissions granted to users or M2M (machine-to-machine) clients within an organization. Roles define “who can do what” inside each organization.
- Organization permissions: Fine-grained non-API actions (e.g., UI features, business logic) that can be assigned to roles.
- API resources: API endpoints/services protected by permissions. Organization roles can be linked to API resources for organization-scoped API access.
- Role-permission mapping: Each organization role in the template can be mapped to one or more permissions.
- Template propagation: Changes to the template update the roles and permissions available to all organizations.
Organization roles and permissions (including API resource permissions) are distinct from global roles and their permissions. However, API resources and their permissions are centrally defined and can be referenced in both global and organization contexts.
Comparison with global roles and permissions
Role type comparison
| Role type | Can have API resource permissions? | Can have organization (non-API) permissions? |
|---|---|---|
| Global | Yes | No |
| Organization | Yes | Yes |
Permissions type comparison
| Permission type | Defined in | Assignable to global roles? | Assignable to organization roles? |
|---|---|---|---|
| API resource | API resource entity | Yes | Yes |
| Organization | Organization template | No | Yes |
Anatomy of an organization template
An organization template is made up of:
- Roles: E.g.,
Admin,Member,Viewer,Billing - Organization permissions: E.g.,
invite:member,manage:billing,view:analytics - Role-permission matrix: A mapping of which permissions (including organization permissions and API resource permissions) are granted by each role.
Visual overview
This diagram illustrates how organization roles, permissions, and API resources connect in a Logto organization template.
Each organization created in Logto will have this same set of roles and permissions, and users/clients can be assigned roles per organization as needed.
Use organization template in your product
Logto's organization template is designed for modern, multi-tenant SaaS applications where:
- Each organization should have the same role and permission options for onboarding, collaboration, and management.
- You want to avoid manually defining roles/permissions for each new organization.
- Consistent RBAC is critical for compliance, security, and customer trust.
- You need to evolve access control as your product changes, without breaking existing organizations.
Example use cases
- SaaS products offering workspaces, teams, or companies (each a tenant).
- Platforms with granular admin/member/viewer roles per organization.
- Products with both API and non-API permissions.
Best practices & versioning
- Keep roles and permissions business-driven: Use clear names that map to real actions (not just technical endpoints).
- Avoid role/permission sprawl: Start simple; add new roles/permissions only when your product genuinely needs them.
- Communicate changes: Let users/admins know if the role or permission options in their organizations are about to change.
- Evolve the template: As your product grows, you can update the template at any time. All organizations will automatically have access to new roles/permissions.
- Versioning (optional): For major changes, consider versioning your template and communicating migration plans to your customers.
Managing your organization template
You can manage the organization template from the Console → Organization template or via the Logto Management API.
- Create roles: Add user roles and M2M roles to your template. Each role is available to all organizations in your Logto tenant.
- Create permissions: Define permissions for both API resources and non-API (in-app) actions.
- Edit the role-permission matrix: Assign permissions to roles using Logto Console or Management API.
- Update or delete roles/permissions: Changes to the template are automatically applied to all organizations. (Users/clients keep their role assignments; only the permission set changes.)
For step-by-step guides on managing the organization roles and permissions, see Role-based access control.
FAQs
Do I have to use organization permissions?
No, organization permissions are optional. You can use the organization template solely for defining roles and API resource permissions if you prefer.
What happens if I change the organization template?
Changes to roles or permissions are immediately reflected across all organizations. Users and clients keep their role assignments; only what those roles allow may change.
Can I customize roles or permissions per organization?
Not directly. Organization templates enforce a consistent model across all tenants. (You can still assign different roles to different users/clients in each organization.)
How do I roll back or migrate changes?
Manually update the template to restore previous roles/permissions. For complex migrations, consider versioning strategies.
What if I delete a role or permission?
Users/clients with that role lose access to permissions tied to it. Deleting a permission removes it from all roles that had it.
Are there limitations?
Customization is at the template level, not per organization. Contact us if you need advanced per-tenant exceptions.
Further reading
Protect organization (non-API) permissionsProtect organization-level API resources
Customizing token claims