Talewright Docs Open the app

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.

ActionCapabilityOwnerAdminMemberworkspace:readfiles:readfiles:writefiles:approveNotes
Create an accountaccount.sign_upAnyoneAnyoneAnyone----No sign-in needed
Sign inauth.sign_inAnyoneAnyoneAnyone----No sign-in needed
Check whether this browser is signed inauth.session_probeAnyoneAnyoneAnyone----No sign-in needed
Sign outauth.sign_outYesYesYesNoNoNoNoBrowser only (credential control)
Verify an email address from the emailed linkaccount.verify_emailAnyoneAnyoneAnyone----No sign-in needed
Ask for a new verification emailaccount.verification.resendAnyoneAnyoneAnyone----No sign-in needed
Ask for a password reset emailaccount.password_reset.requestAnyoneAnyoneAnyone----No sign-in needed
Set a new password from the emailed linkaccount.password_reset.confirmAnyoneAnyoneAnyone----No sign-in needed
Confirm a new email address from the emailed linkaccount.email_change.confirmAnyoneAnyoneAnyone----No sign-in needed
See what an invitation link offersinvitations.previewAnyoneAnyoneAnyone----No sign-in needed

Your own account

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

ActionCapabilityOwnerAdminMemberworkspace:readfiles:readfiles:writefiles:approveNotes
Read your account and the workspaces you reachauth.meYesYesYesNoNoNoNoBrowser only (credential control)
Change your nameaccount.updateYesYesYesNoNoNoNoBrowser only (credential control)
Change your passwordaccount.password.changeYesYesYesNoNoNoNoBrowser only (credential control). Needs the current password. Revokes your API keys and connected apps.
Start an email changeaccount.email.changeYesYesYesNoNoNoNoBrowser only (credential control). Needs the current password.
Cancel a pending email changeaccount.email.cancelYesYesYesNoNoNoNoBrowser only (credential control)
List your sessionsaccount.sessions.listYesYesYesNoNoNoNoBrowser only (credential control)
End one of your sessionsaccount.sessions.revokeYesYesYesNoNoNoNoBrowser only (credential control)
End all your other sessionsaccount.sessions.revoke_othersYesYesYesNoNoNoNoBrowser only (credential control)
Delete your accountaccount.deleteYesYesYesNoNoNoNoBrowser 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 teamaccount.feedback.sendYesYesYesNoNoNoNoBrowser 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.reportYesYesYesNoNoNoNoBrowser only (credential control). At most 10 reports a minute.

Organizations

ActionCapabilityOwnerAdminMemberworkspace:readfiles:readfiles:writefiles:approveNotes
Create an organizationorganizations.createYesYesYesNoNoNoNoBrowser only (access control). Any signed-in person. The creator becomes its owner.
List your organizationsorganizations.listYesYesYesYesNoNoNoA credential sees only its own organization.
Read an organizationorganizations.getYesYesYesYesNoNoNoOwners 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 organizationorganizations.updateYesYesNoNoNoNoNoBrowser only (access control)
Delete the organizationorganizations.deleteYesNoNoNoNoNoNoBrowser only (access control). Needs a verified email and the organization's name typed as confirmation.
Restore a deleted organizationorganizations.restoreYesNoNoNoNoNoNoBrowser only (access control). Within 30 days.
Leave the organizationorganizations.leaveYesYesYesNoNoNoNoBrowser only (access control). The only owner cannot leave.
Request an exportorganizations.exports.createYesYesNoNoNoNoNoBrowser only (access control)
Read an export and get its download linkorganizations.exports.getYesYesNoNoNoNoNoBrowser only (access control)

Workspaces

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

ActionCapabilityOwnerAdminMemberworkspace:readfiles:readfiles:writefiles:approveNotes
List the workspaces you reachworkspaces.listYesYesYesYesYesYesYesA credential lists only its own workspaces that its member still reaches.
Create a workspaceworkspaces.createYesYesNoNoNoNoNoBrowser only (access control)
Rename a workspaceworkspaces.updateYesYesNoNoNoNoNoBrowser only (access control)
Delete a workspaceworkspaces.deleteYesYesNoNoNoNoNoBrowser 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 restoredorganizations.deleted_workspaces.listYesYesNoNoNoNoNoBrowser only (access control)
Restore a deleted workspaceworkspaces.restoreYesYesNoNoNoNoNoBrowser only (access control). Within 30 days.

