> ## Documentation Index
> Fetch the complete documentation index at: https://astronomer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Workspace users with the APC API

<Note>
  The examples on this page show common ways to use the APC API — they're not a complete API reference. For the full, interactive API documentation for your installation, including every available query, mutation, and type, go to `https://houston.<your-base-domain>/v1`, and click on the **Docs** tab. See [Develop and test APC API queries](/docs/astro-private-cloud/v-2-x/houston-api-develop-test) for more on using the built-in GraphQL explorer.
</Note>

You can use the APC API to manage the users in a Workspace. These mutations require Workspace Admin permissions on the target Workspace. Each mutation requires a `workspaceUuid`, which you can retrieve by running `astro workspace list` or using the [`workspaces`](/docs/astro-private-cloud/v-2-x/houston-api-example-queries#workspaces) query.

The `role` value must be one of `WORKSPACE_ADMIN`, `WORKSPACE_EDITOR`, or `WORKSPACE_VIEWER`.

## Add a user to a Workspace

Use the `workspaceAddUser` mutation to add an existing user to a Workspace with a specified role.

```graphql wrap theme={null}
mutation AddWorkspaceUser(
  $workspaceUuid: Uuid! = "<workspace-id>"
  $email: String! = "<user-email-address>"
  $role: Role! = WORKSPACE_VIEWER
) {
  workspaceAddUser(
    workspaceUuid: $workspaceUuid
    email: $email
    role: $role
  ) {
    id
    label
    users {
      id
      username
      roleBindings {
        role
      }
    }
  }
}
```

## Update a user's Workspace role

Use the `workspaceUpsertUserRole` mutation to change the role of a user who already belongs to a Workspace.

```graphql wrap theme={null}
mutation UpdateWorkspaceUserRole(
  $workspaceUuid: Uuid! = "<workspace-id>"
  $email: String! = "<user-email-address>"
  $role: Role! = WORKSPACE_EDITOR
) {
  workspaceUpsertUserRole(
    workspaceUuid: $workspaceUuid
    email: $email
    role: $role
  )
}
```

## Remove a user from a Workspace

Use the `workspaceRemoveUser` mutation to remove a user from a Workspace. Provide the `workspaceUuid` and the `userUuid` of the user to remove. To retrieve the `userUuid`, use the [`workspaceUsers`](/docs/astro-private-cloud/v-2-x/houston-api-example-queries#workspace-users) query or a `users` query.

```graphql wrap theme={null}
mutation RemoveWorkspaceUser(
  $workspaceUuid: Uuid! = "<workspace-id>"
  $userUuid: Uuid! = "<user-id>"
) {
  workspaceRemoveUser(
    workspaceUuid: $workspaceUuid
    userUuid: $userUuid
  ) {
    id
    label
    users {
      id
      username
    }
  }
}
```