SPB Git
spboucher.ai

Repository Public

spbdoc-api

service_accounts.md 41.2 KB

# title: Service Accounts url: https://platform.claude.com/docs/en/api/beta/organization/service_accounts

# Service Accounts

# Create Service Account

POST /v1/organizations/service_accounts

Requires an OAuth access token with the org:admin scope, from ant auth login --scope org:admin or a workload identity federation rule; Admin API keys are not accepted. See Manage WIF with the Admin API.

Create a service account.

A service account is a named workload identity that federation rules target. organization_role is developer (default) or admin; a rule may only be created or retargeted to grant org:admin scope when the target's organization_role is admin. Creating an admin-role service account requires an interactive credential (a user OAuth token or a Console session) — a workload may only create developer-role service accounts.

# Headers

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more

      • "message-batches-2024-09-24"

      • "prompt-caching-2024-07-31"

      • "computer-use-2024-10-22"

      • "computer-use-2025-01-24"

      • "pdfs-2024-09-25"

      • "token-counting-2024-11-01"

      • "token-efficient-tools-2025-02-19"

      • "output-128k-2025-02-19"

      • "files-api-2025-04-14"

      • "mcp-client-2025-04-04"

      • "mcp-client-2025-11-20"

      • "dev-full-thinking-2025-05-14"

      • "interleaved-thinking-2025-05-14"

      • "code-execution-2025-05-22"

      • "extended-cache-ttl-2025-04-11"

      • "context-1m-2025-08-07"

      • "context-management-2025-06-27"

      • "model-context-window-exceeded-2025-08-26"

      • "skills-2025-10-02"

      • "fast-mode-2026-02-01"

      • "output-300k-2026-03-24"

      • "user-profiles-2026-03-24"

      • "user-profiles-2026-08-18"

      • "user-profiles-2026-09-04"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

      • "dreaming-2026-04-21"

      • "thinking-token-count-2026-05-13"

      • "server-side-fallback-2026-06-01"

      • "server-side-fallback-2026-07-01"

      • "fallback-credit-2026-06-01"

      • "fallback-credit-2026-07-01"

      • "agent-memory-2026-07-22"

      • "mid-conversation-tool-changes-2026-07-01"

      • "compact-2026-01-12"

      • "computer-use-2025-11-24"

      • "mcp-tunnels-2026-06-22"

      • "structured-outputs-2025-11-13"

      • "task-budgets-2026-03-13"

      • "thinking-display-updates-2026-08-18"

      • "ce-user-management-2026-07-13"

      • "mid-conversation-output-config-2026-07-01"

      • "thinking-binding-controls-2026-08-01"

      • "mid-conversation-system-clear-at-2026-08-21"

      • "compact-2026-09-04"

# Body parameters

  • name: string

    Slug identifier (lowercase, digits, hyphens). Unique within the organization; a duplicate name returns 409.

    maxLength: 255, minLength: 1

  • description: optional string or null

    Optional free-text description.

    maxLength: 2000

  • organization_role: optional "admin" or "developer"

    Org-level role. Defaults to developer.

    • "admin"

    • "developer"

# Returns

  • BetaServiceAccount object

    Named non-human identity within the caller's organization.

    A service account is a pure identity: name + org. Authorization lives on whatever references it (federation rules).

    • type: "service_account"

      default: service_account

    • id: string

      Tagged ID of the service account.

    • archived_at: string or null

      If set, this service account is archived.

      format: date-time

    • archived_by_actor_id: string or null

      Tagged ID (user_/svac_) of the actor that archived this service account.

    • created_at: string

      When this service account was created.

      format: date-time

    • created_by_actor_id: string or null

      Tagged ID (user_/svac_) of the actor that created this service account.

    • description: string or null

      Optional free-text description.

    • name: string

      Admin-chosen slug identifier.

    • organization_role: "admin" or "developer"

      Org-level role. A federation rule may only be created or retargeted to grant org:admin scope when this is admin. A rule granting org:admin whose target is later demoted to developer is rejected at token exchange. Rules granting org:admin are managed in the Console.

      • "admin"

      • "developer"

    • updated_at: string

      When this service account was last updated.

      format: date-time

    • updated_by_actor_id: string or null

      Tagged ID (user_/svac_) of the actor that last updated this service account.

# Example

bash
curl https://api.anthropic.com/v1/organizations/service_accounts \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d '{
          "name": "ci-deploy-bot"
        }'

# Response (200)

