Espacios de trabajo

Los workspaces proporcionan una forma de organizar el uso de tu API dentro de una organización. Usa workspaces para separar diferentes proyectos, entornos o equipos mientras mantienes la facturación y administración centralizadas.

Cómo funcionan los workspaces

Cada organización tiene un Default Workspace que no se puede renombrar, archivar ni eliminar. Cuando creas workspaces adicionales, puedes asignar miembros, cuentas de servicio, claves de API y límites de recursos a cada uno.

Características clave:

• Los identificadores de workspace usan el prefijo wrkspc_ (por ejemplo, wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ)
• Máximo 100 workspaces por organización de forma predeterminada (los workspaces archivados no cuentan); contacta a tu equipo de cuenta si necesitas más
• El Default Workspace tiene un ID wrkspc_ como cualquier otro workspace (devuelto en el encabezado de respuesta anthropic-workspace-id y aceptado por Get Workspace), pero aparece en los resultados de List Workspaces solo cuando pasas include_default=true, y las claves de API, los informes de uso y los informes de costos muestran null para su workspace_id, al igual que las claves de API de todos los workspaces (el campo scope de una clave de API permite distinguirlas; para una clave vinculada al Default Workspace, contiene el ID real)
• Las claves de API pueden limitarse a un solo workspace. En este caso, solo pueden acceder a recursos dentro de ese workspace. Algunas claves de API pueden recibir permisos en múltiples workspaces, y proporcionar un encabezado de ID de workspace para acceder a recursos dentro de ese workspace

Workspace de Claude Code

Cuando un miembro de tu organización inicia sesión por primera vez en Claude Code con su cuenta de Claude Console, Anthropic crea automáticamente un workspace de Claude Code en la organización y agrega a ese miembro a él. Cada miembro posterior que inicia sesión en Claude Code se agrega de la misma manera.

El workspace de Claude Code mantiene el tráfico de Claude Code separado de tus otras cargas de trabajo de API:

• Claude Code genera una clave de API por usuario en este workspace al iniciar sesión. No puedes crear claves en él manualmente desde la Console.
• Una clave de Claude Code deja de funcionar si su propietario es eliminado del workspace o de la organización, a diferencia de una clave de workspace.
• El uso de Claude Code tiene límites de velocidad por separado, y los administradores pueden limitar su parte de los límites de la organización en Settings > Workspaces.
• Es el único workspace que admite límites de gasto mensual por usuario.

Roles y permisos de workspace

Los miembros pueden tener diferentes roles en cada workspace, lo que permite un control de acceso detallado.

Herencia de roles

• Los administradores de la organización reciben automáticamente acceso de Workspace Admin a todos los workspaces
• Los miembros de facturación de la organización reciben automáticamente acceso de Workspace Billing a todos los workspaces
• Los usuarios y desarrolladores de la organización deben agregarse explícitamente a cada workspace
• Las cuentas de servicio se agregan a los workspaces en Settings > Service accounts: selecciona Add to workspace en el menú de la cuenta o en su propia página. Para ver las cuentas en un workspace, filtra la lista por workspace.

Gestión de workspaces

Usando la Console

Crea y gestiona workspaces en la Claude Console.

Crear un workspace

1. 1

   Abrir la configuración del workspace

   En la Claude Console, ve a Settings > Workspaces.

2. 2

   Crear un workspace

   Haz clic en Create workspace.

3. 3

   Configurar el workspace

   Ingresa un nombre de workspace y selecciona un color para identificación visual.

4. 4

   Crear el workspace

   Haz clic en Create para finalizar.

Editar detalles del workspace

Para modificar el nombre o color de un workspace:

1. Selecciona el workspace de la lista.
2. Haz clic en el menú de puntos suspensivos (...) y elige Edit details.
3. Actualiza el nombre o color y guarda tus cambios.

Agregar miembros a un workspace

1. Navega a la pestaña Members del workspace.
2. Haz clic en Add to Workspace.
3. Selecciona un miembro de la organización y asígnale un rol de workspace.
4. Confirma la adición.

Para eliminar un miembro, haz clic en el icono de papelera junto a su nombre.

Establecer límites de workspace

La configuración de cada workspace divide estos en dos pestañas:

• Límites de velocidad: En la pestaña Rate limits, establece límites por nivel de modelo para solicitudes por minuto, tokens de entrada o tokens de salida
• Límites de gasto: En la pestaña Spend limits, limita el gasto mensual y configura alertas cuando el gasto alcance ciertos umbrales

Archivar un workspace

Para archivar un workspace, haz clic en el menú de puntos suspensivos (...) y selecciona Archive. Archivar:

