Members & Roles

For the steps to invite or add people, see Inviting People. This page explains how access works.

Who is whoCopy Anchor Link

Membership lives in the organization. Every app reads from it.

• Use app-only team members for cashiers, drivers and kitchen crews who use apps but never build.
• Use app users for customers and other outside users.
• Every team member and app user is also a person in the directory.
• Public pages of a deployed app need no sign-in. Your app code decides which routes are public.

Organization rolesCopy Anchor Link

Manage them under Settings → Roles & Permissions. Each team member has exactly one.

Every organization starts with five standard roles. They come with every plan.

Organizations created before Manager existed have it added automatically, and their Member role keeps its name.

Creating new roles comes with Growth and above. On every plan you can rename the built-in roles, change what each one can do and create custom permissions. If you move to a lower plan, roles you already made keep working, but you can't add new ones. Admin's built-in behavior can't be changed. None of the five standard roles can be deleted, and neither can the agent role. Every update keeps what the standard roles can do with Stardeck's Modules in line with those Modules (see below), so to give people different access, duplicate a role and change the copy.

Access level: Team vs App-onlyCopy Anchor Link

Switching a role to App-only clears its dashboard permissions.

Raise access to one appCopy Anchor Link

A Team member can hold a higher Team role on one app. Use it for someone who uses every app but builds only one: give a Viewer the Staff role on the website app, and they get Build, Code and Settings there while every other app stays use-only.

Set it in the member's App-specific access panel with Team role on this app. The app's apps:* permissions from that role are added to their own, so it can raise access but never lower it. Their Team role means no per-app role. Setting it back, or removing the app, ends the extra access, along with any Git access Stardeck granted for that app. Agents acting for the member follow the same rule. App-only members can't be raised this way, and changing it needs roles:manage.

What a role grantsCopy Anchor Link

• Dashboard permissions (Team only). Levels imply the ones below: admin → write → read → public. For apps: apps:read opens apps, apps:write edits and deploys, apps:admin is full management.
• App permissions. Keys from each app's config/permissions.json, granted per app. Anyone with the role gets them when they sign in to that app, with no separate invitation. Stardeck's Modules decide what the standard roles can do with them: Admin gets every key, External Viewer none, and Manager, Staff and Viewer the keys each Module gives them. The app is set up this way when it is created, when a Module is added or removed, and on every update, which also tells you in plain words what staff gained or lost. Those grants on a standard role appear locked with a note; the app's own permissions on a standard role can still be changed.
• Agent access (Team only). Whether members can start agent chats, and which roles those agents may run as. Admins can assign any role.

AI integrations, including a local agent connection, act as the role picked when authorized. That can only be a role the person may assign. Pick the least permissive role that covers the job. Two of the agent permissions, Open Apps in a Browser and Open Apps as Another Person or Role, start on the Admin role only. See Opening an app in your browser.

Duplicate a roleCopy Anchor Link

To give people different access than a standard role allows, open the role and click Duplicate. The copy ("Manager copy") starts with the same dashboard permissions, app permissions and data store access, with nobody assigned. It is an ordinary role: edit it freely, and no update changes it. Move people over by changing their role.

Disable a roleCopy Anchor Link

A role you no longer want handed out can be disabled instead of deleted. Open the role and click Disable (it needs the Disable Roles permission, roles:disable, which Admin always has). A disabled role keeps its permissions and its history, shows a Disabled badge, and disappears from every role picker: nobody can be given it, in an invitation, an invite link, a default or an API key. Click Enable to bring it back; its grants are kept current by updates the whole time, so it comes back correct.

Disabling is refused while anything still uses the role, and the message says what: people who hold it, pending invitations or active invite links, the default role for new members, agent profile defaults, assistants, API keys or agent connections. Move those to another role first. Admin, External Viewer and the agent role can never be disabled. An invite made before a role was disabled stops working for that role; ask for a new invite. A disabled role also can't be used to preview an app, and an agent's browser sign-in opened with it is signed out.

Create a roleCopy Anchor Link

1. Settings → Roles & Permissions → New role.
2. Pick Team or App-only.
3. Enter a Name. The key is generated (lowercase letters, numbers, -, _, :).
4. Click Create role, then select it to set dashboard permissions, app permissions and agent access.

Defaults and catalogCopy Anchor Link

Under Settings → Roles & Permissions:

