Skip to main content
This page covers Control Plane permissions - policies that control access to Formal’s web interface and APIs. For policies that control data access through Connectors (like database query policies), see the Policies section.

​
Introduction

Formal’s permission system is built on the Open Policy Agent (OPA), allowing you to restrict user access to specific applications through Rego policies. By defining granular permissions, you can ensure users have access only to the applications necessary for their roles and responsibilities. These permissions are enforced against our API endpoints.

​
Default permissions

Upon account creation, Formal operates under an allow-by-default model. Meaning, by default, if no permission blocks an endpoint for a given user, then the endpoint is allowed.

​
Permission Model

Unlike other software products, Formal does not have the traditional concept of Roles. Instead, users can leverage Permissions to create role based access control (RBAC) using your organization’s Groups (which can be SCIM provisioned from your IDP into Formal).

​
User experience when blocked

The Formal APIs will return HTTP 403 error status codes if a user is blocked on a particular endpoint. Users who are interacting with the Formal APIs through the Formal console will experience “Forbidden” toasts or dialogs.

​
List of inputs

You can block or allow requests based on the following user and application inputs:

​
User inputs

  • input.user.id
  • input.user.name
  • input.user.first­_name
  • input.user.last­_name
  • input.user.email
  • input.user.groups
  • input.user.ip­_address

​
Application inputs

  • input.app.name
  • input.app.command.name
  • input.app.command.type

​
List of command types

Here is a table listing all command types that can be used. If the API call contains the operation, then it is categorized as the corresponding type.
TypeOperations
readGet, List
createCreate
updateUpdate
deleteDelete
loginLogin

​
List of applications

API endpoints are segmented into Applications. Here is a table listing all applications that can be configured for access permissions:

Public API

These applications have public API endpoints accessible via API keys or the web console.
NameDescription
ConnectorManage Connector proxy instances and listeners.
GraphView Formal’s data graph.
GroupManage user groups for role-based access control.
IntegrationBIManage BI tool integrations (Metabase, Looker, Fivetran).
IntegrationCloudManage cloud provider integrations (AWS, GCP, Azure).
IntegrationDataCatalogManage data catalog integrations (Datahub).
IntegrationMDMManage Mobile Device Management integrations.
IntegrationsLogManage log forwarding (Splunk, Datadog, S3).
InventoryManage discovered schemas, tables, and columns.
LogsView and manage audit logs and retention settings.
PermissionsManage OPA permissions for this API.
PoliciesManage data access policies (masking, blocking, alerts).
PolicyDataLoaderManage external data loaders for policy context.
ResourceManage datastores and APIs proxied by Formal.
SatelliteManage Satellite deployments for data discovery.
ScenarioMonitoringManage real-time alerts and monitoring rules.
SessionsView and replay user session recordings.
SidecarLegacy Connector management (use Connector instead).
SpaceManage Spaces for organizing resources by team or project.
UserManage users, invitations, and account settings.
WorkflowManage automated workflows across Formal.
These applications are only accessible through the Formal web console and do not have public API documentation.
For web console only applications, we recommend restricting access at the application level rather than by individual command types, since the available commands are not publicly documented.
NameDescription
AccessView and manage personal access tokens.
DSPMManage DSPM jobs and tasks.
DashboardView dashboard home page statistics.
DesktopApprove personal desktop app logins.
DeveloperManage developer API keys.
DirectorySyncConfigure SCIM directory sync with identity providers.
SlackConfigure Slack notifications and alerts.
SsoConfigure SAML Single Sign-On.
VersionView latest connector and satellite versions.

​
Example: Single Application

Below is an example of a Rego policy that grants access to the Sessions application exclusively for users in the admin group. 

package formal.app

import future.keywords.in
import future.keywords.if

default allow = false

allow := true if {
    input.app.name == "Sessions"
    "admin" in input.user.groups
}
This policy sets the default access to false, meaning no access is granted unless specified by a rule. The allow rule checks if the application requested is Sessions and if the user belongs to the admin group. If both conditions are met, access is granted.

​
Example: Granular Access Control

package formal.app

import future.keywords.in
import future.keywords.if

default allow = false

# Allow read access to everyone
allow if {
  input.app.command.type == "read"
}

# Allow everyone to get their own Credentials
allow if {
    input.app.name == "Access"
}

# Allow full access if the user is a member of the security team
allow if {
  "security-admins" in input.user.groups
}

# Allow engineers to access relevant applications
allow if {
  input.app.name in ["Desktop"]
  "engineers" in input.user.groups
}
This multi-rule policy demonstrates how to combine different access levels:
  • Broad read access: Everyone can view most data using read command types.
  • Self-service access: Everyone can manage their own credentials in the Access app.
  • Administrative access: Users in security-admins have unrestricted access to all apps.
  • Team-specific access: Users in the engineers group can access developer-focused tools.
Since default allow = false is set, any request that does not match at least one of these allow rules is blocked. Formal returns a 403 Forbidden error for these requests.