Overview
Just want to add a teammate or an app user? See Inviting People — it covers the
everyday tasks (invites, role changes, removing access) without the permission-design detail below.
This page is for setting up and provisioning the roles themselves.
| Layer | Controls | Who it’s for | Where you manage it |
|---|---|---|---|
| Organization roles | Access to the Stardeck dashboard, your agents, and which apps a person can use | Your team and staff | Organization Settings → Roles & Permissions and Settings → Members |
| Deployment roles | What an end-user can do inside one deployed app | The users of your live app | That app’s Settings → Roles & Permissions |
By default, the public pages of a deployed app are open to anyone — no sign-in required. Your
application code decides which routes are public. Roles only govern authenticated access.
Organization roles
Organization roles are defined once and shared across your whole organization. Open the organization dashboard and go to Settings → Roles & Permissions. Every organization starts with these roles:| Role | What it’s for |
|---|---|
| Admin | Full access. Automatically receives every permission, including any added later. Can assign any role to agents. |
| Member | Standard team access. The default for new members unless you change it. |
| Viewer | Read-oriented access. |
| External Viewer | Limited access for outside collaborators. |
Access level: Team vs App-only
The first choice when creating a role is its access level. This is the most important decision — it determines whether the role can reach the Stardeck dashboard at all.| Access level | What members can do |
|---|---|
| Team | Open the Stardeck dashboard and use every app their role allows. For staff who build, configure, or operate inside Stardeck. |
| App-only | Cannot open the dashboard. Can only use the deployed apps they’re explicitly assigned to. For frontline staff — drivers, cashiers, field teams — who use an app but never touch Stardeck. |
Switching a role from Team to App-only clears that role’s dashboard permissions, since
an app-only role can’t use them.
What a role grants
Select a role to open its detail panel. A role grants access in up to three areas:Dashboard permissions
(Team roles only.) What the role can do inside the Stardeck dashboard — things like managing members, editing settings, or running agents. Permissions follow a hierarchy within a resource:billing:admin implies billing:write, billing:read, and billing:public. Implied permissions show a “Granted by” hint so you can see why they’re checked.
App permissions (the bridge to your apps)
What the role can do inside your deployed apps, grouped per app. These keys come from each app’sconfig/permissions.json. Granting one here means: anyone with this organization role gets that capability when they sign into that app — without needing a separate per-app invitation.
This is the bridge between the two layers. Grants are per-app, so giving a role a permission in one app never affects another. (You can manage the same mapping from the app side — see Org-level Roles.)
Agent access
(Team roles only.) Whether members with this role can start agent chats, and which roles those agents may run as. When a user starts a chat, they can have the agent act with a role they’re allowed to assign. Admins can assign any role; other roles can only assign the roles you list here.AI integrations bind to a role
When you connect an external AI client (MCP), you bind it to an organization role. The connection
can only do what that role can. Pick the least permissive role that covers the job.
Creating a role
- Go to Settings → Roles & Permissions.
- Click New role.
- Choose an access level (Team or App-only).
- Enter a Name — a Key is generated automatically (lowercase letters, numbers, hyphens, underscores, and colons).
- Optionally add a Description, then click Create role.
- Select the role to assign its Dashboard permissions, App permissions, and Agent access.
Defaults
Role for new members
The role automatically given to people when they join your organization. If you don’t set one, the Member role is used. Configure it under Settings → Roles & Permissions → Defaults.Agent profile defaults
Each agent profile can run as a specific role by default. This overrides a user’s own role unless they explicitly pick a different one when starting a chat. Set it under Settings → Roles & Permissions → Defaults.Permissions catalog (advanced)
Most teams never need this. Under Permissions catalog you can:- Enable or disable the built-in System Permissions that roles are allowed to grant.
- Create Custom permissions — pick a resource (e.g.
billing) and a level (admin,write,read,public, or a custom level), and a key likebilling:adminis generated for you.
Organization members
Manage people under Settings → Members.- Invite a member — enter their email and pick the role they should receive (defaults to your organization’s “role for new members”). They get an email invitation; pending invitations can be resent or revoked. Bulk invite is available for adding many at once.
- Change a member’s role — pick a different role from the dropdown next to them. Each member has exactly one organization role.
- Grant or revoke admin — promote a member to (or demote them from) the Admin role from the shield action.
- App access — expand a member to see and manage the specific apps they’re assigned to and which deployment role they hold in each. This is how you give an App-only member access to a particular app.
Inviting team members may require a plan that supports multiple users. If your plan only allows
one user, you’ll see an upgrade prompt on the Members tab.
App roles & permissions (deployment roles)
Deployment roles control what end-users can do inside one deployed app. They’re defined per app, so different apps can have entirely different roles. Open the app, then go to Settings → Roles & Permissions. Every app starts with two deployment roles:| Role | Permissions |
|---|---|
| Admin | Admin panel access + user access |
| User | User access only |
Your sandbox must be running to edit an app’s roles and permissions. Start it from the app
dashboard if needed.
Permissions
An app’s permissions come from two places:- Project Permissions — built-in dashboard-style permissions for the app (read-only catalog, shown with a hierarchy).
- App Permissions — the permissions your app declares in
config/permissions.json(for exampleadmin-panel:write). These are the keys your application code checks. You can also add app permissions by hand.
Roles
Roles bundle permissions and are what you assign to users.- Under Roles, click Add Role.
- Enter a Name (e.g. “Moderator”) and optional Description — a key is generated.
- Click Edit Permissions to check the permissions this role should have.
Default Sign-Up Role
The deployment role automatically assigned to users who sign up to your app themselves. Set it under Default Sign-Up Role. Self-service sign-ups must be enabled in the app’s Authentication settings — see User Authentication. This role can’t be deleted while it’s the default.Organization Member Permissions
This setting controls what permissions your organization’s members get when they sign into this deployed app. Two modes:- Organization Role (default) — members forward their organization role’s permissions (the App permissions you granted that role for this app). Members without an org role get no extra permissions.
- Collaborator Role (legacy) — members receive a chosen baseline deployment role, with any org-role permissions added on top.
Org-level Roles
The Org-level Roles section lets you grant this app’s deployment permissions to your organization roles, right from the app. It’s the same bridge described under App permissions — just managed from the app side. Changes here only affect this app; the role’s grants on other apps are untouched. Use Manage roles to jump to the organization-level role editor.Your resolved role in this app
At the top of the tab, Your resolved role in this app shows the role and exact permissions you currently resolve to here — useful for confirming a configuration does what you expect.Project Members vs Deployment Users
Two separate tabs manage the two kinds of people in an app:- Project Members — collaborators who can help build and manage the app in Stardeck (code, settings, deploys). Useful for external developers, freelancers, or partner agencies.
- Deployment Users — end-users who can only sign into the deployed app, never Stardeck. Invite them with a deployment role; change roles, resend or revoke invitations, and remove access from this tab.
How access is determined
When someone accesses Stardeck or one of your apps, access resolves in this order:- Organization access — does the person’s organization role allow the dashboard (Team) or not (App-only)? App-only members only reach apps they’re explicitly assigned.
- App access — for a deployed app, the person’s deployment role and its permissions decide what they can do. Organization members resolve through the Organization Member Permissions setting (their org role’s app permissions, or the legacy collaborator role).
- Self sign-up — when enabled, new users who sign up get the app’s Default Sign-Up Role.
Letting the agent set up roles
You can ask the Developer Agent to create roles and permissions for your app. It edits the app’sconfig/permissions.json and config/roles.json, and the changes sync to the app’s database when committed. These changes are versioned with your chat history — revert a chat version and the role configuration reverts with it.
Common scenarios
SaaS with admins and regular users
- In the app, create an Admin deployment role (admin + user permissions) and a User role (user only).
- Make User the Default Sign-Up Role so self-service signups land there.
- Invite administrators as Deployment Users with the Admin role.
Frontline staff who should never see the dashboard
- Create an App-only organization role (e.g. “Driver”).
- Assign staff that role under Settings → Members, then expand each one and give them App access to the specific app(s) they need.
- They sign into those apps and nothing else — no dashboard.
Client who operates an app but shouldn’t touch Stardeck
- Invite the client as a Deployment User on their app with an admin-level deployment role.
- They run the live app; they can’t see your code or Stardeck settings. Their own customers sign up with the Default Sign-Up Role.
Agency managing many client apps
- Add your developers as organization members with a Team role so they can build across apps.
- Give each client access only to their own app — as a Deployment User, or as an App-only member assigned to that app.
Frequently asked questions
What’s the difference between an organization role and a deployment role?
An organization role governs Stardeck-wide access (the dashboard, agents, and which apps a person can use). A deployment role governs what an end-user can do inside a single deployed app. An org role can also carry permissions into an app via App permissions.What does “App-only” mean?
An App-only organization role can’t open the Stardeck dashboard. Members with it can only use the deployed apps you explicitly assign to them under Members → App access. It’s meant for frontline staff.How does an organization member get permissions inside an app?
Through the app’s Organization Member Permissions setting. In the default Organization Role mode, they receive whatever App permissions you granted their org role for that app.Can I delete a role that has users assigned to it?
For deployment roles, reassign those users first. Deleting an organization role unassigns it from any members who had it.Can I delete the default role?
No. Change which role is the default first, then delete the previous one.Can a Deployment User see my code or settings?
No. Deployment Users can only sign into the deployed app. They can’t reach Stardeck, your code, or any app settings.How do I check a user’s permissions in my application?
Your application receives the user’s resolved role and permissions when they sign in. Check the permission keys to show or hide features and protect routes.Next steps
Inviting People
The everyday tasks: invite teammates and app users, change roles, remove access
User Authentication
Configure sign-ups and sign-in methods for your app
Identities
Manage customers and contacts your agents and apps work with
AI Integrations
Bind external AI clients to an organization role
Publishing & Deployment
Deploy your app to production