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, Cloud API looks 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
- 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 thecc.
/pc.
/bc.
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.
/pc.
/bc.
. 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
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:
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:
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:
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:
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.
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.
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 |
---|---|---|
restdefervalidation |
PolicyCenter | Provides associated callers the ability to use the
|
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:
For example, the following grants the restunmasktaxid
permission to the
role.
API role example
This is the contents of the Adjuster.role.yaml
file:
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.