Members and invitations

ActionCapabilityOwnerAdminMemberworkspace:readfiles:readfiles:writefiles:approveNotes
List the organization's membersorganizations.members.listYesYesYesYesNoNoNo
Change a member's organization roleorganizations.members.updateYesYesNoNoNoNoNoBrowser only (access control). Only owners grant or remove the owner role. The only owner cannot be demoted.
Remove a member from the organizationorganizations.members.removeYesYesNoNoNoNoNoBrowser only (access control). Only owners remove owners. The only owner cannot be removed. To remove yourself, leave the organization.
List a workspace's membersworkspaces.members.listYesYesYesYesNoNoNo
Add a member to a workspace or change their workspace roleworkspaces.members.putYesYesNoNoNoNoNoBrowser only (access control). Only owners grant or remove the workspace owner role.
Remove a member from a workspaceworkspaces.members.removeYesYesNoNoNoNoNoBrowser only (access control)
List pending invitationsorganizations.invitations.listYesYesNoNoNoNoNoBrowser only (access control)
Invite someone, or resend an invitationorganizations.invitations.createYesYesNoNoNoNoNoBrowser only (access control). Only owners invite owners.
Revoke an invitationorganizations.invitations.revokeYesYesNoNoNoNoNoBrowser only (access control)
Accept an invitationinvitations.acceptYesYesYesNoNoNoNoBrowser 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.

ActionCapabilityOwnerAdminMemberworkspace:readfiles:readfiles:writefiles:approveNotes
Read the credential a request presentscredential.readYesYesYesYesYesYesYesFor credentials only. A browser session gets 401.
List your API keyscredential.api_keys.listYesYesYesNoNoNoNoBrowser only (credential control)
Create an API key for yourselfcredential.api_keys.createYesYesYesNoNoNoNoBrowser only (credential control). Only for workspaces you reach. Adding files:approve needs owner or admin in every selected workspace.
Rotate one of your API keyscredential.api_keys.rotateYesYesYesNoNoNoNoBrowser only (credential control)
Revoke one of your API keyscredential.api_keys.revokeYesYesYesNoNoNoNoBrowser only (credential control)
List your connected appscredential.connected_apps.listYesYesYesNoNoNoNoBrowser only (credential control)
Disconnect one of your connected appscredential.connected_apps.disconnectYesYesYesNoNoNoNoBrowser only (credential control)
Read an app's request to connectcredential.oauth_requests.getYesYesYesNoNoNoNoBrowser 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 connectcredential.oauth_requests.decideYesYesYesNoNoNoNoBrowser 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 appscredential.organization.listYesYesNoNoNoNoNoBrowser only (credential control). Expired ones stay listed for 30 days.
Revoke any member's API key or connected appcredential.organization.revokeYesYesNoNoNoNoNoBrowser only (credential control)
Read what was done with a credentialcredential.organization.activityYesYesOwn onlyNoNoNoNoBrowser 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.

ActionCapabilityOwnerAdminMemberworkspace:readfiles:readfiles:writefiles:approveNotes
List the statusesworkspace.file_statuses.listYesYesYesNoYesYesNoThe 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 statusworkspace.file_statuses.createYesYesNoNoNoNoNoBrowser only (access control)
Rename a status, change whether it allows public use, or make it the defaultworkspace.file_statuses.updateYesYesNoNoNoNoNoBrowser only (access control)
Reorder the statusesworkspace.file_statuses.reorderYesYesNoNoNoNoNoBrowser only (access control)
Delete a statusworkspace.file_statuses.deleteYesYesNoNoNoNoNoBrowser only (access control)
List the fieldsworkspace.file_fields.listYesYesYesNoYesYesNoThe 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 fieldworkspace.file_fields.createYesYesNoNoNoNoNoBrowser only (access control)
Rename a fieldworkspace.file_fields.updateYesYesNoNoNoNoNoBrowser only (access control)
Reorder the fieldsworkspace.file_fields.reorderYesYesNoNoNoNoNoBrowser only (access control)
Delete a fieldworkspace.file_fields.deleteYesYesNoNoNoNoNoBrowser only (access control)
Add a choice to a fieldworkspace.file_fields.choices.createYesYesNoNoNoNoNoBrowser only (access control)
Rename a choiceworkspace.file_fields.choices.updateYesYesNoNoNoNoNoBrowser only (access control)
Reorder a field's choicesworkspace.file_fields.choices.reorderYesYesNoNoNoNoNoBrowser only (access control)
Delete a choiceworkspace.file_fields.choices.deleteYesYesNoNoNoNoNoBrowser 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.