• Preserva los datos históricos para informes
• Desactiva el workspace y archiva cada clave de API creada para él
• No se puede deshacer

Usando la Admin API

Gestiona workspaces de forma programática usando la Admin API.

Los siguientes ejemplos de SDK y CLI construyen el cliente predeterminado, que lee la clave de Admin API de la variable de entorno ANTHROPIC_API_KEY; los SDK exponen estos endpoints en client.organization.workspaces. Los métodos de listado de los SDK obtienen páginas adicionales bajo demanda, por lo que limit establece el tamaño de página; los ejemplos de PHP, Ruby y curl devuelven una página.

Crear un workspace:

client = anthropic.Anthropic()

workspace = client.organization.workspaces.create(name="Production")

print(f"id: {workspace.id}")
print(f"name: {workspace.name}")

Listar workspaces:

client = anthropic.Anthropic()

workspaces = client.organization.workspaces.list(limit=10, include_archived=False)

for workspace in workspaces:
    print(f"{workspace.id}: {workspace.name}")

Archivar un workspace:

client = anthropic.Anthropic()

workspace = client.organization.workspaces.archive("wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ")

print(f"id: {workspace.id}")
print(f"archived_at: {workspace.archived_at}")

Para obtener detalles completos de los parámetros y los esquemas de respuesta, consulta la referencia de la API de Workspaces.

Gestión de miembros del workspace

Agregar un miembro a un workspace:

client = anthropic.Anthropic()

member = client.organization.workspaces.members.add(
    "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
    user_id="user_01XyDMpzjS89pFZXqSFUBDr6",
    workspace_role="workspace_developer",
)

print(f"user_id: {member.user_id}")
print(f"workspace_role: {member.workspace_role}")

Actualizar el rol de un miembro:

client = anthropic.Anthropic()

member = client.organization.workspaces.members.update(
    "user_01XyDMpzjS89pFZXqSFUBDr6",
    workspace_id="wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
    workspace_role="workspace_admin",
)

print(f"user_id: {member.user_id}")
print(f"workspace_role: {member.workspace_role}")

Eliminar un miembro de un workspace:

client = anthropic.Anthropic()

removed_member = client.organization.workspaces.members.remove(
    "user_01XyDMpzjS89pFZXqSFUBDr6",
    workspace_id="wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
)

print(f"user_id: {removed_member.user_id}")

Para obtener detalles completos de los parámetros, consulta la referencia de la API de Workspace Members.

Claves de API y alcance de recursos

Cada solicitud se ejecuta en exactamente un workspace y solo puede acceder a recursos dentro de ese workspace. Qué workspace depende del tipo de clave:

• Una clave de workspace (una clave heredada sin propietario) pertenece al workspace en el que se creó y siempre se ejecuta ahí.
• Una clave personal o clave de cuenta de servicio actúa como su usuario o cuenta de servicio. Una clave de un solo workspace siempre se ejecuta en el workspace elegido cuando se creó. Una clave de múltiples workspaces se ejecuta en el workspace nombrado por el encabezado anthropic-workspace-id de cada solicitud. Las cuentas deben tener acceso al workspace para usarlo.

Los recursos limitados a workspaces incluyen:

• Archivos creados a través de la Files API
• Message Batches creados a través de la Batch API
• Skills creados a través de la Skills API

Algunos recursos se gestionan de manera diferente:

• Los túneles MCP se gestionan con un token OAuth workspace:manage_tunnels obtenido a través de Workload Identity Federation, no con una clave de API. Los túneles se crean en un workspace, y la lista de MCP tunnels de la Console y el selector de servidor de Managed Agent muestran los túneles solo en el workspace actual; el límite de 10 túneles activos se aplica a toda la organización. La gestión de túneles requiere un rol con permisos de gestión de túneles; los desarrolladores de la organización pueden verlos pero no cambiarlos.
• Los workspaces en sí mismos y los miembros de la organización se gestionan a nivel de organización a través de la Admin API, usando una clave de Admin API, un token OAuth org:admin, o una clave personal o de cuenta de servicio que no esté limitada a un workspace específico.

Para consultar los ID de workspace de tu organización, llama al endpoint List Workspaces (pasa include_default=true para incluir el Default Workspace) o búscalos en la Claude Console.

Identificar el workspace detrás de una respuesta de API

Las respuestas de la Claude API incluyen un encabezado anthropic-workspace-id junto con los encabezados de respuesta request-id y anthropic-organization-id. Su valor es el ID con prefijo wrkspc_ del workspace al que se resolvió la clave de API o el token de acceso de la solicitud, incluso cuando ese workspace es el Default Workspace. Por ejemplo, una respuesta exitosa incluye encabezados como estos:

