Skip to Content

Documentation

Risk Cloud API: About Users, Roles, and Permissions

Updated on:

The Risk Cloud uses the same permission model for the UI and the API. Every API call is evaluated against the access of the user behind the token. If that user can perform an action in the UI, they can perform it through the API. If they can’t, the API returns a 401, a 403, or an empty result.

This article covers how the permission model applies to API requests, with a reference description of the model itself at the end. For applying it to automated integration accounts, see Risk Cloud API: Service Accounts.

How the Permissions Model Applies to API Requests

Every API call runs as the user behind the access token. That user’s Roles, Application Entitlements, Permission Sets, and Build Access are evaluated on every request.

Endpoints fall into a few categories of authorization:

  • Any authenticated user. The endpoint requires only a valid token. The response may still be filtered by permission.
  • Requires a specific module permission. For example, RECORDS for fetching Records, or BUILD for editing a Workflow.
  • Requires access to a specific entity. The endpoint walks from the entity to the calling user’s Application Entitlements and Permission Sets to decide whether to allow the call.
  • Combined. Some endpoints require multiple checks. Editing an Application’s design requires both BUILD and Build Access on the parent Application, for example.

List Endpoints Filter by Permission

List endpoints do not return 403 for individual objects the caller cannot see. They omit those objects from the response.

  • GET /api/v2/records returns only Records the calling user has Read access to. Records on Steps the user cannot see are absent from the page.
  • GET /api/v2/applications returns only Applications the user has an Application Entitlement on.
  • A saved Table Report applies the same per-Record filtering. Two users running the same report can see different rows.

If an integration is missing Records it should be returning, check the calling user’s Step Permission Sets.

Troubleshooting

401 Unauthorized on every call from a new account. The user’s API access permission is not enabled. Toggle it in the user’s settings and re-generate the token.

401 Unauthorized. The bearer token is missing, malformed, or has been invalidated. Generate a new token.

403 Forbidden on a single-entity endpoint. The token is valid but the user lacks permission for that object. Walk the model: module entitlement, then Application Entitlement, then Build Access for build endpoints, then Step Permission Set for Record endpoints.

403 Forbidden on a list endpoint. Unusual. List endpoints prefer to return an empty page over a 403. A 403 here usually means the underlying module entitlement is missing entirely.

Empty results when Records should exist. Permission filtering. The user is allowed to call the endpoint but lacks Read access on the Steps where the missing Records currently sit.

The Permission Model

Permissions in Risk Cloud are built from five concepts:

  • Role. A named bundle of entitlements and permission sets. Users belong to one or more Roles.
  • Module entitlement. Coarse-grained access to a functional area such as Build, Admin, Records, or Import. Module entitlements attach to Roles.
  • Application entitlement. Read or Edit access to an entire Application. Granted to users directly, on a per-Application basis.
  • Step permission set. A bundle of per-Step Read or Edit permissions. Attached to Roles.
  • Build Access. A per-Application list of users who can modify that Application’s design (Workflows, Steps, Fields).

A user can belong to multiple Roles. Their effective permissions are the union of everything those Roles grant.

Users

There are two kinds of users in the system.

Regular users authenticate via password or SSO and use the Risk Cloud interactively.

Service users are accounts created for automated integrations. They have Roles, entitlements, and permission sets like regular users. See Risk Cloud API: Service Accounts for setup.

The user account behind any API token must have the API access permission enabled in the admin UI. This applies to both regular users and service accounts. A user without API access enabled cannot generate a token or call any endpoint, even if their Role and Permission Sets look correct.

Roles

Roles bundle permissions for a job function. Examples: “Risk Analyst,” “Compliance Auditor,” “Application Admin,” “Integration: Risk Sync.” Granting a user a Role grants every entitlement and permission set on that Role.

Module Entitlements

Module entitlements grant access to functional areas. They attach to Roles. The ones that appear in API endpoint requirements:

  • BUILD: modify Workflows, Steps, Fields, and Paths.
  • ADMIN: modify account-level settings, Roles, entitlements, and themes.
  • RECORDS: create, update, transition, and bulk-operate on Records.
  • ASSIGN: assign Records to other users.
  • IMPORT: bulk-import Records.
  • DELETE_RECORDS: delete Records.
  • STATUS: view aggregated status reports.
  • TABLE_REPORTS_READ and DASHBOARDS_READ: view saved Table Reports and Dashboards.
  • APPLICATION: list Applications you are entitled to.

Most modules have a Read tier and an Edit tier. A Role with a module at the Read tier can list and view things in that area but not modify them.

Application Entitlements

Application entitlements decide which Applications a user can interact with. They are granted directly to a user, scoped per Application, and come in two tiers: Read and Edit. A user with no Application Entitlement on an Application sees nothing in that Application. List endpoints silently omit it.

Step Permission Sets

A Step Permission Set assigns Read or Edit permission on each Step in a Workflow. A Permission Set might grant Read on Step A, Edit on Step B, and no access to Step C. Permission Sets attach to Roles.

This layer controls Record visibility. A Record sits on a single Step at any time, and a user can see or update the Record only if their Role’s Permission Set grants Read or Edit on that Step. A user with the RECORDS module and the right Application Entitlement still sees no Records if their Permission Set does not include the Step those Records are on.

Build Access

Build Access is a per-Application list of users who can modify the Application’s design. It is separate from the BUILD module entitlement. Build-time work requires both.

The BUILD module entitlement grants the ability to do build work somewhere in the environment. Build Access on a specific Application grants the ability to do it on that Application. A user with BUILD but no Build Access on the target Application gets a 403. A user with Build Access but no BUILD module also gets a 403.