API role files

API roles are defined in YAML files that are named RoleName.role.yaml. For example:

Claimant.role.yaml
ServiceRequestSpecialist.role.yaml
Adjuster.role.yaml

Location of API role files

API roles are declared in Studio in the Integration > roles directory. When checking for role files, Cloud API looks in this directory only (and not in any subdirectories of the roles directory).

Note: In most cases when an insurer adds files to an instance of ClaimCenter, the best practice is to add these files to a subdirectory that is named after the insurer. However, an insurer cannot follow this practice with role files. For a role file to be available to Cloud API, the file must be declared directly in the roles directory. It cannot be declared in a subdirectory.

Structure of API role files

API roles are declared in Studio in the Integration > roles directory. Every file identifies:

The role name
The endpoints and endpoint operations for associated users
The fields that associated users can view or edit
Any special permission granted to associated callers

Note that these parts can be listed in any order.

API role names

Guidewire recommends using the same string of characters for the role name declared in the file and the role name as it appears in the file name. If an API role name must be multiple words, the file name must use underscores (such as User_Admin.role.yaml). Guidewire recommends using the same string in the file's Role Name section, but with spaces instead of underscores (such as name: "User Admin").

For example, if a new API role is for Fraud Investigators:

Name the file Fraud_Investigator.role.yaml.
In the file, declare the name as name: "Fraud Investigator".

For API roles for internal users:

There must be a user role in ClaimCenter assigned to the appropriate users.
The API role name and the user role name must be the same.

For API roles for external users:

The IdP must be able to associate each user with the API role name.
The IdP must identify the role with a "cc.", "pc.", or "bc." substring followed by the role name.
- The string in the IdP that identifies the role must start with cc./pc./bc.. The substring after the cc./pc./bc. must match the role name. For example, "cc.Manager" will be matched with the role named "Manager".)

For API roles for services:

Guidewire recommends you name the role insurercode_name (such as acme_locationphotos), where:
- insurercode is an insurer code, such as acme.
- name is a meaningful name in lower case.
When the service is registered with Guidewire Hub, the role must be named with an initial cc./pc./bc.. But do not include the prefix in the API role file name or in the Role Name section.

API role endpoints

The endpoints section identifies the endpoints a grantee can use and the methods (GET, POST, PATCH, or DELETE) that a grantee can use on that endpoint. This section acts as an allowlist. By default, a caller cannot use any operation on any endpoint. To enable endpoint use, each endpoint and method must be explicitly allowlisted.

The endpoints section contains a list of endpoints in the following pattern:

endpoints:
  - endpoint: <endpoint 1>
    methods:
    - <method 1 on endpoint 1>
    - <method 2 on endpoint 1>
  - endpoint: <endpoint 2>
    methods:
    - <method 1 on endpoint 2>
    - <method 2 on endpoint 2>

Wildcards in the `endpoints` section

You can use the asterisk (*) wildcard in the endpoints section.

A single * wildcard indicates access is provided for anything one level below the current endpoint level. For example:

/common/v1/activities/* means "anything one level below /activities".
/common/v1/activities/*/notes means "the notes for anything one level below /activities".

A double ** wildcard indicates access is provided for anything below the current level. For example:

