Teams & roles

A workspace can be shared. You bring colleagues into the same backend — same data, same products — each joining with a role that sets exactly what they can do. Inviting happens on the concierge at https://hdls.ai/api/mcp with one tool, invite_teammate, and it is deliberately human-confirmed: an assistant can propose a share, but a real person has to approve it before anyone is let in.

💬 Just ask

  • "Invite jane@acme.com to my workspace as a member."
  • "Add my colleague as an admin so they can install products too."

You don't call these tools yourself — just tell your assistant; the technical reference below is for when you want the details.

At a glance

You want to…ToolWho can use it
Propose inviting a teammateinvite_teammateadmin / owner
Approve the inviteopen the confirm link at /share/confirm, signed inadmin / owner of that workspace

Why a human in the loop? Your assistant operates with a powerful credential. If invite_teammate sent invitations directly, a misused assistant could quietly grant a stranger access to your data. So it doesn't send anything — it hands back a one-time confirm link that an owner or admin must open and approve while signed in. No one joins your workspace without a human approving it.

Inviting is a two-step, human-confirmed flow

Step 1 — your assistant proposes the share (admin/owner only)

// tool: invite_teammate   (on https://hdls.ai/api/mcp)
{
  "email": "jane@acme.com",
  "role": "member"
}
  • role is optional and defaults to member. Valid values: reader, member, admin. An invite cannot grant owner — ownership is conferred separately.
  • Nothing is sent yet. The response makes that explicit and returns a confirm link:
{
  "proposed": true,
  "requires_confirmation": true,
  "email": "jane@acme.com",
  "role": "member",
  "confirm_url": "https://hdls.ai/share/confirm?token=…",
  "expires_at": "2026-06-09T12:00:00.000Z",
  "note": "Share PROPOSED — not yet sent. An owner/admin must confirm it…"
}

If the email already belongs to a member of this workspace, the proposal is refused up front — no duplicate invite is created.

Step 2 — a human confirms at https://hdls.ai/share/confirm

  1. Open the confirm_url in a browser and sign in.
  2. You'll see exactly who is being invited, to which workspace, and at what role. Proposing an admin shows an extra warning, because admins can reshape product schemas and invite others.
  3. Click Confirm & send invite (or cancel to drop it). Only on confirm is the invitation actually created and the email sent.

The invitee then receives a branded email with a one-time sign-in link. They join the moment they sign in with that email address — no password, no extra step.

  • Single-use. Once confirmed, the link can't be reused — the proposal is atomically claimed.
  • Time-limited. The link expires (about 24 hours; the exact expires_at is in the proposal response). After that, ask your assistant to propose the invite again.
  • Owner/admin only — verified at confirm time. Even if someone else opens the link, confirmation is rejected unless the signed-in person is an admin or owner of that workspace. The token alone isn't enough; the confirmer's identity is re-checked.
  • Already a member. If the email already belongs to a member, the proposal is refused before any link is handed out.

The role model

Every member holds exactly one role. Roles are ranked, lowest to highest, and each level includes everything below it:

reader  <  member  <  admin  <  owner

Think of them as four concentric circles of capability:

  • reader — look, don't touch. Read records and the shared workspace profile, search and read skills. A reader cannot even save a personal bio or preference.
  • member — do the day-to-day work. Everything a reader can, plus create, update, and delete records, relate records with links, and manage their own personal memory (bio + preferences).
  • admin — run the workspace. Everything a member can, plus reshape product schemas (add/drop tables and columns — DDL), install products, edit the shared workspace profile, link a bring-your-own database, promote a custom field to the whole team, and invite teammates. One notch below owner.
  • owner — full control. Everything an admin can, plus owner-only actions like uninstalling a product and managing keys/billing for the workspace.

Capability table

Capabilityreadermemberadminowner
Read records & the shared workspace profile✅✅✅✅
Search & read skills✅✅✅✅
Manage your own bio & preferences—✅✅✅
Create / update / delete records—✅✅✅
Create & traverse links between records—✅✅✅
Edit the shared workspace profile (set_workspace)——✅✅
Change product schemas (add/drop tables & columns)——✅✅
Install products & invite teammates——✅✅
Link a bring-your-own database——✅✅
Promote a custom field to the team——✅✅
Uninstall a product———✅
Manage API keys & billing———✅

Reader caveat. Readers can read the shared workspace profile, but they cannot save a personal bio or preferences — those start at member.

One credential = one role in one workspace. A person's capabilities come from the role on their credential for this workspace. To act in a different workspace, they connect with that workspace's credential. Role governs capability; isolation (which workspace's rows you can see) is enforced separately by the database.

A natural first session for a team lead

  1. Set the shared context so the whole team's assistant works the same way — see Workspace memory: set_workspace({ … }) (admin+).
  2. Bring in a colleague and approve it yourself: invite_teammate({ email: "jane@acme.com", role: "member" }), then open the returned confirm_url and click Confirm & send invite.
  3. They get a passwordless sign-in email and join the moment they sign in.

From there, the actual record work — accounts, deals, contacts, tickets — happens on each product's own endpoint (e.g. https://hdls.ai/api/mcp/crm), where that product's named tools live. The concierge is where you grow the team and set how it works.

Where to go next