json
{
  "id": "svac_01SDCCSbTxrXDpWc1phhtcfK",
  "archived_at": "2019-12-27T18:11:19.117Z",
  "archived_by_actor_id": "archived_by_actor_id",
  "created_at": "2024-10-30T23:58:27.427722Z",
  "created_by_actor_id": "created_by_actor_id",
  "description": "description",
  "name": "ci-deploy-bot",
  "organization_role": "admin",
  "type": "service_account",
  "updated_at": "2024-10-30T23:58:27.427722Z",
  "updated_by_actor_id": "updated_by_actor_id"
}

# List Service Accounts

GET /v1/organizations/service_accounts

Requires an OAuth access token with the org:admin scope, from ant auth login --scope org:admin or a workload identity federation rule; Admin API keys are not accepted. See Manage WIF with the Admin API.

List service accounts in the caller's organization.

Results are ordered by creation time, newest first. Use limit and the next_page cursor to paginate; set include_archived=true to include archived service accounts.

# Query parameters

  • include_archived: optional boolean

    Include archived resources. Defaults to false.

    default: false

  • limit: optional number

    Number of results per page.

    default: 20, maximum: 100, minimum: 1

  • page: optional string

    Opaque cursor from a previous response's next_page.

# Headers

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more

      • "message-batches-2024-09-24"

      • "prompt-caching-2024-07-31"

      • "computer-use-2024-10-22"

      • "computer-use-2025-01-24"

      • "pdfs-2024-09-25"

      • "token-counting-2024-11-01"

      • "token-efficient-tools-2025-02-19"

      • "output-128k-2025-02-19"

      • "files-api-2025-04-14"

      • "mcp-client-2025-04-04"

      • "mcp-client-2025-11-20"

      • "dev-full-thinking-2025-05-14"

      • "interleaved-thinking-2025-05-14"

      • "code-execution-2025-05-22"

      • "extended-cache-ttl-2025-04-11"

      • "context-1m-2025-08-07"

      • "context-management-2025-06-27"

      • "model-context-window-exceeded-2025-08-26"

      • "skills-2025-10-02"

      • "fast-mode-2026-02-01"

      • "output-300k-2026-03-24"

      • "user-profiles-2026-03-24"

      • "user-profiles-2026-08-18"

      • "user-profiles-2026-09-04"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

      • "dreaming-2026-04-21"

      • "thinking-token-count-2026-05-13"

      • "server-side-fallback-2026-06-01"

      • "server-side-fallback-2026-07-01"

      • "fallback-credit-2026-06-01"

      • "fallback-credit-2026-07-01"

      • "agent-memory-2026-07-22"

      • "mid-conversation-tool-changes-2026-07-01"

      • "compact-2026-01-12"

      • "computer-use-2025-11-24"

      • "mcp-tunnels-2026-06-22"

      • "structured-outputs-2025-11-13"

      • "task-budgets-2026-03-13"

      • "thinking-display-updates-2026-08-18"

      • "ce-user-management-2026-07-13"

      • "mid-conversation-output-config-2026-07-01"

      • "thinking-binding-controls-2026-08-01"

      • "mid-conversation-system-clear-at-2026-08-21"

      • "compact-2026-09-04"

# Returns

  • data: array of BetaServiceAccount

    • type: "service_account"

      default: service_account

    • id: string

      Tagged ID of the service account.

    • archived_at: string or null

      If set, this service account is archived.

      format: date-time

    • archived_by_actor_id: string or null

      Tagged ID (user_/svac_) of the actor that archived this service account.

    • created_at: string

      When this service account was created.

      format: date-time

    • created_by_actor_id: string or null

      Tagged ID (user_/svac_) of the actor that created this service account.

    • description: string or null

      Optional free-text description.

    • name: string

      Admin-chosen slug identifier.

    • organization_role: "admin" or "developer"

      Org-level role. A federation rule may only be created or retargeted to grant org:admin scope when this is admin. A rule granting org:admin whose target is later demoted to developer is rejected at token exchange. Rules granting org:admin are managed in the Console.

      • "admin"

      • "developer"

    • updated_at: string

      When this service account was last updated.

      format: date-time

    • updated_by_actor_id: string or null

      Tagged ID (user_/svac_) of the actor that last updated this service account.

  • next_page: string or null

    Opaque cursor for the next page, or null if no more results.

# Example

bash
curl https://api.anthropic.com/v1/organizations/service_accounts \
    -H 'anthropic-version: 2023-06-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

# Response (200)

json
{
  "data": [
    {
      "id": "svac_01SDCCSbTxrXDpWc1phhtcfK",
      "archived_at": "2019-12-27T18:11:19.117Z",
      "archived_by_actor_id": "archived_by_actor_id",
      "created_at": "2024-10-30T23:58:27.427722Z",
      "created_by_actor_id": "created_by_actor_id",
      "description": "description",
      "name": "ci-deploy-bot",
      "organization_role": "admin",
      "type": "service_account",
      "updated_at": "2024-10-30T23:58:27.427722Z",
      "updated_by_actor_id": "updated_by_actor_id"
    }
  ],
  "next_page": "next_page"
}

