Filtered, unfiltered, and privileged access

Filtered and unfiltered access

The fields in a resource are defined in the resource's schema. By default, users cannot access any fields. Instead, every user is granted one or more API roles. Every API role defines the endpoints the user can use and the fields the user can access on resources returned by those endpoints.

The following diagram illustrates an example of the field access information.
Fields in a schema and which fields are exposed in the role file

The diagram depicts the fields in the VehicleIncident schema. (To simplify the example, some fields have been omitted.) It also identifies the VehicleIncident fields that a user can access when they have been assigned the role of Claimant. Note that a user with the Claimant role can access most fields in the schema. But, they do not have access to valuationRequired or valuationSource.

For resources that a claimant or producer attempts to access, Cloud API determines if the user gets "unfiltered" access or "filtered" access.

  • With unfiltered access, the user can access all fields on the resource as defined by their API roles. In other words, the user's business relationship with the resource does not require any additional restrictions.
  • With filtered access, the user can access the resource, but they can access only a subset of fields on the resource as defined by their API roles. In other words, the user's business relationship with the resource does require additional restrictions.
The following diagram illustrates an example of this.
Fields in a role file and which fields are in unfiltered and filtered access

The diagram depicts two levels of access for VehicleIncident resources when accessed through the Claimant role.

  • If a caller has unfiltered access, they can access all fields available to the API role. The diagram represents unfiltered access with dashed lines. This is because there is no additional file that defines unfiltered access. Once a caller is given unfiltered access, they can access all fields available to the API role.
  • If a caller has filtered access, they can access only a subset of fields available to the API role. These fields are explicitly declared in an accessiblefields.yaml file.

Based on the example above, a Claimant with unfiltered access has access to a vehicle's licenseplate, make, model, vin, and year. A Claimant with filtered access can access the vehicle's make, model, and year, but not the licenseplate or vin.

Warning: Be careful of situations where sensitive information is included in an entity's display name. For some base configuration resources, a caller with filtered access can access the entity's display name. If the logic for generating the display name includes sensitive information, then a filtered caller would have access to it through the display name.

Privileged access

Cloud API uses the term privileged to mean "you are looking at your own data". This term is used in method names and accessiblefields.yaml files names.

Privileged access could be filtered or unfiltered. For example, suppose you have a claim with two exposures. For the first exposure, the insured is the claimant. For the second exposure, a third party is the claimant.

The insured is granted:

  • Privileged unfiltered access to the first exposure.
    • The exposure is their own data, so they have privileged access.
    • They have no restrictions beyond what their API role specifies, so they have unfiltered access.
  • Filtered access to the second exposure.
    • The exposure is not their own data, so the access they have is not privileged.
    • They have restrictions in addition to what their API role specifies, so the access they have is filtered.

The third party is granted:

  • No access to the first exposure.
  • Privileged filtered access to the second exposure.
    • The exposure is their own data, so they have privileged access.
    • They have restrictions in addition to what their API role specifies, so the access they have is filtered.