Permissions

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.email
input.user.groups
input.user.ip_address
input.user.type (i.e. human or machine)
input.user.aws_principal_arn — full AWS principal ARN (AWS SigV4 authentication machine auth only)
input.user.aws_account_id — AWS account ID (AWS SigV4 authentication machine auth only)

input.user.aws_principal_arn and input.user.aws_account_id are populated only for requests authenticated with AWS SigV4. API key and SSO requests leave these fields empty.

Application inputs

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

The permissions system also supports blocking or allowing requests based on the request payload for any API call based on input arguments (input.args).

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.

Type	Operations
read	`Get`, `List`
create	`Create`
update	`Update`
delete	`Delete`
login	`Login`

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.

Name	Description
ChangeAuthorization	Manage change authorization workflows for infrastructure changes.
Connector	Manage Connector proxy instances and listeners.
Graph	View Formal’s data graph.
Group	Manage user groups for role-based access control.
Hook	Manage webhooks and event delivery settings.
Insights	View security findings and suggested next steps.
IntegrationBI	Manage BI tool integrations (Metabase, Looker, Fivetran).
IntegrationCloud	Manage cloud provider integrations (AWS, GCP, Azure).
IntegrationMDM	Manage Mobile Device Management integrations.
IntegrationsLog	Manage log forwarding (Splunk, Datadog, S3).
Inventory	Manage discovered schemas, tables, and columns.
Logs	View and manage audit logs and retention settings.
Permissions	Manage OPA permissions for this API.
Policies	Manage data access policies (masking, blocking, alerts).
PolicyDataLoader	Manage external data loaders for policy context.
Resource	Manage datastores and APIs proxied by Formal.
Satellite	Manage Satellite deployments for data discovery.
ScenarioMonitoring	Manage real-time alerts and monitoring rules.
Sessions	View and replay user session recordings.
Space	Manage Spaces for organizing resources by team or project.
User	Manage users, invitations, and account settings.
Workflow	Manage automated workflows across Formal.

Web Console Only

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.

Name	Description
Access	View and manage personal access tokens.
Agent	AI-powered conversational assistant for Formal.
AgentObservability	View AI usage, policy actions, and session activity.
DSPM	Manage DSPM jobs and tasks.
Dashboard	View dashboard home page statistics.
Desktop	Approve personal desktop app logins.
Developer	Manage developer API keys.
DirectorySync	Configure SCIM directory sync with identity providers.
Reports	Create and manage security reports and widgets.
Search	Search across resources, connectors, policies, and more.
Slack	Configure Slack notifications and alerts.
Sso	Configure SAML Single Sign-On.
Version	View 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.

Example: Argument-based Access Control

package formal.app

import future.keywords.if

default allow = true

allow := false if {
  input.app.command.name == "UpdatePolicy"
  input.args.id == "policy_01kg6rhpe7em4rr2v0mcwm0mp4"
  not "security-admins" in input.user.groups
}

This policy blocks updates to the policy with the ID policy_01kg6rhpe7em4rr2v0mcwm0mp4 unless the user is in the security-admins group.

Example: AWS SigV4 machine access

Use input.user.aws_principal_arn and input.user.aws_account_id to scope AWS SigV4-authenticated machine users by AWS principal or account.

package formal.app

import future.keywords.if

default allow = false

allow if {
  input.user.type == "machine"
  input.user.aws_account_id == "123456789012"
  startswith(input.user.aws_principal_arn, "arn:aws:iam::123456789012:role/formal-")
  input.app.name == "Resource"
  input.app.command.type == "read"
}

This policy allows read access to the Resource application only for machine users authenticated from AWS account 123456789012 whose principal ARN starts with arn:aws:iam::123456789012:role/formal-.

Getting Started

Configuring Formal

Leveraging Formal

Integrations

Configuration

Client Apps

Example Use Cases

Introduction

Default permissions

Permission Model

User experience when blocked

List of inputs

User inputs

Application inputs

List of command types

List of applications

Example: Single Application

Example: Granular Access Control

Example: Argument-based Access Control

Example: AWS SigV4 machine access

​Introduction

​Default permissions

​Permission Model

​User experience when blocked

​List of inputs

​User inputs

​Application inputs

​List of command types

​List of applications

​Example: Single Application

​Example: Granular Access Control

​Example: Argument-based Access Control

​Example: AWS SigV4 machine access

Introduction

Default permissions

Permission Model

User experience when blocked

List of inputs

User inputs

Application inputs

List of command types

List of applications

Example: Single Application

Example: Granular Access Control

Example: Argument-based Access Control

Example: AWS SigV4 machine access