API role files
API roles are defined in YAML files that are named
RoleName.role.yaml
. For example:
Insured.role.yaml
ServiceRequestSpecialist.role.yaml
Adjuster.role.yaml
Location of API role files
API roles are declared in Studio in the roles directory).
directory. When checking for role files, the system APIs look in this directory only (and not in any subdirectories of theStructure of API role files
API roles are declared in Studio in the
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 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.
" 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 thecc.
/pc.
must match the role name. For example, "cc.Manager" will be matched with the role named "Manager".)
- The string in the IdP that identifies the role must start with
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.
- insurercode is an insurer code, such as
- 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 theRole Name
section.
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:
- "*"
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.
- The Admin API's
- 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.