Getting Started
Connector
Security gateway that protects your infrastructure The Connector sits between identities (employees, ai agents…) and your databases, APIs, Kubernetes clusters, and other resources. It intercepts every connection, enforces access policies, logs all activity, and can mask sensitive data—without requiring changes to your applications. Also known as: Proxy Related: Resource, Listener, SpaceResource
Any system protected by Formal A Resource is any infrastructure you want to secure: PostgreSQL databases, MongoDB clusters, Snowflake warehouses, SSH servers, Kubernetes pods, APIs, and more. Resources are accessed through the Connector, which enforces policies and logs all activity. Examples: Production database, staging API, Kubernetes cluster Related: Connector, Native UserPolicy
Rules that control who can access what Policies are security rules that the Connector evaluates for every connection and query. They determine who can connect, what data they can see, which queries they can run, and whether to mask sensitive information. Policies are written in Rego, a purpose-built policy language. Examples: “Engineers can only read from dev databases”, “Mask SSNs for support team” Related: Rego, Policy Stage, MaskingSession
A recorded connection to a resource A Session is a logged connection from a user through the Connector to a Resource. Sessions capture all queries, commands, responses, and metadata, providing a complete audit trail for compliance and security investigations. Also known as: Connection, Access Session Related: Audit Log, Session RecordingDeployment & Architecture
Space
Isolated environment for your resources A Space is a logical grouping of Connectors, Satellites, and Resources that can securely communicate with each other. Spaces provide network isolation and organizational boundaries—think of them like separate environments (production, staging) or teams. Also known as: Environment, Deployment Zone Related: Connector, SatelliteSatellite
Optional add-on for advanced features A Satellite is an application deployed alongside Connectors to enable advanced capabilities like automatic PII detection, data discovery, and schema scanning. Satellites help you classify sensitive data and maintain an up-to-date inventory of your resources. Also known as: Data Scanner, Add-on Service Related: Data Label, PII DetectionListener
Port configuration for routing connections A Listener is a configuration on the Connector that accepts connections on a specific port and routes them to designated Resources. Listeners enable a single Connector to handle multiple protocols (PostgreSQL, MongoDB, SSH) simultaneously. Also known as: Port Configuration, Connection Rule Related: Connector, Protocol DetectionControl Plane
Management layer and APIs for Formal The Control Plane is Formal’s management layer that coordinates between your Connectors and Satellites. It provides the APIs used by the Formal console, Terraform provider, and CLI. It’s completely separate from your data—the Control Plane never sees or stores your actual data. Related: Data Plane, Connector, Formal consoleFormal console
The web interface for managing Formal The Formal console (available at app.joinformal.com) is the primary web interface for interacting with the Control Plane. Use it to configure policies, manage users, view sessions, and monitor your infrastructure through a browser. Also known as: Web Console, Management UI Related: Control PlaneData Plane
Where your data flows The Data Plane consists of your Connectors, which handle actual data traffic. All database queries and API requests flow through the Data Plane, not the Control Plane or Formal console. This separation ensures Formal never has access to your data. Also known as: Data Gateway, Traffic Layer Related: Control Plane, ConnectorAccess & Authentication
Native User
Credential used to connect to resources A Native User is the actual credential (username/password, IAM role, or certificate) that the Connector uses to authenticate to a Resource on behalf of end users. Native Users can be static credentials, cloud IAM roles, or dynamically generated temporary credentials. Also known as: Database Credential, Resource Credential, Service Account Related: Dynamic Secrets, End-user IdentityEnd-user Identity
Tracking who’s actually making requests End-user Identity is the process of identifying the real person behind a connection, even when they’re using tools like Metabase, Retool, or other applications. Formal extracts user information from application parameters to attribute all queries to specific individuals. Also known as: Identity Propagation, User Attribution Related: Native User, SessionJust-in-Time Access
Temporary access granted on request Just-in-Time (JIT) Access means users request temporary permissions that expire after a set time period. Instead of permanent access, engineers can request 2-hour database access that automatically revokes, reducing the risk of compromised credentials. Also known as: Temporary Access, Time-bound Access Related: Approval Workflow, Break GlassDynamic Secrets
Temporary credentials that auto-expire Dynamic Secrets are short-lived credentials automatically generated for each connection and revoked when the session ends. This eliminates the risk of long-lived passwords being leaked or compromised. Also known as: Temporary Credentials, Ephemeral Secrets Related: Native User, Just-in-Time AccessMFA (Multi-Factor Authentication)
Two-step verification for high-risk access MFA requires users to provide a second form of authentication (like a code from their phone) in addition to their password. Formal can enforce MFA for specific resources, time periods, or query types. Also known as: Two-Factor Authentication, 2FA Related: SSO, PolicySSO (Single Sign-On)
Log in once, access everything SSO allows users to authenticate through your company’s identity provider (Okta, Azure AD, Google) instead of managing separate Formal credentials. Once logged in, users can access all permitted resources without additional logins. Also known as: SAML, Identity Federation Related: Directory Sync, MFAPolicies & Rules
Rego
Policy language for writing access rules Rego is the language used to write Formal policies. It’s designed specifically for access control and uses a JSON-like syntax. Rego policies evaluate user attributes, query patterns, and context to make allow/deny/mask decisions. Also known as: Policy Language Related: Policy, OPAOPA (Open Policy Agent)
Engine that executes policy decisions OPA is the open-source policy engine that powers Formal’s policy evaluation. It reads Rego policies and evaluates them in real-time for every connection and query, making access decisions in milliseconds. Also known as: Policy Engine Related: Rego, PolicyPolicy Stage
When a policy is evaluated Policies can run at three stages:- Connection Time: When a user first connects (check credentials, enforce MFA)
- Before Query: Before a query executes (block unauthorized queries)
- After Query: After query execution (mask sensitive data in results)
Policy Data Loader
Connect external data to policies A Policy Data Loader is custom code that fetches data from external systems (HR databases, ticketing systems, APIs) and makes it available to policies. This enables dynamic decisions like “allow if user is on-call” or “deny if user has open security tickets.” Also known as: External Data Connector, Policy Data Source Related: Policy, RegoMasking
Hide sensitive data in query results Masking is the process of replacing sensitive data with obfuscated values. Formal can mask data in real-time as query results flow through the Connector, showing “XXX-XX-1234” instead of full social security numbers. Masking Types:- Redaction: Replace with fixed characters (
***) - Partial Redaction: Show first/last characters (
joh***@example.com) - Hashing: One-way encryption (always same output for same input)
- Random: Replace with realistic fake data