Talewright Docs Open the app

Members and roles

Summary

A member is an account that belongs to an organization. Every member has exactly one organization role: owner, admin or member.

  • Owners do everything, including managing other owners and deleting the organization.
  • Admins manage the organization, its workspaces, members, invitations and exports, and reach every workspace.
  • Members work in the workspaces they are added to.

A member can also hold a role in a single workspace. That is how a plain member reaches a workspace at all, and it can give them more rights in that one workspace than they have in the organization.

This page says exactly what each role can do, how roles change, how members are removed, the rule that an organization always keeps an owner, and what happens to a removed member's sessions, credentials, connected apps and files.

Who can do what

"Session" means a person signed in with a browser. "Credential" means an API key or a connected app acting for a member. A credential never has more rights than its member has at the moment of the request.

In the organization

ActionOwnerAdminMemberCredential (scope)
Read the organization and its IDYesYesYesYes (workspace:read)
List the organization's membersYesYesYesYes (workspace:read)
Rename the organizationYesYesNoNo
Create a workspaceYesYesNoNo
Delete a workspace (verified email)YesYesNoNo
List and restore deleted workspacesYesYesNoNo
Reach every workspaceYesYesNoWithin the credential's workspaces
Change a member's role to admin or memberYesYes, unless the member is an ownerNoNo
Make a member an ownerYesNoNoNo
Change an owner's roleYesNoNoNo
Remove an admin or memberYesYesNoNo
Remove an ownerYesNoNoNo
Invite an admin or memberYesYesNoNo
Invite an ownerYesNoNoNo
List and revoke pending invitationsYesYesNoNo
Start and download an exportYesYesNoNo
See and revoke every member's API keys and connected appsYesYesNoNo
Change the organization folderYesYesNoWith files:write, as an owner's or admin's credential
Manage the organization folder's statuses, fields and choicesYesYesNoNo
Rename and delete the organization folder's tagsYesYesNoWith files:write, as an owner's or admin's credential
Read the organization folderYesYesYesYes (files:read)
Leave the organizationYes, unless the only ownerYesYesNo
Delete the organization (verified email)YesNoNoNo
Restore a deleted organizationYesNoNoNo

In a workspace

The role that counts in a workspace is the effective role: the stronger of the member's organization role (if it is owner or admin) and their role in that workspace.

ActionWorkspace ownerWorkspace adminWorkspace memberCredential (scope)
Open the workspace and read its filesYesYesYesYes (files:read)
Upload, edit, organize, trash and restore filesYesYesYesYes (files:write)
Manage the workspace's statuses, fields and choicesYesYesNoNo
Rename and delete the workspace's tagsYesYesNoYes (files:write)
Set the status of a fileYesYesNoYes, with files:approve and a verified email
Share files and folders publiclyYesYesNoNo
Delete files for goodYesYesNoNo
List the workspace's membersYesYesYesYes (workspace:read)
Rename the workspaceYesYesNoNo
Add an organization member to the workspace, as admin or memberYesYesNoNo
Give or take away the workspace role ownerYesNoNoNo
Remove a workspace membershipYesYes, unless it is an owner'sNoNo
Delete or restore the workspaceOnly as organization owner or adminOnly as organization owner or adminNoNo

File rules are described in full under Files & Assets and Roles and permissions. This page states only which role is asked.

How it works

Organization roles

  • The roles are owner, admin and member. In the app they read "Owner", "Admin" and "Member".
  • These three are the only roles. There are no custom roles, no guests and no read-only role.
  • Every member has exactly one organization role.
  • An organization has at least one owner. It can have any number of owners, admins and members.
  • Owners and admins reach every workspace of the organization without being added to it.
  • Members reach only the workspaces they have been added to. A member added to no workspace belongs to the organization but can open no workspace yet. They still read the organization's member list and its organization folder, and they can leave. The API serves the organization folder to them. The app opens the organization folder from inside a workspace.
  • The app describes the roles like this:
    • Owner: "Everything an admin can do, plus managing owners and deleting the organization."
    • Admin: "Manages members, invitations, workspaces and exports, and reaches every workspace."
    • Member: "Works in the workspaces they are added to."
  • The difference between owner and admin is exactly this: only owners make someone an owner, change an owner's role, remove an owner, invite an owner, delete the organization and restore it.
  • Roles are checked on every request. A change of role takes effect at once, also for pages that are already open and for credentials.