• Defaults → Role for new members: Staff (Member in older organizations) if unset. Use your least-privileged role.
• Defaults → Agent profile defaults: the role each in-Stardeck agent profile runs as. External AI connections ignore it.
• Permissions catalog (advanced): enable or disable system permissions, or add custom ones such as billing:admin.

App rolesCopy Anchor Link

App roles control what someone can do inside one deployed app. Manage them in the app under Settings → Roles & Permissions.

• Every app starts with one standard app role, Customer. It is the default for people who sign in, and it can't be deleted or renamed. It holds none of the permissions Stardeck's Modules declare, so a stranger who signs up never reaches staff features. To give customers more, Duplicate Customer (optionally making the copy the default) or add your own role, and choose it as the default.
• Any app role, Customer included, can be disabled from the Roles section (same Disable Roles permission). A disabled app role can't be given to anyone and is hidden from role pickers. It is refused while a member, pending invitation, invite link or per-app override still uses it, or while it is the default sign-up or collaborator role. Customer can be disabled once another role is the default and nobody holds it.
• Project Permissions are built in. App Permissions come from config/permissions.json (for example admin-panel:write). Your code checks these keys.
• Default sign-up role is given to self sign-ups. Enable self sign-up under User Authentication. A role that still has members can't be deleted.
• Team member permissions sets what team members get in this app:
  • Organization Role (default): the app permissions granted to their organization role.
  • Collaborator Role (legacy): a baseline app role plus their organization-role permissions.
  • Project editors always keep their collaborator role.
• Organization roles grants this app's permissions to organization roles from the app side. It only affects this app.
• Your role shows your effective role and permissions in this app.

Let the agent set up rolesCopy Anchor Link

Ask your coding agent. Through the Stardeck MCP server it reads and writes the whole role setup with get_app_auth_config and set_app_auth_config, which validate it at once; tools such as create_app_role and set_app_role_permissions make single changes. Starcat Developer does the same from the Build tab, and its role changes revert with the chat version.

Don't hand-edit config/permissions.json or config/roles.json: they are synced output. A hand edit isn't checked until the sandbox next starts, when it is reconciled with the saved roles.

How access is determinedCopy Anchor Link

1. Organization: Team roles reach the dashboard. App-only roles reach only assigned apps.
2. App: the app role decides what someone can do. Team members resolve through Team Member Permissions.
3. Self sign-up: new users get the Default Sign-Up Role.

Who may grant whatCopy Anchor Link

Keep Admin to two or three people. Give location managers members:invite without roles:manage.

Bulk actionsCopy Anchor Link

In Settings → Team Members, admins tick members (not themselves) and use:

• Set role: one organization role, or No role. Members who already have it are skipped.
• Add to app: an app and an app role, or Default role.
• Remove: confirms first. Lists any managed accounts that will be deleted.

Each member gets the same permission checks as single edits. Failures stay selected with a reason; the rest go through.

Staff importCopy Anchor Link

To load a staff list into an app and then give people logins:

1. The app imports people. Each row finds or creates a person in the directory by email, and the app stores its own staff data (location, job) against that person. No logins yet. Re-importing finds the same people. Ask your coding agent to build a staff import screen.
2. An admin creates logins. The app offers a file with email, first_name, last_name, role, app, app_role and identity (the person's id). Upload it under Team Members → Create accounts. Each login joins its person.

Step 2 needs identities:govern. People who already have a team login are skipped. Rows without an email can't get an account.

Claim links for app-only staffCopy Anchor Link

On an app's Settings → Users tab, App-only team members creates a claim link for an app-only role. Staff who open it sign in, join the organization with that role, and land in the app. Create the app-only role first.

LifecycleCopy Anchor Link

Stardeck audits account creation, app assignments at creation, ties to existing people, managed account edits and merges. Generated passwords and invite link URLs are shown once.

Managing members from a deployed appCopy Anchor Link

Membership stays in Stardeck. An app does one of two things:

• Link to Stardeck (default). Link to Settings → Team Members or Settings → Roles & Permissions. Starcat Developer does this unless asked otherwise.
• Embed it through the server-side API. The app's server can list team members and organization roles, invite a member, and change a member's organization role. Removing members, assigning apps and creating accounts stay in Stardeck.

Stardeck checks the signed-in team member's current permissions on every call. App users and app-only team members are refused.

An app must not create logins, keep its own staff passwords, keep its own membership or roles table as the record, or change roles outside Stardeck. It can store its own data about people (shifts, locations) keyed to the person or login Stardeck provides.

Next stepsCopy Anchor Link