Open app
Moonborn — Developers

Workspace + RBAC setup

Stand up a Moonborn workspace, invite teammates, assign roles, and configure an SSO + SCIM provider for org-wide identity.

Workspaces are the Moonborn project container; orgs sit above them. RBAC binds users to roles, roles to actions, actions to resources. This tutorial covers the practical sequence: create an org, create a workspace, invite teammates, assign roles, and (for Enterprise) wire SAML + SCIM.

1. Create the org + workspace

When you sign up, an org is created automatically — that's your billing root. Inside it, create one or more workspaces:

const ws = await client.workspaces.createWorkspace({
  name: 'Product team',
  description: 'Persona work for the consumer surface.',
});

2. Invite teammates

const invitation = await client.memberships.inviteMember({
  email: 'designer@acme.co',
  role: 'editor',
  workspaceId: ws.id,
});
console.log(invitation.acceptUrl);

The invitation email lands with an accept URL. Until accepted, the membership sits in pending.

3. Built-in roles

Seven roles ship out of the box (PRD §H, plan.md §1.6):

RoleReadWriteNotable can-do
ownerallalltransfer org, delete workspace
adminallallmanage members, billing
editorallpersonas + chatcreate + refine personas
viewerallnoneread-only
api-onlyscopedscopedservice accounts, no UI access
billinginvoicespayment methodsfor finance team members
auditoraudit log + confignonefor compliance teams

Custom roles are Enterprise — they let you define a resource × action matrix tailored to your org.

4. Change roles

await client.memberships.updateMembership({
  id: 'mem_...',
  role: 'admin',
});

The membership audit log records every role change with the actor + timestamp.

5. Set up SAML SSO (Enterprise)

For orgs on the Enterprise plan, swap the default credentials provider for SAML 2.0:

await client.config.setItem({
  key: 'identity.sso.saml.enabled',
  value: true,
  scope: 'org',
  scopeId: 'org_...',
});
 
await client.config.setItem({
  key: 'identity.sso.saml.idp_metadata_url',
  value: 'https://your-idp.example.com/metadata',
  scope: 'org',
  scopeId: 'org_...',
});

Initiate a SAML flow at POST /v1/auth/sso/saml/initiate; the IdP posts back to /v1/auth/sso/saml/acs. See the SSO / SAML setup guide for the IdP-side configuration.

6. Set up SCIM provisioning (Enterprise)

SCIM lets your IdP push user lifecycle changes (create, update, deactivate) into Moonborn automatically. The endpoints follow RFC 7644:

  • GET/POST /v1/auth/scim/v2/Users
  • PATCH/DELETE /v1/auth/scim/v2/Users/{id}
  • GET/POST /v1/auth/scim/v2/Groups

Configure your IdP (Okta, Azure AD, Google) with these endpoints + the SCIM bearer token from Settings → SSO. New hires auto-provision; departures auto-deprovision.

7. IP allowlists (Enterprise)

await client.config.setItem({
  key: 'identity.ip_allowlist.cidrs',
  value: '203.0.113.0/24,198.51.100.0/24',
  scope: 'org',
  scopeId: 'org_...',
});

Connections outside the allowlist get rejected at the gateway. Useful for orgs that constrain API access to corporate networks.

8. Audit it

Every role change, every membership change, every config edit lands in the immutable audit log:

const events = await client.audit.listEvents({
  workspaceId: ws.id,
  category: 'rbac',
  limit: 50,
});

The audit log is hash-chained and retained per privacy.retention.audit_log_years (default 7 for Enterprise, 1 for Pro/Team).

Tier

  • Basic workspaces + 4 built-in roles: Free.
  • Editor / api-only / billing / auditor roles: Pro.
  • SCIM + SAML SSO + IP allowlists + custom roles: Enterprise.

Next