---
name: layer-manage-workspace
description: Administer a Layer workspace — projects, groups, members, roles, usage limits, and Creative Unit consumption — over the REST API or the Layer Management MCP server. Use when asked to onboard or offboard teammates, organise work into projects, cap a team's spend, or report on how many Creative Units a workspace has used.
---

# Administer a Layer workspace

Administration lives on its own surface, kept apart from generation so admin tools do not crowd
the creative toolset. Every path below is workspace-scoped and needs an `ADMIN` or `OWNER` role
in the target workspace; a lower role gets 403, and retrying will not change that.

## Spend and usage

```bash
curl -H "Authorization: Bearer $LAYER_TOKEN" \
  https://api.app.layer.ai/api/v2/workspaces/$WORKSPACE_ID/usage
```

Returns `balance_creative_units`, `reserved_creative_units` (held by runs in flight),
`available_creative_units`, the current `period_start`/`period_end`, `total_creative_units` for
the period, and a `daily` breakdown. This is the report to read before answering "how much have
we spent" — Creative Units are the consumption currency, and Layer charges no per-seat fee.

## Members

- `GET /v2/workspaces/{workspace_id}/members` — list, with `email`, `name`, `role`, and `status`.
- `POST /v2/workspaces/{workspace_id}/members` — invite by `email`, with a `role` (defaults to
  member).
- `PATCH /v2/workspaces/{workspace_id}/members/{user_id}` — change `role`, or set `status` to
  `suspended` / `active`. Suspending is the reversible way to offboard someone.

Roles, least- to most-privileged: `VIEWER`, `MEMBER`, `ADMIN`, `OWNER`. Reads need `VIEWER`;
anything that changes state or starts a run needs at least `MEMBER`.

## Groups and usage limits

Groups carry a role and can carry a spend cap, which is how a team is budgeted rather than
policed one person at a time.

- `GET|POST /v2/workspaces/{workspace_id}/groups`
- `PATCH|DELETE /v2/workspaces/{workspace_id}/groups/{group_id}`
- `GET|POST /v2/workspaces/{workspace_id}/groups/{group_id}/members`,
  `DELETE …/members/{user_id}`
- `PUT /v2/workspaces/{workspace_id}/groups/{group_id}/usage-limit` with
  `{ "cu_limit": 5000, "period": "monthly" }` (`daily`, `weekly`, or `monthly`);
  `DELETE` the same path removes the cap.

## Projects

- `GET|POST /v2/workspaces/{workspace_id}/projects` — a project has a `name`, `description`, and
  `instructions` (standing guidance applied to work inside it).
- `GET|PATCH|DELETE /v2/workspaces/{workspace_id}/projects/{project_id}` — `PATCH` can set
  `archived`; status is `active`, `archived`, or `deleted`.
- `POST /v2/workspaces/{workspace_id}/projects/{project_id}/members` with `user_ids`, and
  `DELETE …/members/{user_id}`.

Project membership is a real authorization boundary: project-scoped resources check it in
addition to the workspace role.

## Over MCP

The management server is a second endpoint, `https://mcp.app.layer.ai/mcp-management`, added to a
client separately from the creative one. It carries `list_workspaces`, `get_workspace_usage`,
`list_workspace_members`, `invite_member`, `suspend_member`, `reactivate_member`, `create_group`,
`update_group_role`, `delete_group`, `list_groups`, `list_group_members`, `add_group_member`,
`remove_group_member`, `set_group_usage_limit`, `remove_group_usage_limit`, `create_project`,
`update_project`, `delete_project`, `list_projects`, `get_project`, `add_project_members`, and
`remove_project_member`.

## Note on credentials

A Personal Access Token inherits **all** of its creating user's permissions — including these. If
an integration only needs to generate assets, do not give it an admin's token; provision a
dedicated user with the narrowest role that works.

## Reference

- Management MCP server: <https://layer.ai/docs/mcp/management>
- REST reference: <https://layer.ai/docs/v2/rest-api>
- Permission model: <https://layer.ai/docs/authentication#permissions>