> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stardeck.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Members & Roles
> Control who can access your Stardeck organization, your agents, and your deployed apps with organization roles and per-app deployment roles
## Overview
Just want to add a teammate or an app user? See [Inviting People](/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.
Stardeck access control has **two layers**. Keep them separate in your head and everything else follows:
| 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** |
Organization roles answer *"what can this person do across Stardeck?"* Deployment roles answer *"what can this person do inside this one app?"* A role assigned at the organization level can also carry permissions into your apps — that bridge is covered under [App permissions](#app-permissions-the-bridge-to-your-apps).
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**](https://www.stardeck.ai/dashboard/settings?tab=roles).
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. |
You can edit these (except for the built-in behavior of **Admin**), add your own, or delete ones you don't use.
## 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. |
You can switch a role between Team and App-only at any time from the role's detail panel.
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:
```
admin → write → read → public
```
A higher level automatically grants the lower ones. For example, granting `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's `config/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](#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.
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
1. Go to **Settings → Roles & Permissions**.
2. Click **New role**.
3. Choose an **access level** (Team or App-only).
4. Enter a **Name** — a **Key** is generated automatically (lowercase letters, numbers, hyphens, underscores, and colons).
5. Optionally add a **Description**, then click **Create role**.
6. 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 like `billing:admin` is generated for you.
Custom and system permissions then appear as options when you edit a role's Dashboard permissions.
***
# Organization members
Manage people under [**Settings → Members**](https://www.stardeck.ai/dashboard/settings?tab=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**](https://www.stardeck.ai/projects/~/dashboard/config/roles).
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 example `admin-panel:write`). These are the keys your application code checks. You can also add app permissions by hand.
The permission key is what your application code uses to gate features and routes. Keys are lowercase and may contain letters, numbers, hyphens, underscores, and colons.
## Roles
Roles bundle permissions and are what you assign to users.
1. Under **Roles**, click **Add Role**.
2. Enter a **Name** (e.g. "Moderator") and optional **Description** — a key is generated.
3. 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**](https://www.stardeck.ai/projects/~/dashboard/config/auth) settings — see [User Authentication](/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](#app-permissions-the-bridge-to-your-apps) 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.
Project editors always keep their collaborator role regardless of this setting.
## 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](#app-permissions-the-bridge-to-your-apps) — 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**](https://www.stardeck.ai/projects/~/dashboard/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**](https://www.stardeck.ai/projects/~/dashboard/config/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:
1. **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.
2. **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).
3. **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's `config/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](#app-permissions-the-bridge-to-your-apps).
### 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](#app-permissions-the-bridge-to-your-apps) 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
The everyday tasks: invite teammates and app users, change roles, remove access
Configure sign-ups and sign-in methods for your app
Manage customers and contacts your agents and apps work with
Bind external AI clients to an organization role
Deploy your app to production