Identities - Stardeck Documentation

An identity is one person, group or customer account in your organization’s directory. The same record is used everywhere: your team edits it in the dashboard, your apps read and write it through the SDK, and a customer-facing AI agent uses it to decide whose data a conversation may read. Identities live at the organization level, alongside Data Stores. A data-store table can reference an identity, so an order, a booking or a support ticket belongs to a person rather than to a copy of their name and email. Open Identities in your Stardeck dashboard to see and manage the directory.

Who’s in the directory

Most identities are added for you:

Source	What gets added
Team members	Every member of your organization, linked to their dashboard login
People who sign in to apps	Each app user, when the app has Customer Identity turned on
Inbound messages	A person for each direct message, or a group for each group chat, on a connected channel
Your apps	Anyone an app creates, such as a walk-in customer or a new staff member
You	Anyone you create by hand in the dashboard

Customer Identity is a per-app setting under Settings → Authentication. Turn it on for customer-facing apps so that a customer who signs in to two of your apps is one person. Leave it off for staff tools that shouldn’t add their users as customers.

Identity types

Every identity is one of three types. The type decides how it nests and whether it can be linked to a channel.

Type	What it is	Nests under	Channel-linked?
Account	The root scope unit: a company or customer	Nothing (it’s a root)	No
Group	A collective subject, e.g. a LINE group chat	An account or group	Yes
Person	An individual	An account or group	Yes

Account: the top of a tier. An account never has a parent and is never linked to a channel. It holds groups and people and anchors their shared data.
Group: a collective such as a LINE group or room. A group nests under an account (or another group) and can be linked to the channel’s group or room id.
Person: an individual. A person nests under a parent (or stands alone) and can be linked to one or more channel identifiers or logins: a LINE user id, an email, a phone number and so on.

How scope works

Identities nest into tiers through memberships: an account holds groups, a group holds people. Read scope flows upward. A subject reads its own data plus every ancestor’s, and never its members’ or its siblings’. Given the tree above:

Sam reads Sam’s data, the Acme support chat’s data, and Acme Inc.’s data (the full path up to the root).
Dana reads Dana’s data and Acme Inc.’s data, but not Sam’s or the support chat’s.
Acme Inc. reads only its own data; it has no parent.

This keeps one customer’s conversation from reaching another’s data, while everyone in a company still shares what belongs to the company.

An identity’s Memberships section shows its effective read scope: the subject plus all of its ancestors, resolved into a flat list. That list is exactly what a scoped agent run can read, so check it to confirm a customer is set up correctly before you point an agent at them.

Channel links

A channel link ties an external identifier or login to a person or group, so inbound messages and sign-ins resolve to the right identity. Accounts are never channel-linked.

Link kind	Typical value
LINE	A LINE user id (person) or group id
Facebook	A Facebook page-scoped user id
Instagram	An Instagram-scoped user id
Email	An email address
Phone	A phone number
App login	A person’s sign-in to one of your deployed apps
Dashboard user	A team member’s Stardeck login

A link marked verified is proof that the identifier belongs to that person. An email or phone recorded without proof (typed in by reception, captured by a booking form) stays unverified, and the same unverified email or phone can be recorded on several people, such as a family sharing one number. App logins, dashboard logins and channel ids each belong to one identity only.

Inbound messages add identities automatically. When a message arrives on a connected channel, Stardeck finds the sender by their channel link, or creates an identity on the spot: a person for a direct message or a group for a group or room chat. For live channels you usually tidy, link and organize the identities that arrive rather than create them by hand.

Managing identities

Create an identity

Open Identities

Go to Identities in your dashboard and click New Identity.

Pick a type

Choose Account, Group, or Person.

Add details

Give it a display name and, optionally, an external reference: your own customer key, so you can match the identity to a record in another system.

Optionally set a parent

For a group or person, you can choose the account or group it belongs to. Setting a parent moves read scope, so it requires the govern permission (see Permissions).

Edit attributes

