Roles & Permissions

Overview#

Artifi uses a two-layer access model to control what users can do:

1. Membership level — Controls access to the admin dashboard (team management, settings, API keys)
2. Permission roles — Controls accounting operations (AR, AP, GL, reporting) via conversational tools

These are independent: a user can be a "Viewer" membership (read-only dashboard) but have the "Controller" permission role (full accounting access through Claude).

---

Membership Levels#

Membership determines what a user can do in the admin dashboard.

The Owner level is not selectable when inviting new users -- it is exclusively for the organization creator.

Auto-Provisioned Users#

When a new user connects via Claude.ai for the first time, they are automatically provisioned as an Owner with full Admin permissions and a complete database schema. No invitation is needed. See the Authentication guide for details.

---

Permission Roles (RBAC)#

Permission roles control what accounting operations a user can perform. Artifi includes 6 built-in system roles that cannot be modified:

---

Permission Groups#

Permissions follow the format category:action. A wildcard (category:*) grants all actions within a category.

Admin#

Accounting#

Accounts Receivable#

Accounts Payable#

Payments#

Master Data#

Dimensions#

Reporting, Configuration, and Audit#

---

Entity Scoping#

Both membership and permission roles support entity scoping, allowing you to restrict access to specific legal entities.

Membership Entity Access#

• All entities — User can access all legal entities (default)
• Specific entities — User can only access listed entity IDs

Role Entity Scoping#

• All entities — Role applies across all entities (default)
• Specific entities — Role only applies to listed entity IDs

A user can have the same role assigned multiple times with different entity scopes. For example:

• Controller role scoped to Entity 1 (US operations)
• AR Accountant role scoped to Entity 2 (UK operations)

---

Custom Roles#

Organizations can create custom roles combining any permission groups.

Properties#

• Unique name within the organization (slug format: lowercase alphanumeric + underscores)
• Can be activated or deactivated (deactivating removes the role from all users)
• Can be edited (description and permissions)
• Cannot reuse system role names

Creating Custom Roles#

Navigate to Team > Roles > Create Role in the admin dashboard. The form presents permission group checkboxes organized by category, making it easy to compose the exact permissions needed.

---

Invitation Flow#

Team invitations use a token-based email flow for secure onboarding.

Lifecycle#

1. Admin sends invite — Fills the invite form with email, name, membership level, entity access, and permission roles. An invitation email is sent with an "Accept Invitation" link.

2. Recipient clicks link — The link validates the token, checks expiry (7 days), and redirects to the sign-up flow with a pre-filled email address.

3. Auth callback — After signing up or logging in, the system creates the user account, sets up organization membership with the specified entity access, and applies the assigned permission roles.

4. Pending display — Pending invitations appear in the team members list with an "Invited" status badge. Admins can revoke pending invitations at any time.

5. Re-invite — Sending a new invitation to an email with a pending invite replaces the old one with a fresh token and email.

Partner Organization Invitations#

For partner organizations, the invite form includes a "Client organization access" section. This lets the admin grant the invitee access to selected client organizations in a single step:

• Each client organization can have its own membership level
• All invitations share the same token -- the accept flow processes all linked invitations at once
• Only one email is sent (for the partner organization)

Partner Role Propagation#

When a new client organization is created under a partner, all users from the partner organization are automatically given access to the new client organization. Their membership level in the client matches their level in the partner (owner stays owner, admin stays admin, etc.).

Role Downgrade Protection#

When accepting an invitation, the system checks if you already have a higher membership level in the target organization. If so, the existing level is preserved -- accepting an invite as "member" will not downgrade an existing "admin" or "owner".

Priority order: owner > admin > member > viewer

---

Linked Employees#

Team members can be automatically linked to employee records. When a user account matches an employee record, the team list displays the linked employee's ID and name.

This enables role-to-employee coordination -- for example, ensuring an employee who handles AP is assigned the ap_accountant role.

---

Admin Dashboard Pages#

---

Summary#

• Two-layer model: Membership controls dashboard access; permission roles control accounting operations
• 6 built-in roles: Administrator, Controller, AP Accountant, AR Accountant, Auditor, Investor
• 11 permission categories: Admin, Accounting, AR, AP, Payments, Master Data, Dimensions, Reporting, Configuration, Global IDs, Audit
• Entity scoping: Restrict any role to specific legal entities
• Custom roles: Compose your own permission combinations
• Token-based invitations: Secure email flow with 7-day expiry
• Partner support: Multi-organization invitations and automatic role propagation