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

# vetta identity

> Personas, the agents that hold them, and OAuth connections.

A **persona** is a durable identity an agent can act as — with its own inboxes, phone numbers, connections, and [vault](/docs/cli/vault). Agents hold personas through a *grant*, not as a field on the agent.

## Commands

| Command                      | Description                              |
| ---------------------------- | ---------------------------------------- |
| `vetta identity create`      | Create a persona.                        |
| `vetta identity list`        | List personas.                           |
| `vetta identity show <id>`   | Show one persona.                        |
| `vetta identity update <id>` | Update name or description.              |
| `vetta identity delete <id>` | Delete a persona.                        |
| `vetta identity agents <id>` | List agents granted this persona.        |
| `vetta identity attach`      | Grant a persona to an agent.             |
| `vetta identity detach`      | Revoke the grant.                        |
| `vetta identity connect`     | Start an OAuth connection for a persona. |
| `vetta identity disconnect`  | Revoke a connection.                     |

Sub-groups have their own pages: [`identity domain` and `identity email`](/docs/cli/comms), [`identity phone`](/docs/cli/phone), and `identity connections` below.

## create, list, show, update, delete

```bash theme={"system"}
vetta identity create --name "Ava Sales" --description "Outbound SDR persona"
vetta identity list --limit 2
```

```json theme={"system"}
{
  "data": [
    {
      "id": "idn_6sc5s97c5jt1ds84qngajv659p",
      "object": "identity",
      "name": "Ava Sales",
      "description": "Outbound SDR persona",
      "emails": [],
      "phones": [],
      "domains": [],
      "connections": [],
      "metadata": {},
      "created_at": "2026-08-22T23:47:54.081Z",
      "updated_at": "2026-08-22T23:47:54.081Z"
    }
  ],
  "has_more": true,
  "next_cursor": "idn_sxassvr215v63cx94nfx9nn3gx"
}
```

`create` and `update` take `--name` and `--description`. `show` and `delete` take the id positionally and accept no flags. The `emails`, `phones`, `domains`, and `connections` arrays are the persona's attached channels — populated by the sub-groups.

## Granting a persona to an agent

```bash theme={"system"}
vetta identity attach --agent agt_kt88353jaw132sjakt4sytz4a6 --identity idn_6sc5s97c5jt1ds84qngajv659p
vetta identity detach --agent agt_... --identity idn_...
```

| Flag         | Description            |
| ------------ | ---------------------- |
| `--agent`    | Agent id (required).   |
| `--identity` | Persona id (required). |

The grant is a two-sided edge, so both sides are named on the command that makes it, and you can read it from either end:

```bash theme={"system"}
vetta identity agents idn_...   # agents that hold this persona
vetta agent identities agt_...  # personas this agent holds
```

```json theme={"system"}
{ "data": [], "has_more": false, "next_cursor": null }
```

<Warning>
  `--identity` on `vetta agent create` is **not** supported and exits `2` with an explanation. A persona is granted with `vetta identity attach`, never set as a field on the agent. `vetta session create --identity …` *is* supported — that selects which already-granted persona a run acts as.
</Warning>

## Connections

An OAuth connection lets a persona act in a third-party tool.

| Command                                 | Description                                                              |
| --------------------------------------- | ------------------------------------------------------------------------ |
| `vetta identity connections apps`       | Search the app catalogue.                                                |
| `vetta identity connections app`        | Show one app: auth methods, default tools, what connecting will ask for. |
| `vetta identity connect`                | Start an OAuth flow for a persona.                                       |
| `vetta identity connections list`       | List a persona's connections.                                            |
| `vetta identity connections show`       | Show one connection.                                                     |
| `vetta identity connections configs`    | List the org's auth configs.                                             |
| `vetta identity connections config-add` | Register an auth config for a connector.                                 |
| `vetta identity connections config-rm`  | Remove an auth config.                                                   |
| `vetta identity disconnect`             | Revoke a connection.                                                     |

```bash theme={"system"}
vetta identity connections configs
```

```json theme={"system"}
{ "data": [], "has_more": false, "next_cursor": null }
```

An **auth config** is org-level: it holds the OAuth client for one app, and every persona connects through it. **There is no list of supported apps** — `--connector` takes an app id out of the catalogue, so start by searching it:

```bash theme={"system"}
vetta identity connections apps --search helpdesk
vetta identity connections app zendesk
```

`app` is worth reading before `config-add`: it prints which auth methods work (`managed_oauth` needs no credentials of your own), the operations that get pinned by default, and any value connecting will still ask for — an account subdomain, a region. `--auth` takes one of `managed_oauth`, `oauth`, `api_key`; anything else exits `2` and lists the valid values. Register the config once, then connect each persona:

```bash theme={"system"}
vetta identity connections config-add --connector zendesk --auth managed_oauth
vetta identity connect --identity idn_... --auth-config ac_... --field subdomain=acme
vetta identity connections show ca_...
vetta identity connections list --identity idn_...
vetta identity disconnect --connection ca_...
```

`connect` answers with a `connect_link`. Hand it to the person who owns the account; the connection stays `initiated` until they finish authorizing, and `connections show` is the poll that reconciles it — there is no webhook for this yet.

| Command                  | Flags                                                                                 |
| ------------------------ | ------------------------------------------------------------------------------------- |
| `connections apps`       | `--search`, `--limit`, `--after`                                                      |
| `connections app`        | `--app` (or a positional app id)                                                      |
| `connect`                | `--identity`, `--auth-config`, `--field` (repeatable, `name=value`)                   |
| `connections list`       | `--identity`                                                                          |
| `connections show`       | `--connection`                                                                        |
| `connections config-add` | `--connector`, `--auth`, `--scope` (repeatable), `--tool` (repeatable), `--client-id` |
| `connections config-rm`  | `--auth-config`                                                                       |
| `disconnect`             | `--connection`                                                                        |

<Note>
  `configs` returning an empty list means no app has been registered for this org yet — `connect` has nothing to connect *through* until `config-add` runs.
</Note>