Workspace roles

  • A workspace membership adds one organization member to one workspace with a role: owner, admin or member.
  • Only someone who is already a member of the organization can be added to one of its workspaces.
  • A member's effective role in a workspace is the stronger of two: their organization role when it is owner or admin, and their workspace role. Owner is stronger than admin, and admin is stronger than member.
  • An organization owner is therefore owner in every workspace, and an organization admin is at least admin in every workspace.
  • A plain member with the workspace role admin manages that one workspace: they rename it, manage its members, manage its statuses, fields and tags, set file statuses, share publicly and delete files for good there. They cannot manage the organization folder's statuses, fields or tags. They still cannot create, delete or restore workspaces, invite people or manage the organization.
  • A plain member with the workspace role owner can do the same, and can also give and take away the workspace role owner in that workspace.
  • The workspace member list shows everyone who can open the workspace, with the effective role and where the access comes from:
    • source workspace - a workspace membership. It can be removed.
    • source organization - access through the organization role owner or admin, with no workspace membership. It cannot be removed here.
  • Adding, changing and removing workspace memberships is described step by step in Workspaces.

The member list

  • Every member can read the organization's member list.
  • Each entry holds the member's name, email address, organization role and the date they joined.
  • The list is always the full list. A plain member sees every other member's name and email address, also of people in workspaces they cannot open. This is kept on purpose: an organization is one team that can reach each other.
  • Every member also reads the organization folder, whatever workspaces they are in.
  • For an organization that holds several clients, one workspace each, this means: people of one client see the names and email addresses of the people of every other client, and the files of the organization folder. Workspaces keep files apart. They do not keep people from seeing each other. Clients that must not see each other belong in separate organizations.
  • The list is in the order members joined, oldest first.
  • The list cannot be searched and cannot be sorted another way.
  • The list does not show when a member was last active.
  • A member is in the organization or not. There is no suspended state. To stop someone for a while, remove their workspace memberships, so that a plain member can open no workspace, or remove them and invite them again later.
  • The list is paged: 50 entries by default, at most 100 a page.
  • Pending invitations are not in the member list. Owners and admins see them in their own list. See Invitations.
  • Someone who is not a member cannot read the list. They get 404 NOT_FOUND.

Changing roles

  • Owners and admins change roles. Members cannot change anyone's role.
  • An admin sets the roles admin and member, for admins and members.
  • Only an owner makes someone an owner, and only an owner changes the role of an owner.
  • You can change your own role under the same rules. An admin can make themselves a member. An owner can step down when another owner remains.
  • Setting the role a member already has succeeds and changes nothing, for someone who may change that member's role. No email is sent.
  • The only owner cannot be made admin or member. That answers 409 SOLE_OWNER.
  • When a member becomes an owner, they get the email "You are now an owner of {organization}". It cannot be turned off. No other role change sends an email.
  • When a member's role is lowered, the pending invitations they sent that their new role could not send are deleted, and their links stop working:
    • An owner made admin loses the owner invitations they sent. Their admin and member invitations stay.
    • An owner or admin made member loses every invitation they sent.
  • A role change does not revoke the member's API keys or connected apps. Each request made with them is checked against the member's role at that moment.
  • A role change does not add or remove workspace memberships.
    • A member made admin reaches every workspace from then on.
    • An admin made member keeps only the workspaces they were added to. If they were added to none, they can open no workspace.
  • A role change does not sign anyone out.

The checks happen in this order. The first that fails decides the answer:

  1. Not signed in: 401 UNAUTHENTICATED.
  2. The organization is unknown, deleted or not yours: 404 NOT_FOUND.
  3. The request does not name a valid role: 422 VALIDATION_FAILED.
  4. You are a plain member: 403 FORBIDDEN.
  5. The person is not a member of the organization: 404 NOT_FOUND.
  6. The request names the role owner, or the person is an owner, and you are not an owner: 403 FORBIDDEN.
  7. The person already has the role: 200, nothing changes.
  8. The person is the only owner: 409 SOLE_OWNER.
  9. Otherwise the role changes: 200 with the member and the new role.

