Espacios de trabajo

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

Cómo funcionan los espacios de trabajo

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

Características clave:

• Los identificadores de espacio de trabajo usan el prefijo wrkspc_ (por ejemplo, wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ)
• Máximo de 100 espacios de trabajo por organización de forma predeterminada (los espacios de trabajo archivados no cuentan); contacta a tu equipo de cuenta si necesitas más
• El Default Workspace tiene un ID wrkspc_ como cualquier otro espacio de trabajo (devuelto en el encabezado de respuesta anthropic-workspace-id y aceptado por Get Workspace), pero no aparece en los resultados de List Workspaces, 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 espacios de trabajo (el campo scope de una clave de API las distingue; para una clave vinculada al Default Workspace contiene el ID real)
• Las claves de API pueden tener alcance limitado a un único espacio de trabajo. En este caso, solo pueden acceder a recursos dentro de ese espacio de trabajo. A algunas claves de API se les pueden otorgar permisos en múltiples espacios de trabajo, y proporcionan un encabezado de ID de espacio de trabajo para acceder a recursos dentro de ese espacio de trabajo

Espacio de trabajo 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 espacio de trabajo 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 espacio de trabajo de Claude Code mantiene el tráfico de Claude Code separado de tus otras cargas de trabajo de la API:

• Claude Code genera una clave de API por usuario en este espacio de trabajo 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 espacio de trabajo o de la organización, a diferencia de una clave de espacio de trabajo.
• El uso de Claude Code tiene un límite de velocidad independiente, y los administradores pueden limitar su parte de los límites de la organización en Settings > Workspaces.
• Es el único espacio de trabajo que admite límites de gasto mensuales por usuario.

Roles y permisos de espacio de trabajo

Los miembros pueden tener diferentes roles en cada espacio de trabajo, 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 espacios de trabajo
• Los miembros de facturación de la organización reciben automáticamente acceso de Workspace Billing a todos los espacios de trabajo
• Los usuarios y desarrolladores de la organización deben agregarse explícitamente a cada espacio de trabajo
• Las cuentas de servicio se agregan a los espacios de trabajo desde la página de la cuenta de servicio en Settings → Service accounts o desde la pestaña Service accounts del espacio de trabajo

Gestión de espacios de trabajo

Usando la Console

Crea y gestiona espacios de trabajo en la Claude Console.

Crear un espacio de trabajo

1. 1

   Abre la configuración de espacios de trabajo

   En la Claude Console, ve a Settings > Workspaces.

2. 2

   Crea un espacio de trabajo

   Haz clic en Create workspace.

3. 3

   Configura el espacio de trabajo

   Ingresa un nombre para el espacio de trabajo y selecciona un color para su identificación visual.

4. 4

   Crea el espacio de trabajo

   Haz clic en Create para finalizar.

Editar los detalles del espacio de trabajo

Para modificar el nombre o el color de un espacio de trabajo:

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

Agregar miembros a un espacio de trabajo

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

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

Establecer límites del espacio de trabajo

La configuración de cada espacio de trabajo divide estos límites 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 espacio de trabajo

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

• Conserva los datos históricos para informes
• Desactiva el espacio de trabajo y archiva todas las claves de API creadas para él
• No se puede deshacer

Usando la Admin API

Gestiona espacios de trabajo 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 bajo client.beta.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 espacio de trabajo:

client = anthropic.Anthropic()

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

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

Listar espacios de trabajo:

client = anthropic.Anthropic()

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

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

Archivar un espacio de trabajo:

client = anthropic.Anthropic()

workspace = client.beta.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 esquemas de respuesta, consulta la referencia de la API de Workspaces.

Gestión de miembros del espacio de trabajo

Agregar un miembro a un espacio de trabajo:

client = anthropic.Anthropic()

member = client.beta.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.beta.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 espacio de trabajo:

client = anthropic.Anthropic()

removed_member = client.beta.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 espacio de trabajo y solo puede acceder a recursos dentro de ese espacio de trabajo. Qué espacio de trabajo depende del tipo de clave:

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

Los recursos con alcance limitado a espacios de trabajo incluyen:

• Archivos creados a través de la Files API
• Lotes de mensajes creados a través de la Batch API
• Skills creadas 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 espacio de trabajo, y la lista MCP tunnels de la Console y el selector de servidores de Managed Agent muestran solo los túneles del espacio de trabajo 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 modificarlos.
• Los espacios de trabajo en sí 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 tenga alcance limitado a un espacio de trabajo específico.

Para consultar los ID de espacio de trabajo de tu organización, llama al endpoint List Workspaces o encuéntralos en la Claude Console.

Identificar el espacio de trabajo detrás de una respuesta de la 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 espacio de trabajo al que se resolvió la clave de API o el token de acceso de la solicitud, incluso cuando ese espacio de trabajo 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 espacio de trabajo (por ejemplo, en solicitudes a la Admin API) o cuando la solicitud falla antes de que se complete la autenticación, como en un error 401.

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

client = anthropic.Anthropic()

response = client.messages.with_raw_response.create(
    model="claude-opus-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 métodos de acceso leen el encabezado también desde otros endpoints de la Claude API, incluidas las API de Claude Managed Agents. Por ejemplo, lee anthropic-workspace-id de la respuesta que crea una sesión para registrar a qué espacio de trabajo pertenece la sesión.

Con el ID del espacio de trabajo de una respuesta, puedes:

• Confirmar para qué espacio de trabajo se contabilizaron el uso, el costo y los límites de velocidad de la solicitud
• Compararlo con el campo workspace_id en los informes de la Usage and Cost API y en objetos de la Admin API como las claves de API (ambos reportan null para el Default Workspace, como también lo hacen las claves de API para las claves de todos los espacios de trabajo; el campo scope de una clave de API distingue ambos casos y, para una clave vinculada a un espacio de trabajo, contiene el ID real de ese espacio de trabajo)
• Verificar 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
• Abrir ese espacio de trabajo en la Console para encontrar los recursos de la solicitud, como sesiones, archivos, lotes de mensajes y skills

Límites del espacio de trabajo

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

Establecer límites del espacio de trabajo

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

• Límites de gasto: Limita el gasto mensual de un espacio de trabajo. Establécelos en la pestaña de configuración Spend limits del espacio de trabajo 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 espacio de trabajo 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 los límites de velocidad actuales de tu organización y espacio de trabajo de forma programática con la Rate Limits API.

Seguimiento de uso y costos

Realiza un seguimiento del uso y los costos por espacio de trabajo 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 espacios de trabajo separados para desarrollo, staging y producción:

Aislamiento por equipo o departamento

Asigna espacios de trabajo 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 espacios de trabajo para proyectos o productos específicos para realizar un seguimiento del uso y los costos por separado.

Mejores prácticas

1. 1

   Planifica la estructura de tus espacios de trabajo

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

2. 2

   Usa nombres significativos

   Nombra los espacios de trabajo con claridad 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 de velocidad para evitar costos inesperados y garantizar una distribución justa de los recursos.

4. 4

   Audita el acceso regularmente

   Revisa la membresía de los espacios de trabajo periódicamente para asegurarte de que solo los usuarios apropiados tengan acceso.

5. 5

   Monitorea el uso

   Usa la Usage and Cost API para realizar un seguimiento del consumo a nivel de espacio de trabajo.

Preguntas frecuentes

Ver también

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