# Remove role from user

> **Legacy.** This endpoint is kept for existing integrations. Use the current API reference for new work.

Remove role from user

- Endpoint: `POST https://api.returning.ai/roles/{userId}/{roleId}/remove`
- Section: Legacy / Roles and permissions
- Authentication: `Authorization: Bearer <API_KEY>` (Community API key)
- Guide: generated from the published specification
- Last updated: 26 Sep 2026
- Web page: https://docs.returning.ai/api-reference/legacy-roles-and-permissions/remove-role-from-user

## Authentication

- Header: `Authorization: Bearer <API_KEY>`

## Behaviour

**Legacy category**

This endpoint is retained for compatibility, historical admin tooling, or test workflows. Do not use it as the default choice for new integrations unless the backend team confirms this exact route is still supported for your community.

**What it is for**

Remove role from user.

**How to use it**

Send a POST request to `/roles/{userId}/{roleId}/remove` with the documented body, query parameters, headers, or multipart fields. Prefer the newer authenticated `/v1/...` integration API where available.

**Successful response**

HTTP 2xx. Older endpoints may return a legacy response envelope or a resource-specific payload rather than the newer `{ status, message, data }` wrapper.

**Common error states**

- `400` invalid request body, query, ObjectId, pagination, file format, or missing required field.
- `401` missing, invalid, expired, or insufficient API key/token.
- `403` key is valid but cannot access this community/channel/user/resource, where supported by the service.
- `404` route or target resource was not found. Several legacy root routes return `404` on `https://api.returning.ai`; confirm with Returning.AI before using them.
- `409` duplicate or conflicting state for create/update operations, where applicable.
- `500` unexpected Returning.AI service error.

**Legacy status**

Compatibility endpoint retained for older integrations. Do not use this endpoint for new integrations unless Returning.AI specifically tells you to maintain a legacy flow. Prefer the current `/v1/...` endpoint in the matching non-Legacy category when one exists.

**Source-backed clarification**

These are compatibility endpoints using older server/role terminology. Use them only when maintaining an existing integration. For new public docs and integrations, prefer community/user permission language and scoped API-key permissions.

## Request

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `userId` | `string` | Yes | User ID in Returning.AI. |
| `roleId` | `string` | Yes | Role ObjectId. |

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Yes | API key. (`Bearer <API_KEY>`) |
| `x-api-key` | `string` | Yes | Legacy server API key header. Prefer `Authorization: Bearer <API_KEY>` for `/v1/...` integration APIs. |

### Example request

```bash
curl --request POST \
  --url 'https://api.returning.ai/roles/<userId>/<roleId>/remove' \
  --header 'Authorization: Bearer <API_KEY>'
```

## Response

### Response fields

| Field | Type | Presence | Description |
| --- | --- | --- | --- |
| `meta` | `object` | always | - |
| `meta.success` | `boolean` | always | - |
| `meta.message` | `string` | always | - |
| `meta.devMessage` | `string` | always | - |
| `body` | `object` | always | - |
| `_id` | `string` | always | - |
| `name` | `string` | always | - |
| `email` | `string` | always | - |
| `displayname` | `string` | always | - |
| `first` | `string` | always | - |
| `last` | `string` | always | - |
| `nicename` | `string` | always | - |
| `signup_date` | `string` | always | - |
| `last_login` | `string` | always | - |
| `isVerified` | `boolean` | always | - |
| `joinServer` | `boolean` | always | - |
| `createdAt` | `string` | always | - |
| `updatedAt` | `string` | always | - |
| `id` | `string` | always | - |
| `__v` | `integer` | always | - |
| `badges` | `object` | always | - |
| `server_roles` | `string[]` | always | - |

### Example response (200)

```json
{
  "meta": {
    "success": true,
    "message": "Role has been removed from user successfully",
    "devMessage": "Role has been removed from user successfully"
  },
  "body": {
    "_id": "{_id}",
    "name": "Reti Him",
    "email": "lazosa@uiemail.com",
    "displayname": "lazosa",
    "first": "Reti",
    "last": "Him",
    "nicename": "lazosa",
    "signup_date": "2025-04-30T04:54:51.777Z",
    "last_login": "2025-04-30T08:27:33.138Z",
    "isVerified": true,
    "joinServer": true,
    "createdAt": "2025-04-30T04:54:51.780Z",
    "updatedAt": "2025-04-30T08:52:39.550Z",
    "id": "{id}",
    "__v": 0,
    "badges": {},
    "server_roles": []
  }
}
```

## Errors

### Fix the request

| Status | Code | What to do |
| --- | --- | --- |
| 400 | - | Invalid request. Check required parameters, body fields, file format, pagination values, and ObjectId values. |
| 401 | - | Missing, invalid, expired, or insufficient API key/token. Older permission middleware may also return 401 for missing permissions. |
| 403 | - | The API key is valid but is not allowed to access this community, channel, user, or resource. |

### Fix the data

| Status | Code | What to do |
| --- | --- | --- |
| 404 | - | The requested resource, route, community, channel, user, API key, status, or job was not found. |
| 409 | - | The request conflicts with an existing resource or immutable state, such as a duplicate slug/key/name or an already-processed record. |

### Retry with backoff

| Status | Code | What to do |
| --- | --- | --- |
| 500 | - | Unexpected Returning.AI service error. |

## Next step

- [List badges](https://docs.returning.ai/api-reference/legacy-badges/list-badges.md): `GET /badges`.