Access Control
Organization and project hierarchy, role-based permissions, and user management.
Entities and Relationships
Organizations
Organizations are the top-level entity in our system. Each organization can contain multiple projects and has its own set of members. Organizations implement a role-based access control system with two distinct roles: admin and member. These roles determine what actions users can perform within the organization and its projects.
Projects
Projects exist within organizations and serve as containers for related resources that require similar access control. Unlike team-based structures, projects are designed to group resources that should be protected and accessed in a consistent manner. This resource-centric approach allows for fine-grained access control based on the nature of the resources rather than organizational hierarchy.
Membership Rules
Project membership is tied to organization membership. A user must first be a member of an organization before they can be added to any projects within that organization. This hierarchical structure ensures proper access control across your resources.
API keys have the same permissions as project members. This means they can access project resources but cannot perform administrative actions that are reserved for project admins.
Roles and Permissions
The following table categorizes permissions by functional area to clearly show what each role can do:
Organization Management Permissions
| Permission | Org Admin | Org Member | Project Admin | Project Member | API Key |
|---|---|---|---|---|---|
| Create new projects | ✅ | ❌ | ❌ | ❌ | ❌ |
| Invite users to organization | ✅ | ❌ | ❌ | ❌ | ❌ |
| View organization members | ✅ | ✅ | ❌ | ❌ | ❌ |
| Manage organization member roles | ✅ | ❌ | ❌ | ❌ | ❌ |
| Remove members from organization | ✅ | ❌ | ❌ | ❌ | ❌ |
Project Access Control Permissions
| Permission | Org Admin | Org Member | Project Admin | Project Member | API Key |
|---|---|---|---|---|---|
| Access all projects automatically | ✅ | ❌ | ❌ | ❌ | ❌ |
| Add organization members to a project | ✅ | ❌ | ✅ | ❌ | ❌ |
| Remove members from a project | ✅ | ❌ | ✅ | ❌ | ❌ |
| Change project member roles | ✅ | ❌ | ✅ | ❌ | ❌ |
| View projects they are members of | ✅ | ✅ | ✅ | ✅ | N/A |
Resource Access Permissions
| Permission | Org Admin | Org Member | Project Admin | Project Member | API Key |
|---|---|---|---|---|---|
| Access project resources | ✅ | ✅* | ✅ | ✅ | ✅ |
| Create API keys for a project | ✅ | ❌ | ✅ | ✅ | ❌ |
| Manage project resources | ✅ | ❌ | ✅ | ❌ | ❌ |
*Only for projects they are members of
Organization Roles in Detail
Organization Admin
Organization admins have complete control over the organization. They have full access to all projects within the organization, regardless of whether they are explicitly added as project members. Organization admins are the only users who can create new projects, invite users to join the organization, manage the roles of organization members, and remove members from the organization.
Organization Member
Organization members have limited access within the organization. They can view the member list of the organization but can only access projects to which they have been explicitly added. Their permissions within accessible projects are determined by their project role.
Project Roles in Detail
Project Admin
Project admins have management capabilities within their specific project. They can add existing organization members to their project, remove members from the project, and change the roles of project members. However, project admins cannot invite new users to the organization—this capability is reserved for organization admins.
Project Member
Project members have basic access to the project resources according to the system’s permission model. They can view and interact with the project but cannot modify membership or roles.
API Keys
API Keys function exclusively at the project level and have the same permissions as project members. They can:
- Access project resources and data
- Make API calls within the project scope
- Cannot perform any administrative actions
API Keys are ideal for service accounts, automated processes, and integrations that need programmatic access to project resources.
Invitation Process
User invitations can only be created by organization admins. When creating an invitation, the admin specifies the invitee’s email address, organization role, and a default project and project role.
Upon invitation creation, an email is sent to the invitee with a unique link. After the invitee authenticates and accepts the invitation, the system verifies that the account email matches the invitation email. Once verified, the user is added to the organization with the specified role and to the default project contained in the invitation.
Invitations expire 7 days after creation. The invitation can only be accepted if the account accepting it has the same email as the invitation.
Usage Guidelines
Projects should be used strategically to group resources that require similar access control patterns. Rather than organizing by teams or departments, consider organizing projects based on resource types, security requirements, or functional boundaries.
Consider the following best practices:
- Create projects based on resource sensitivity and access requirements
- Group resources that are commonly accessed together in the same project
- Use projects to implement the principle of least privilege by limiting access to only necessary resources
- Regularly audit project membership and permissions
- Rotate API keys periodically for enhanced security