Granular Permissions in Organizations

Granular permissions control what each member can view or change inside an organization. They improve security by reducing broad access and allowing only the actions each person needs.

In practice, you can let a user view only one project, read logs without changing settings, trigger deploys without accessing billing, or manage payments without touching environment variables.

Access model

Access combines four elements:

Element	Purpose
Role	Defines the member's base level: `owner`, `assistant`, or `member`
Resource	Defines the affected area, such as organization, project, template, database, managed service, billing, AI key, or global API key
Action	Defines the allowed operation, such as reading logs, changing environment variables, or creating checkout
Reusable policy	Named set of permissions that can be attached to several members

The owner has full access to the organization and bypasses granular checks. For assistant and member, access is denied by default: the effective permission is the union of the member's direct permissions and the permissions of the policies attached to them.

When you invite an assistant, Zenifra applies an initial template covering operation of projects, databases, managed services, and AI keys, plus inviting members and adjusting permissions. This template does not include billing, API Keys, or templates. A member starts with no permissions.

Protected resources

Permissions can be applied to different organization resources.

Resource	Access examples
organization	Create projects, templates, databases, managed services, AI keys, and API Keys; invite members; update permissions
project	View project, logs, metrics, costs, variables, domain, network, instances, image, Git source, deploys, and Preview environments
template	View, edit, publish, and remove organization templates
database	View status, access connection, rotate password, and update version
managed_service	Operate Valkey managed services (Key-Value, Cache, and Queue)
ai_key	View, update, and delete keys, and inspect AI usage and costs
api_key	View and revoke global organization API keys
billing	View billing, transactions, checkout, and payment methods

Some permissions are sensitive and should be granted carefully. Access to environment variables, database connection data, billing, and deploy changes can affect operations, security, or costs.

Resource scope

Permissions can be granted for every resource of a type or for a specific resource. For example, a member can receive access only to the staging project without viewing production projects.

Examples:

access to logs and metrics for one project;
permission to update the image for all projects in an organization;
permission to view connection data for a specific database;
permission to revoke a specific global API key;
read access to billing without permission to configure payment;
authorization to trigger deploys from the Git repository without changing the configured source.

This scope prevents people with limited responsibilities from seeing or controlling resources outside their work.

Organization API keys use the same resource scopes; member, invitation, and policy administration routes accept only a user session. The complete operational catalog, including resource scope and representative endpoints, is available in Organization API Keys. Creation scopes are granted on organization:*; actions on a resource should prefer its specific ID.

Reusable policies

Reusable policies avoid repeating the same configuration across members. On the Members page, create a policy with a name, an optional description, and permissions, then attach it to invitations or existing members. The same policies can also be used as a starting point when creating an API Key.

a member can have several policies, plus direct permissions;
editing a policy automatically changes the effective permission of every attached member;
removing a policy removes its permissions from attached members; access granted by another policy or by a direct permission still applies;
creating, editing, and attaching policies requires member.permissions.update on organization:*, and an assistant can attach policies to members only when they already hold every permission in them.

Recommended roles

Use roles as a starting point and adjust permissions as needed.

Profile	Recommended configuration
Founder or main administrator	`owner`, with periodic member review
Technical lead	`assistant`, with operational access to the required projects
Developer of one service	`member`, with access to the specific project, logs, metrics, and deploy
Finance analyst	`member`, with billing and transaction read access
Support user	`member`, with logs and metrics read access, without environment changes

Avoid making every collaborator an assistant. The broader the role, the higher the impact of human error, compromised credentials, or unplanned changes.

Practical examples

Developer with access to one project

Grant project read access, logs, metrics, and deploy only for the specific resource. If the person also needs to change environment variables, add that action explicitly.

Billing owner

Grant billing and transaction read access. Allow payment configuration or checkout creation only when the person is actually responsible for payment methods.

Database operator

Grant status and connection access for the specific database. Password rotation and version updates should remain restricted to authorized people.

Ownership transfer

Each organization has a single owner. Only the owner can change roles, remove members, and transfer organization ownership to another active member. On transfer, the previous owner becomes a member with no permissions; if they still need access, the new owner must grant the required permissions. Currently the transfer is done through the API, at PATCH /v1/organizations/{id}/ownership, sending the new owner's user_id with a user session.

Security best practices

apply the principle of least privilege;
prefer project-scoped access in critical environments;
review permissions when someone changes roles;
remove members who no longer participate in the organization;
limit access to billing, secrets, and deploy configuration;
use individual accounts, never shared credentials.

Granular permissions are most effective when they are part of a governance routine. Review members and permissions at defined intervals, especially in organizations with production systems, sensitive data, or relevant costs.