Security levels

API roles specify the resources that callers can access, and the properties on those resources that callers can view or edit. In an API role file, you can explicitly list each property and its view and edit access. However, there may be some situations where it is easier to grant access to a set of properties without explicitly naming all of them. In these situations, you can use security levels.

Security level is a property-level attribute that can be used by API roles to grant view or edit permissions to a set of properties. API roles can grant view or edit permissions using the "*level" expression, which means "grant the permission to all properties on this resource with the security level of level."

There are three security levels: internal, sensitive, and public. These levels are not hierarchical. Granting access to a specific security level does not inherently include any other security levels. Also, there is no inherent meaning tied to them. They are arbitrary labels that you can use in whatever way is most appropriate.

Specifying a field's security level

Security levels are set in the resource's schema file. The syntax is "securityLevel": level.

  • level must be either internal, sensitive, or public.
  • If a property has no specified security level, it defaults to public.

For example, the following code snippet, from policyperiod_core-1.0.schema.json, declares two properties for the Cost resource:

"Cost": {
  "properties": {
    "adjustedRate": {
        ... 
        "securityLevel": "internal"
      }
    },
    "amount": {
        ...
    },

The adjustedRate property has a security level of internal. The amount property has no defined security level, and therefore defaults to a security level of public.

Using security levels in API roles

In an API role file, when specifying view and edit permissions for a given resource, you can use the expression "*level" to indicate "all properties on the resource that have the specified level". For example, the following grants access to fields on the Cost resource. The grantee can edit and view all properties on the Cost resource that have a security level of public as well as the sortableId property (which presumably is not a public field). (Based on the previous code snippet, the grantee would be able to view and edit amount but not adjustedRate.)

accessibleFields:
  Cost:
    edit:
    - "*public"
    - sortableId
    view:
    - "*public"
    - sortableId

Additional behaviors of security levels

Security levels are not hierarchical. To grant access to multiple levels, all levels must be listed explicitly. For example, the following grants edit access to all properties on the Cost resource that are public or sensitive:

Cost:
  edit:
  - ["*public", "*sensitive"]

If the view or edit section of a resource lists both explicit properties and a "*level" expression, the grantee has access to all explicitly listed properties and all properties with the given security level. For example, the following grants edit access to all properties on the Cost resource that are public as well as the sortableId property:

Cost:
  edit:
  - "*public"
  - sortableId