Remove Users

Removing a user revokes their access and cleans up their assignments. Blue offers two scopes, mapped to two mutations:

• removeProjectUser detaches a user from a single workspace (Workspace) while keeping their organization (Organization) membership and access to other workspaces.
• removeOrganizationUser removes a user from the organization entirely, cascading the removal across every workspace they belonged to.

Both are permanent. There is no “undo” — re-granting access means re-inviting the user with inviteUser. Historical data the user created (records, comments, activity) is preserved.

Authentication

All requests go to https://api.blue.app/graphql with your personal access token. The project header is not required for either mutation — both take their scope from the input.

curl https://api.blue.app/graphql \
  -H "blue-token-id: YOUR_TOKEN_ID" \
  -H "blue-token-secret: YOUR_TOKEN_SECRET" \
  -H "blue-org-id: YOUR_ORG_ID" \
  -H "Content-Type: application/json" \
  --data '{"query":"..."}'

Header names are case-insensitive. See Authentication for token setup.

Request

Remove a user from a workspace

Use removeProjectUser to detach a user from one workspace. The projectId must be the workspace ID — this mutation does not accept a slug.

mutation RemoveWorkspaceUser {
  removeProjectUser(input: { projectId: "project_123", userId: "user_123" }) {
    success
    operationId
  }
}

Remove a user from the organization

Use removeOrganizationUser to remove a user from the whole organization. companyId accepts either the organization ID or slug.

mutation RemoveOrganizationUser {
  removeOrganizationUser(input: { companyId: "company_123", userId: "user_123" })
}

Parameters

RemoveProjectUserInput

RemoveCompanyUserInput

Response

removeProjectUser returns a MutationResult. The resolver returns only { success: true }, so operationId is always null for this mutation.

{
  "data": {
    "removeProjectUser": {
      "success": true,
      "operationId": null
    }
  }
}

removeOrganizationUser returns a bare Boolean — true on success. There are no subfields to select.

{
  "data": {
    "removeOrganizationUser": true
  }
}

Returns

removeProjectUser — MutationResult!

removeOrganizationUser — Boolean

true when the user was removed from the organization.

Side effects

These mutations do more than drop a membership row. Know what each one cleans up before you call it.

removeProjectUser

• Unassigns the user from every record (Record) in the workspace.
• Removes the user from any assignee custom-field values on records in the workspace.
• Deletes the user’s personal saved views in the workspace (shared saved views are kept).
• Deletes the user’s per-workspace folders.
• Removes the workspace membership and publishes a real-time update to other members.
• Writes an activity-log entry.

removeOrganizationUser

Cascades across every workspace in the organization:

• Unassigns the user from all records in all workspaces.
• Removes the user from all assignee custom-field values across the organization.
• Deletes the user’s workspace folders everywhere.
• Removes every workspace membership.
• Removes the organization membership (which cascades the organization-level folders).
• Decrements the organization’s billed seat count by syncing the Stripe subscription quantity.
• Sends a removal-notification email to the removed user.
• Writes an activity-log entry.

Errors

A FORBIDDEN error covers every authorization failure these mutations raise:

{
  "errors": [
    {
      "message": "You are not authorized.",
      "extensions": { "code": "FORBIDDEN" }
    }
  ]
}

Permissions

removeProjectUser

Requires a workspace access level of OWNER or ADMIN. A workspace OWNER cannot be removed — transfer ownership first.

removeOrganizationUser

Requires an organization access level of OWNER. Organization ADMINs cannot remove users.

Related

• Invite a User — re-grant access after a removal.
• List Users — find a user’s ID before removing them.
• Retrieve Custom Role — inspect a user’s role and permissions.