/common/v1/activities/** means "any resource or endpoint that can be accessed from the /common/v1/activities path".

Exercise caution when using **

Guidewire recommends that insurers exercise caution when using the ** wildcard. This is because later releases of Cloud API may add new endpoints that users will unexpectedly have access to through ** wildcards. For example, suppose in release 1.0 that an insurer creates an API role that provides access to common/v1/activities/**. As of release 1.0, this provides access to the following:

common/v1/activities/{activityId}
common/v1/activities/{activityId}/assignees
common/v1/activities/{activityId}/notes

Then, in release 2.0, Guidewire adds the following endpoint:

common/v1/activities/{activityId}/confidentialAnalysis

The API role will automatically have access to the new endpoint, even if this is not what the insurer intended when creating the API role for release 1.0.

API role accessible fields

The accessibleFields section identifies the fields of each resource that a grantee can view or edit. This section acts as a allowlist. By default, a caller cannot view or edit any fields on any resource. To enable viewing and editing, each resource, field, and permission must be explicitly allowlisted.

The accessibleFields section contains a list of resources in the following pattern:

accessibleFields:
  <Resource 1>:
    edit:
    - <fields the grantee can edit on resource 1>
    view:
    - <fields the grantee can view on resource 1>
  <Resource 2>:
    edit:
    - <fields the grantee can edit on resource 2>
    view:
    - <fields the grantee can view on resource 2>

Allowlisting resources

Resources can be named in several ways. You can name the resource explicitly. For example, the following specifies permissions for the Activity resource only:

accessibleFields:
  Activity:
    edit:
    - <fields the grantee can edit on this resource>
    view:
    - <fields the grantee can view on this resource>

You can also use the "*" wildcard. In this context, it means "all resources available to the endpoints listed in the endpoints section". For example, the following specifies permissions for all resources available to the role's endpoints:

accessibleFields:
  "*":
    edit:
    - <fields the grantee can edit on this resource>
    view:
    - <fields the grantee can view on this resource>

Allowlisting fields

For every resource, you can specify two field-level permissions: edit and view. If a permission is not explicitly listed, then callers will not have that permission for any fields on the resource.

Field-level permissions can be named in several ways. You can explicitly name the field and permission. For example, the following grants edit access to the Activity resource's subject field , and view access to priority field and the subject field.

accessibleFields:
  Activity:
    edit:
    - "subject"
    view:
    - "priority"
    - "subject"

You can also use the "*" wildcard. In this context, it means "all fields". For example, the following grants edit access to the subject field on the Activity resource, and view access to all fields.

accessibleFields:
  Activity:
    edit:
    - "subject"
    view:
    - "*"

API role special permissions

A special permission is a permission that does not operate at the endpoint, endpoint method, or field level. The special permissions supported in this release are defined in the following table.


Permission Name	Applicable Applications	Description
`restcreateautomatedactivity`	ClaimCenter	Provides associated callers the ability to create activities using AutomatedOnly activity patterns. For more information, see the section on AutomatedOnly activity patterns, which appears after this table.
`restdefervalidation`	PolicyCenter	Provides associated callers the ability to use the `deferValidation` query parameter.
`restunmasktaxid`	BillingCenter, ClaimCenter, PolicyCenter, ContactManager	In responses that include a contact's `taxId` field, returns the complete and unmasked `taxId`

To add special permissions to a role.yaml file, use the following syntax:

permissions:
- <permissionName>

For example, the following grants the restunmasktaxid permission to the role.

permissions:
            - restunmasktaxid

Creating activities from AutomatedOnly activity patterns

Activity patterns have an AutomatedOnly field. This field designates whether or not a user can create activities through the user interface using that activity pattern.

false - users can create activities with this activity pattern through the user interface
true - users cannot create activities with this activity pattern through the user interface

When a caller attempts to create an activity through Cloud API, the default behavior is to prohibit the use of any activity pattern whose AutomatedOnly field is set to true.

There is a system permission named restcreateautomatedactivity that can be used to override this behavior. If a caller has some association with this permission, then that caller can create activities from AutomatedOnly activity patterns. There are two ways this association can exist.

First, if the caller is an internal user, then the caller has this permission if they have a user role that includes this permission. For example, suppose this permission is added to the Adjuster role through the ClaimCenter user interface. Then, any internal user who has the Adjustor role can create activities from AutomatedOnly activity patterns through Cloud API.

For all types of callers (internal users, external users, and services), the caller has this permission if they have an API role that lists this permission in the permissions section. For example, suppose there is a General.role.yaml API role file that has a permissions section which lists restcreateautomatedactivity. Then, any caller with the General API role can create activities from AutomatedOnly activity patterns through Cloud API. This includes:

Internal users who have been assigned a user role named General in ClaimCenter (even if the system permission itself is not part of the General user role in ClaimCenter).
External users with a JWT whose groups claim includes gwa.<planetclass>.cc.General.
Services with a JWT whose scp claim includes scp.cc.General.

If the caller is a service with user context, the both the service and the user of context must be associated with the restcreateautomatedactivity permission.

API role example

This is the contents of the Adjuster.role.yaml file:

endpoints:
  - endpoint: "/admin/v1/openapi.json"
    methods:
    - "*"
- endpoint: "/claim/v1/**"
    methods:
    - "*"
- endpoint: "/common/v1/**"
    methods:
    - "*"
accessibleFields:
  "*":
    view:
      - "*"
    edit:
      - "*"
name: Adjuster

Note the following:

A user with the Adjuster role has access to the following endpoints:
- The Admin API's openapi.json endpoint
- All endpoints in the Claim API.
- All endpoints in the Common API.
A user with the Adjuster role can use all operations (GET, POST, PATCH, and so on) on those endpoints.
A user with the Adjuster role can view and edit all fields on the available endpoints.