Roles and Permissions

Socotra mandates specific permissions for each API endpoint to ensure that users have adequate authorization to perform certain operations.

You do not assign permissions to users directly. Instead, you define a role, assign it a set of permissions, and then assign that role to the user. A user can have multiple roles. A given user’s full set of permissions is the union of permissions granted to that user’s roles.

See the User Management API for details on user and role management endpoints.

Special Roles

The platform defines two special roles:

admin: this grants all privileges to any tenant within the same Business Account.
read-only: this grants read privileges across the API.

Tenant Access

Permissions for an API call are evaluated after examining the user’s tenants assignment, which governs overall tenant API access. If a user has been assigned a role with adequate permissions for an API endpoint, but the user is not authorized to work with a specific tenant, then the user will not be able to exercise granted privileges for that API endpoint on that tenant. The platform recognizes two convenience names for the tenants list:

any: allows the user or client to perform API calls on any tenant within the same Business Account according to assigned roles.
type:test: allows the user to perform API calls on any tenant with type “TEST” within the same Business Account according to assigned roles.

A user with the admin role has implicit access to any tenant in the business account and does not require an explicit tenant list.

Available Permissions

Permissions take the form group.action, where group pertains to a platform category such as “quotes” or “invoices”, and action is an enablement such as “list” or “write”.

Each endpoint’s list of required permissions is provided with that endpoint’s description in the API reference (e.g. Create a Quote). When an endpoint has more than one permission, it means that the user must possess all of those permissions in order to call the endpoint.

See the Comprehensive Permissions Listing for a complete overview of all available permissions.

Wildcard Patterns

You can assign all permissions in a group with a single expression: group.*. For example, to assign all permissions associated with invoices to a role, you can create the role with the permission invoices.*. You may also grant all permissions with *.*. Wildcards for groups in an expression such as *.write are not supported.

Auth Tokens

Users with requisite permissions may create Auth Tokens (also known as Personal Access Tokens), which support use cases involving services making requests to the API on the user’s behalf. Auth Tokens are assigned specific permissions, not roles, and can also be assigned tenants, with the restriction that an Auth Token cannot be created with access privileges exceeding those of the user to whom the Auth Token belongs. We recommend that Auth Tokens be created following the principle of least privilege. See the Authentication API for details on managing Auth Tokens.