Users & Role-Based Access Control

HeadlessOps uses a five-level role system per workspace. Every workspace member has exactly one role, and permissions are cumulative from VIEWER upward.

New in IAM v1: Label grants now control which resources a member can see. Roles control what a member can do; labels control which resources they can do it on. See Labels & Permissions for the full guide.

Role Reference

Permission Matrix

Note on resource visibility: For non-admin members, the rows above only apply to resources the member can already see. A DEVELOPER cannot edit an integration they cannot see due to label restrictions. See Labels & Permissions.

Inviting Users

Required role: ADMIN or OWNER

Via the Web UI

1. Go to Workspace Settings → Members
2. Click Invite Member
3. Enter the email address and select a role
4. Click Send Invite

The invited user receives an email with a link to accept. Pending invites are visible in the Members list and expire after 7 days.

Via the API

curl -X POST https://app.headlessops.ai/api/workspaces/ws_abc123/members/invite \
  -H "Cookie: session=YOUR_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com",
    "role": "DEVELOPER"
  }'

Response:

{
  "inviteId": "inv_abc123",
  "inviteUrl": "https://app.headlessops.ai/invite/inv_abc123"
}

Share the inviteUrl with the user. They log in (or create an account) and are immediately added to the workspace.

Listing Members

curl https://app.headlessops.ai/api/workspaces/ws_abc123/members \
  -H "Cookie: session=YOUR_SESSION"

Returns both current members and pending invites:

{
  "members": [
    {
      "id": "mem_1",
      "role": "OWNER",
      "user": { "id": "u_1", "name": "Alice", "email": "alice@example.com" }
    },
    {
      "id": "mem_2",
      "role": "DEVELOPER",
      "user": { "id": "u_2", "name": "Bob", "email": "bob@example.com" }
    }
  ],
  "invites": [
    {
      "id": "inv_1",
      "email": "carol@example.com",
      "role": "VIEWER",
      "expiresAt": "2026-06-11T00:00:00Z"
    }
  ]
}

User Invite Flow

ADMIN/OWNER                    Invited User
    │                               │
    │── POST /members/invite ──▶    │
    │◀── { inviteId, inviteUrl } ── │
    │                               │
    │    [share inviteUrl]          │
    │                  ────────────▶│
    │                  [open link]  │
    │                  [log in / sign up]
    │                  [accept invite]
    │                               │
    │◀─────────────── added to workspace ──

Two-Factor Authentication (2FA)

HeadlessOps supports TOTP-based 2FA compatible with Google Authenticator, Authy, 1Password, and similar apps.

Enabling 2FA (Per User)

1. Go to Account Settings → Security
2. Click Enable Two-Factor Authentication
3. Scan the QR code with your authenticator app
4. Enter the 6-digit code to confirm
5. Save your backup codes in a secure location

Requiring 2FA Workspace-Wide

Workspace owners and admins can enforce 2FA for all members:

1. Go to Workspace Settings → Security
2. Toggle Require 2FA for all members
3. Members without 2FA enabled will be prompted to set it up on next login

Note: Members with 2FA disabled when enforcement is turned on will not lose access immediately — they are redirected to the 2FA setup page on their next login.

Recovery

If a member loses access to their authenticator app:

1. The member contacts the workspace ADMIN or OWNER
2. The admin can temporarily disable the 2FA requirement at the workspace level
3. The member logs in and reconfigures 2FA using their backup codes or a new authenticator
4. Re-enable workspace-wide 2FA enforcement after recovery

Removing Members

# Remove a member (ADMIN or OWNER required)
curl -X DELETE https://app.headlessops.ai/api/workspaces/ws_abc123/members/mem_2 \
  -H "Cookie: session=YOUR_SESSION"

Removing a member immediately revokes their access. Any API keys they created remain valid until explicitly revoked.

Role Assignment Best Practices

Labels & Fine-Grained Access

Roles alone are a coarse-grained control. For finer control — such as limiting a developer to only their team's resources, or giving a client access only to their own integrations — use label grants.

Label grants are additive to roles. A DEVELOPER with no label grants sees nothing (all resources are admin-only until labeled). A DEVELOPER with a read grant on client-acme sees only integrations, credentials, and knowledge docs tagged client-acme.

See Labels & Permissions for the complete guide.