Core concepts

Workspace, team & roles

Who can do what, how to get your colleagues in, and the settings that live at workspace level.

The workspace

Signing up creates a user; naming a workspace creates an organisation and makes you its owner. There is exactly one owner, and it is the account that created the workspace.

Renaming is safe — the slug in your tracking tag URL does not change:

curl -X PATCH https://app.stitchwork.io/api/v1/organizations/me \
  -H "Content-Type: application/json" -b cookies.txt \
  -d '{"name":"Maison Aurelia Ltd"}'

Names are 2–80 characters. Owner or workspace admin only.

Roles and permissions

There are two independent role systems, and both matter. Workspace roles say how much of the business you can change. Channel roles say which stores you work in.

Workspace roles

Channel roles

A workspace member reaches real work through channels. Owners and workspace admins can do anything on any channel regardless of these.

A shop-floor salesperson is typically workspace member + channel associate. That is enough to sign in, look up customers, build quotes and send them — without being able to touch prices or the catalogue.

Inviting people

Team → Invite, or the API. You supply an email, a workspace role, and optionally a channel plus a channel role to grant at the same time.

curl -X POST https://app.stitchwork.io/api/v1/team/invitations \
  -H "Content-Type: application/json" -b cookies.txt \
  -d '{
    "email": "sam@example.com",
    "org_role": "member",
    "channel_id": 3,
    "channel_role": "associate"
  }'

Three things can happen, and the response tells you which:

Invitations expire, are single-use, and are stored as a hash — the raw token only ever exists in the email. Pending invites can be resent (which mints a fresh token) or revoked. At most one outstanding invite per email per workspace.

Accepting an invite

The invitee opens /invite?token=…. If they already have an account, the token is enough — possession of it proves control of the mailbox, so their password is never touched. If they don't, they set a name and password on the accept form.

Either way they end up signed in, with the workspace membership and any channel grant the invite carried. An expired or already-used token returns 410 Gone.

Managing the roster

# who's here
curl https://app.stitchwork.io/api/v1/team/members -b cookies.txt

# promote someone to workspace admin
curl -X PATCH https://app.stitchwork.io/api/v1/team/members/42 \
  -H "Content-Type: application/json" -b cookies.txt \
  -d '{"role":"admin"}'

# remove them from the workspace
curl -X DELETE https://app.stitchwork.io/api/v1/team/members/42 -b cookies.txt

Reading the roster is open to any member — colleagues seeing each other is fine. Every write requires owner or admin. You cannot remove yourself.

Channel staff

The per-channel roster lives on the channel detail page, and its API mirrors the team one. Adding someone by email who has no account issues them a workspace invitation carrying the channel grant, so a store manager can staff their own shop without going through the workspace admin first.

curl -X POST https://app.stitchwork.io/api/v1/channels/3/users \
  -H "Content-Type: application/json" -b cookies.txt \
  -d '{"email":"sam@example.com","role":"associate"}'

Your own account

# profile
curl -X PATCH https://app.stitchwork.io/api/v1/users/me \
  -H "Content-Type: application/json" -b cookies.txt \
  -d '{"name":"Ada Lovelace","email":"ada@example.com"}'

# password (min 8 characters; rotates the session id on success)
curl -X POST https://app.stitchwork.io/api/v1/users/me/password \
  -H "Content-Type: application/json" -b cookies.txt \
  -d '{"current_password":"…","new_password":"…"}'

Forgotten passwords

POST /api/v1/auth/forgot-password always returns the same 200 whether or not the email exists, so the endpoint can't be used to probe for accounts. Reset tokens are stored hashed, expire in 60 minutes, and are single-use. Completing a reset signs you straight in.

Sessions

The app authenticates with a plain session cookie: HttpOnly, SameSite=Lax, 14-day lifetime, and Secure whenever the request arrives over HTTPS — including behind Cloudflare, CloudFront or an ALB, where the forwarded-proto header is trusted. The session id is regenerated on sign-in and on password change.

Workspace settings reference

Everything on the Settings page, and the endpoint behind it.