HTTP/1.1 200 OK
request-id: req_018EeWyXxfu5pfWkrYcMdjWG
anthropic-organization-id: 0d0e7a3b-52f1-4c7e-9a51-3f6f2f7c1b9e
anthropic-workspace-id: wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ

El encabezado está ausente cuando la credencial no se resuelve a un workspace (por ejemplo, en solicitudes de la Admin API) o cuando la solicitud falla antes de que se complete la autenticación, como un error 401.

Los siguientes ejemplos envían una solicitud de la Messages API e imprimen el ID del workspace de los encabezados de respuesta:

client = anthropic.Anthropic()

response = client.messages.with_raw_response.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
workspace_id = response.headers.get("anthropic-workspace-id")
print(f"Workspace ID: {workspace_id}")

Workspace ID: wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ

Los mismos accesores leen el encabezado de otros endpoints de la Claude API también, incluyendo las APIs de Claude Managed Agents. Por ejemplo, lee anthropic-workspace-id de la respuesta que crea una sesión para registrar a qué workspace pertenece la sesión.

Con el ID del workspace de una respuesta, puedes:

• Confirmar hacia qué uso, costo y límites de velocidad del workspace contó la solicitud
• Compararlo con el campo workspace_id en los informes de la Usage and Cost API y en los objetos de la Admin API como las claves de API (ambos informan null para el Default Workspace, al igual que las claves de API para las claves de todos los workspaces; el campo scope de una clave de API distingue las dos y, para una clave vinculada a un workspace, lleva el ID real de ese workspace)
• Comprobar si es el ID de tu Default Workspace pasándolo a Get Workspace con una clave de Admin API: el Default Workspace se devuelve con "name": "Default", aunque List Workspaces lo omite a menos que pases include_default=true
• Abrir ese workspace en la Console para encontrar los recursos de la solicitud, como sesiones, archivos, lotes de mensajes y skills

Límites de workspace

Puedes establecer límites personalizados de gasto y velocidad para cada workspace para protegerte contra el uso excesivo y garantizar una distribución justa de recursos.

Establecer límites de workspace

Puedes establecer límites de workspace más bajos que (pero no más altos que) los límites de tu organización:

• Límites de gasto: Limita el gasto mensual de un workspace. Establécelos en la pestaña de configuración Spend limits del workspace en la Claude Console.
• Límites de velocidad: Limita las solicitudes por minuto, los tokens de entrada por minuto o los tokens de salida por minuto. Establécelos en la pestaña de configuración Rate limits del workspace en la Claude Console.

Para obtener información detallada sobre los límites de velocidad y cómo funcionan, consulta Límites de velocidad. También puedes leer tus límites de velocidad actuales de organización y workspace de forma programática con la Rate Limits API.

Seguimiento de uso y costos

Rastrea el uso y los costos por workspace usando la Usage and Cost API:

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-08T00:00:00Z&\
workspace_ids[]=wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ&\
group_by[]=workspace_id&\
bucket_width=1d" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

El uso y los costos atribuidos al Default Workspace tienen un valor null para workspace_id.

Casos de uso comunes

Separación de entornos

Crea workspaces separados para desarrollo, staging y producción:

Aislamiento de equipo o departamento

Asigna workspaces a diferentes equipos para la asignación de costos y el control de acceso:

• Equipo de ingeniería con acceso de desarrollador
• Equipo de ciencia de datos con sus propias claves de API
• Equipo de soporte con acceso limitado para herramientas de clientes

Organización basada en proyectos

Crea workspaces para proyectos o productos específicos para rastrear el uso y los costos por separado.

Mejores prácticas

1. 1

   Planifica la estructura de tu workspace

   Considera cómo organizarás los workspaces antes de crearlos. Piensa en las necesidades de facturación, control de acceso y seguimiento de uso.

2. 2

   Usa nombres significativos

   Nombra los workspaces claramente para indicar su propósito (por ejemplo, "Production - Customer Chatbot" o "Dev - Internal Tools").

3. 3

   Establece límites apropiados

   Configura límites de gasto y velocidad para prevenir costos inesperados y garantizar una distribución justa de recursos.

4. 4

   Audita el acceso regularmente

   Revisa la membresía del workspace periódicamente para garantizar que solo los usuarios apropiados tengan acceso.

5. 5

   Monitorea el uso

   Usa la Usage and Cost API para rastrear el consumo a nivel de workspace.

Preguntas frecuentes

Consulta también

• Admin API
• Referencia de la Admin API
• Límites de velocidad
• Usage and Cost API