# Team


# Team

One account, many people. Each member has their own API key (so their agent or MCP client shows
who they are), a role, and an optional monthly credit cap. Everything anyone makes (brand kits,
stored characters, styles, uploads, finished videos, posts) belongs to the account and is shared
with the team, with the member who made it recorded on it.

## Roles

| role | can |
|---|---|
| `admin` | Everything: invite and remove members, mint and revoke keys, approve posts, change account settings, plus all of creator. |
| `manager` | Everything a creator can, plus run one team: give teammates credit budgets, cap their keys, read the team's audit log. Needs governance (below). |
| `creator` | Make things (analyze, edit, record, generate, explainers, brand kits, characters) and draft posts. |
| `reviewer` | Read everything, approve or reject posts, file reports. Cannot create or spend. |

Account-level keys from before teams existed keep working: an admin key acts as `admin`, an agent
key as `creator`.

## Invite someone: `POST /v1/members` (admin)

```json
{ "name": "Urav", "email": "urav@example.com", "role": "creator", "monthlyCreditCap": 500 }
```

Returns the member, their API key **once**, and a `claimUrl`. Send the person the claim link: it shows
them the key one time and expires in 72 hours, so the key never passes through chat. They put it in
their own MCP client (`SECOND_STUDIO_API_KEY`) and are up: `GET /v1/me` shows their name, role and spend.
Keys made by an admin are active immediately.

**First member:** an account that has no members yet may create its first one from any account-level
key. It becomes the account's admin. That is how a new customer bootstraps their team on day one.

Member fields: `role`, `email`, `monthlyCreditCap`, `monthlyUsdCap`, `perJobUsdCap`, `allowedSocialAccounts`
(accountIds this person may post to), `webhookUrl` (POSTed a `job.finished` event when their jobs end).

- `GET /v1/members`: everyone, with role, live keys, cap and `spentThisMonth`.
- `POST /v1/members/{id}`: change `role`, `name`, `email`, `monthlyCreditCap` (`null` removes it). Changing the role re-scopes the member's keys at once.
- `DELETE /v1/members/{id}`: their keys stop working; what they made stays.
- `POST /v1/members/{id}/keys`: another key for the same person (e.g. a second agent).
- `GET /v1/keys` · `DELETE /v1/keys/{id}`: every live key on the account and whose it is.

## Spend control

Three caps, all checked **before** a job starts, from its estimate, with a `402 member_cap` that
says which cap, what's spent and what the job would cost:

- `monthlyCreditCap`: credits per month.
- `monthlyUsdCap`: estimated **provider dollars** per month. This is the one that matters on
  accounts that run on their own provider keys, where a job costs 1–4 credits of platform fee but
  real money at the provider (about $0.45 per character-sheet render, about $34 for a 30 s 1080p video).
- `perJobUsdCap`: no single job over this estimate.

`GET /v1/members` shows `spentThisMonth: { credits, usd }` per person; refunds for failed and
canceled jobs net out for the same person.

## Teams, budgets and audit (governance)

Teams and credit budgets are two separate switches. **Accounts created from now on have both on.**
Accounts created earlier keep exactly their current behavior until we enable one or both for them
(ask us); until then the endpoints for that feature answer `403 governance_disabled`.

With either on, people can also sign in (through Clerk, with Google, GitHub, Apple or email) to manage the
account; agents keep using API keys. A sign-in links to the member with the same verified email.
Apps use Clerk with Convex's `ConvexProviderWithClerk`:

```tsx
<ClerkProvider publishableKey={CLERK_PUBLISHABLE_KEY}>
  <ConvexProviderWithClerk client={convex} useAuth={useAuth}>
    <App />
  </ConvexProviderWithClerk>
</ClerkProvider>
```

**Teams.** Group members and give each team a manager. Admins create, rename and delete teams;
naming a manager makes that member a `manager` of the team. Deleting a team keeps its members on
the account, without a team, and revokes the team's budgets.

- `GET /v1/teams`: teams with their manager and members (any member).
- `POST /v1/teams` `{ "name": "Video", "managerMemberId": "…" }` (admin).
- `POST /v1/teams/{id}` `{ "name": "…", "managerMemberId": "…" | null }` (admin; `null` removes the manager, who becomes a creator).
- `DELETE /v1/teams/{id}` (admin).
- `POST /v1/members/{id}/team` `{ "teamId": "…" | null }` (admin).

