Understanding System Roles & Permissions

Two-Tier Authorization Model

Agentyk.me uses a two-tier authorization system to separate platform-wide administration from organization-level access control. This design lets a single platform admin manage infrastructure while each organization independently controls its own member permissions.

Platform Admin

The platform admin has full control over the Agentyk.me instance. This includes managing all organizations, viewing system health, configuring SSO providers, and accessing audit logs across every tenant. Platform admin privileges are assigned via environment configuration and cannot be granted through the UI.

Organization Roles

Within each organization, members are assigned one of five roles. Roles are hierarchical — higher roles inherit all permissions of lower roles.

1. 1

   Owner

   Full control over the organization. Can delete the org, transfer ownership, manage billing, and assign any role including Admin. Each organization has exactly one Owner.

2. 2

   Admin

   Can manage members, invite users, change roles (up to Admin), configure organization settings, and manage API keys. Cannot delete the organization or transfer ownership.

3. 3

   Billing Manager

   Can view and manage subscription plans, payment methods, invoices, and usage reports. Cannot manage members or organization settings.

4. 4

   Member

   Standard access. Can use AI models, create conversations, view shared resources, and manage their own profile. Cannot invite users or change settings.

5. 5

   Viewer

   Read-only access. Can view conversations shared with them and browse organization resources. Cannot create new conversations or modify anything.

Permissions Breakdown

The following table summarizes which actions each role can perform:

Permission                 Owner  Admin  Billing  Member  Viewer
─────────────────────────  ─────  ─────  ───────  ──────  ──────
Use AI models                ✓      ✓       ✓       ✓       ✗
Create conversations         ✓      ✓       ✓       ✓       ✗
View shared resources        ✓      ✓       ✓       ✓       ✓
Manage own profile           ✓      ✓       ✓       ✓       ✓
View usage reports           ✓      ✓       ✓       ✗       ✗
Manage API keys              ✓      ✓       ✗       ✗       ✗
Invite members               ✓      ✓       ✗       ✗       ✗
Remove members               ✓      ✓       ✗       ✗       ✗
Change member roles          ✓      ✓       ✗       ✗       ✗
Edit org settings            ✓      ✓       ✗       ✗       ✗
View billing & invoices      ✓      ✓       ✓       ✗       ✗
Manage payment methods       ✓      ✗       ✓       ✗       ✗
Change subscription plan     ✓      ✗       ✓       ✗       ✗
View audit logs              ✓      ✓       ✗       ✗       ✗
Configure SSO / SAML         ✓      ✗       ✗       ✗       ✗
Transfer ownership           ✓      ✗       ✗       ✗       ✗
Delete organization          ✓      ✗       ✗       ✗       ✗

Full Permission Reference

All 17 permissions grouped by category:

Conversations & AI

• Use AI models — send messages to any enabled model
• Create conversations — start new chat sessions
• View shared resources — access conversations and files shared within the org

Member Management

• Invite members — send invitations to new users
• Remove members — revoke organization access
• Change member roles — assign or change roles (within your own level)
• Manage own profile — update name, avatar, and notification preferences

Billing & Usage

• View usage reports — see token consumption and costs
• View billing & invoices — access payment history and upcoming charges
• Manage payment methods — add or remove credit cards and bank accounts
• Change subscription plan — upgrade, downgrade, or cancel the plan

Organization Administration

• Edit org settings — change organization name, defaults, and preferences
• Manage API keys — create, rotate, and revoke API keys
• View audit logs — review all actions taken within the organization
• Configure SSO / SAML — set up single sign-on for Enterprise accounts
• Transfer ownership — assign the Owner role to another Admin
• Delete organization — permanently remove the org and all its data

Role Hierarchy & Management Rules

• Roles follow a strict hierarchy: Owner > Admin > Billing Manager > Member > Viewer.
• You can only assign roles at or below your own level — an Admin cannot promote someone to Owner.
• Ownership transfer requires the current Owner to explicitly initiate it.
• Removing the last Admin is blocked to prevent lock-out.
• Role changes take effect immediately and are logged in the audit trail.

Common Scenarios

Inviting a new team member

An Owner or Admin navigates to Organization Settings → Members, clicks "Invite", enters the email address, selects a role, and sends the invitation. The invitee receives an email with a link to join the organization.

Delegating billing access

Assign the Billing Manager role to your finance team. They can view invoices, update payment methods, and change plans without having access to member management or organization settings.

Auditing team activity

Owners and Admins can access the audit log from Organization Settings → Audit Log. Every action — member invites, role changes, API key creation, billing updates — is recorded with a timestamp and actor.

Managing API keys

Owners and Admins can create, rotate, and revoke API keys from Organization Settings → API Keys. Each key can be scoped to specific permissions and has an optional expiration date.