Click an identity to open it. You can rename it, set its external reference, and edit its attributes: free-form fields such as a position, a loyalty tier or a preferred language. Your apps read and write the same attributes (see Using identities from your app).

Attach a channel link

Open an identity and add a link under Channel links: pick the kind (LINE, email, phone and so on), enter the external id, and mark it verified if you’re sure it belongs to that person. This is how you connect a known customer to the channels they message you from.

Organize memberships

An identity’s Memberships control where it sits in the tier graph:

Belongs to: the parents it reads up from. Add a parent to widen its read scope; remove one to narrow it.
Members: the identities that belong to it.

Adding or removing a parent changes what an agent can read, so these actions need the govern permission.

Merge

If the same customer ends up as two identities (for example, they messaged from two channels before you linked them), merge redirects one into a surviving identity of the same type. The merged identity’s channel links and scope move onto the survivor. Merging needs the govern permission, is audited, and can’t be undone automatically.

Team members in the directory

Every member of your organization is a person in the directory, linked to their dashboard login. Their display name and email attribute follow their team account: when they change their name or email, or an admin edits their managed account, the directory updates. While someone is on your team, those two fields are read-only here, in the dashboard and to your apps. Team members change their own name and email in their Stardeck account; an admin edits an organization-managed account from Settings → Members. Their other attributes stay editable. Once someone leaves the organization, their name and email are editable again. When you create an account for someone who is already in the directory, such as a customer who joins your staff, pick them in the Person column of Create accounts so the new login joins their existing profile instead of creating a second person. Your apps don’t see people who are only team members: they’re left out of the SDK’s list and search. Someone who is both a team member and an app user is included.

Connecting customers to their profile

Reception often creates a customer’s profile before the customer has an account: a walk-in, a phone booking, an imported list. When that customer later signs in to one of your apps, a profile connection joins their login to the profile that already holds their history. Stardeck hosts the whole flow. Your app asks for a link, and the customer confirms on a Stardeck page.

Email or phone invitation: the app sends a link to an email or phone already recorded on the profile. The customer proves they own it, then connects.
Profile invite link: for a profile with no email or phone on record, such as a new staff member known only by name. The app shows the link in person, as a QR code or a printed slip. Nothing is verified: whoever opens the link and signs in gets that profile, so never send one to an address you’re not sure of.

Profile invite links are on by default. To turn them off for an app, go to Settings → Authentication and switch off Profile Invite Links. Links already handed out stop working at once. Stardeck refuses a connection when another login already owns the profile or has already proved the contact. Your app never merges profiles itself.

Permissions

Identity management is controlled by organization permissions (see Members & Roles):

Permission	Grants
`identities:manage`	View the directory, create and edit identities, and attach channel links
`identities:govern`	Actions that move read scope: add or remove memberships, merge, and archive
`identities:impersonate`	Preview sandbox apps as a specific person from the directory

The manage/govern split exists because anything that changes an identity’s place in the tier graph changes what an agent can read. A teammate with only identities:manage can keep the directory tidy, but can’t widen or narrow a customer’s read scope.

Using identities with AI agents

Customer-facing agents that read data scoped to an identity are in early access. To try them, email support@stardeck.ai.

On the AI Agents page, each conversation carries the identity it’s about. Because inbound messages add and link identities automatically, most conversations already have the right one. To correct one (an agent mis-identified a sender, or an older thread predates linking), open the conversation and change the Identity selector in its header. The agent’s data reads for that thread follow the new identity from its next reply. Changing it requires identities:manage. The View person button opens the identity’s details without leaving the conversation.

Using identities from your app

Apps read and write the directory through integrations.identities in the integrations-sdk package. The package’s SKILL.md has the full API, including profile connections; this section covers attributes.

Profile attributes

Attributes live on the identity’s profile object. Set them when you create the identity:

const person = await integrations.identities.create({
  type: "person",
  displayName: "Somchai",
  profile: { position: "Head chef", branch: "Silom" },
});

update replaces the whole profile. It doesn’t merge. Read the identity, change what you need, and write the full object back:

const { identity } = await integrations.identities.get(person.id);
await integrations.identities.update(person.id, {
  profile: { ...identity.profile, position: "Sous chef" },
});

For a current team member, an update that changes the display name or the email attribute is refused (see Team members in the directory). Writing the existing values back unchanged is fine, and a profile that leaves out email keeps the team member’s current email.

Finding people by attribute

Pass attributes to search:

const page = await integrations.identities.search({
  attributes: { position: "Head chef" },
});

Matching is exact, and every key must match.
Values are compared with their JSON type: "5" doesn’t match 5.
Values must be a string (up to 500 characters), number or boolean. Objects, arrays and null are rejected.
You can filter on up to 10 keys, each 1–100 characters.
attributes combines with query, which matches the display name or the external id of any link (an email, phone or channel id).
Pagination works the same way with or without attributes: pass nextCursor back as cursor. limit is 1–100 and defaults to 50.

Keeping internal data private

Scope decides which customer an agent can read. It doesn’t decide what about that customer the agent may show. A support record often holds both: the order and its status are fine to share with the customer; the margin, your private notes and a churn flag are not. Stardeck draws this line on the data store, not in your app’s code. A scoped agent reads the store directly, so any filtering you write in your app never runs for it. A customer-facing agent (one replying to the customer) sees only the data you’ve marked client-facing; a staff agent (one of your own team’s agents, scoped to a customer to help them) sees the whole record. You separate the two in one of two ways.

A staff-only store

Keep internal data in its own data store and turn on Staff-only store in the store’s General settings. A customer-facing assistant can never be granted a staff-only store, so it can’t read anything in it; your staff agents still can. Point both stores at the same customer (the same identity), and a staff agent reads across both while a customer-facing agent reads only the client-facing store. Use this when your internal data already lives in its own tables: private notes, risk scores, financial detail.

Column and row visibility on a shared store

When client and internal data share a table (the same record has a public status and a private note), tag the sensitivity instead of splitting the table. In the store’s General settings, turn on Enforce client/internal visibility, then:

Column tiers: mark each column Client or Internal. A customer-facing agent reads only the Client columns; Internal ones are hidden, and can’t be searched or sorted on either.
Row visibility: for each table, pick the column that decides whether a row is visible to the customer (for example, a “visible to client” checkbox your app already sets). A customer-facing agent reads only the rows where it’s on. A table left Not configured stays hidden from customer-facing agents entirely.
Default tier: un-tagged columns fall back to the store default. Leave it Internal so a new column stays private until you deliberately mark it Client.

Staff agents are never filtered: they read every column and row for the customer they’re scoped to. Only customer-facing agents get the trimmed view, so one shared table can serve both. The customer sees their slice; your team sees the whole record.

Don’t rely on hiding fields in your app code to keep them from a customer-facing agent. The agent reads the data store directly and never runs that code. Mark the data Internal (or move it to a staff-only store) so the platform enforces it.

Next steps

Data Stores: reference identities from your tables so agents and apps read per-customer data.
Inviting people: add team members and app users, who appear in the directory.
Members & Roles: grant your team the identity permissions.
LINE: connect a channel whose inbound messages add and link identities.

​Who’s in the directory

​Identity types

​How scope works

​Channel links

​Managing identities

​Create an identity

​Edit attributes

​Attach a channel link

​Organize memberships

​Merge

​Archive

​Team members in the directory

​Connecting customers to their profile

​Permissions

​Using identities with AI agents

​Using identities from your app

​Profile attributes

​Finding people by attribute

​Keeping internal data private

​A staff-only store

​Column and row visibility on a shared store

​Next steps

Who’s in the directory

Identity types

How scope works

Channel links

Managing identities

Create an identity

Edit attributes

Attach a channel link

Organize memberships

Merge

Archive

Team members in the directory

Connecting customers to their profile

Permissions

Using identities with AI agents

Using identities from your app

Profile attributes

Finding people by attribute

Keeping internal data private

A staff-only store

Column and row visibility on a shared store

Next steps