# Get Service Account

GET /v1/organizations/service_accounts/{service_account_id}

Requires an OAuth access token with the org:admin scope, from ant auth login --scope org:admin or a workload identity federation rule; Admin API keys are not accepted. See Manage WIF with the Admin API.

Retrieve a service account by its ID (svac_...).

# Path parameters

  • service_account_id: string

    ID of the service account.

# Headers

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more

      • "message-batches-2024-09-24"

      • "prompt-caching-2024-07-31"

      • "computer-use-2024-10-22"

      • "computer-use-2025-01-24"

      • "pdfs-2024-09-25"

      • "token-counting-2024-11-01"

      • "token-efficient-tools-2025-02-19"

      • "output-128k-2025-02-19"

      • "files-api-2025-04-14"

      • "mcp-client-2025-04-04"

      • "mcp-client-2025-11-20"

      • "dev-full-thinking-2025-05-14"

      • "interleaved-thinking-2025-05-14"

      • "code-execution-2025-05-22"

      • "extended-cache-ttl-2025-04-11"

      • "context-1m-2025-08-07"

      • "context-management-2025-06-27"

      • "model-context-window-exceeded-2025-08-26"

      • "skills-2025-10-02"

      • "fast-mode-2026-02-01"

      • "output-300k-2026-03-24"

      • "user-profiles-2026-03-24"

      • "user-profiles-2026-08-18"

      • "user-profiles-2026-09-04"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

      • "dreaming-2026-04-21"

      • "thinking-token-count-2026-05-13"

      • "server-side-fallback-2026-06-01"

      • "server-side-fallback-2026-07-01"

      • "fallback-credit-2026-06-01"

      • "fallback-credit-2026-07-01"

      • "agent-memory-2026-07-22"

      • "mid-conversation-tool-changes-2026-07-01"

      • "compact-2026-01-12"

      • "computer-use-2025-11-24"

      • "mcp-tunnels-2026-06-22"

      • "structured-outputs-2025-11-13"

      • "task-budgets-2026-03-13"

      • "thinking-display-updates-2026-08-18"

      • "ce-user-management-2026-07-13"

      • "mid-conversation-output-config-2026-07-01"

      • "thinking-binding-controls-2026-08-01"

      • "mid-conversation-system-clear-at-2026-08-21"

      • "compact-2026-09-04"

# Returns

  • BetaServiceAccount object

    Named non-human identity within the caller's organization.

    A service account is a pure identity: name + org. Authorization lives on whatever references it (federation rules).

    • type: "service_account"

      default: service_account

    • id: string

      Tagged ID of the service account.

    • archived_at: string or null

      If set, this service account is archived.

      format: date-time

    • archived_by_actor_id: string or null

      Tagged ID (user_/svac_) of the actor that archived this service account.

    • created_at: string

      When this service account was created.

      format: date-time

    • created_by_actor_id: string or null

      Tagged ID (user_/svac_) of the actor that created this service account.

    • description: string or null

      Optional free-text description.

    • name: string

      Admin-chosen slug identifier.

    • organization_role: "admin" or "developer"

      Org-level role. A federation rule may only be created or retargeted to grant org:admin scope when this is admin. A rule granting org:admin whose target is later demoted to developer is rejected at token exchange. Rules granting org:admin are managed in the Console.

      • "admin"

      • "developer"

    • updated_at: string

      When this service account was last updated.

      format: date-time

    • updated_by_actor_id: string or null

      Tagged ID (user_/svac_) of the actor that last updated this service account.

# Example

bash
curl https://api.anthropic.com/v1/organizations/service_accounts/$SERVICE_ACCOUNT_ID \
    -H 'anthropic-version: 2023-06-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

# Response (200)

json
{
  "id": "svac_01SDCCSbTxrXDpWc1phhtcfK",
  "archived_at": "2019-12-27T18:11:19.117Z",
  "archived_by_actor_id": "archived_by_actor_id",
  "created_at": "2024-10-30T23:58:27.427722Z",
  "created_by_actor_id": "created_by_actor_id",
  "description": "description",
  "name": "ci-deploy-bot",
  "organization_role": "admin",
  "type": "service_account",
  "updated_at": "2024-10-30T23:58:27.427722Z",
  "updated_by_actor_id": "updated_by_actor_id"
}

# Update Service Account

POST /v1/organizations/service_accounts/{service_account_id}

Requires an OAuth access token with the org:admin scope, from ant auth login --scope org:admin or a workload identity federation rule; Admin API keys are not accepted. See Manage WIF with the Admin API.

Update a service account.

