InsuranceNow API authorization

Overview

API security groups enable fine-grained access control by determining which authenticated users can execute specific API operations. Rather than granting individual endpoint permissions, InsuranceNow assigns security groups to user roles, streamlining authorization administration and enforcing consistent access policies across portal applications.

Each security group contains a set of related API endpoints. When a role includes a security group, users with that role can access all endpoints in that group. This role-to-group mapping is configured in your authority-role.xml file.

Security Motivation

In 2026.2.1, InsuranceNow introduced new security groups to address critical security issues with API authorization. The previous configuration allowed malicious users with valid session tokens to access information beyond their authorized scope. Specifically:

• Modified URLs could be used to gain unauthorized access to insurance agent and provider details.
• Default roles used for portal applications were over-privileged, granting more access than necessary for typical portal operations.

To address these vulnerabilities, two new security groups were introduced: DirectSalesPortalAltGroup and ServicePortalAltGroup. The release also moved sensitive endpoints from the base groups to these new "Alt" groups and removed access to certain endpoints entirely. This change enforces a more restrictive default posture, ensuring that portals have access only to the endpoints they actually need.

For complete information about these security changes, including endpoint reassignments and required actions, see the Core Release Notes.

Least Privilege Principle

The foundation of API security groups is the principle of least privilege: each role should have access only to the API endpoints it actually needs to perform its function. No more, no less.

When configuring roles:

• Review your portal's actual API usage to identify which endpoints it calls.
• Enable only the security groups that contain those endpoints.
• Disable or remove security groups that your portal does not require.
• Regularly audit your role configurations to remove any extraneous authorizations.

By following this principle, you reduce the attack surface: if a user account is compromised, the damage is limited to the specific endpoints and operations they actually need.

Available Security Groups

InsuranceNow provides the following API security groups for portal applications:

Endpoint Mapping Reference

Each security group contains a specific set of API endpoints. To determine which group an endpoint belongs to, or to review all endpoints in a group, see InsuranceNow API Endpoint Security Mapping.

This reference topic provides:

• A complete list of endpoints in each security group
• HTTP methods (GET, POST, PATCH, PUT, DELETE) for each endpoint
• Information about endpoints that have been removed or moved in recent releases

Use this reference to identify which groups your portal role must include based on the endpoints your portal calls.

Configuring Role-Based Access

Security groups are enabled or disabled per role in your authority-role.xml configuration file. Each security group appears as an AuthorityAttribute entry with a boolean Value setting:

• Value='Yes' — Enables access to the endpoints in this group
• Value='No' — Disables access to the endpoints in this group

Example:

<AuthorityAttribute Name="APISecurity-ServicePortalAltGroup" Value="Yes"/>
<AuthorityAttribute Name="APISecurity-DirectSalesPortalAltGroup" Value="No"/>

Use the following steps to configure your role-based access in authority-role.xml:

1. Identify all API endpoints your portal or integration calls.
2. Find each endpoint in InsuranceNow API Endpoint Security Mapping to determine its required security group.
3. Add the required security group to your role's AuthorityAttribute elements, setting Value='Yes'.
4. Remove any security groups not needed for your portal's endpoints, setting Value='No' or deleting them entirely.
5. Redeploy InsuranceNow to apply the changes.
6. Test your portal to verify all endpoints are accessible.

If your portal receives HTTP 403 (Forbidden) errors after an upgrade, use this process to verify that the appropriate security groups are enabled for your role. Check InsuranceNow API Endpoint Security Mapping to identify which group each endpoint requires.

Troubleshooting HTTP 403 errors

If your portal receives HTTP 403 (Forbidden) errors on API calls after upgrading to 2026.2.1:

1. Note the endpoint that returned the error.
2. Find the endpoint in this mapping to identify its security group.
3. Verify that your role includes that security group in authority-role.xml.
4. If the security group is missing, add it and redeploy InsuranceNow.
5. Ensure users log out and log back in after redeployment to refresh their permissions.

Best Practices

• Start restrictive: Enable only the groups your portal actually requires. It's easier to add permissions later than to restrict them retroactively.
• Audit regularly: Review your role configurations periodically to ensure groups remain necessary as your portal evolves.
• Document your choices: Maintain a record of why each role has the security groups it does. This helps with troubleshooting and audits.
• Test after changes: When modifying role configurations, redeploy and test your portal thoroughly to ensure all required endpoints work correctly.
• Monitor for 403 errors: HTTP 403 responses indicate missing security group permissions. Check the Release Notes and the endpoint reference to identify which group is needed.

Related Topics

• InsuranceNow API Endpoint Security Mapping — Complete reference of which endpoints belong to each security group
• Core Release Notes — Release notes on 2026.2.1 security changes and required actions