ActionCapabilityOwnerAdminMemberworkspace:readfiles:readfiles:writefiles:approveNotes
List the statuseslibrary.file_statuses.listYesYesYesNoYesYesNoThe 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 statuslibrary.file_statuses.createYesYesNoNoNoNoNoBrowser only (access control)
Rename a status, change whether it allows public use, or make it the defaultlibrary.file_statuses.updateYesYesNoNoNoNoNoBrowser only (access control)
Reorder the statuseslibrary.file_statuses.reorderYesYesNoNoNoNoNoBrowser only (access control)
Delete a statuslibrary.file_statuses.deleteYesYesNoNoNoNoNoBrowser only (access control)
List the fieldslibrary.file_fields.listYesYesYesNoYesYesNoThe 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 fieldlibrary.file_fields.createYesYesNoNoNoNoNoBrowser only (access control)
Rename a fieldlibrary.file_fields.updateYesYesNoNoNoNoNoBrowser only (access control)
Reorder the fieldslibrary.file_fields.reorderYesYesNoNoNoNoNoBrowser only (access control)
Delete a fieldlibrary.file_fields.deleteYesYesNoNoNoNoNoBrowser only (access control)
Add a choice to a fieldlibrary.file_fields.choices.createYesYesNoNoNoNoNoBrowser only (access control)
Rename a choicelibrary.file_fields.choices.updateYesYesNoNoNoNoNoBrowser only (access control)
Reorder a field's choiceslibrary.file_fields.choices.reorderYesYesNoNoNoNoNoBrowser only (access control)
Delete a choicelibrary.file_fields.choices.deleteYesYesNoNoNoNoNoBrowser only (access control)

Files in a workspace

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

ActionCapabilityOwnerAdminMemberworkspace:readfiles:readfiles:writefiles:approveNotes
List and search filesworkspace.files.searchYesYesYesNoYesYesNo
Read a fileworkspace.files.getYesYesYesNoYesYesNo
List a file's versionsworkspace.files.versions.listYesYesYesNoYesYesNo
Get a temporary URL for a version's bytes, thumbnail, preview or playbackworkspace.files.signed_urlYesYesYesNoYesYesNo
Download a version's bytes through the APIworkspace.files.readYesYesYesNoYesYesNo
Download folders and files as one ZIPworkspace.files.archiveYesYesYesNoYesYesNo
Count the files by status, in the whole place or one folder and the folders below itworkspace.files.status.countYesYesYesNoYesYesNo
Rename, move, tag or describe a file, or set its field valuesworkspace.files.updateYesYesYesNoNoYesNoA move that makes the file public needs an owner or admin, and files:approve through a credential.
Set one field on up to 100 filesworkspace.files.fields.setYesYesYesNoNoYesNo
Set the status of up to 100 filesworkspace.files.status.setYesYesNoNoNoNoYesThrough a credential the member's email must also be verified.
Move a file to the trashworkspace.files.trashYesYesYesNoNoYesNo
Restore a file from the trashworkspace.files.restoreYesYesYesNoNoYesNoA 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 goodworkspace.files.purgeYesYesNoNoNoNoNoBrowser only (permanent deletion)
Make a file public or restrictedworkspace.files.visibility.setYesYesNoNoNoNoNoBrowser only (access control)
Empty the trashworkspace.trash.emptyYesYesNoNoNoNoNoBrowser only (permanent deletion)

Folders and tags in a workspace

