# Roles and permissions

## Summary

This page is the complete permission matrix of Talewright: every action the
product has, who may do it by role, and whether a credential (an API key or a
connected app) may do it and with which scope. It has one row for each of the
172 operations of the API, named by its capability ID.

Two things decide every request:

1. **The person's role.** `owner`, `admin` or `member`.
2. **How the request proves who it is.** A browser session, or a credential
   with scopes that acts for one member.

A credential never has more rights than its member. It has its member's
current role, cut down to the workspaces and scopes the credential was given.

## How it works

### Roles

- There are three roles: `owner`, `admin` and `member`. An owner can do
  everything an admin can, and an admin everything a member can.
- A person has a role in each organization they belong to.
- A person can also have an explicit role in a single workspace.
- Owners and admins of an organization reach every workspace in it.
- A member of an organization reaches only the workspaces they were added to.
- When a person has an organization role and a workspace role, the stronger
  one counts in that workspace. This is the effective role.
- For actions on an organization, the columns below mean the organization
  role. For actions in a workspace, they mean the effective role in that
  workspace.
- Someone who cannot reach an organization or a workspace gets `404 NOT_FOUND`
  for everything in it, not `403`.
- The workspace selected in the web app is only where you are looking. It
  grants nothing.

### Workspace files and organization folder files

