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

# Agent authentication

> Let an Agent you run call tools for people in your workspace with their own Okta access tokens.

> [!WARNING]
>
> **Beta:** This requires the [Agents beta](https://pipedream.com/docs/conduit/use/agents.md). Test with one Agent,
> one person and a harmless tool, following
> [Connect an Agent with Okta](https://pipedream.com/docs/conduit/configure/agent-authentication/okta.md), before
> giving an Agent access for more people.

An Agent signs a person in at Okta and sends Conduit that person's Okta **user
access token**. Conduit verifies the token itself, works out which Agent sent
it and which person it acts for, and runs only the tools both may use. Okta
issues and renews the tokens; Conduit keeps none of them.

An Agent's request runs only while all of these hold:

* **External agent access** is on for the instance.
* The person's Okta or Custom OIDC sign-in provider is enabled, and its
  **Agent access** is on.
* The Agent is switched on, and its Okta app is approved for it.
* The person is in the workspace and has signed in to Conduit through that
  provider, in a way the workspace's sign-in settings accept.
* The Agent's [Delegation](https://pipedream.com/docs/conduit/use/agent-access.md#delegation) includes the person.
* The tool is allowed both for the person and by the Agent's groups.

## Who approves

Approving trusts a set of Okta tokens to act for people, so it takes a
workspace owner: turning on, creating or changing a provider's Agent access,
and approving an Agent's Okta app. Every workspace admin can switch a
provider's Agent access off without other changes and remove an Agent's app,
so stopping access never waits for an owner. Admins also create Agents,
switch them on and off, and choose their groups and Delegation.

An instance provider is the instance's to vouch for: Agent access through
one, and the apps of Agents using it, are approved by an instance
administrator, and only in a workspace that accepts that provider for
sign-in. Instance administrators can approve in every workspace.

An instance administrator also controls **External agent access**, at the
top of **Agents**. It's off by default. Turning it off pauses every Agent in
every workspace and keeps their configuration. Upgrade every replica to the
current release before turning it on.

## Turn on Agent access for a sign-in provider

As a workspace owner, open **Settings → Sign-in**, find your Okta or Custom
OIDC provider, and choose **Agent access** from its menu.

1. Turn on **Allow Agent access with this provider**.
2. Conduit uses the provider's own issuer when it is an Okta custom
   authorization server (`https://company.okta.com/oauth2/<server-id>`).
   Otherwise, turn on **Use a different Okta authorization server** and enter
   the **Access-token issuer**: a custom authorization server on the same Okta
   domain as the provider.
3. Select **Save**. Reopen **Agent access** and select **Check signing keys**
   to confirm Conduit can fetch the issuer's keys.
4. [Check the claims in Okta](#check-the-claims-in-okta) before you rely on it.

The dialog shows the **Access-token audience**, the **MCP server URL** and the
**Required scope**; give them to the Agent's developer. Conduit fetches signing
keys from the issuer's `/v1/keys` endpoint. Each issuer serves one provider's
Agent access in a workspace. Browser sign-in keeps its own client, redirect
URI and scopes, and each Agent signs people in with its own Okta app.

The provider's row on **Sign-in** reads **Agent access enabled**, **Agent
access paused** or **Agent access needs review**.

### How Conduit finds the person

Okta puts the person's Okta user ID (it normally begins with `00u`) in a
different claim in each token. An Agent's access token carries it as `uid`;
its `sub` is the person's Okta username, often an email address, which can
change. The ID token of their Conduit sign-in carries it as `sub`. Conduit
matches the access token's `uid` with the `sub` of the person's sign-in
through the provider, so there is nothing to configure, and an email never
identifies anyone.

### Check the claims in Okta

1. In the Okta Admin Console, open **Security → API → Authorization Servers**.
   Select the server used by Conduit's browser sign-in and open **Token
   Preview**.
2. Select the **Conduit browser application**, **Authorization Code**, a test
   person, and the scopes `openid email profile`. Preview the **ID token** and
   note its `sub`.
3. Open **Token Preview** on the Agent's authorization server. Select the
   **Agent application**, the same person and grant, and the scopes
   `openid conduit:connectors`. Preview the **access token** and note `uid`.
4. Check that both values are the person's Okta user ID: find the person under
   **Directory → People**, where the profile URL contains it (it normally
   begins with `00u`). Repeat with a second person; each pair matches, and
   the two people's IDs differ.

Compare the Conduit browser app's ID token with the Agent app's access token:
they are separate applications. If browser sign-in uses Okta's org
authorization server, which Token Preview doesn't cover, inspect a real
browser ID token with your usual OIDC diagnostics. Okta's
[Token Preview guide](https://help.okta.com/oie/en-us/content/topics/security/api-config-test.htm)
shows the controls, and its
[token reference](https://developer.okta.com/docs/api/openapi/okta-oauth/guides/overview#reserved-claims-in-the-payload-section)
defines `uid`. A preview checks configuration; a real sign-in and a permitted
tool call test the integration.

## Approve the Agent's Okta app

On the Agent's page in **Agents**, a workspace owner selects **Configure
authentication** under **Authentication**, chooses the **Sign-in provider**
and enters the **Agent OAuth client ID** of the Agent's Okta app. Each Agent
has one Okta app, and an app identifies one Agent in a workspace. To move an
Agent to another provider, remove its app and approve it again there.

Then set the Agent's [Tool access and Delegation](https://pipedream.com/docs/conduit/use/agent-access.md) and switch
it on.

## The people an Agent acts for

An Agent acts for someone through the Conduit account they signed in to
through the provider. Conduit matches the token's `uid` with that sign-in, so
each person signs in to Conduit through the provider at least once. This uses
their existing account for that provider, including a SCIM-provisioned account
once sign-in establishes its identity. A password-only account, including one
created by accepting an invite, stays separate even if its email matches.
Tools and connected accounts on that separate account do not carry over. The
Agent uses the tools and accounts on the account signed in through the provider.

The workspace's sign-in settings apply as if the person signed in directly:

* The workspace must accept sign-in through the provider. When it accepts an
  instance provider only for its own domains, the person's verified email must
  be in one of them. Owners are exempt, as when they sign in themselves.
* When the workspace asks people to sign in again after a set time, the
  token's `auth_time` must fall within it. Okta keeps the original `auth_time`
  when it refreshes a token, so once that time passes the person signs in at
  Okta again and the Agent uses the new token.

## Send the access token

The Agent's backend gets user access tokens with
[Authorization Code with PKCE](https://developer.okta.com/docs/guides/implement-grant-type/authcodepkce/main/),
requesting `openid conduit:connectors`, and sends each request to the
workspace's MCP server URL:

```text theme={null}
Access-token audience: https://conduit.example.com/mcp
MCP server URL:        https://conduit.example.com/mcp/WORKSPACE_ID
Authorization:         Bearer <Okta user access token>
```

Conduit accepts a token with:

* an RS256 signature from the approved issuer's keys;
* exactly one audience, the access-token audience;
* the scope `conduit:connectors`;
* the person's `uid` and the approved Agent app's `cid`;
* integer `iat` and `exp`, at most 15 minutes apart.

ID tokens, Client Credentials tokens, tokens from Okta's org authorization
server and tokens for other APIs are refused, as is any token carrying an
`act`, `may_act` or `cnf` claim. A token sent to `/mcp` itself gets **400**
`invalid_request` naming the workspace URL to use. The Agent's client secret
and refresh tokens stay in its backend.

## What an Agent can use

An Agent lists and calls remote tools, including through Conduit's
`list_available_tools`, `describe_tools` and `call_tool`. Prompts, resources,
MCP Apps, local tools, Conduit's administration tools, sampling and
elicitation are for people's own assistants; for an Agent, prompt and resource
lists are empty and the rest is refused. Agents are managed on **Agents**: the
**MCP Clients** page and its client rules cover people's assistants.

## Pause and stop access

Switching off a provider's Agent access, the provider itself, an Agent or
**External agent access** is enforced before a tool result is delivered;
an idle stream can take up to five seconds to end. A request whose response
hasn't started gets
**403**, and an open stream ends. New requests get **403**, or **401** while
**External agent access** is off, when Conduit accepts no Agent tokens.
Switching it back on accepts tokens that haven't expired yet. Tool and
permission changes apply within five seconds. A side effect an upstream app
already accepted can't be undone.

To stop an Agent acting for one person, remove them, or their group, from its
Delegation.

Editing a provider's issuer or client ID marks its Agent access **needs
review** and pauses it until an owner opens **Agent access** and saves it
again; each person then signs in through the provider once more. Deleting a
provider deletes its Agent access and the Okta apps approved through it.

Open streams are rechecked every five seconds and end when the token expires;
the Agent reconnects with a fresh token. Each Agent holds at most eight open
streams for one person on each Conduit server; beyond that, a new stream gets
**429** with `Retry-After`.

## Security limits

* **Okta revocation reaches Conduit at expiry.** Conduit verifies tokens
  itself, so a token revoked at Okta (by logout, revocation or a policy
  change) works until it expires. Keep lifetimes short; Conduit refuses
  lifetimes over 15 minutes.
* **A removed signing key can verify for up to 5 minutes.** After removing a
  compromised key at Okta, select **Check signing keys** in the provider's
  **Agent access**: every Conduit server drops its cached keys at once.
* **Tokens are bearer tokens.** They aren't sender-constrained
  ([RFC 9700 §2.2.1](https://www.rfc-editor.org/rfc/rfc9700.html#section-2.2.1)):
  anyone holding one can use it until it expires. Keep tokens in the Agent's
  backend, out of browsers and logs.
* **A token works in every workspace that approved its app.** Its audience is
  the instance's MCP address, so any workspace on the same instance that
  approved the same Okta app through the same issuer accepts it for the same
  person. Each workspace approves an app separately, so nobody can extend an
  Agent to another workspace alone. Give each Agent its own Okta app in each
  workspace.

The audit log records each change to Agent access and each tool call an Agent
runs, naming the Agent and the person and never the tool's arguments or
results. A refused call is recorded as a policy denial naming the Agent.
Calls whose results are withheld after cancellation, expiry or an access
change are recorded as failures. The connected service may still have made
changes before the call ended.

## Troubleshooting

| Response | What to check |
| - | - |
| 401 `invalid_token` | The token: signature, issuer, audience, lifetime, expiry during the request, or a signing key the issuer has since replaced; or Conduit doesn't accept it here: **External agent access** is off, or the provider's Agent access or the Agent's app isn't approved in this workspace |
| 403 | A valid token Conduit won't act on: the person hasn't signed in through the provider, the provider's Agent access, the provider or the Agent is off or needs review, the workspace's sign-in settings refuse the sign-in, or Delegation leaves the person out. A new token from the same sign-in doesn't help |
| 403 `insufficient_scope` | The token lacks `conduit:connectors` |
| 400 `invalid_request` | The request went to `/mcp`; use the MCP server URL |
| 429 on a stream | Too many open streams for this Agent and person; close one |
| 503 | Conduit can't reach the issuer's signing keys, or couldn't check the token; retry after `Retry-After` |
| Empty tool list | The person's own tools and policies, and the Agent's groups |
| Connection required | The person connects the account on **Home** |