ActionCapabilityOwnerAdminMemberworkspace:readfiles:readfiles:writefiles:approveNotes
List foldersworkspace.folders.listYesYesYesNoYesYesNo
Create a folderworkspace.folders.createYesYesYesNoNoYesNo
Rename or move a folderworkspace.folders.updateYesYesYesNoNoYesNoA 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 trashworkspace.folders.trashYesYesYesNoNoYesNo
Restore a folder from the trashworkspace.folders.restoreYesYesYesNoNoYesNoA 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 goodworkspace.folders.purgeYesYesNoNoNoNoNoBrowser only (permanent deletion)
Make a folder public or restrictedworkspace.folders.visibility.setYesYesNoNoNoNoNoBrowser only (access control)
List tagsworkspace.tags.listYesYesYesNoYesYesNo
Rename a tag everywhereworkspace.tags.renameYesYesNoNoNoYesNoOwners and admins of the workspace or the organization. Tagging a file is workspace.files.update.
Delete a tag everywhereworkspace.tags.deleteYesYesNoNoNoYesNoOwners 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.

ActionCapabilityOwnerAdminMemberworkspace:readfiles:readfiles:writefiles:approveNotes
Start an upload of a new file or a replacementworkspace.uploads.createYesYesYesNoNoYesNo
Complete your uploadworkspace.uploads.completeYesYesYesNoNoYesNo
Cancel your uploadworkspace.uploads.cancelYesYesYesNoNoYesNo
Read your uploadworkspace.uploads.getYesYesYesNoYesYesNo
List your uploadsworkspace.uploads.listYesYesYesNoYesYesNo

Library proposals (Suggestions) in a workspace

ActionCapabilityOwnerAdminMemberworkspace:readfiles:readfiles:writefiles:approveNotes
List proposalsworkspace.library_proposals.listYesYesYesNoYesYesNo
Read a proposalworkspace.library_proposals.getYesYesYesNoYesYesNo
Propose changes to filesworkspace.library_proposals.createYesYesYesNoNoYesNo
Reject items of a proposalworkspace.library_proposals.rejectYesYesYesNoNoYesNo
Apply items of a proposalworkspace.library_proposals.applyYesYesYesNoNoNoNoBrowser 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.

ActionCapabilityOwnerAdminMemberworkspace:readfiles:readfiles:writefiles:approveNotes
List your favoritesworkspace.favorites.listYesYesYesNoYesYesNo
Add a file or folder to your favoritesworkspace.favorites.addYesYesYesNoYesYesNo
Reorder your favoritesworkspace.favorites.reorderYesYesYesNoYesYesNo
Remove a favoriteworkspace.favorites.removeYesYesYesNoYesYesNo

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.

ActionCapabilityOwnerAdminMemberworkspace:readfiles:readfiles:writefiles:approveNotes
List the groups of identical filesworkspace.duplicates.listYesYesYesNoYesYesNoA group names only copies in places the caller can open.
Hide the duplicate warning of a file and its copies for yourselfworkspace.duplicates.hideYesYesYesNoYesYesNo
Show a hidden duplicate warning againworkspace.duplicates.showYesYesYesNoYesYesNo

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.

ActionCapabilityOwnerAdminMemberworkspace:readfiles:readfiles:writefiles:approveNotes
List and search fileslibrary.files.searchYesYesYesNoYesYesNo
Read a filelibrary.files.getYesYesYesNoYesYesNo
List a file's versionslibrary.files.versions.listYesYesYesNoYesYesNo
Get a temporary URL for a version's bytes, thumbnail, preview or playbacklibrary.files.signed_urlYesYesYesNoYesYesNo
Download a version's bytes through the APIlibrary.files.readYesYesYesNoYesYesNo
Download folders and files as one ZIPlibrary.files.archiveYesYesYesNoYesYesNo
Count the files by status, in the whole place or one folder and the folders below itlibrary.files.status.countYesYesYesNoYesYesNo
Rename, move, tag or describe a file, or set its field valueslibrary.files.updateYesYesNoNoNoYesNoA move that makes the file public also needs files:approve through a credential.
Set one field on up to 100 fileslibrary.files.fields.setYesYesNoNoNoYesNo
Set the status of up to 100 fileslibrary.files.status.setYesYesNoNoNoNoYesThrough a credential the member's email must also be verified.
Move a file to the trashlibrary.files.trashYesYesNoNoNoYesNo
Restore a file from the trashlibrary.files.restoreYesYesNoNoNoYesNoA 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 goodlibrary.files.purgeYesYesNoNoNoNoNoBrowser only (permanent deletion)
Make a file public or restrictedlibrary.files.visibility.setYesYesNoNoNoNoNoBrowser only (access control)
Empty the trashlibrary.trash.emptyYesYesNoNoNoNoNoBrowser only (permanent deletion)

