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

# Social accounts

> Connect social accounts to a Vetta identity and let its agent publish under policy.

Social accounts belong to an **identity**. If Ava and Billing are two identities in the same
organization, they activate and connect separate social workspaces. An agent can publish only when
its session selected the identity that owns those accounts.

The setup flow is short:

1. Activate Social for the identity with `POST /v1/identities/{id}/social/activate`.
2. Create a hosted portal link with `POST /v1/identities/{id}/social/portal`.
3. Give the returned URL to the person who owns the accounts.
4. Poll `GET /v1/identities/{id}/social/accounts`; it reads the provider's current state.

Vetta never receives an OAuth token. It stores only which remote workspace belongs to the identity;
the provider holds and refreshes account grants.

The Worker must have `VETTA_SOCIAL_API_KEY` configured. This is the Bundle Social API key, not the
generic Composio connections key. Without it, activation fails closed with `feature_not_configured`.

## Agent tools

When a session selects an activated identity, its harness receives two tools:

* `social.accounts` lists connected accounts.
* `social.post` publishes or schedules a text post.

`social.post` defaults to `ask`, including when the agent's default tool policy is `allow`. Set an
explicit policy for `social.post` if the agent should always be allowed or denied. A session with no
selected identity receives neither tool.

Publishing supports text and URL-backed media on Bluesky, Facebook, LinkedIn, Mastodon, Threads,
and X. The account portal also connects Instagram, TikTok, YouTube, Pinterest, and Reddit. The API
can read account/post analytics and post comments, and can delete a post after verifying it belongs
to the identity's provider workspace.

<Card title="Social API" icon="share-nodes" href="/docs/api/social">
  Activate a workspace, connect accounts, and publish text posts.
</Card>