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.
![Fields in a schema and which fields are exposed in the role file](../../../graphics/third-party-data-access-01-schema-and-role.png)
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.
![Fields in a role file and which fields are in unfiltered and filtered access](../../../graphics/third-party-data-access-02-unfilter-and-filtered-access.png)
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
.
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.