Roles allow you to group permissions together and assign them to users and software clients, in order to control access to policy administration data. Familiarity with the object model and API are needed to craft roles that fit your business requirements.

Current users will maintain existing access and permissions during the transition to the Roles feature.

Socotra Connected Core includes the following pre-defined roles in the base configuration:

  • Full Access - This role grants full create, read, update, and delete permissions to policy administration data in Socotra.

  • Claims Only - This role grants read permissions to most policy administration data along with full permissions to claims, update permissions for media, and the ability to quote and check calculations.

  • Read Only - This role grants read permissions to all policy administration data in Socotra.

The roles feature now allows you to both modify the pre-defined base roles, and to create new roles. Roles are tenant-based. If you have a test tenant and a production tenant, for example, then you must configure your role(s) on each tenant.

To opt-in to using the new roles feature, set the feature flag property.roles.and.permissions.enabled to true for each tenant. After you set this flag, the feature will remain enabled (even if you remove the flag or set it to false).


The roles feature requires the latest Connected Core authentication and user interface. Do not enable this feature if you are using legacy authentication or the deprecated Legacy User Interface.


Permissions define what each role is allowed to do. Permissions are based on the objects in the data model and the actions that can be taken against those objects. See the Object Model topic for more information.

For example, an invoice can be:

  • Reviewed (invoice.fetch)

  • Paid (, or

  • Written off (invoice.writeOff)

See the API Permissions reference topic for a list of endpoints and the associated required permissions.

Assigning Permissions to Roles

As you create a new role, you select and assign the appropriate permissions needed for that role. For example, for sales agents who are authorized to create quotes and draft policies for consumers, but are not authorized to issue those policies, you can create a role called Sales Agent with the following permissions:

  • Create and quote policies

    • policy.create

    • policy.fetch

    • policy.quote

  • Create and update policyholders

    • policy.fetch

    • policyholder.fetch

    • policyholder.create

    • policyholder.update

  • Create, update, and manage (but not issue) quotes

    • quote.fetch

    • quote.update

    • quote.create

    • quote.invalidate

    • quote.discard

    • quote.quote

  • Full permissions for aux data

    • auxData.*

  • Manage quote documents

    • document.write

  • Use the Core user interface

    • product.fetch

    • ontology.fetch

    • workflow.fetch

    • tenant.fetch

Creating new roles

Roles can be created either through the Roles API endpoints or through the administrator panel. Only administrators can create, update, delete, or assign roles.

To create a role:

  1. Choose which policy administration data a user should be able to access or update.

  2. Review the object model and the API permissions for necessary relationship permissions. As an example, a user cannot review payments without also being able to review invoices.

  3. Consider whether the user needs to access the Core user interface. If so, include the following permissions:

  • product.fetch

  • ontology.fetch

  • workflow.fetch

  • tenant.fetch

  1. Add the full list of permissions to your new role. Please note that the role name and display name cannot be modified once the role is created.

  2. Test your new role to confirm that only intended actions are accessible in Socotra.

  3. You can now assign users to the new role.


If a user is assigned to more than one role, the user will have all of the permissions available from any of the assigned roles. As an example, if a user is assigned both Read Only and Full Access, the user will have full access to all policy administration data.

Updating roles

The permissions associated with a role can be modified. The role name and display name cannot be changed. If you update a role, users must log out and log back in for the new permissions to take effect. If you remove a role from a user, the user will be logged out (so that the reduced permissions take effect as soon as possible).

Removing roles

If any users are assigned to a role, that role cannot be deleted.


The pre-defined roles included in the base configuration can be modified, but cannot be permanently deleted.