- Every organization has one organization folder (the API's library), shared
  by all its workspaces.
- In a workspace, every member reads and changes files: upload, edit,
  organize, trash.
- In the organization folder, every member of the organization reads. Only
  owners and admins change it.
- In both, only owners and admins set statuses, change general access (public
  or restricted) and delete for good.
- Each workspace and the organization folder have their own statuses, fields
  and tags. A file carries only those of its own workspace or organization
  folder. Managing them (statuses, fields and choices, and renaming and
  deleting tags) needs an owner or admin of that place: for a workspace, its
  owners and admins and the organization's; for the organization folder, the
  organization's.

### Credentials and scopes

- A credential holds one or more of four scopes: `workspace:read`,
  `files:read`, `files:write` and `files:approve`.
- `files:write` includes `files:read`. No other scope includes another.
- `files:approve` alone sets file statuses. It does not read or change
  anything else.
- A scope column says "Yes" when a credential holding only that scope may call
  the operation. The role columns still apply: the credential's member must
  have the role the row asks for.
- A credential reaches only the workspaces it lists, and the organization
  folder of its organization.
- "Browser only" means no credential can do it, whatever its scopes. A valid
  bearer token gets `403 FORBIDDEN` with reason `SESSION_REQUIRED`, or
  `HUMAN_APPROVAL_REQUIRED` for applying a proposal. The words in brackets say
  why the operation is browser only.
- A bearer token that does not authenticate gets `401 UNAUTHENTICATED` with
  reason `INVALID_TOKEN` on every browser-only operation and on every
  operation a credential may call. It is checked before anything else about
  the operation, and it counts as a failed authentication of the client
  address.
- "Anyone" means the operation needs no sign-in. Such an operation ignores
  the `Authorization` header, whatever it holds. A bearer token sent
  together with a session cookie is still refused with `401
  UNAUTHENTICATED`, reason `AMBIGUOUS_CREDENTIALS`.

### Extra conditions

- **A verified email** is needed to delete your account, an organization or a
  workspace. It is also needed to set file statuses, or to make files public
  by a move, through a credential. In a browser session those file actions
  need none.
- **Making files public by moving them** follows the rule for public access,
  not the rule for moving. It needs an owner or admin. Through a credential
  it also needs `files:approve`, in addition to `files:write`.
- **Granting `files:approve`** to a new key or connected app needs the
  effective role owner or admin in every workspace the credential lists. An
  organization owner or admin has that in every workspace. An organization
  member has it only in the workspaces where their workspace role is admin
  or owner. If one listed workspace is one where the person is a plain
  member, creating the key or allowing the app answers `403 FORBIDDEN`.
- **The owner role** is granted and removed only by owners.

## The matrix

### Signing up and signing in

No organization role applies here. Nobody needs to be signed in for these, except to sign out.

| Action | Capability | Owner | Admin | Member | `workspace:read` | `files:read` | `files:write` | `files:approve` | Notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Create an account | `account.sign_up` | Anyone | Anyone | Anyone | - | - | - | - | No sign-in needed |
| Sign in | `auth.sign_in` | Anyone | Anyone | Anyone | - | - | - | - | No sign-in needed |
| Check whether this browser is signed in | `auth.session_probe` | Anyone | Anyone | Anyone | - | - | - | - | No sign-in needed |
| Sign out | `auth.sign_out` | Yes | Yes | Yes | No | No | No | No | Browser only (credential control) |
| Verify an email address from the emailed link | `account.verify_email` | Anyone | Anyone | Anyone | - | - | - | - | No sign-in needed |
| Ask for a new verification email | `account.verification.resend` | Anyone | Anyone | Anyone | - | - | - | - | No sign-in needed |
| Ask for a password reset email | `account.password_reset.request` | Anyone | Anyone | Anyone | - | - | - | - | No sign-in needed |
| Set a new password from the emailed link | `account.password_reset.confirm` | Anyone | Anyone | Anyone | - | - | - | - | No sign-in needed |
| Confirm a new email address from the emailed link | `account.email_change.confirm` | Anyone | Anyone | Anyone | - | - | - | - | No sign-in needed |
| See what an invitation link offers | `invitations.preview` | Anyone | Anyone | Anyone | - | - | - | - | No sign-in needed |

### Your own account

Every signed-in person does these for their own account, whatever their roles.

| Action | Capability | Owner | Admin | Member | `workspace:read` | `files:read` | `files:write` | `files:approve` | Notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Read your account and the workspaces you reach | `auth.me` | Yes | Yes | Yes | No | No | No | No | Browser only (credential control) |
| Change your name | `account.update` | Yes | Yes | Yes | No | No | No | No | Browser only (credential control) |
| Change your password | `account.password.change` | Yes | Yes | Yes | No | No | No | No | Browser only (credential control). Needs the current password. Revokes your API keys and connected apps. |
| Start an email change | `account.email.change` | Yes | Yes | Yes | No | No | No | No | Browser only (credential control). Needs the current password. |
| Cancel a pending email change | `account.email.cancel` | Yes | Yes | Yes | No | No | No | No | Browser only (credential control) |
| List your sessions | `account.sessions.list` | Yes | Yes | Yes | No | No | No | No | Browser only (credential control) |
| End one of your sessions | `account.sessions.revoke` | Yes | Yes | Yes | No | No | No | No | Browser only (credential control) |
| End all your other sessions | `account.sessions.revoke_others` | Yes | Yes | Yes | No | No | No | No | Browser only (credential control) |
| Delete your account | `account.delete` | Yes | Yes | Yes | No | No | No | No | Browser only (credential control). Needs the current password, not a verified email. Refused while you are the only owner of a live organization. |
| Send feedback to the Talewright team | `account.feedback.send` | Yes | Yes | Yes | No | No | No | No | Browser only (credential control). At most 10 reports an hour. |
| Report a crash of the web app (the app does it on its own) | `account.client_errors.report` | Yes | Yes | Yes | No | No | No | No | Browser only (credential control). At most 10 reports a minute. |

### Organizations

| Action | Capability | Owner | Admin | Member | `workspace:read` | `files:read` | `files:write` | `files:approve` | Notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Create an organization | `organizations.create` | Yes | Yes | Yes | No | No | No | No | Browser only (access control). Any signed-in person. The creator becomes its owner. |
| List your organizations | `organizations.list` | Yes | Yes | Yes | Yes | No | No | No | A credential sees only its own organization. |
| Read an organization | `organizations.get` | Yes | Yes | Yes | Yes | No | No | No | Owners also see a deleted organization while it is restorable. A credential reads only its own organization and sees only its own workspaces in it. |
| Rename the organization | `organizations.update` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Delete the organization | `organizations.delete` | Yes | No | No | No | No | No | No | Browser only (access control). Needs a verified email and the organization's name typed as confirmation. |
| Restore a deleted organization | `organizations.restore` | Yes | No | No | No | No | No | No | Browser only (access control). Within 30 days. |
| Leave the organization | `organizations.leave` | Yes | Yes | Yes | No | No | No | No | Browser only (access control). The only owner cannot leave. |
| Request an export | `organizations.exports.create` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Read an export and get its download link | `organizations.exports.get` | Yes | Yes | No | No | No | No | No | Browser only (access control) |

### Workspaces

For renaming a workspace and managing its members, the role is the effective role in that workspace.

| Action | Capability | Owner | Admin | Member | `workspace:read` | `files:read` | `files:write` | `files:approve` | Notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| List the workspaces you reach | `workspaces.list` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | A credential lists only its own workspaces that its member still reaches. |
| Create a workspace | `workspaces.create` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Rename a workspace | `workspaces.update` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Delete a workspace | `workspaces.delete` | Yes | Yes | No | No | No | No | No | Browser only (access control). Needs a verified email and the workspace's name typed as confirmation. The last live workspace cannot be deleted. |
| List deleted workspaces that can be restored | `organizations.deleted_workspaces.list` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Restore a deleted workspace | `workspaces.restore` | Yes | Yes | No | No | No | No | No | Browser only (access control). Within 30 days. |

### Members and invitations

| Action | Capability | Owner | Admin | Member | `workspace:read` | `files:read` | `files:write` | `files:approve` | Notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| List the organization's members | `organizations.members.list` | Yes | Yes | Yes | Yes | No | No | No |  |
| Change a member's organization role | `organizations.members.update` | Yes | Yes | No | No | No | No | No | Browser only (access control). Only owners grant or remove the owner role. The only owner cannot be demoted. |
| Remove a member from the organization | `organizations.members.remove` | Yes | Yes | No | No | No | No | No | Browser only (access control). Only owners remove owners. The only owner cannot be removed. To remove yourself, leave the organization. |
| List a workspace's members | `workspaces.members.list` | Yes | Yes | Yes | Yes | No | No | No |  |
| Add a member to a workspace or change their workspace role | `workspaces.members.put` | Yes | Yes | No | No | No | No | No | Browser only (access control). Only owners grant or remove the workspace owner role. |
| Remove a member from a workspace | `workspaces.members.remove` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| List pending invitations | `organizations.invitations.list` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Invite someone, or resend an invitation | `organizations.invitations.create` | Yes | Yes | No | No | No | No | No | Browser only (access control). Only owners invite owners. |
| Revoke an invitation | `organizations.invitations.revoke` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Accept an invitation | `invitations.accept` | Yes | Yes | Yes | No | No | No | No | Browser only (access control). The signed-in account's email must be the invited address. |

### Credentials and connected apps

Every row here needs a person in a browser, except reading the presented credential.

| Action | Capability | Owner | Admin | Member | `workspace:read` | `files:read` | `files:write` | `files:approve` | Notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Read the credential a request presents | `credential.read` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | For credentials only. A browser session gets `401`. |
| List your API keys | `credential.api_keys.list` | Yes | Yes | Yes | No | No | No | No | Browser only (credential control) |
| Create an API key for yourself | `credential.api_keys.create` | Yes | Yes | Yes | No | No | No | No | Browser only (credential control). Only for workspaces you reach. Adding `files:approve` needs owner or admin in every selected workspace. |
| Rotate one of your API keys | `credential.api_keys.rotate` | Yes | Yes | Yes | No | No | No | No | Browser only (credential control) |
| Revoke one of your API keys | `credential.api_keys.revoke` | Yes | Yes | Yes | No | No | No | No | Browser only (credential control) |
| List your connected apps | `credential.connected_apps.list` | Yes | Yes | Yes | No | No | No | No | Browser only (credential control) |
| Disconnect one of your connected apps | `credential.connected_apps.disconnect` | Yes | Yes | Yes | No | No | No | No | Browser only (credential control) |
| Read an app's request to connect | `credential.oauth_requests.get` | Yes | Yes | Yes | No | No | No | No | Browser only (credential control). The first account to read a request owns it; for anyone else it does not exist. |
| Allow or deny an app's request to connect | `credential.oauth_requests.decide` | Yes | Yes | Yes | No | No | No | No | Browser only (credential control). Only the account the request belongs to (the first that read it, or the decider when none did). Allowing needs a workspace you reach. Granting `files:approve` needs owner or admin in every selected workspace. |
| List every member's API keys and connected apps | `credential.organization.list` | Yes | Yes | No | No | No | No | No | Browser only (credential control). Expired ones stay listed for 30 days. |
| Revoke any member's API key or connected app | `credential.organization.revoke` | Yes | Yes | No | No | No | No | No | Browser only (credential control) |
| Read what was done with a credential | `credential.organization.activity` | Yes | Yes | Own only | No | No | No | No | Browser only (credential control). Members read the activity of their own credentials. |

### Statuses and fields of a workspace

Each workspace has its own statuses and fields. The role is the effective role in the workspace, so the workspace's owners and admins and the organization's manage them. A credential must also list the workspace.

| Action | Capability | Owner | Admin | Member | `workspace:read` | `files:read` | `files:write` | `files:approve` | Notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| List the statuses | `workspace.file_statuses.list` | Yes | Yes | Yes | No | Yes | Yes | No | The counts cover the workspace's live files and are the same for everyone who reads it. `trashedFileCount` is a number only for an owner or admin in a browser session. |
| Add a status | `workspace.file_statuses.create` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Rename a status, change whether it allows public use, or make it the default | `workspace.file_statuses.update` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Reorder the statuses | `workspace.file_statuses.reorder` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Delete a status | `workspace.file_statuses.delete` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| List the fields | `workspace.file_fields.list` | Yes | Yes | Yes | No | Yes | Yes | No | The counts cover the workspace's live files and are the same for everyone who reads it. `trashedFileCount` is a number only for an owner or admin in a browser session. |
| Add a field | `workspace.file_fields.create` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Rename a field | `workspace.file_fields.update` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Reorder the fields | `workspace.file_fields.reorder` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Delete a field | `workspace.file_fields.delete` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Add a choice to a field | `workspace.file_fields.choices.create` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Rename a choice | `workspace.file_fields.choices.update` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Reorder a field's choices | `workspace.file_fields.choices.reorder` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Delete a choice | `workspace.file_fields.choices.delete` | Yes | Yes | No | No | No | No | No | Browser only (access control) |

### Statuses and fields of the organization folder

The organization folder has its own statuses and fields. The role is the organization role: only the organization's owners and admins manage them, not a workspace admin who is a plain member of the organization.

| Action | Capability | Owner | Admin | Member | `workspace:read` | `files:read` | `files:write` | `files:approve` | Notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| List the statuses | `library.file_statuses.list` | Yes | Yes | Yes | No | Yes | Yes | No | The counts cover the organization folder's live files and are the same for everyone who reads it. `trashedFileCount` is a number only for an owner or admin in a browser session. |
| Add a status | `library.file_statuses.create` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Rename a status, change whether it allows public use, or make it the default | `library.file_statuses.update` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Reorder the statuses | `library.file_statuses.reorder` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Delete a status | `library.file_statuses.delete` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| List the fields | `library.file_fields.list` | Yes | Yes | Yes | No | Yes | Yes | No | The counts cover the organization folder's live files and are the same for everyone who reads it. `trashedFileCount` is a number only for an owner or admin in a browser session. |
| Add a field | `library.file_fields.create` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Rename a field | `library.file_fields.update` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Reorder the fields | `library.file_fields.reorder` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Delete a field | `library.file_fields.delete` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Add a choice to a field | `library.file_fields.choices.create` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Rename a choice | `library.file_fields.choices.update` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Reorder a field's choices | `library.file_fields.choices.reorder` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Delete a choice | `library.file_fields.choices.delete` | Yes | Yes | No | No | No | No | No | Browser only (access control) |

### Files in a workspace

The role is the effective role in the workspace. A credential must also list the workspace.

| Action | Capability | Owner | Admin | Member | `workspace:read` | `files:read` | `files:write` | `files:approve` | Notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| List and search files | `workspace.files.search` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| Read a file | `workspace.files.get` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| List a file's versions | `workspace.files.versions.list` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| Get a temporary URL for a version's bytes, thumbnail, preview or playback | `workspace.files.signed_url` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| Download a version's bytes through the API | `workspace.files.read` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| Download folders and files as one ZIP | `workspace.files.archive` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| Count the files by status, in the whole place or one folder and the folders below it | `workspace.files.status.count` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| Rename, move, tag or describe a file, or set its field values | `workspace.files.update` | Yes | Yes | Yes | No | No | Yes | No | A move that makes the file public needs an owner or admin, and `files:approve` through a credential. |
| Set one field on up to 100 files | `workspace.files.fields.set` | Yes | Yes | Yes | No | No | Yes | No |  |
| Set the status of up to 100 files | `workspace.files.status.set` | Yes | Yes | No | No | No | No | Yes | Through a credential the member's email must also be verified. |
| Move a file to the trash | `workspace.files.trash` | Yes | Yes | Yes | No | No | Yes | No |  |
| Restore a file from the trash | `workspace.files.restore` | Yes | Yes | Yes | No | No | Yes | No | A restore that would make a file public that was not public when it went to the trash needs an owner or admin, and `files:approve` through a credential. |
| Delete a trashed file for good | `workspace.files.purge` | Yes | Yes | No | No | No | No | No | Browser only (permanent deletion) |
| Make a file public or restricted | `workspace.files.visibility.set` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Empty the trash | `workspace.trash.empty` | Yes | Yes | No | No | No | No | No | Browser only (permanent deletion) |

### Folders and tags in a workspace

| Action | Capability | Owner | Admin | Member | `workspace:read` | `files:read` | `files:write` | `files:approve` | Notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| List folders | `workspace.folders.list` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| Create a folder | `workspace.folders.create` | Yes | Yes | Yes | No | No | Yes | No |  |
| Rename or move a folder | `workspace.folders.update` | Yes | Yes | Yes | No | No | Yes | No | A move that makes files inside public needs an owner or admin, and `files:approve` through a credential. |
| Move a folder and its content to the trash | `workspace.folders.trash` | Yes | Yes | Yes | No | No | Yes | No |  |
| Restore a folder from the trash | `workspace.folders.restore` | Yes | Yes | Yes | No | No | Yes | No | A restore that would make a file public that was not public when it went to the trash needs an owner or admin, and `files:approve` through a credential. |
| Delete a trashed folder for good | `workspace.folders.purge` | Yes | Yes | No | No | No | No | No | Browser only (permanent deletion) |
| Make a folder public or restricted | `workspace.folders.visibility.set` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| List tags | `workspace.tags.list` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| Rename a tag everywhere | `workspace.tags.rename` | Yes | Yes | No | No | No | Yes | No | Owners and admins of the workspace or the organization. Tagging a file is `workspace.files.update`. |
| Delete a tag everywhere | `workspace.tags.delete` | Yes | Yes | No | No | No | Yes | No | Owners and admins of the workspace or the organization. |

### Uploads in a workspace

An upload belongs to the person who started it. Nobody else reads, completes or cancels it.

| Action | Capability | Owner | Admin | Member | `workspace:read` | `files:read` | `files:write` | `files:approve` | Notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Start an upload of a new file or a replacement | `workspace.uploads.create` | Yes | Yes | Yes | No | No | Yes | No |  |
| Complete your upload | `workspace.uploads.complete` | Yes | Yes | Yes | No | No | Yes | No |  |
| Cancel your upload | `workspace.uploads.cancel` | Yes | Yes | Yes | No | No | Yes | No |  |
| Read your upload | `workspace.uploads.get` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| List your uploads | `workspace.uploads.list` | Yes | Yes | Yes | No | Yes | Yes | No |  |

### Library proposals (Suggestions) in a workspace

| Action | Capability | Owner | Admin | Member | `workspace:read` | `files:read` | `files:write` | `files:approve` | Notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| List proposals | `workspace.library_proposals.list` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| Read a proposal | `workspace.library_proposals.get` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| Propose changes to files | `workspace.library_proposals.create` | Yes | Yes | Yes | No | No | Yes | No |  |
| Reject items of a proposal | `workspace.library_proposals.reject` | Yes | Yes | Yes | No | No | Yes | No |  |
| Apply items of a proposal | `workspace.library_proposals.apply` | Yes | Yes | Yes | No | No | No | No | Browser only (human approval). A person in a browser only. A move that makes files public needs an owner or admin. |

### Favorites in a workspace

Favorites are private to one person. Nobody else sees or changes them, admins included.

| Action | Capability | Owner | Admin | Member | `workspace:read` | `files:read` | `files:write` | `files:approve` | Notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| List your favorites | `workspace.favorites.list` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| Add a file or folder to your favorites | `workspace.favorites.add` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| Reorder your favorites | `workspace.favorites.reorder` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| Remove a favorite | `workspace.favorites.remove` | Yes | Yes | Yes | No | Yes | Yes | No |  |

### Duplicates in a workspace

Hiding a duplicate warning is private to one person. It changes nothing for anyone else, and reading the place is enough to do it.

| Action | Capability | Owner | Admin | Member | `workspace:read` | `files:read` | `files:write` | `files:approve` | Notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| List the groups of identical files | `workspace.duplicates.list` | Yes | Yes | Yes | No | Yes | Yes | No | A group names only copies in places the caller can open. |
| Hide the duplicate warning of a file and its copies for yourself | `workspace.duplicates.hide` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| Show a hidden duplicate warning again | `workspace.duplicates.show` | Yes | Yes | Yes | No | Yes | Yes | No |  |

### Files in the organization folder

The role is the organization role. Every member reads the organization folder; only owners and admins change it. A credential always reaches the organization folder of its own organization, whatever workspaces it is limited to.

| Action | Capability | Owner | Admin | Member | `workspace:read` | `files:read` | `files:write` | `files:approve` | Notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| List and search files | `library.files.search` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| Read a file | `library.files.get` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| List a file's versions | `library.files.versions.list` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| Get a temporary URL for a version's bytes, thumbnail, preview or playback | `library.files.signed_url` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| Download a version's bytes through the API | `library.files.read` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| Download folders and files as one ZIP | `library.files.archive` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| Count the files by status, in the whole place or one folder and the folders below it | `library.files.status.count` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| Rename, move, tag or describe a file, or set its field values | `library.files.update` | Yes | Yes | No | No | No | Yes | No | A move that makes the file public also needs `files:approve` through a credential. |
| Set one field on up to 100 files | `library.files.fields.set` | Yes | Yes | No | No | No | Yes | No |  |
| Set the status of up to 100 files | `library.files.status.set` | Yes | Yes | No | No | No | No | Yes | Through a credential the member's email must also be verified. |
| Move a file to the trash | `library.files.trash` | Yes | Yes | No | No | No | Yes | No |  |
| Restore a file from the trash | `library.files.restore` | Yes | Yes | No | No | No | Yes | No | A restore that would make a file public that was not public when it went to the trash also needs `files:approve` through a credential. |
| Delete a trashed file for good | `library.files.purge` | Yes | Yes | No | No | No | No | No | Browser only (permanent deletion) |
| Make a file public or restricted | `library.files.visibility.set` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| Empty the trash | `library.trash.empty` | Yes | Yes | No | No | No | No | No | Browser only (permanent deletion) |

### Folders and tags in the organization folder

| Action | Capability | Owner | Admin | Member | `workspace:read` | `files:read` | `files:write` | `files:approve` | Notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| List folders | `library.folders.list` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| Create a folder | `library.folders.create` | Yes | Yes | No | No | No | Yes | No |  |
| Rename or move a folder | `library.folders.update` | Yes | Yes | No | No | No | Yes | No | A move that makes files inside public also needs `files:approve` through a credential. |
| Move a folder and its content to the trash | `library.folders.trash` | Yes | Yes | No | No | No | Yes | No |  |
| Restore a folder from the trash | `library.folders.restore` | Yes | Yes | No | No | No | Yes | No | A restore that would make a file public that was not public when it went to the trash also needs `files:approve` through a credential. |
| Delete a trashed folder for good | `library.folders.purge` | Yes | Yes | No | No | No | No | No | Browser only (permanent deletion) |
| Make a folder public or restricted | `library.folders.visibility.set` | Yes | Yes | No | No | No | No | No | Browser only (access control) |
| List tags | `library.tags.list` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| Rename a tag everywhere | `library.tags.rename` | Yes | Yes | No | No | No | Yes | No |  |
| Delete a tag everywhere | `library.tags.delete` | Yes | Yes | No | No | No | Yes | No |  |

### Uploads in the organization folder

| Action | Capability | Owner | Admin | Member | `workspace:read` | `files:read` | `files:write` | `files:approve` | Notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Start an upload of a new file or a replacement | `library.uploads.create` | Yes | Yes | No | No | No | Yes | No |  |
| Complete your upload | `library.uploads.complete` | Yes | Yes | No | No | No | Yes | No |  |
| Cancel your upload | `library.uploads.cancel` | Yes | Yes | No | No | No | Yes | No |  |
| Read your upload | `library.uploads.get` | Yes | Yes | Yes | No | Yes | Yes | No | Only someone who started an upload has one to read. |
| List your uploads | `library.uploads.list` | Yes | Yes | Yes | No | Yes | Yes | No | Only someone who started an upload has any. |

### Library proposals (Suggestions) in the organization folder

| Action | Capability | Owner | Admin | Member | `workspace:read` | `files:read` | `files:write` | `files:approve` | Notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| List proposals | `library.library_proposals.list` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| Read a proposal | `library.library_proposals.get` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| Propose changes to files | `library.library_proposals.create` | Yes | Yes | No | No | No | Yes | No |  |
| Reject items of a proposal | `library.library_proposals.reject` | Yes | Yes | No | No | No | Yes | No |  |
| Apply items of a proposal | `library.library_proposals.apply` | Yes | Yes | No | No | No | No | No | Browser only (human approval). A person in a browser only. |

### Favorites in the organization folder

| Action | Capability | Owner | Admin | Member | `workspace:read` | `files:read` | `files:write` | `files:approve` | Notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| List your favorites | `library.favorites.list` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| Add a file or folder to your favorites | `library.favorites.add` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| Reorder your favorites | `library.favorites.reorder` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| Remove a favorite | `library.favorites.remove` | Yes | Yes | Yes | No | Yes | Yes | No |  |

### Duplicates in the organization folder

Hiding a duplicate warning is private to one person. It changes nothing for anyone else, and reading the place is enough to do it.

| Action | Capability | Owner | Admin | Member | `workspace:read` | `files:read` | `files:write` | `files:approve` | Notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| List the groups of identical files | `library.duplicates.list` | Yes | Yes | Yes | No | Yes | Yes | No | A group names only copies in places the caller can open. |
| Hide the duplicate warning of a file and its copies for yourself | `library.duplicates.hide` | Yes | Yes | Yes | No | Yes | Yes | No |  |
| Show a hidden duplicate warning again | `library.duplicates.show` | Yes | Yes | Yes | No | Yes | Yes | No |  |

### Service endpoints

| Action | Capability | Owner | Admin | Member | `workspace:read` | `files:read` | `files:write` | `files:approve` | Notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Read the API contract | `operations.openapi` | Anyone | Anyone | Anyone | - | - | - | - | No sign-in needed |
| Check that the service is running | `operations.health` | Anyone | Anyone | Anyone | - | - | - | - | No sign-in needed |
| Check that the service is ready | `operations.ready` | Anyone | Anyone | Anyone | - | - | - | - | No sign-in needed |

## What only a person in a browser can do

No credential, whatever its scopes, can do any of these. They are the 78
operations marked "Browser only" above, in four groups:

| Group | What it covers |
| --- | --- |
| Credential control | Signing out, your account, your sessions, API keys, connected apps, consent to an app, and an organization's oversight of credentials. A credential can never create, extend or recover a credential, an account or access. |
| Access control | Creating, renaming, deleting and restoring organizations and workspaces; members, roles and invitations; managing statuses and fields; general access (public or restricted) of files and folders; exports; leaving. |
| Permanent deletion | Deleting a trashed file or folder for good, and emptying the trash. |
| Human approval | Applying a library proposal. |

## Edge cases

- **A member is demoted after creating a key with `files:approve`.** The key
  keeps the scope, but each use checks the member's current role. Setting a
  status answers `403 FORBIDDEN`.
- **A member is removed from a workspace a key lists.** The key loses that
  workspace at its next request. It answers `404 NOT_FOUND` there, exactly
  like an unknown workspace.
- **A member becomes an admin.** Their existing credentials act with the new
  role at the next request. Their scopes do not change.
- **A credential with `files:approve` and nothing else.** It lists only the
  two status tools and the discovery tools. It cannot read the files it sets
  statuses on.
- **A credential with `files:write` moves a file into a public folder.** When
  that would make the file public, the answer is `403 FORBIDDEN` with reason
  `INSUFFICIENT_SCOPE`. With `files:approve` too, and an owner or admin behind
  it, the move still needs `confirmVisibilityChange`.
- **A member moves a file into a public folder in the browser.** When that
  would make the file public, the answer is `403 FORBIDDEN` with reason
  `MAKES_FILES_PUBLIC` and nothing changes.
- **A member restores a file from the trash.** Any member of the workspace
  restores its files and folders; in the organization folder only owners and
  admins do. A file that was public when it went to the trash may come back
  public for whoever may restore it. A restore that would make a file public
  that was not public then (its folder became public meanwhile) is refused
  with `403 FORBIDDEN`: reason `MAKES_FILES_PUBLIC` for a member, reason
  `INSUFFICIENT_SCOPE` for a credential without `files:approve`.
- **An admin invites an owner.** Refused with `403 FORBIDDEN`. Only owners
  invite owners.
- **An admin removes or demotes an owner.** Refused with `403 FORBIDDEN`.
- **A member removes themselves through the member list.** Refused with
  `403 FORBIDDEN`: removing members needs an owner or admin. A member leaves
  with "Leave" (`organizations.leave`).
- **The only owner leaves, is removed or demoted.** Refused with
  `409 SOLE_OWNER`.
- **A member opens "Key management".** The page says only owners and admins
  see it, and the API answers `403 FORBIDDEN`.
- **A member reads another member's credential activity.** The answer is
  `404 NOT_FOUND`, the same as for an unknown credential.
- **Favorites through a credential.** Adding, reordering and removing
  favorites need only `files:read`, because they change nothing but the
  member's own list.
- **Duplicate warnings through a credential.** Hiding a warning and showing
  it again need only `files:read`, for the same reason. A hide made with a
  credential covers the copies that credential can open.
- **Uploads through a credential.** An upload started with a credential
  belongs to the member, who can read it in a browser session too.
- **A deleted organization.** Its owners still list and read it and can
  restore it. Everyone else gets `404`. Its credentials answer `401`.

## Questions and answers

**Can a member invite people?**
No. Inviting needs an owner or admin.

**Can a member create a workspace?**
No. Owners and admins create, rename, delete and restore workspaces.

**Can a member create an API key?**
Yes, for themselves, for the workspaces they reach. They can give it
`files:approve` only when their effective role is owner or admin in every
workspace the key lists. A member with the workspace role admin in all of
them can. A plain member of any listed workspace cannot.

**Can an admin see my API keys?**
Owners and admins see every member's keys and connected apps in the
organization: name, prefix, workspaces, scopes, dates and activity. Nobody
ever sees a key's secret again after it is created.

**Can an agent make a file public?**
No tool makes a file public directly. General access is browser only. An agent
with `files:approve`, acting for an owner or admin, can set a status, and can
confirm a move that makes files public through a public folder.

**Can an agent delete a file for good?**
No. An agent can move files to the trash. Deleting for good is browser only.

**Can an agent apply its own proposal?**
No. A person applies proposals in the browser.

**Who can set a file's status?**
Owners and admins. In a browser session directly, and through a credential
that holds `files:approve`.

**Who can change an organization folder file?**
Owners and admins of the organization. Members read the organization folder.

**Does `files:write` let an agent read files?**
Yes. `files:write` includes `files:read`.

**Does `files:approve` include `files:write`?**
No. It is separate in both directions.

**Why does my admin key get `403` on status changes?**
Check three things: the key holds `files:approve`, you are still an owner or
admin of that workspace (or of the organization, for organization folder
files), and your email is verified.

**What does a credential see of other workspaces?**
Nothing. Lists that reach past one workspace, such as a file's duplicates or
the organization's workspaces, show only the credential's workspaces.

## Related pages

- [Members and roles](../organizations/members-and-roles.md)
- [Credentials and scopes](../agents/credentials.md)
- [Connected apps](../agents/connected-apps.md)
- [MCP](../agents/mcp.md)
- [The REST API](../agents/rest-api.md)
- [Statuses](../files/statuses.md)
- [Sharing and public links](../files/sharing.md)
- [Errors](errors.md)

