API role files

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

Account_Holder.role.yaml
Producer.role.yaml
Underwriter.role.yaml

Location of API role files

API roles are declared in Studio in the Integration > roles directory. When checking for role files, the system APIs look 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 PolicyCenter, 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 the system APIs, 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

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, Guidewire recommends using underscores in the file name, and spaces in the file's Role Name section.

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 PolicyCenter 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." or "pc." substring followed by the role name.
- The string in the IdP that identifies the role must start with cc./pc.. The substring after the cc./pc. 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." or "pc.". But do not include the prefix in the API role file name or in the Role Name section.

Be aware that the naming convention for API roles for services is also used for:

API roles for Guidewire services (such as the API role for Cloud Rating service, named as gw_cloudrating)
API roles for other Guidewire functionality that connect to PolicyCenter (such as the API role for Cloud Rules Engine, named as gw_cloudrulesengine)

API role endpoints

The endpoints section identifies the endpoints a grantee can use and the operations (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 operation 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 the system APIs 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:
    - "*"

Some resource schemas tag individual fields with a security level of internal, sensitive, or public. When specifying field permissions, you can use the expression "*<level>" to indicate "all fields on the resource that have the specified level". For example, the following grants access to fields on the Job resource. The grantee can edit and view all fields on the Job resource that have a security level of public as well as the jobFilter field (which presumably does not have a security level of public).

accessibleFields:
  Job:
    edit:
    - "*public"
    - jobFilter
    view:
    - "*public"
    - jobFilter

For more information on security levels, see Security levels.

API role example

For example, the following is a portion of the contents of the Underwriter.role.yaml file:

name: Underwriter 
endpoints:
  - endpoint: /account/v1/accounts
    methods:
    - GET
    - POST
  - endpoint: "/account/v1/accounts/*"
    methods:
    - GET
    - PATCH
  - endpoint: "/account/v1/accounts/*/activities"
    methods:
    - GET
    - POST
    ...
accessibleFields:
  "*":
    view: "*"
    edit: "*"

Based on this portion, note the following:

A user with the Underwriter role can use:
- GET and POST on the /account/v1/accounts endpoint
- GET and PATCH on all endpoints one level below /account/v1/accounts
- GET and POST on the activities for all resource one level below /account/v1/accounts
A user with the Underwriter role can view and edit all fields on the available endpoints.