Only description and organization_role are mutable; name cannot be changed. Archived service accounts cannot be updated; this returns 400. Setting organization_role to admin (even when unchanged) requires an interactive credential (a user OAuth token or a Console session).

# Path parameters

  • service_account_id: string

    ID of the service account to update.

# Headers

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more

      • "message-batches-2024-09-24"

      • "prompt-caching-2024-07-31"

      • "computer-use-2024-10-22"

      • "computer-use-2025-01-24"

      • "pdfs-2024-09-25"

      • "token-counting-2024-11-01"

      • "token-efficient-tools-2025-02-19"

      • "output-128k-2025-02-19"

      • "files-api-2025-04-14"

      • "mcp-client-2025-04-04"

      • "mcp-client-2025-11-20"

      • "dev-full-thinking-2025-05-14"

      • "interleaved-thinking-2025-05-14"

      • "code-execution-2025-05-22"

      • "extended-cache-ttl-2025-04-11"

      • "context-1m-2025-08-07"

      • "context-management-2025-06-27"

      • "model-context-window-exceeded-2025-08-26"

      • "skills-2025-10-02"

      • "fast-mode-2026-02-01"

      • "output-300k-2026-03-24"

      • "user-profiles-2026-03-24"

      • "user-profiles-2026-08-18"

      • "user-profiles-2026-09-04"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

      • "dreaming-2026-04-21"

      • "thinking-token-count-2026-05-13"

      • "server-side-fallback-2026-06-01"

      • "server-side-fallback-2026-07-01"

      • "fallback-credit-2026-06-01"

      • "fallback-credit-2026-07-01"

      • "agent-memory-2026-07-22"

      • "mid-conversation-tool-changes-2026-07-01"

      • "compact-2026-01-12"

      • "computer-use-2025-11-24"

      • "mcp-tunnels-2026-06-22"

      • "structured-outputs-2025-11-13"

      • "task-budgets-2026-03-13"

      • "thinking-display-updates-2026-08-18"

      • "ce-user-management-2026-07-13"

      • "mid-conversation-output-config-2026-07-01"

      • "thinking-binding-controls-2026-08-01"

      • "mid-conversation-system-clear-at-2026-08-21"

      • "compact-2026-09-04"

# Body parameters

  • description: optional string or null

    Replaces the description. Omit to leave unchanged; send null to clear (the field is stored as an empty string).

    maxLength: 2000

  • organization_role: optional "admin" or "developer" or null

    Replaces the org-level role. Omit or send null to leave unchanged.

    • "admin"

    • "developer"

# Returns

  • BetaServiceAccount object

    Named non-human identity within the caller's organization.

    A service account is a pure identity: name + org. Authorization lives on whatever references it (federation rules).

    • type: "service_account"

      default: service_account

    • id: string

      Tagged ID of the service account.

    • archived_at: string or null

      If set, this service account is archived.

      format: date-time

    • archived_by_actor_id: string or null

      Tagged ID (user_/svac_) of the actor that archived this service account.

    • created_at: string

      When this service account was created.

      format: date-time

    • created_by_actor_id: string or null

      Tagged ID (user_/svac_) of the actor that created this service account.

    • description: string or null

      Optional free-text description.

    • name: string

      Admin-chosen slug identifier.

    • organization_role: "admin" or "developer"

      Org-level role. A federation rule may only be created or retargeted to grant org:admin scope when this is admin. A rule granting org:admin whose target is later demoted to developer is rejected at token exchange. Rules granting org:admin are managed in the Console.

      • "admin"

      • "developer"

    • updated_at: string

      When this service account was last updated.

      format: date-time

    • updated_by_actor_id: string or null

      Tagged ID (user_/svac_) of the actor that last updated this service account.

# Example

bash
curl https://api.anthropic.com/v1/organizations/service_accounts/$SERVICE_ACCOUNT_ID \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d '{}'

# Response (200)

json
{
  "id": "svac_01SDCCSbTxrXDpWc1phhtcfK",
  "archived_at": "2019-12-27T18:11:19.117Z",
  "archived_by_actor_id": "archived_by_actor_id",
  "created_at": "2024-10-30T23:58:27.427722Z",
  "created_by_actor_id": "created_by_actor_id",
  "description": "description",
  "name": "ci-deploy-bot",
  "organization_role": "admin",
  "type": "service_account",
  "updated_at": "2024-10-30T23:58:27.427722Z",
  "updated_by_actor_id": "updated_by_actor_id"
}

# Archive Service Account

POST /v1/organizations/service_accounts/{service_account_id}/archive

Requires an OAuth access token with the org:admin scope, from ant auth login --scope org:admin or a workload identity federation rule; Admin API keys are not accepted. See Manage WIF with the Admin API.

Archive a service account.