**Invites** (teams on). Admins invite anyone, into any team; a manager invites creators and
reviewers into their own team. Every invite is in the audit log.

- `POST /v1/invites` `{ "email": "zed@example.com", "role": "creator", "teamId": "…", "expiresInDays": 14 }`:
  a pending membership. It becomes active the first time that person signs in with
  the same verified email. We do not send the email yet (the response says `"emailSent": false`),
  so tell the person yourself.
- `POST /v1/invites/links` `{ "role": "creator", "teamId": "…", "expiresInHours": 168, "maxUses": 1 }`:
  a shareable link. The token is shown once and only its hash is stored. Whoever opens it signs in
  and joins with that role and team, until it expires, runs out of uses or is revoked.
- `GET /v1/invites`: pending email invites and live links (managers see their team's).
- `DELETE /v1/invites/{id}`: revoke a link or cancel a pending email invite.

**Credit budgets.** A budget is a spend limit on the account balance, not extra credits. Give one
to a member or a whole team, per month (`"period": "month"`, resets on the 1st, UTC) or in total
(`"period": "total"`). Admins can budget anyone and any team; a manager can budget members of their
own team, but not themselves and not the team as a whole. Budgets are checked on the server when a
job or post is accepted, in the same step as the charge; going over answers
`402 budget_exceeded` with the scope (`member`, `team` or `key`), budget, amount spent and cost.
Refunds for failed jobs give the budget back.

- `GET /v1/allocations`: live budgets (all for admins, the team's for managers, your own otherwise).
- `POST /v1/allocations` `{ "memberId": "…", "credits": 500, "period": "month", "note": "…" }`, or `teamId` instead of `memberId`.
- `DELETE /v1/allocations/{id}`: revoke one.

**Key caps.** `POST /v1/keys/{id}/cap` `{ "creditCap": 200 }` sets a monthly credit cap on one API
key (`null` removes it), handy for an agent that should never spend more than a set amount.
Admins, or a manager for keys of their team.

**Audit log.** `GET /v1/audit` lists who changed what, newest first: governance switched on, team
changes, member roles and teams, budgets granted and revoked, key caps, Google sign-in links.
Admins see everything; managers see entries about their team.

**Your accounts.** `GET /v1/me/memberships` lists the accounts the person behind this key belongs
to (through their Google sign-in), with role and team.

## Who may change what

Everything is visible to every member. Changing or deleting a brand kit, skill, character or voice
is for admins and the member who created it. Removing a member keeps what they made.

Any member except a reviewer can connect a repository and run an index, within their budget and
the account's team, key, and monthly caps. Reviewers can read the docs and skills. A private skill
is visible to its author and to admins. Deleting a repository is for an admin, the member who
connected it, or that team's manager.

## Shared library: `GET /v1/library`

One call that lists what the team can reuse by id: brand kits, stored characters (with sheet
URLs), analyzed styles, finished videos and uploads. Each with `createdBy`. Agents should look
here before creating something that may already exist: Urav's character sheet, the brand kit,
last week's launch style.

## Attribution

`memberId` (who made it) is on jobs, assets, brand kits, characters, posts and reports; posts also
carry `decidedBy` and `decidedAt` for the approval. `GET /v1/reports` shows who filed each one.

## Your own provider keys

Approved accounts connect their own Higgsfield and ElevenLabs keys themselves: `POST /v1/providers/higgsfield`
`{ keyId, secret }`, `POST /v1/providers/elevenlabs` `{ apiKey }` (admin, over TLS; verified with the
provider, stored encrypted, never returned; `DELETE` to disconnect; `GET /v1/providers` shows what is
connected). With your own key, jobs cost the platform fee in credits and the provider bills you.
Ask us to enable it on your account.

## Through MCP

`library`, `list_members`, `invite_member`, `update_member`, `remove_member`, `create_member_key`,
`list_keys`, `revoke_key`, `list_providers`, `connect_provider`, `disconnect_provider`. Reviewer keys see every tool but can only run the read-only ones plus
`approve_post`, `reject_post` and `report_issue`.

Governance tools (teams or budgets on): `list_invites`, `invite_by_email`, `create_invite_link`,
`revoke_invite`, `my_memberships`, `list_teams`, `create_team`,
`update_team`, `delete_team`, `set_member_team`, `list_budgets`, `allocate_budget`, `revoke_budget`,
`set_key_credit_cap`, `list_audit`. They run through the same permission checks as the REST endpoints.