Permissions matrix

This matrix shows what each role can do in bb-sign. The app and the API apply the same rules to every operation, so a person and an integration with the same role have the same reach.

Permissions are grouped in two levels. Organization roles define what can be administered. Workspace roles define what can be done with the envelopes of each workspace.

Organization roles

Role	Who holds it	Scope
Platform admin (platform_admin)	Binary Bridges staff	Everything an organization admin can do, in any organization, plus creating organizations, quotas and the signature appearance.
Organization admin (org_admin)	Your organization’s admins	Users, workspaces, labels, credentials, webhooks and audit. Reaches every workspace without being a member (workspace:access-all).
Organization member (org_member)	Your organization’s users	View workspaces and label keys. Everything else comes from their workspace roles, including Contributor in General.
API credential (org_api)	Integrations	The same as a member, with the workspace roles you assign.

Permissions by role

Organization permissions by role

Permission	platform_admin	org_admin	org_member	org_api
audit:read-org	Yes	Yes	No	No
label:read	Yes	Yes	Yes	Yes
label:manage	Yes	Yes	No	No
credential:manage	Yes	Yes	No	Never
webhook:manage	Yes	Yes	No	Never
workspace:read	Yes	Yes	Yes	Yes
workspace:manage	Yes	Yes	No	Never
workspace:manage-members	Yes	Yes	No	Never
workspace:access-all	Yes	Yes	No	Never

Workspace permissions by workspace role

Permission	viewer	auditor	contributor	manager
envelope:read	Yes	Yes	Yes	Yes
archive:read	Yes	Yes	Yes	Yes
audit:read	No	Yes	Yes	Yes
document:download	No	Yes	Yes	Yes
envelope:create	No	No	Yes	Yes
envelope:update	No	No	Yes	Yes
document:upload	No	No	Yes	Yes
label:assign	No	No	Yes	Yes
envelope:send	No	No	Yes	Yes
envelope:cancel	No	No	No	Yes

In the first table, “Never” marks a permission reserved for people: an API credential never receives it. In the second, Contributor is every member’s role in General; in other workspaces you assign Viewer, Auditor or Manager from Workspaces and members.

Tasks reserved for people

API credentials automate work with envelopes, and administration always stays with people. That way, if a secret leaks, revoking the credential is enough to close the access: the credential could not have created other credentials or widened its own reach. bb-sign checks this rule every time the service starts.

These five permissions are never granted to a credential:

1. Create credentials (credential:manage), so that revoking a credential fully closes its access.
2. Manage webhooks (webhook:manage), so that your envelopes’ events reach only the destinations you configured.
3. Create, rename and delete workspaces (workspace:manage), so that an admin decides the access structure.
4. Grant and remove workspace roles (workspace:manage-members), so that a credential cannot widen its own memberships.
5. Access every workspace (workspace:access-all), so that each credential acts only in the workspaces you assigned.

When a credential needs more reach, it is added as a member of other workspaces, like a person. See API credentials.

When someone cannot see an envelope

Check the workspace first

To protect confidentiality, an envelope in a workspace the person does not belong to is shown as if it did not exist: “Envelope not found.” or “That workspace no longer exists, or you can’t use it”. If a user tells you an envelope does not exist, check whether they are a member of its workspace.

An administrative action the role does not allow, such as opening Users as a member, shows “Access Denied” or “You don’t have permission to do this”.