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 admin_pl-1.0.schema.json, declares two properties for the User resource:

"User": {
  "properties": {
    "firstName": {
        ...
    },
    "homePhone": {
        ... 
        "securityLevel": "internal"
      }
    },

The homePhone property has a security level of internal. The firstName 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 User resource. The grantee can edit and view all properties on the User resource that have a security level of public as well as the workPhone property (which presumably is not a public field). (Based on the previous code snippet, the grantee would be able to view and edit firstName and workPhone, but not homePhone.)

accessibleFields:
  User:
    edit:
    - "*public"
    - workPhone
    view:
    - "*public"
    - workPhone

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 User resource that are public or sensitive:

User:
  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 User resource that are public as well as the workPhone property:

User:
  edit:
  - "*public"
  - workPhone