Members & Roles
Managing team members, invites, and roles within your Cosmo organization.
Manage who has access to your organization and what they can do. Cosmo supports role-based access control (RBAC) at the organization level, powered by Clerk's B2B Organizations.
Creating an Organization
After signing up, you'll be prompted to create your first organization. This is required before you can start using Cosmo. Enter a name for your team workspace and you're in — zero to value in under 5 minutes.
If you're invited by a teammate, you'll automatically join their organization after accepting the invite.
Switching Organizations
If you belong to multiple organizations, use the Organization Switcher at the bottom of the sidebar to switch between them. Your chat sessions and workspaces are scoped to each organization, so switching orgs will load that org's data.
Roles
Cosmo uses Clerk's built-in organization roles. On the free plan, two roles are available:
| Role | Clerk Role | Description |
|---|---|---|
| Owner | org:admin | Full access. Can manage billing, invite/remove members, manage integrations, and configure org settings. The org creator automatically gets this role. |
| Member | org:member | Can create workspaces, use chat, and access shared artifacts. Default role for invited members. |
The database schema also supports Admin and Viewer roles for future use when Clerk custom roles are enabled.
Inviting Teammates
Owners and Admins can invite new members:
- Click Settings in the sidebar
- Navigate to the Members tab
- Enter the teammate's email address and select a role
- Click Invite
The invited person will receive an email with a link to join your organization. Pending invitations can be viewed, resent, and revoked from the same settings panel.
Duplicate invites
Some addresses cannot be invited. When that happens the form says so straight away, in a message that appears under the invite field rather than at the top of the page — it is feedback about the address you just submitted. The message names that address, so you can see exactly which one was refused.
| Message | What it means | What you can do |
|---|---|---|
| "Already a member of this organisation" | The address already belongs to someone in the org. | Nothing — find them in the Members list above. |
| "An invite is already pending for this address — resend it instead?" | An unexpired invite is already outstanding. | Use the Resend invite action on the message. It sends a fresh email for the invite that already exists, rather than creating a second one. |
| "This email address is already associated with another organization. Users can only belong to one organization at a time, so you cannot send an invitation to this email address." | The address belongs to someone who is already in a different organization. | Nothing from here. A person can only be in one organization at a time, so they cannot accept. They have to leave the other organization first — if they own it, by deleting it under Settings → Delete organization; otherwise an admin there has to remove them. |
The address is cleared from the field. Sending the same one again would be refused in exactly the same way, so the form empties it rather than leaving a value that cannot work. The message keeps naming it, so nothing is lost.
The message goes away on its own. The two messages you cannot act on disappear after a few seconds, and you can close either sooner with the × on the right. The pending-invite message stays until you dismiss it, because it carries the Resend invite button and a control that vanishes while you are reaching for it is worse than one you close yourself. Typing a different address also clears whichever message is showing.
What the invited person sees
Following the link opens an account-creation form that is bound to the invitation itself:
- Email is filled in from the invitation and cannot be edited — the account is created for the address you invited, so there is no way to end up with an account that belongs to no organization.
- First name and last name are collected here and saved to their profile.
- Create Password sets their password for the first time.
If the invited address already has a Cosmo account, the page says so and sends them to sign in instead.
Managing Members
From the organization settings modal:
- Change a member's role — Click on their current role to update it (Owner only)
- Remove a member — Owners and Admins can remove members from the organization
API Access (CLI)
The server exposes org management endpoints for CLI and programmatic access:
| Method | Endpoint | Auth Required | Description |
|---|---|---|---|
GET | /org/members | Any member | List all org members |
POST | /org/invite | Owner / Admin | Invite by email. 409 when the address cannot be invited — the body carries code, one of "ALREADY_MEMBER", "INVITE_PENDING" (plus inviteId, the invite to resend) or "IN_ANOTHER_ORG", alongside the email and a human-readable message. Branch on code, never on the message text |
GET | /org/invites | Owner / Admin | List pending invites |
POST | /org/invite/:id/resend | Owner / Admin | Resend a pending invite |
DELETE | /org/invite/:id | Owner / Admin | Revoke a pending invite |
PATCH | /org/members/:userId/role | Owner | Update a member's role |
DELETE | /org/members/:userId | Owner / Admin | Remove a member |
All endpoints require a valid Bearer token (Cosmo JWT or Clerk session token) and are scoped to the authenticated user's active organization.