Idempotent; re-archiving returns the service account with its original archived_at. Rejected with 400 if any live (non-archived) federation rule still targets this service account, same as issuer archival; archive those rules first or change their target to another service account.

# Path parameters

  • service_account_id: string

    ID of the service account to archive.

# Headers

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more

      • "message-batches-2024-09-24"

      • "prompt-caching-2024-07-31"

      • "computer-use-2024-10-22"

      • "computer-use-2025-01-24"

      • "pdfs-2024-09-25"

      • "token-counting-2024-11-01"

      • "token-efficient-tools-2025-02-19"

      • "output-128k-2025-02-19"

      • "files-api-2025-04-14"

      • "mcp-client-2025-04-04"

      • "mcp-client-2025-11-20"

      • "dev-full-thinking-2025-05-14"

      • "interleaved-thinking-2025-05-14"

      • "code-execution-2025-05-22"

      • "extended-cache-ttl-2025-04-11"

      • "context-1m-2025-08-07"

      • "context-management-2025-06-27"

      • "model-context-window-exceeded-2025-08-26"

      • "skills-2025-10-02"

      • "fast-mode-2026-02-01"

      • "output-300k-2026-03-24"

      • "user-profiles-2026-03-24"

      • "user-profiles-2026-08-18"

      • "user-profiles-2026-09-04"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

      • "dreaming-2026-04-21"

      • "thinking-token-count-2026-05-13"

      • "server-side-fallback-2026-06-01"

      • "server-side-fallback-2026-07-01"

      • "fallback-credit-2026-06-01"

      • "fallback-credit-2026-07-01"

      • "agent-memory-2026-07-22"

      • "mid-conversation-tool-changes-2026-07-01"

      • "compact-2026-01-12"

      • "computer-use-2025-11-24"

      • "mcp-tunnels-2026-06-22"

      • "structured-outputs-2025-11-13"

      • "task-budgets-2026-03-13"

      • "thinking-display-updates-2026-08-18"

      • "ce-user-management-2026-07-13"

      • "mid-conversation-output-config-2026-07-01"

      • "thinking-binding-controls-2026-08-01"

      • "mid-conversation-system-clear-at-2026-08-21"

      • "compact-2026-09-04"

# Returns

  • BetaServiceAccount object

    Named non-human identity within the caller's organization.

    A service account is a pure identity: name + org. Authorization lives on whatever references it (federation rules).

    • type: "service_account"

      default: service_account

    • id: string

      Tagged ID of the service account.

    • archived_at: string or null

      If set, this service account is archived.

      format: date-time

    • archived_by_actor_id: string or null

      Tagged ID (user_/svac_) of the actor that archived this service account.

    • created_at: string

      When this service account was created.

      format: date-time

    • created_by_actor_id: string or null

      Tagged ID (user_/svac_) of the actor that created this service account.

    • description: string or null

      Optional free-text description.

    • name: string

      Admin-chosen slug identifier.

    • organization_role: "admin" or "developer"

      Org-level role. A federation rule may only be created or retargeted to grant org:admin scope when this is admin. A rule granting org:admin whose target is later demoted to developer is rejected at token exchange. Rules granting org:admin are managed in the Console.

      • "admin"

      • "developer"

    • updated_at: string

      When this service account was last updated.

      format: date-time

    • updated_by_actor_id: string or null

      Tagged ID (user_/svac_) of the actor that last updated this service account.

# Example

bash
curl https://api.anthropic.com/v1/organizations/service_accounts/$SERVICE_ACCOUNT_ID/archive \
    -X POST \
    -H 'anthropic-version: 2023-06-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

# Response (200)

json
{
  "id": "svac_01SDCCSbTxrXDpWc1phhtcfK",
  "archived_at": "2019-12-27T18:11:19.117Z",
  "archived_by_actor_id": "archived_by_actor_id",
  "created_at": "2024-10-30T23:58:27.427722Z",
  "created_by_actor_id": "created_by_actor_id",
  "description": "description",
  "name": "ci-deploy-bot",
  "organization_role": "admin",
  "type": "service_account",
  "updated_at": "2024-10-30T23:58:27.427722Z",
  "updated_by_actor_id": "updated_by_actor_id"
}

# Domain types

