Managing Team Members, Invites & Custom Policy Permissions (PBAC)

To collaborate securely within a Business Workspace, Nyota Imara implements an enterprise Policy-Based Access Control (PBAC) engine. Instead of rigid, one-size-fits-all roles (admin, editor, viewer), permissions are defined using granular, declarative JSON policy statements.

This guide explains how workspace invitations work under the hood, how to assign policy presets, how to write custom security policies, and how to troubleshoot permission errors.

1. How It Works Under the Hood

When you invite a colleague to a Business Workspace, the Nyota backend executes a secure three-step lifecycle:

1. INVITATION DISPATCH
    Workspace Admin sends invite -> System creates row in workspaces.workspace_members
    (status: "pending_invite", generates secure 7-day token).
                         │
                         ▼
 2. ACCEPTANCE & SSO BINDING
    Recipient clicks email link -> Authenticates via accounts.nyotaimara.com IdP ->
    Session binds user's Supabase UUID to the workspace (status: "active").
                         │
                         ▼
 3. DYNAMIC POLICY ENFORCEMENT
    On every API or dashboard action, the backend evaluates all assigned JSON statements:
    - Checks actions: ["sms:send", "drive:file:write"]
    - Evaluates explicit Denies (explicit DENY always overrides an ALLOW).

The Core Rule of PBAC:

Explicit Denies Always Win: If a user is assigned an allow policy for all storage operations (drive:*), but their assigned department has a deny policy for file deletions (drive:file:delete), the user cannot delete files.

2. Default Policy Presets vs. Custom JSON Statements

Workspace administrators can choose between rapid Pre-Built Policy Presets or write Custom JSON Statements.

Available Pre-Built Presets

3. Writing Custom Policy Statements

For organizations with complex compliance rules, you can attach custom JSON policy statements directly to any workspace member or Organizational Unit (OU):

Example 1: Allow SMS Drafting, but Deny Campaign Dispatch

Allows an intern or junior marketer to compose and test SMS broadcasts, but prevents them from submitting campaigns to live telecom carriers:

[
  {
    "effect": "allow",
    "actions": ["sms:message:read", "sms:message:write", "sms:contact:*"],
    "resources": ["*"]
  },
  {
    "effect": "deny",
    "actions": ["sms:campaign:dispatch", "sms:campaign:send"],
    "resources": ["*"]
  }
]

Example 2: Scoping Storage Access to a Specific Department OU

Restricts a contractor to accessing files located strictly within the /Engineering/Mobile folder path:

[
  {
    "effect": "allow",
    "actions": ["drive:file:read", "drive:file:write"],
    "resources": ["ou:/engineering/mobile/*"]
  }
]

4. Common Pitfalls & How to Troubleshoot

Pitfall A: "My invited teammate sees 'Invitation Invalid or Expired'."

• The Cause: Workspace invitation links expire automatically after 7 calendar days for security. Alternatively, the teammate clicked the invite link while logged into a different browser profile with a personal email address.
• The Resolution:
• 1. Go to accounts.nyotaimara.com.
  2. Locate the user under Pending Invitations.
  3. Click "Resend Invitation" to refresh the token and dispatch a new email.

Pitfall B: "My engineer gets 403 Forbidden: Missing required scope."

• The Cause: The user’s assigned policy statement does not include the exact action required by the endpoint.
• The Resolution:
• 1. Navigate to Team Members on accounts.nyotaimara.com.
  2. Click on the affected member and select Edit Permissions.
  3. Check whether an explicit deny statement is active on their account or parent department OU.
  4. Add the missing action (e.g., id:session:create or drive:file:write).

5. Step-by-Step: How to Invite a New Team Member

1. Log in to accounts.nyotaimara.com and verify your Business Workspace is selected in the top-left corner.
2. Navigate to Team Members in the left sidebar.
3. Click the "Invite Member" button in the top right.
4. Enter the recipient’s business email address.
5. Select an initial Policy Preset (e.g., Developer, Communications Manager).
6. (Optional) Assign the user to an existing Organizational Unit (OU).
7. Click "Send Invitation".

The invitee will receive an email from noreply@nyotaimara.com containing their secure join link.

Related Support Guides & Links

• Understanding Personal vs. Business Workspaces
• Generating & Managing Developer API Keys
• Managing Workspace Team Members