Folders and tags in the organization folder

ActionCapabilityOwnerAdminMemberworkspace:readfiles:readfiles:writefiles:approveNotes
List folderslibrary.folders.listYesYesYesNoYesYesNo
Create a folderlibrary.folders.createYesYesNoNoNoYesNo
Rename or move a folderlibrary.folders.updateYesYesNoNoNoYesNoA move that makes files inside public also needs files:approve through a credential.
Move a folder and its content to the trashlibrary.folders.trashYesYesNoNoNoYesNo
Restore a folder from the trashlibrary.folders.restoreYesYesNoNoNoYesNoA 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 goodlibrary.folders.purgeYesYesNoNoNoNoNoBrowser only (permanent deletion)
Make a folder public or restrictedlibrary.folders.visibility.setYesYesNoNoNoNoNoBrowser only (access control)
List tagslibrary.tags.listYesYesYesNoYesYesNo
Rename a tag everywherelibrary.tags.renameYesYesNoNoNoYesNo
Delete a tag everywherelibrary.tags.deleteYesYesNoNoNoYesNo

Uploads in the organization folder

ActionCapabilityOwnerAdminMemberworkspace:readfiles:readfiles:writefiles:approveNotes
Start an upload of a new file or a replacementlibrary.uploads.createYesYesNoNoNoYesNo
Complete your uploadlibrary.uploads.completeYesYesNoNoNoYesNo
Cancel your uploadlibrary.uploads.cancelYesYesNoNoNoYesNo
Read your uploadlibrary.uploads.getYesYesYesNoYesYesNoOnly someone who started an upload has one to read.
List your uploadslibrary.uploads.listYesYesYesNoYesYesNoOnly someone who started an upload has any.

Library proposals (Suggestions) in the organization folder

ActionCapabilityOwnerAdminMemberworkspace:readfiles:readfiles:writefiles:approveNotes
List proposalslibrary.library_proposals.listYesYesYesNoYesYesNo
Read a proposallibrary.library_proposals.getYesYesYesNoYesYesNo
Propose changes to fileslibrary.library_proposals.createYesYesNoNoNoYesNo
Reject items of a proposallibrary.library_proposals.rejectYesYesNoNoNoYesNo
Apply items of a proposallibrary.library_proposals.applyYesYesNoNoNoNoNoBrowser only (human approval). A person in a browser only.

Favorites in the organization folder

ActionCapabilityOwnerAdminMemberworkspace:readfiles:readfiles:writefiles:approveNotes
List your favoriteslibrary.favorites.listYesYesYesNoYesYesNo
Add a file or folder to your favoriteslibrary.favorites.addYesYesYesNoYesYesNo
Reorder your favoriteslibrary.favorites.reorderYesYesYesNoYesYesNo
Remove a favoritelibrary.favorites.removeYesYesYesNoYesYesNo

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.

ActionCapabilityOwnerAdminMemberworkspace:readfiles:readfiles:writefiles:approveNotes
List the groups of identical fileslibrary.duplicates.listYesYesYesNoYesYesNoA group names only copies in places the caller can open.
Hide the duplicate warning of a file and its copies for yourselflibrary.duplicates.hideYesYesYesNoYesYesNo
Show a hidden duplicate warning againlibrary.duplicates.showYesYesYesNoYesYesNo

Service endpoints

ActionCapabilityOwnerAdminMemberworkspace:readfiles:readfiles:writefiles:approveNotes
Read the API contractoperations.openapiAnyoneAnyoneAnyone----No sign-in needed
Check that the service is runningoperations.healthAnyoneAnyoneAnyone----No sign-in needed
Check that the service is readyoperations.readyAnyoneAnyoneAnyone----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:

GroupWhat it covers
Credential controlSigning 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 controlCreating, 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 deletionDeleting a trashed file or folder for good, and emptying the trash.
Human approvalApplying 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.