> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-harris-1786029617-6b0a55e.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Add identity to Managed Deep Agents

> Authenticate callers and expose verified identity to threads, tools, and middleware.

Identity authenticates callers to a Managed Deep Agents deployment. When you declare identity, Managed Deep Agents gives each caller private threads and exposes the verified caller to tools and middleware.

<Note>
  Managed Deep Agents is in **public [beta](/langsmith/release-stages)** and available on [LangSmith Cloud](/langsmith/cloud) in the US region only.
</Note>

## Add identity

Create `identity.py` or `identity.ts` at the project root and export a named `identity` declaration:

<CodeGroup>
  ```python identity.py theme={null}
  from managed_deepagents import define_identity

  identity = define_identity()
  ```

  ```ts identity.ts theme={null}
  import { defineIdentity } from "managed-deepagents";

  export const identity = defineIdentity();
  ```
</CodeGroup>

This declaration uses backend authentication, the default. The only configurable identity option is `auth`, which controls how Managed Deep Agents authenticates callers.

Managed Deep Agents supplies the remaining identity behavior:

* **Threads**: Each thread belongs to the authenticated caller. Requests cannot select another caller's thread owner.
* **Runtime identity**: Tools and middleware receive the verified caller through `runtime.identity`.

Identity does not configure durable memory or downstream connections. Do not pass `scope`, `credentials`, `connect`, or memory options to `defineIdentity(...)` or `define_identity(...)`.

<Note>
  Adding identity to an existing deployment does not add owner metadata to existing threads. Plan and test a migration before relying on identity-based access for those threads.
</Note>

## Choose how callers authenticate

The `auth` option supports two patterns:

* **Backend authentication**: Your backend authenticates the caller and sends trusted identity headers. This is the default.
* **Validated-token authentication**: The caller sends an identity-provider token that Managed Deep Agents verifies.

### Use backend authentication

Use backend authentication when your application server already authenticates users through a session, OAuth flow, or another mechanism. Your server proxies requests to the deployment with these headers:

| Header                 | Purpose                                                              |
| ---------------------- | -------------------------------------------------------------------- |
| `X-MDA-Ingress-Secret` | Shared secret that must match the deployment's `MDA_INGRESS_SECRET`. |
| `X-MDA-User-Id`        | Stable identifier for the authenticated caller.                      |

The argument-free declaration selects this mode. You can also set it explicitly:

<CodeGroup>
  ```python identity.py theme={null}
  from managed_deepagents import define_identity

  identity = define_identity(auth="backend")
  ```

  ```ts identity.ts theme={null}
  import { defineIdentity } from "managed-deepagents";

  export const identity = defineIdentity({ auth: "backend" });
  ```
</CodeGroup>

After your backend authenticates the caller, forward the request with the reserved headers:

```ts theme={null}
await fetch(`${deploymentUrl}/threads/${threadId}/runs`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-MDA-Ingress-Secret": process.env.MDA_INGRESS_SECRET!,
    "X-MDA-User-Id": authenticatedUser.id,
  },
  body: JSON.stringify(runBody),
});
```

Set `MDA_INGRESS_SECRET` as a hosted deployment secret. `mda dev` configures local identity automatically, so local Studio requests do not require these headers.

<Warning>
  Send `MDA_INGRESS_SECRET` only from a trusted backend. Do not expose it in browser code or commit it to source control.
</Warning>

Backend authentication accepts only the caller id from the public identity headers. It does not accept groups, email, organization, or arbitrary claims from the client.

### Use validated-token authentication

Use validated-token authentication when a browser or another client calls the deployment directly. The client sends:

```http theme={null}
Authorization: Bearer <token>
```

Managed Deep Agents verifies the token and maps its claims to the caller identity.

As a first party example, use `auth.supabase(...)` to authenticate callers with Supabase.

#### Authenticate with Supabase

Configure Supabase with a project reference or project URL:

<CodeGroup>
  ```python identity.py theme={null}
  from managed_deepagents import auth, define_identity

  identity = define_identity(
      auth=auth.supabase(project_ref="your-project-ref"),
  )
  ```

  ```ts identity.ts theme={null}
  import { auth, defineIdentity } from "managed-deepagents";

  export const identity = defineIdentity({
    auth: auth.supabase({ projectRef: "your-project-ref" }),
  });
  ```
</CodeGroup>

After signing in with Supabase Auth, send the user's access token in the `Authorization` header. By default, Managed Deep Agents verifies JWTs against Supabase JWKS. Pass `url` for a custom auth domain.

## Use `runtime.identity`

Tools and middleware receive a frozen identity object built from the trusted authentication result. Client-supplied identity keys in the normal configurable payload are not trusted.

The identity contains:

* **`user`**: The caller's `id`, `kind`, and optional `email`.
* **`groups`**: Optional group memberships mapped from a validated token.
* **`source`**: The run's ingress provider and optional source thread id.
* **`claims`**: Optional verified token claims.

Use `ManagedDeepAgentRuntime` for typed access:

<CodeGroup>
  ```python tools/whoami.py theme={null}
  from langchain.tools import tool
  from managed_deepagents import ManagedDeepAgentRuntime


  @tool
  def whoami(runtime: ManagedDeepAgentRuntime) -> str:
      """Return the authenticated user id for this run."""
      identity = runtime.identity
      if not identity:
          return "No authenticated caller on this run."
      return f"Signed in as {identity['user']['id']}"
  ```

  ```ts tools/whoami.ts theme={null}
  import { tool } from "langchain";
  import type { ManagedDeepAgentRuntime } from "managed-deepagents";
  import { z } from "zod";

  export const whoami = tool(
    async (_input, runtime: ManagedDeepAgentRuntime) => {
      const identity = runtime.identity;
      if (!identity) {
        return "No authenticated caller on this run.";
      }
      return `Signed in as ${identity.user.id}`;
    },
    {
      name: "whoami",
      description: "Return the authenticated user id for this run.",
      schema: z.object({}),
    },
  );
  ```
</CodeGroup>

In Python, read the optional source thread as `runtime.identity["source"]["thread_id"]`. In TypeScript, read it as `runtime.identity.source.threadId`.

Use verified identity for personalization, audit records, and authorization decisions. Do not trust a user id supplied in a tool argument or request body.

## Understand identity boundaries

Identity provides a fixed user boundary rather than configurable scope axes:

* Threads are always per caller.
* Validated-token groups and claims are available for authorization logic, but they do not change thread ownership.
* Durable memory is configured in `memory.py` or `memory.ts` and is shared across the deployment.

## Test and deploy

Test the project locally with [`mda dev`](/langsmith/managed-deep-agents-cli#develop-locally), then deploy it with [`mda deploy`](/langsmith/managed-deep-agents-deploy). Open deployment traces in LangSmith to inspect model calls, tool calls, errors, and latency.

Authentication failures return 401. Attempts to access another caller's thread return 403. For backend authentication, confirm that the deployment has `MDA_INGRESS_SECRET` and that your proxy sends both reserved headers.

***

<div className="source-links">
  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>

  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/langsmith/managed-deep-agents-identity.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>