# Beta Service Account

  • BetaServiceAccount object

    Named non-human identity within the caller's organization.

    A service account is a pure identity: name + org. Authorization lives on whatever references it (federation rules).

    • type: "service_account"

      default: service_account

    • id: string

      Tagged ID of the service account.

    • archived_at: string or null

      If set, this service account is archived.

      format: date-time

    • archived_by_actor_id: string or null

      Tagged ID (user_/svac_) of the actor that archived this service account.

    • created_at: string

      When this service account was created.

      format: date-time

    • created_by_actor_id: string or null

      Tagged ID (user_/svac_) of the actor that created this service account.

    • description: string or null

      Optional free-text description.

    • name: string

      Admin-chosen slug identifier.

    • organization_role: "admin" or "developer"

      Org-level role. A federation rule may only be created or retargeted to grant org:admin scope when this is admin. A rule granting org:admin whose target is later demoted to developer is rejected at token exchange. Rules granting org:admin are managed in the Console.

      • "admin"

      • "developer"

    • updated_at: string

      When this service account was last updated.

      format: date-time

    • updated_by_actor_id: string or null

      Tagged ID (user_/svac_) of the actor that last updated this service account.

# Beta Service Account Workspace Member

  • BetaServiceAccountWorkspaceMember object

    • type: "service_account_workspace_member"

      default: service_account_workspace_member

    • created_by_actor_id: string or null

      Tagged ID (user_.../svac_...) of the actor who created this membership.

    • implicit: boolean or null

      True when this is the implicit default-workspace membership every service account has when no explicit membership exists. Implicit memberships have role workspace_user and cannot be removed.

    • service_account_id: string

      Tagged service account ID (svac_...).

    • workspace_id: string

      Tagged workspace ID (wrkspc_...).

    • workspace_role: BetaWorkspaceRole

      Role of the service account in this workspace. Service accounts cannot hold the workspace_billing role.

      • "workspace_admin"

      • "workspace_billing"

      • "workspace_developer"

      • "workspace_restricted_developer"

      • "workspace_user"

# Service Accounts › Workspaces

# Add Workspace To Service Account

POST /v1/organizations/service_accounts/{service_account_id}/workspaces

Requires an OAuth access token with the org:admin scope, from ant auth login --scope org:admin or a workload identity federation rule; Admin API keys are not accepted. See Manage WIF with the Admin API.

Add a service account to a workspace with the given workspace_role.

Mirror of POST /workspaces/{workspace_id}/service_accounts, addressed from the service-account side; both create the same membership. If the service account is already an explicit member of the workspace, its workspace_role is replaced with the value supplied here. Archived workspaces return 400. Archived service accounts cannot be added and are rejected.

# Path parameters

  • service_account_id: string

    ID of the service account.

# Headers

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more

      • "message-batches-2024-09-24"

      • "prompt-caching-2024-07-31"

      • "computer-use-2024-10-22"

      • "computer-use-2025-01-24"

      • "pdfs-2024-09-25"

      • "token-counting-2024-11-01"

      • "token-efficient-tools-2025-02-19"

      • "output-128k-2025-02-19"

      • "files-api-2025-04-14"

      • "mcp-client-2025-04-04"

      • "mcp-client-2025-11-20"

      • "dev-full-thinking-2025-05-14"

      • "interleaved-thinking-2025-05-14"

      • "code-execution-2025-05-22"

      • "extended-cache-ttl-2025-04-11"

      • "context-1m-2025-08-07"

      • "context-management-2025-06-27"

      • "model-context-window-exceeded-2025-08-26"

      • "skills-2025-10-02"

      • "fast-mode-2026-02-01"

      • "output-300k-2026-03-24"

      • "user-profiles-2026-03-24"

      • "user-profiles-2026-08-18"

      • "user-profiles-2026-09-04"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

      • "dreaming-2026-04-21"

      • "thinking-token-count-2026-05-13"

      • "server-side-fallback-2026-06-01"

      • "server-side-fallback-2026-07-01"

      • "fallback-credit-2026-06-01"

      • "fallback-credit-2026-07-01"

      • "agent-memory-2026-07-22"

      • "mid-conversation-tool-changes-2026-07-01"

      • "compact-2026-01-12"

      • "computer-use-2025-11-24"

      • "mcp-tunnels-2026-06-22"

      • "structured-outputs-2025-11-13"

      • "task-budgets-2026-03-13"

      • "thinking-display-updates-2026-08-18"

      • "ce-user-management-2026-07-13"

      • "mid-conversation-output-config-2026-07-01"

      • "thinking-binding-controls-2026-08-01"

      • "mid-conversation-system-clear-at-2026-08-21"

      • "compact-2026-09-04"

# Body parameters

  • workspace_id: string

    Tagged workspace ID to add the service account to.

  • workspace_role: BetaNoBillingWorkspaceRole

    Role to assign to the service account in this workspace.

    • "workspace_admin"

    • "workspace_developer"

    • "workspace_restricted_developer"

    • "workspace_user"

