Team context

Query effective account benefits

Use GET /api/v1/open/account/entitlements with the account scope for Personal, or GET /api/v1/open/teams/{team_id}/entitlements with team_read or team_manage for a Team. Team tokens cannot read Personal or other Teams. Both return accountType, accountId, entitlements and sources inside the standard data envelope. Personal accountId is the application's isolated user subject.

entitlements.storage.maxFileBytes and totalBytes describe file and total storage benefit limits in bytes. Teams also expose memberLimit (including the owner) and planFeatures; Personal exposes byok. Active sources include their benefits and UTC startsAt/endsAt; a null end means no expiry. Membership is a time-limited benefit source. Do not infer permission from its name: higher quotas apply across sources, and purchased seats add together. Server role, ownership, balance and feature checks still apply.

Upload quota errors are ATTACHMENT_FILE_LIMIT_REACHED or ATTACHMENT_STORAGE_LIMIT_REACHED (HTTP 413). Ask users to update benefits or free space instead of repeatedly uploading. Storage services and dedicated media endpoints may impose additional technical limits. Expiry never deletes existing files. Additional seats are purchased through the Team portal, prorated over the current membership period and expire with that period.

Teams must activate a seat plan before purchasing credit packs. Read canPurchaseCredits from membership data; neither a positive balance nor accessActive replaces this flag. Without an active plan, customer and admin-sponsored credit orders return TEAM_CREDIT_PACK_PLAN_REQUIRED (HTTP 402). Plan catalog seats exposes includedMembers, allowPurchase, and monthlyPriceMinor; the owner counts toward capacity. Credit packs only add credits: accessDays is always 0, and they never activate a team or extend its plan. Existing credits retain their original expiry; an expired team plan must be renewed to resume team model calls.

Team OAuth is not a transparent upgrade from Personal OAuth. A Team token is bound to the user, open agent, exact Team, membership, authorization record, and context version.

Authorization

Prefer an explicit team_id in the authorization request. Ordinary members cannot receive team_manage; only Owner/Admin members may grant management scope. Disabling a member, removing them, lowering their role, or disabling the Team invalidates the old authorization.

Required model-call headers

X-Xiaoya-Team-Id: <team-id>
X-Xiaoya-Workflow-Version-Id: <workflow-version-id>
X-Xiaoya-Run-Id: <run-id>
X-Xiaoya-Node-Id: <node-id>
X-Xiaoya-Attempt: <1..6>

These trusted server-generated fields form the Team reservation, settlement, refund, and idempotency boundary. Browser code and AI input must not be allowed to invent them.

Team model calls currently require "stream": false. Streaming returns TEAM_USAGE_STREAMING_UNSUPPORTED; an incomplete tuple returns TEAM_USAGE_CONTEXT_INCOMPLETE.

Team balance and model routes are available, but the Personal /api/v1/open/usage endpoint rejects Team-bound tokens. Team overview metrics are not a drop-in replacement for Personal usage detail.

curl 'https://claw.zhenhuiai.com/api/v1/open/teams/team_01/context' \
  --header 'Authorization: Bearer <team-access-token>'

curl 'https://claw.zhenhuiai.com/api/v1/open/teams/team_01/balance' \
  --header 'Authorization: Bearer <team-access-token>'

{
  "success": true,
  "data": {
    "teamId": "team_01",
    "teamContextVersion": 7,
    "memberId": "member_01",
    "role": "member",
    "memberStatus": "active"
  },
  "request_id": "req_team_context"
}

Team web purchases use POST /api/v1/open/teams/{team_id}/charge; refunds use /refund. Both require the Team token, server-generated points and idempotency keys, and a key space isolated from Personal orders.

{ "points": 20, "idempotencyKey": "team_order_20260830_0001" }

{
  "points": 20,
  "chargeIdempotencyKey": "team_order_20260830_0001",
  "idempotencyKey": "team_refund_20260830_0001"
}

Complete Team model call:

curl 'https://claw.zhenhuiai.com/api/proxy/v1/chat/completions' \
  --header 'Authorization: Bearer <team-access-token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Xiaoya-Team-Id: team_01' \
  --header 'X-Xiaoya-Workflow-Version-Id: workflow_version_01' \
  --header 'X-Xiaoya-Run-Id: run_01' \
  --header 'X-Xiaoya-Node-Id: summarize' \
  --header 'X-Xiaoya-Attempt: 1' \
  --data '{
    "model":"othan-2.0",
    "messages":[{"role":"user","content":"Summarize the knowledge-base update"}],
    "stream":false
  }'

Common errors include TEAM_CONTEXT_MISMATCH, TEAM_OAUTH_AUTHORIZATION_REQUIRED, TEAM_USAGE_CONTEXT_INCOMPLETE, TEAM_USAGE_STREAMING_UNSUPPORTED, and OPEN_AGENT_SCOPE_REQUIRED.

The complete API reference also lists all public Team management, members, roles, departments, positions, organization roles, shared assets, execution grants, runtime assets, and sandbox operations with their real scopes and schemas.