vetta identity

A persona is a durable identity an agent can act as — with its own inboxes, phone numbers, connections, and 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, identity phone, and identity connections below.

create, list, show, update, delete

vetta identity create --name "Ava Sales" --description "Outbound SDR persona"
vetta identity list --limit 2

{
  "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

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:

vetta identity agents idn_...   # agents that hold this persona
vetta agent identities agt_...  # personas this agent holds

{ "data": [], "has_more": false, "next_cursor": null }

--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.

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.

vetta identity connections configs

{ "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:

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:

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`

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.

Getting started

Building & running

Organization

Identity

vetta identity

Commands

create, list, show, update, delete

Granting a persona to an agent

Connections

​Commands

​create, list, show, update, delete

​Granting a persona to an agent

​Connections

Commands

create, list, show, update, delete

Granting a persona to an agent

Connections