Removing members

  • Owners and admins remove members.
  • An admin removes admins and members. Only an owner removes an owner.
  • The only owner cannot be removed: 409 SOLE_OWNER.
  • Removal takes effect at once. The removed person is not asked and gets no email.
  • A plain member cannot remove anyone, themselves included. To go, they leave.
  • An admin or owner who removes themselves gets the same result as leaving.

The checks happen in this order:

  1. Not signed in: 401 UNAUTHENTICATED.
  2. The organization is unknown, deleted or not yours: 404 NOT_FOUND.
  3. You are a plain member: 403 FORBIDDEN.
  4. The person is not a member of the organization: 404 NOT_FOUND.
  5. The person is an owner and you are not: 403 FORBIDDEN.
  6. The person is the only owner: 409 SOLE_OWNER.
  7. Otherwise they are removed: 204.

What removal does

All of this happens together, at the moment of removal. It is the same when a member leaves by themselves.

  • Membership. Their organization membership is deleted.
  • Workspaces. Every workspace membership they had in the organization is deleted.
  • Credentials. Every API key they hold for this organization is revoked. A request with one answers 401 UNAUTHENTICATED from then on.
  • Connected apps. Every connected app they authorized for this organization is revoked the same way. Its tokens stop working.
  • Invitations they sent. Their pending invitations for this organization are deleted. Those links stop working. Invitations sent by other people stay.
  • Sessions. Nothing happens to their sessions. They stay signed in.
  • Other organizations. Nothing happens to their memberships, credentials or files in other organizations.
  • Files. Files and versions they uploaded stay where they are. The history still shows their name.
  • Public links. Public links to files they uploaded or made public stay as they are. Removing a member stops no public link.
  • Their account. The account is untouched. They can still sign in, create an organization and accept invitations.

A removed person comes back only through a new invitation. The invitation decides their role and workspaces afresh. Revoked credentials do not come back; they create new ones.

What the removed person sees

  • If they have a workspace of the organization open, their next action there is refused. The app says "You no longer have access to {workspace}" and takes them home.
  • Home opens another workspace they can still reach.
  • With no organization left, home is "Set up your organization".
  • With organizations left but no workspace they can open, home is "No workspace yet".
  • The organization leaves their workspace switcher and their organization list.
  • Its settings pages show "Not found".

The last-owner rule

  • A live organization always has at least one owner.
  • Four actions could take the last owner away, and each is refused with 409 SOLE_OWNER:
    • changing the only owner's role to admin or member,
    • removing the only owner,
    • the only owner leaving,
    • the only owner deleting their account. See Deleting an account.
  • The error names the organization in details.organizationIDs. Account deletion lists every organization the account alone owns.
  • The way out is always the same: make another member an owner first, or delete the organization.
  • The rule holds when two owners act at the same moment. The two changes are handled one after the other, so one of them finds the other already done and is refused.
  • The rule protects live organizations only. See the edge case about a deleted organization below.

Account deletion and membership

  • When a member deletes their account, they leave every organization they belong to, with everything listed under "What removal does".
  • Files they uploaded stay. Their name in the history becomes "Deleted user".
  • Account deletion is refused while the account is the only owner of a live organization.

In the app

The Members page

Settings > Organization > Members has the section "Members", with the line "Owners and admins reach every workspace; members reach the workspaces they are added to."

  • The table has the columns "Name", with the member's name and email address, and "Role".
  • Your own row carries the label "You".
  • "Load more" shows further members when there are more than one page.
  • Owners and admins see a menu button on the rows they may manage. Its name is "Manage {name}".
  • An admin sees no menu on an owner's row.
  • A member sees no menus at all, and no "Invitations" section.

Changing a role

  1. Open "Manage {name}".
  2. Under "Role", choose "Owner", "Admin" or "Member". The current role is marked.
  3. Roles you cannot give are disabled. For an admin that is "Owner".

Some changes ask first:

ChangeConfirmationTextButton
Making someone an owner"Make {name} an Owner?""Owners can delete {organization} and change or remove any member, including you.""Make Owner"
Making another owner an admin"Make {name} an Admin?""{name} can no longer manage owners or delete {organization}.""Make Admin"
Making another owner a member"Make {name} a Member?""{name} can no longer manage {organization} or reach workspaces they are not added to.""Make Member"
Lowering your own role from owner to admin"Give up Owner?""You can no longer manage owners or delete {organization}. Another owner must give the role back.""Give up Owner"
Lowering your own role from owner to member"Give up Owner?""You can no longer manage {organization} or reach workspaces you are not added to. Another owner must give the role back.""Give up Owner"
Lowering your own role from admin to member"Give up Admin?""You can no longer manage {organization} or reach workspaces you are not added to. An owner or admin must give the role back.""Give up Admin"
  • Changing someone else between "Admin" and "Member" happens at once, without a confirmation.
  • After the change the app shows "{name} is now an Admin" (or "a Member", "an Owner"), or "You are now an Admin" for your own role.
  • For the only owner, the other roles on their own row are disabled, with the hint "Make another member an owner first."

Removing a member

  1. Open "Manage {name}" and choose "Remove from organization". The entry is not offered on your own row.
  2. The confirmation "Remove {name}?" says "They lose access to {organization} and its workspaces at once. Files they uploaded stay."
  3. "Remove member" removes them. "Cancel" does nothing.
  4. The app shows "Removed {name}" and the row disappears.

Workspace members

Each workspace's settings page (its "General", under Settings > File spaces) has the section "Members", described in Workspaces.

Messages when something is refused

MessageWhen
"Your role no longer allows that. The page now shows what you can do."Your own role changed since the page loaded. The page redraws for your new role.
"{organization} needs another owner first. Make another member an owner, then try again."The action would leave the organization without an owner.
"Could not change the role. Try again."The role change failed for another reason, for example because the member was removed meanwhile.
"Could not remove the member. Try again."The removal failed for another reason, for example because someone else already removed them.
"Too many attempts. Try again {when}."A rate limit was reached.

For agents

A credential can read who is in the organization and in a workspace. It cannot change roles or remove anyone.

OperationCapability IDMCP toolScope
GET /v1/organizations/{organizationID}/membersorganizations.members.listorganizations_members_listworkspace:read
GET /v1/workspaces/{workspaceID}/membersworkspaces.members.listworkspaces_members_listworkspace:read
PATCH /v1/organizations/{organizationID}/members/{userID}organizations.members.updatenonesession only
DELETE /v1/organizations/{organizationID}/members/{userID}organizations.members.removenonesession only
PUT /v1/workspaces/{workspaceID}/members/{userID}workspaces.members.putnonesession only
DELETE /v1/workspaces/{workspaceID}/members/{userID}workspaces.members.removenonesession only

Listing members

Both list operations take limit (1 to 100, default 50) and cursor, and return the same shape:

{
  "items": [
    {
      "user": {
        "id": "01928f3e-0000-7000-8000-00000000000a",
        "email": "ada@example.com",
        "fullName": "Ada Aziz"
      },
      "role": "owner",
      "source": "organization",
      "joinedAt": "2026-10-01T09:30:00Z"
    }
  ],
  "nextCursor": null
}
  • In the organization list, role is the organization role and source is always organization. The order is the order of joining.
  • In the workspace list, role is the effective role in that workspace. source is workspace for a workspace membership and organization for an owner or admin who reaches it through their organization role.
  • In the workspace list, joinedAt is when the workspace membership was made, or when the member joined the organization if they have none.
  • A credential reads the member list of its own organization and of the workspaces it was given. Any other ID answers 404 NOT_FOUND.

A worked example

An agent wants to know who can approve a file in a workspace. $TALEWRIGHT is the address of your Talewright app.

curl -s "$TALEWRIGHT/v1/workspaces/01928f40-1111-7aaa-8bbb-000000000001/members" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"

Everyone in the answer whose role is owner or admin can set file statuses in that workspace. Over MCP the call is workspaces_members_list with {"workspaceID": "01928f40-1111-7aaa-8bbb-000000000001"}.