# Returns

  • BetaServiceAccountWorkspaceMember object

    • type: "service_account_workspace_member"

      default: service_account_workspace_member

    • created_by_actor_id: string or null

      Tagged ID (user_.../svac_...) of the actor who created this membership.

    • implicit: boolean or null

      True when this is the implicit default-workspace membership every service account has when no explicit membership exists. Implicit memberships have role workspace_user and cannot be removed.

    • service_account_id: string

      Tagged service account ID (svac_...).

    • workspace_id: string

      Tagged workspace ID (wrkspc_...).

    • workspace_role: BetaWorkspaceRole

      Role of the service account in this workspace. Service accounts cannot hold the workspace_billing role.

      • "workspace_admin"

      • "workspace_billing"

      • "workspace_developer"

      • "workspace_restricted_developer"

      • "workspace_user"

# Example

bash
curl https://api.anthropic.com/v1/organizations/service_accounts/$SERVICE_ACCOUNT_ID/workspaces \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d '{
          "workspace_id": "workspace_id",
          "workspace_role": "workspace_admin"
        }'
# Response (200)
json
{
  "created_by_actor_id": "created_by_actor_id",
  "implicit": true,
  "service_account_id": "service_account_id",
  "type": "service_account_workspace_member",
  "workspace_id": "workspace_id",
  "workspace_role": "workspace_admin"
}

# List Workspaces For Service Account

GET /v1/organizations/service_accounts/{service_account_id}/workspaces

Requires an OAuth access token with the org:admin scope, from ant auth login --scope org:admin or a workload identity federation rule; Admin API keys are not accepted. See Manage WIF with the Admin API.

List the workspaces a service account is a member of.

Each entry includes the service account's workspace_role in that workspace. Use limit and the next_page cursor to paginate. When the service account has no explicit default-workspace membership, the implicit (implicit: true) membership is returned as the first entry on the first page; with limit=1 the first page may return up to 2 entries (the implicit entry plus one explicit membership) so a pagination cursor can be derived. Memberships are returned only while the service account is active. Without a page cursor, an archived service account returns an empty list. A page cursor that does not match an active membership returns a 400 invalid-request error. A cursor stops matching when the membership is removed, the workspace is deleted, or the service account is archived. Restart pagination from the first page to recover.

# Path parameters

  • service_account_id: string

    ID of the service account.

# Query parameters

  • limit: optional number

    Number of results per page.

    default: 20, maximum: 100, minimum: 1

  • page: optional string

    Opaque cursor from a previous response's next_page.

# Headers

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more

      • "message-batches-2024-09-24"

      • "prompt-caching-2024-07-31"

      • "computer-use-2024-10-22"

      • "computer-use-2025-01-24"

      • "pdfs-2024-09-25"

      • "token-counting-2024-11-01"

      • "token-efficient-tools-2025-02-19"

      • "output-128k-2025-02-19"

      • "files-api-2025-04-14"

      • "mcp-client-2025-04-04"

      • "mcp-client-2025-11-20"

      • "dev-full-thinking-2025-05-14"

      • "interleaved-thinking-2025-05-14"

      • "code-execution-2025-05-22"

      • "extended-cache-ttl-2025-04-11"

      • "context-1m-2025-08-07"

      • "context-management-2025-06-27"

      • "model-context-window-exceeded-2025-08-26"

      • "skills-2025-10-02"

      • "fast-mode-2026-02-01"

      • "output-300k-2026-03-24"

      • "user-profiles-2026-03-24"

      • "user-profiles-2026-08-18"

      • "user-profiles-2026-09-04"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

      • "dreaming-2026-04-21"

      • "thinking-token-count-2026-05-13"

      • "server-side-fallback-2026-06-01"

      • "server-side-fallback-2026-07-01"

      • "fallback-credit-2026-06-01"

      • "fallback-credit-2026-07-01"

      • "agent-memory-2026-07-22"

      • "mid-conversation-tool-changes-2026-07-01"

      • "compact-2026-01-12"

      • "computer-use-2025-11-24"

      • "mcp-tunnels-2026-06-22"

      • "structured-outputs-2025-11-13"

      • "task-budgets-2026-03-13"

      • "thinking-display-updates-2026-08-18"

      • "ce-user-management-2026-07-13"

      • "mid-conversation-output-config-2026-07-01"

      • "thinking-binding-controls-2026-08-01"

      • "mid-conversation-system-clear-at-2026-08-21"

      • "compact-2026-09-04"

# Returns

  • data: array of BetaServiceAccountWorkspaceMember

    • type: "service_account_workspace_member"

      default: service_account_workspace_member

    • created_by_actor_id: string or null

      Tagged ID (user_.../svac_...) of the actor who created this membership.

    • implicit: boolean or null

      True when this is the implicit default-workspace membership every service account has when no explicit membership exists. Implicit memberships have role workspace_user and cannot be removed.

    • service_account_id: string

      Tagged service account ID (svac_...).

    • workspace_id: string

      Tagged workspace ID (wrkspc_...).

    • workspace_role: BetaWorkspaceRole

      Role of the service account in this workspace. Service accounts cannot hold the workspace_billing role.

      • "workspace_admin"

      • "workspace_billing"

      • "workspace_developer"

      • "workspace_restricted_developer"

      • "workspace_user"

  • next_page: string or null

    Opaque cursor for the next page, or null if no more results.

