---
title: "Rename or rescope an agent account"
method: PATCH
path: "/v1/agent-accounts/{id}"
tags: ["Agent accounts"]
---

# Rename or rescope an agent account

`PATCH /v1/agent-accounts/{id}`

## Request

- Base URL: `https://api.shardflux.dev`
- URL: `https://api.shardflux.dev/v1/agent-accounts/{id}`
- Auth: HTTP bearer

## Path parameters

- `id` string, uuid, required

## Query parameters

- `project_id` string, uuid

## Request body

- object
  - `label` string
  - `scope` union: Who may make it the active account. personal (every sign-in unless set otherwise): only the member who added it, as an owner or admin. team: any owner or admin.
    - 'personal'
    - 'team'
  - `position` integer: Retired: the order no longer chooses the account; answers 409 account_pool_retired.

## Response `200`

Default Response

- object
  - `id` string, uuid, required: UUIDv7, lowercase canonical form.
  - `provider` union, required
    - 'claude'
    - 'codex'
  - `kind` union, required: oauth: a subscription sign-in. api_key: a provider API key added before 2026-10-12 (listed and removable; cannot be active).
    - 'oauth'
    - 'api_key'
  - `label` string, required
  - `email` string, nullable, required
  - `chatgpt_account_id` string, nullable: Codex: the ChatGPT account (workspace) id its login signs in to, as tokens.account_id in ~/.codex/auth.json; null for Claude and when the login did not say. The Codex app opens a Cloud thread only while signed in to the thread’s account.
  - `plan_type` string, nullable, required: Claude: pro, max, team, enterprise. Codex: plus, pro, team, business, enterprise. API keys: api.
  - `scope` union, required: Who may make it the active account. personal (every sign-in unless set otherwise): only the member who added it, as an owner or admin. team: any owner or admin.
    - 'personal'
    - 'team'
  - `owner_user_id` string, uuid, nullable, required: UUIDv7, lowercase canonical form.
  - `mine` boolean, required: The caller signed this account in (an API key counts as the member who created it).
  - `position` integer, required: Order within the provider (the order the accounts were added), from 0.
  - `active` boolean, required: New conversations and every running conversation VM of this provider use this account’s login. One per provider (Claude: per organization; Codex: per project); you choose it with POST /agent-accounts/{id}/activate.
  - `preferred` boolean, required: Deprecated: the same as active.
  - `pool_eligible` boolean, required: Deprecated: always false.
  - `status` union, required: signed_in; low (a window is at 90 % or more, until it is below 80 % or resets); limited (a window is used up until it resets); expired (sign in again). Information only: the active account changes only when you choose another.
    - 'signed_in'
    - 'low'
    - 'limited'
    - 'expired'
  - `windows` object[], required
    - `window` union, required: Claude: five_hour, seven_day, seven_day_opus, seven_day_sonnet. Codex: primary and secondary, whose length is window_minutes (300: the 5-hour window, 10080: the weekly one); a plan may report only one.
      - 'five_hour'
      - 'seven_day'
      - 'seven_day_opus'
      - 'seven_day_sonnet'
      - 'primary'
      - 'secondary'
    - `used_percent` number, required
    - `resets_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
    - `window_minutes` integer, nullable, required
    - `source` union, required
      - 'header'
      - 'poll'
      - 'app_server'
    - `observed_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
  - `as_of` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
  - `stale` boolean, required: The newest reading is more than 30 minutes old.
  - `threads` integer, required: Open conversations running on this account (the active account’s open conversations of its provider; 0 for the others).
  - `can_activate` boolean, required: The caller can make this account active now: an owner or admin, a subscription sign-in with a working login, a team account or their own, of this project (ChatGPT), not already active.
  - `can_remove` boolean, required: The caller can remove this account: it is theirs, or they are an owner or admin and it is not the active account while another could take its place.
  - `created_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
  - `updated_at` string, date-time, required: RFC 3339 UTC timestamp with Z.

## Other responses

- `4XX`: Default Response
- `5XX`: Default Response

---

[API](https://skmtc.dev/shardflux/apis/shardflux-api.md) · [All operations](https://skmtc.dev/shardflux/apis/shardflux-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shardflux/apis/shardflux-api/revisions/ea685f7b39c4?raw)