Session-only operations

  • PATCH .../members/{userID} takes {"role": "owner" | "admin" | "member"} and answers 200 with the member.
  • DELETE .../members/{userID} takes no body and answers 204.
  • A credential that calls either gets 403 FORBIDDEN with details.reason SESSION_REQUIRED.

Edge cases

SituationWhat happensWhy
An admin tries to make a member an owner403 FORBIDDEN. Nothing changes.Only owners grant owner.
An admin tries to make an owner an admin403 FORBIDDEN.Only owners change an owner's role.
An admin tries to remove an owner403 FORBIDDEN.Only owners remove owners.
A member tries to change a role or remove someone403 FORBIDDEN. Nothing changes.Members do not manage members.
An admin makes another admin a memberIt works.Admins manage admins and members.
An admin removes another adminIt works.Same rule.
An admin makes themselves a memberIt works, after "Give up Admin?" in the app. They cannot undo it themselves.You may change your own role under the same rules as anyone's.
The only owner makes themselves an admin409 SOLE_OWNER.The organization would have no owner.
An owner steps down after making a second ownerIt works.An owner remains.
Two owners, the only two, make each other admin at the same momentOne change succeeds. The other gets 403 FORBIDDEN, because its sender is an admin by then. One owner remains.The two changes are handled one after the other, and each rechecks the roles.
One owner leaves while the other removes them, both at once, with no third ownerOne succeeds. The other gets 409 SOLE_OWNER.Same protection.
An admin's role is lowered while they are changing someone else's roleTheir change is refused with 403 FORBIDDEN.The sender's role is read again at the moment of the change, not from when the page loaded.
The role is set to the one the member already has200. Nothing changes, no email.There is nothing to do.
An admin "sets" an owner to owner403 FORBIDDEN. Nothing changes.Admins never act on an owner, also when nothing would change.
The role in the request is not owner, admin or member422 VALIDATION_FAILED.Unknown roles are refused.
The person named is not a member of the organization404 NOT_FOUND.There is no membership to change or remove.
Two admins remove the same member; the second request arrives after the firstThe second gets 404 NOT_FOUND. The app says "Could not remove the member. Try again."The membership is already gone.
A member is made an ownerThey get the email "You are now an owner of {organization}" with a button "Open organization settings".New owners are always told.
Someone joins as owner by accepting an invitationThey get no new-owner email.That email is sent only when an existing member's role is changed to owner.
An owner who invited two owners is made an adminThe two pending owner invitations are deleted. Their member invitations stay.An invitation lasts only while its sender could still send it.
An admin who sent invitations is made a memberAll their pending invitations are deleted.Members cannot invite.
An admin is made a member and was never added to a workspaceThey stay in the organization and can open no workspace. Home shows "No workspace yet".Admin access to every workspace came from the role, not from memberships.
A member with workspace memberships is made admin, then member againThey keep the workspace memberships they had.Role changes do not touch workspace memberships.
A member's role is lowered while their API key holds files:approveThe key still exists, but setting a file status with it is refused.The key acts with the member's current role on every request.
A member is removed while they have a workspace openTheir next action is refused. They read "You no longer have access to {workspace}" and are taken home. A file they were uploading is not added.Access ends at once.
A removed member is still signed inYes. Their session works for their account and their other organizations.Removal does not end sessions.
A removed member had an API key for another organizationThat key keeps working.Only credentials for the organization they left are revoked.
A removed member is invited againThey join with the new role and workspaces. Old workspace memberships and credentials are not restored.Removal deleted them.
A removed member uploaded filesThe files stay, with their name in the history.Files belong to the workspace, not to the uploader.
A member deletes their accountThey leave every organization. Their name in file history becomes "Deleted user".The account is anonymized; the files stay.
The only owner of a deleted organization deletes their accountIt is allowed. The deleted organization then has no owner, so nobody can restore it, and it is removed for good at its deadline.The last-owner rule protects live organizations only.
A plain member calls the remove operation on themselves403 FORBIDDEN.Removing is for owners and admins. A member leaves instead.
Someone outside the organization lists its members404 NOT_FOUND.Outsiders cannot tell the organization exists.
An organization admin is also added to a workspace as memberThe workspace list shows them once, with role admin and source workspace.The stronger role wins; the membership is still recorded.
That admin is later made a plain member of the organizationThey keep that workspace, now with role member.The workspace membership was kept.
Email cannot be sent at the moment someone is made an owner503 UNAVAILABLE with details.reason EMAIL_UNAVAILABLE. The role does not change.The new owner must be told, so the change and its email succeed or fail together.
A page lists a member whose role changed in another browserThe list shows the new role after its next refresh. Any action you take meanwhile is checked against the real roles.The server decides, not the page.