# Example

bash
curl https://api.anthropic.com/v1/organizations/service_accounts/$SERVICE_ACCOUNT_ID/workspaces \
    -H 'anthropic-version: 2023-06-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"
# Response (200)
json
{
  "data": [
    {
      "created_by_actor_id": "created_by_actor_id",
      "implicit": true,
      "service_account_id": "service_account_id",
      "type": "service_account_workspace_member",
      "workspace_id": "workspace_id",
      "workspace_role": "workspace_admin"
    }
  ],
  "next_page": "next_page"
}

# Remove Workspace From Service Account

DELETE /v1/organizations/service_accounts/{service_account_id}/workspaces/{workspace_id}

Requires an OAuth access token with the org:admin scope, from ant auth login --scope org:admin or a workload identity federation rule; Admin API keys are not accepted. See Manage WIF with the Admin API.

Remove a service account from a workspace.

Mirror of DELETE /workspaces/{workspace_id}/service_accounts/{service_account_id}, addressed from the service-account side. Removal is idempotent (returns 200 even if the membership was already removed). A DELETE against the implicit default-workspace membership returns 200 but is a no-op and the membership persists; deleting an explicit default-workspace row reverts to the implicit workspace_user membership. Archived workspaces return 400.

# Path parameters

  • service_account_id: string

    ID of the service account.

  • workspace_id: string

    ID of the workspace.

# Headers

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more

      • "message-batches-2024-09-24"

      • "prompt-caching-2024-07-31"

      • "computer-use-2024-10-22"

      • "computer-use-2025-01-24"

      • "pdfs-2024-09-25"

      • "token-counting-2024-11-01"

      • "token-efficient-tools-2025-02-19"

      • "output-128k-2025-02-19"

      • "files-api-2025-04-14"

      • "mcp-client-2025-04-04"

      • "mcp-client-2025-11-20"

      • "dev-full-thinking-2025-05-14"

      • "interleaved-thinking-2025-05-14"

      • "code-execution-2025-05-22"

      • "extended-cache-ttl-2025-04-11"

      • "context-1m-2025-08-07"

      • "context-management-2025-06-27"

      • "model-context-window-exceeded-2025-08-26"

      • "skills-2025-10-02"

      • "fast-mode-2026-02-01"

      • "output-300k-2026-03-24"

      • "user-profiles-2026-03-24"

      • "user-profiles-2026-08-18"

      • "user-profiles-2026-09-04"

      • "advisor-tool-2026-03-01"

      • "managed-agents-2026-04-01"

      • "cache-diagnosis-2026-04-07"

      • "dreaming-2026-04-21"

      • "thinking-token-count-2026-05-13"

      • "server-side-fallback-2026-06-01"

      • "server-side-fallback-2026-07-01"

      • "fallback-credit-2026-06-01"

      • "fallback-credit-2026-07-01"

      • "agent-memory-2026-07-22"

      • "mid-conversation-tool-changes-2026-07-01"

      • "compact-2026-01-12"

      • "computer-use-2025-11-24"

      • "mcp-tunnels-2026-06-22"

      • "structured-outputs-2025-11-13"

      • "task-budgets-2026-03-13"

      • "thinking-display-updates-2026-08-18"

      • "ce-user-management-2026-07-13"

      • "mid-conversation-output-config-2026-07-01"

      • "thinking-binding-controls-2026-08-01"

      • "mid-conversation-system-clear-at-2026-08-21"

      • "compact-2026-09-04"

# Returns

  • type: "service_account_workspace_member_deleted"

    default: service_account_workspace_member_deleted

  • service_account_id: string

    Tagged service account ID (svac_...) named in the delete request. Removal is idempotent; see the endpoint description for the implicit-membership no-op.

  • workspace_id: string

    Tagged workspace ID (wrkspc_...) named in the delete request.

# Example

bash
curl https://api.anthropic.com/v1/organizations/service_accounts/$SERVICE_ACCOUNT_ID/workspaces/$WORKSPACE_ID \
    -X DELETE \
    -H 'anthropic-version: 2023-06-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"
# Response (200)
json
{
  "service_account_id": "service_account_id",
  "type": "service_account_workspace_member_deleted",
  "workspace_id": "workspace_id"
}
Files main
Menu

Theme
↑↓navigate ↵open escclose /⌘Kanywhere