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:
- The person's role.
owner,adminormember. - 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,adminandmember. 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_FOUNDfor everything in it, not403. - 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:writeandfiles:approve. files:writeincludesfiles:read. No other scope includes another.files:approvealone 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 FORBIDDENwith reasonSESSION_REQUIRED, orHUMAN_APPROVAL_REQUIREDfor applying a proposal. The words in brackets say why the operation is browser only. - A bearer token that does not authenticate gets
401 UNAUTHENTICATEDwith reasonINVALID_TOKENon 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
Authorizationheader, whatever it holds. A bearer token sent together with a session cookie is still refused with401 UNAUTHENTICATED, reasonAMBIGUOUS_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 tofiles:write. - Granting
files:approveto 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 answers403 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 answers403 FORBIDDEN. - A member is removed from a workspace a key lists. The key loses that
workspace at its next request. It answers
404 NOT_FOUNDthere, 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:approveand 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:writemoves a file into a public folder. When that would make the file public, the answer is403 FORBIDDENwith reasonINSUFFICIENT_SCOPE. Withfiles:approvetoo, and an owner or admin behind it, the move still needsconfirmVisibilityChange. - A member moves a file into a public folder in the browser. When that
would make the file public, the answer is
403 FORBIDDENwith reasonMAKES_FILES_PUBLICand 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: reasonMAKES_FILES_PUBLICfor a member, reasonINSUFFICIENT_SCOPEfor a credential withoutfiles: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 answer401.
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.