Errors

CodeStatusWhenWhat to do
UNAUTHENTICATED401Not signed in, or an invalid, expired or revoked credential.Sign in or use a valid credential.
FORBIDDEN403A member manages members; an admin grants, changes or removes owner; your role was lowered meanwhile.Ask an owner.
FORBIDDEN, reason SESSION_REQUIRED403A credential calls a role change or removal.A person does this in a browser.
FORBIDDEN, reason INSUFFICIENT_SCOPE403A credential without workspace:read lists members.Use a credential with workspace:read.
NOT_FOUND404The organization or workspace is unknown, deleted or not yours; or the person is not a member.Check the IDs.
SOLE_OWNER409The change would leave a live organization without an owner. details.organizationIDs names it.Make another member an owner first, or delete the organization.
VALIDATION_FAILED422role is missing or not one of the three; an invalid limit or cursor when listing.Correct the request.
RATE_LIMITED429A credential passed its request limit.Wait for Retry-After seconds.
UNAVAILABLE, reason EMAIL_UNAVAILABLE503Making someone an owner while email cannot be sent.Try again later. Nothing changed.

See Errors for the shape of every error.

Limits

WhatValue
Organization roles per memberExactly 1
Owners per organizationAt least 1, no upper limit
Members per organizationNo limit
Workspace memberships per memberNo limit
Page size of a member list1 to 100, default 50

Questions and answers

What is the difference between an owner and an admin? Only owners make someone an owner, change or remove an owner, invite an owner, and delete or restore the organization. Everything else an owner can do, an admin can do too.

What can a member do? Open the workspaces they were added to, and read, upload, edit, organize, trash and restore files there. They can read the organization folder, see the member list and leave. They cannot manage anything.

Can an organization have more than one owner? Yes, any number. It must have at least one.

How do I transfer ownership? Make the other person an owner. Then lower your own role or leave. There is no separate transfer step.

Why can I not lower my own role? You are the only owner. Make another member an owner first.

Can an admin remove an owner? No. Only an owner removes an owner.

Can an admin remove another admin? Yes.

Can I remove myself? Admins and owners can, with the same result as leaving. Members use "Leave organization".

Is the person told when I remove them or change their role? Only when they are made an owner. Removal and other role changes send no email.

What happens to someone's files when I remove them? Nothing. The files and their history stay.

What happens to their API keys and connected apps? The ones for this organization are revoked at once. Their keys and apps for other organizations keep working.

Are they signed out? No. They stay signed in. They simply cannot open this organization any more.

Can they see the organization's files after removal? No. Access ends at once, in the app and through every credential.

Does a role change sign the member out or revoke their keys? No. Sessions and credentials stay. Every request is checked against the new role from then on.

I was made admin. Why do I now see every workspace? Owners and admins reach every workspace of the organization without being added to each one.

I was made a member and lost all workspaces. Why? As an admin you reached workspaces through your role. As a member you reach only the workspaces you were added to. An owner or admin can add you.

What is a workspace role? A role in one workspace. A plain member gets one when they are added to a workspace. It can be member, admin or owner, and it counts only there.

Can a member be an admin of just one workspace? Yes. Give them the workspace role admin. They then manage that workspace and its files, but not the organization.

Who can see the member list? Every member of the organization, with names, email addresses and roles.

Can an agent change roles or remove members? No. A credential can only read the member lists.

Where are pending invitations? Not in the member list. Owners and admins see them under "Invitations" on the Members page. See Invitations.

What does "SOLE_OWNER" mean? The action would leave an organization without an owner. Make another member an owner, then try again.