> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.hoop.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Per-Query Approval and Data Masking for AI Agents with Okta

> Okta decides who an agent or engineer is and whether they connect. The hoop.dev Sidecar decides what each statement does after that, and your Okta groups decide who approves a held one.

Okta decides who a person or an AI agent is, and whether they may connect. The hoop.dev Sidecar, a proxy in front of your database or API, decides what each statement does once they are connected. It can [refuse it](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/policy-rules.md), [mask what comes back](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/config-file.md#masking), [hold it for an approver](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/risk-analysis.md#holding-a-statement-for-a-person) and [record it](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/config-file.md#audit). The two meet at the approval step: the [Control Plane](https://mintlify.hoop.dev/docs/core-concepts/control-plane.md) signs approvers in through Okta and [reads their groups at each login](https://mintlify.hoop.dev/docs/control-plane/slack.md#3-give-approvers-their-groups), and those groups decide who may release a held statement. You keep Okta where it is and put the Sidecar in front of [PostgreSQL, MySQL, SQL Server, MongoDB, ClickHouse, HTTP APIs, SSH or an MCP server](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/config-file.md#listeners).

> [!NOTE]
>
> Last checked against Okta's documentation and ours on November 10, 2026. Okta ships often, so open the Okta pages linked below before you rely on a row about Okta.

***

## What does Okta decide, and what does the Sidecar decide?

Each request meets two kinds of check. Okta answers questions about the caller. The Sidecar answers questions about the statement. The table follows one statement from sign-in to the audit row. Sign-in uses the Control Plane's [identity provider settings](https://mintlify.hoop.dev/docs/control-plane/environment-variables.md#identity-provider), and the caller's name comes from the [lane's identity source](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/components.md#identity). Statements meet [guardrails](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/policy-rules.md) and the [analyzer](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/risk-analysis.md), responses meet [masking](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/config-file.md#masking), and every decision lands in the [audit trail](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/config-file.md#audit).

| Stage | Who decides | What it checks | When the answer is no |
| - | - | - | - |
| An approver signs in | Okta, through the Control Plane's OIDC sign-in | The person, under your Okta sign-on policy | Okta refuses the sign-in |
| Groups reach hoop.dev | Okta's `groups` claim, read by the Control Plane | Group membership, at each login | A removed group stops counting at the next login |
| A client connects | The Sidecar listener | The caller's name: the Postgres `user`, or a header your proxy sets | No name runs as `anonymous`, and your policy decides |
| Each statement | Guardrails and OPA in the Sidecar | The operations, tables, words and patterns your rules name | Refused with the message your rule sets |
| A risky statement | The analyzer, then the level's approver | The risk level, then an approval agent or a person in the level's groups | Rejected, or held until someone approves |
| Each response | Mask rules in the Sidecar | The entity types and columns your rules name | Masked before the client reads it |
| The record | The Sidecar's audit trail | Session start, each statement or denial, masking, session end | A denial is written as a `violation` event |

***

## What does Okta already cover?

Okta covers a lot of this ground, and a team that runs it well has most identity questions answered:

* **Agents as identities.** [Okta for AI Agents](https://www.okta.com/products/govern-ai-agent-identity/) registers agents in Universal Directory with a human owner, issues them short-lived tokens, and governs them with certifications, approval workflows and deactivation.
* **Tool calls through MCP.** [Agent Gateway](https://developer.okta.com/docs/concepts/agent-gateway/) is, in Okta's words, "an identity-native proxy that sits between AI agents and the enterprise tools that they call." It attributes each tool call to the agent's identity, and an admin picks the tools each connection exposes. Its docs describe remote MCP servers that accept OAuth bearer tokens, not servers on a private network. Okta's [September 22 announcement](https://www.okta.com/newsroom/press-releases/ai-innovations-oktane-2026/) said it was planned for general availability in Q3, and its docs page states no status.
* **Database credentials for people.** [Okta Privileged Access](https://www.okta.com/blog/product-innovation/opa-securing-databases/) vaults and rotates shared database passwords for PostgreSQL, MySQL, SQL Server, MongoDB, MariaDB and Oracle, with time-bound checkout and MFA on each request.

Those answers stop at the connection. Okta's docs describe who connects, which tools an agent may call, and which database account a person checks out. They do not describe reading the statements inside a database session, masking values in a result, or holding one statement for a person. That is the layer the Sidecar adds, and it runs behind Okta.

***

## When is Okta enough on its own?

Pick by the question you need answered:

* **Which agents exist, who owns them, and how to switch one off:** Okta for AI Agents.
* **Which SaaS tools an agent may call through a remote MCP server:** Okta Agent Gateway.
* **Which person may check out a shared database password, and for how long:** Okta Privileged Access.
* **Whether a `DROP` or `DELETE` runs on this database at all:** the Sidecar, with an [operation guardrail](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/policy-rules.md#operation).
* **Whether an email address leaves the database in a result:** the Sidecar, with a [mask rule](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/config-file.md#masking) on `EMAIL_ADDRESS`.
* **Whether the payments team approves an `UPDATE` first:** the Sidecar, with an [approver per risk level](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/risk-analysis.md#holding-a-statement-for-a-person) whose groups come from Okta.
* **An agent that runs SQL against a database, not through MCP:** the Sidecar. Agent Gateway's docs cover MCP tool calls.

If every answer you need is in the first three lines, Okta covers you. The Sidecar earns its place from the fourth line down.

***

## How do Okta groups decide who approves a held statement?

This is where the two products connect today. The Control Plane signs approvers in with OIDC, Okta sends their groups at each login, and each listener names the groups that may approve each risk level.

**1. Create the Okta application**

In Okta, create an OIDC web application with the sign-in redirect `{API_URL}/api/callback`, and copy its client ID and secret, as in [Okta](https://mintlify.hoop.dev/docs/setup/configuration/idp/okta.md). Then, on the authorization server you use as the issuer (`default`, for example):

* **Add a `groups` claim** to the ID token, with the value type **Groups**, so Okta sends each user's groups.
* **Assign an access policy to the application**, with a rule that allows the Authorization Code grant. Without one, Okta refuses the sign-in with "Policy evaluation failed".

> [!NOTE]
>
> Tested on November 13, 2026 with an Okta Integrator org and Control Plane 1.309.2: the sign-in worked, and the user arrived in hoop.dev with their Okta groups.

**2. Point the Control Plane at Okta**

Set the [identity provider variables](https://mintlify.hoop.dev/docs/control-plane/environment-variables.md#identity-provider). Any `IDP_*` variable switches sign-in from local users to OIDC.

```bash theme={"dark"}
IDP_ISSUER='https://<your-okta-domain>/oauth2/default'
IDP_CLIENT_ID='<client-id>'
IDP_CLIENT_SECRET='<client-secret>'
IDP_GROUPS_CLAIM='groups'
```

`IDP_GROUPS_CLAIM` defaults to `https://app.hoop.dev/groups`. Okta sends groups in `groups`, so set it. At startup, the Control Plane prints the redirect it resolved: `loaded oidc provider configuration, redirect-url=...`.

**3. Name the Okta groups that approve each level**

In the listener's analyzer, give each held level an approver. A `human` level names groups. An approver is a user [in a group the rule names](https://mintlify.hoop.dev/docs/control-plane/slack.md#3-give-approvers-their-groups), so write the Okta group names as Okta sends them.

```yaml config.yaml theme={"dark"}
listeners:
  - name: payments
    protocol: postgres
    # ...
    analyzer:
      trigger: {operations: [update, delete]}
      high: require_approval
      medium: require_approval
      low: allow
      approvers:
        high:   {type: human, groups: [payments-approvers]}
        medium: {type: ai_agent, prompt: "Approve a write only when it names its rows by id."}
```

A `human` level files its request with the Control Plane, which checks the approver's groups. An `ai_agent` level is decided in the Sidecar at once and files nothing. `approvers` needs Sidecar 1.297.0 or later. See [Holding a statement for a person](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/risk-analysis.md#holding-a-statement-for-a-person).

**4. Approve where people already work**

Connect [Slack](https://mintlify.hoop.dev/docs/control-plane/slack.md), so approvers click **Approve** in a channel. The Control Plane matches the Slack user to a hoop.dev user by Slack ID, then by email, and checks the group.

With Okta as the identity provider, the [first login creates the user](https://mintlify.hoop.dev/docs/control-plane/slack.md#3-give-approvers-their-groups), so nobody needs an invitation. A group change in Okta reaches hoop.dev at the approver's next login.

> [!NOTE]
>
> The approval agent on a `medium` level reads the statement as untrusted data and must call `approve` or `reject` with a reason code. Anything else rejects, so it [fails closed](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/risk-analysis.md#the-approval-agent). The client sees the code, such as `(unbounded_scope)`, and never the agent's text.

***

## How does the Sidecar know which agent or engineer sent a statement?

An Okta token proves who the caller is to services that check Okta tokens. The Sidecar reads a name from the connection, and the [source depends on the lane](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/components.md#identity):

| Lane | Where the name comes from |
| - | - |
| `postgres` | The `user` the client names when it connects |
| `http`, `grpc`, `spanner` | A header your authenticating proxy sets, named by `identity_header` |
| `http` | A Google bearer token, checked with [`google_identity`](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/protocols/http#google-identity) |
| `mcp` | A header, or the `name` of a [`caller_token`](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/protocols/mcp#caller-token) |
| `ssh` | The certificate the lane verified |

For an Okta identity, the documented pattern is a proxy in front that authenticates the caller and sets a header, and a Sidecar listener that trusts that header:

```yaml config.yaml theme={"dark"}
listeners:
  - name: payments-api
    protocol: http
    listen: 127.0.0.1:18080
    upstream: payments:8080
    identity_header: x-hoop-user      # trust only behind an authenticating proxy
```

The header proves nothing on its own. [`identity_header`](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/protocols/http#identity) verifies nothing, so any process that reaches the port can claim any name. Bind the listener to loopback or a unix socket, behind the proxy that checked the caller. A request without the header runs as `anonymous`, and a policy that needs a named caller must deny `input.context.principal == "anonymous"` itself.

The Sidecar does not check Okta tokens itself. Use the authenticating proxy you already run in front of the service, and let it pass the verified name in the header.

On a Postgres lane, the name is the `user` the client sends when it connects.

***

## Can an AI agent go around the Sidecar?

Only if the network lets it. The Sidecar decides on the traffic that passes through it. A database credential used from a host that reaches the database directly skips every rule on this page, whoever issued that credential.

The integration guides close that path with the network. On [Claude Managed Agents](https://mintlify.hoop.dev/docs/integrations/claude-managed-agents.md#why-the-agent-cannot-skip-the-sidecar), the sandbox reaches the Sidecar's host and no other. On [Amazon Bedrock AgentCore](https://mintlify.hoop.dev/docs/integrations/aws-agentcore.md#why-the-agent-cannot-skip-the-sidecar), four VPC controls do the same, and a CI check fails if one goes away. In both, the network closes the path, and the Sidecar decides on what reaches it. Plan the network for your own agents the same way.

***

## What happens when something in the chain fails?

Every row below comes from the page linked beside it.

| What fails | What happens | Source |
| - | - | - |
| The Control Plane is unreachable, on a listener that holds for a person | Every statement that listener would hold is denied | [Control Plane](https://mintlify.hoop.dev/docs/core-concepts/control-plane.md) |
| The Control Plane is unreachable, on any other listener | The Sidecar keeps serving with the configuration it holds | [Control Plane](https://mintlify.hoop.dev/docs/core-concepts/control-plane.md) |
| Nobody approves within 30 minutes | The statement times out. Once someone approves, an identical retry runs once | [Control Plane](https://mintlify.hoop.dev/docs/core-concepts/control-plane.md) |
| The approval agent's model times out, refuses or errors | The agent rejects with `the approval agent did not decide` | [The approval agent](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/risk-analysis.md#the-approval-agent) |
| A request arrives without the identity header | It runs as `anonymous`, and your policy can refuse it | [HTTP identity](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/protocols/http.md#identity) |
| Someone leaves an Okta group | They stop approving for that group at their next login | [Slack approvals](https://mintlify.hoop.dev/docs/control-plane/slack.md#3-give-approvers-their-groups) |
| An audit record cannot be written | The statement runs and the error is logged, unless `fail_closed: true` | [Audit](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/config-file.md#audit) |

***

## What does each audit trail record?

Okta's [System Log](https://developer.okta.com/docs/reference/api/system-log/) "records system events that are related to your organization in order to provide an audit trail." That is where sign-ins and group changes in your Okta org show up.

The Sidecar's [audit trail](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/config-file.md#audit) writes six kinds of event: `session_start`, `statement`, `violation`, `masked`, `error` and `session_end`. Each carries the caller's name, the protocol and the listener. A denial is written as a `violation`, so a security team can select denials without reading every statement. A masked value is recorded as masked, never as the value.

A level the approval agent decides adds `approver: ai_agent`, `approval_decision` and `approval_reason_code` to the statement's event. The agent's own reason is kept only after the [PII detector redacts it](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/risk-analysis.md#the-approval-agent).

Read the two side by side. Okta shows who signed in and which groups they held. The Sidecar shows what ran under that name, what was refused and who released it.

***

## Can MCP clients sign in to the Sidecar with Okta?

Not yet. The Sidecar's MCP lane names a caller by a header or a [caller token](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/protocols/mcp.md#caller-token). Its docs list "a verified identity per user, and OAuth login of MCP clients" as [not supported yet](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/protocols/mcp.md#auth).

Today the lane [hides and refuses the tools](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/protocols/mcp.md#tool-allow-and-deny) a rule denies. It records [one audit session per MCP session](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/protocols/mcp.md#sessions-and-audit), [masks tool results](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/protocols/mcp.md#masking), and lets the [AI analyzer](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/protocols/mcp.md#ai-analyzer) block a risky call. It cannot hold a call for approval yet. See [Limits](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/protocols/mcp.md#limits).

Two paths sign MCP clients in with Okta today:

* **The hoop.dev Gateway**, the earlier architecture, sends MCP clients to your identity provider for OAuth. If your Okta org does not offer dynamic client registration, pre-register an OIDC application for the client. See [MCP server configuration](https://mintlify.hoop.dev/docs/setup/configuration/mcp-server-configuration.md) and the [Gateway overview](https://mintlify.hoop.dev/docs/gateway/overview.md).
* **Okta Agent Gateway**, for agents that call remote MCP servers that accept OAuth bearer tokens. See [Okta's docs](https://developer.okta.com/docs/concepts/agent-gateway/).

***

## Free and Enterprise

The Sidecar runs free from a config file. Okta sign-in, approver groups and human approval live in the [Control Plane](https://mintlify.hoop.dev/docs/core-concepts/control-plane.md), which is Enterprise. An `ai_agent` approval level is decided in the Sidecar and needs no Control Plane.

> [!NOTE]
>
> **Free tier:** one Sidecar per organization, with one Guardrail, one Data Masking rule and one Access Request rule. The Sidecar logs in to join your organization. More than one rule per feature, more than one Sidecar, or your own Control Plane needs [Enterprise](https://hoop.dev/start).

***

## Next

> [card] [Risk Analysis](https://mintlify.hoop.dev/docs/setup/configuration/hoop-sidecar/risk-analysis.md)
>
> Risk levels, approvers per level and the approval agent.

> [card] [Identity Provider Variables](https://mintlify.hoop.dev/docs/control-plane/environment-variables.md#identity-provider)
>
> The `IDP_*` settings that point the Control Plane at Okta.

> [card] [Slack Approvals](https://mintlify.hoop.dev/docs/control-plane/slack.md)
>
> Approve held statements in a channel, with groups from Okta.

> [card] [hoop.dev vs Teleport](https://hoop.dev/compare/hoop-vs-teleport)
>
> Run Teleport too? See what each one decides.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.