# Members

The people in a workspace and its pending invitations, with their grants; list them or remove a member.

Belongs to: [Users](https://sparklogs.com/docs/api/reference/users.md)

Ids: text.

- `GET /workspaces/{workspace_id}/members` [List members](#list-members)
- `DELETE /workspaces/{workspace_id}/members/{user_id}` [Remove a member](#delete-member)

## Member object

A member is a person in the workspace, with the grants and groups that give them access.

- `user_id` (string, required): The member's user id.
- `email` (email, required): The member's email address.
- `full_name` (string or null, required): The member's full name.
- `display_name` (string or null, required): The name the app shows for the member.
- `is_self` (boolean, required): Whether the member is you.
- `created_at` (date-time, required): When the member joined the workspace.
- `deleted_at` (date-time or null, required): When the person's account was deleted; null while it is active.
- `grants` (array of Grant, required): The member's own grants you are shown: all of yours, and anyone else's inside your reach. Grants held through a group are on the group.
- `other_grants` (boolean, required): True when the member holds a grant you are not shown.
- `groups` (array of GroupRef, required): The groups the member is in that `group.read` shows you; on your own row, every group you are in.

## List members

`GET https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/members`

Preview

Returns the workspace's members, deleted accounts included, each with its grants, a page at a time, oldest membership first. Needs `member.read`; you see the members your reach contains, with their grants inside it. Pending invitations are listed by `list-invitations`. A workspace token's grants are not listed here; the app lists them, and they change through the grant calls. Without `member.read` over every organization, a member is listed only through a grant at or below an organization you reach, so a member with no such grant, or none at all, is not listed.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: any of `admin:read`, `admin:write`
- Privilege: `member.read`

Needs `member.read`. `member.read` applies at each organization a grant covers and every organization below it. A caller who reaches no organization gets an empty list.

### Behavior

- Retry: Safe to send again
- Paging: Cursor · 1000 a page by default, up to 5000

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.

### Query parameters

- `email` (string): Only the member with this email address. A person you are not shown answers an empty page, as one who is no member does. Matched exactly, ignoring case; every match you can see is returned. Spaces around the value are ignored.
- `limit` (integer): How many members a page holds: 1 to 5000, 1000 by default.
  Default: `1000` · 1 to 5000
- `cursor` (string): The `next_cursor` of the previous page, with the same filters.

### Response (200)

- `members` (array of Member, required): The members you are shown, deleted accounts included, oldest membership first.
- `next_cursor` (string or null, required): Null on the last page. Otherwise pass it as `cursor`, with the same filters, for the next page.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A query parameter it does not take, or one given twice. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A filter's value is empty, names an empty item, is not one of the values the filter takes, or is not an id or a time where the filter asks for one; `parameter` names the filter. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `limit` is not 1 to 5000, or `cursor` cannot be read or was sent with other filters. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE` (cause `token_scope` or `no_privilege`) | You do not hold `member.read`. The same refusal comes when the path names a workspace other than the token's own. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [Remove a member](https://sparklogs.com/docs/api/reference/members.md#delete-member)

### Example

List members

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/members" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "members retrieved",
  "members": [
    {
      "user_id": "AlexRiveraExampleUserId00001",
      "email": "alex.rivera@example.com",
      "full_name": "Alex Rivera",
      "display_name": "Alex",
      "is_self": false,
      "created_at": "2026-11-01T09:00:00Z",
      "deleted_at": null,
      "grants": [
        {
          "id": "6a170000-0000-4000-8000-000000000501",
          "role_id": "admin",
          "scope": {
            "kind": "all",
            "org_ids": [],
            "inherited": false,
            "other_orgs": false
          }
        }
      ],
      "other_grants": false,
      "groups": []
    },
    {
      "user_id": "SamChenExampleUserId00000002",
      "email": "sam.chen@example.com",
      "full_name": "Sam Chen",
      "display_name": "Sam",
      "is_self": false,
      "created_at": "2026-11-02T10:00:00Z",
      "deleted_at": null,
      "grants": [
        {
          "id": "6a170000-0000-4000-8000-000000000502",
          "role_id": "engineer",
          "scope": {
            "kind": "selected",
            "org_ids": [
              "0a9e0000-0000-4000-8000-000000000101"
            ],
            "inherited": false,
            "other_orgs": false
          }
        }
      ],
      "other_grants": false,
      "groups": [
        {
          "id": "9a0b0000-0000-4000-8000-000000000401",
          "name": "Helpdesk Tier 1"
        }
      ]
    }
  ],
  "next_cursor": null
}
```

## Remove a member

`DELETE https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/members/{user_id}`

Preview · Destructive

Removes a member from the workspace with their grants, their group memberships and every personal token and connected app they hold there. Needs `member.manage`, and the member must sit inside your reach. A repeat returns 404 once the member is gone: treat that as done. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 15 minutes.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: `admin:write`
- Privilege: `member.manage`

Needs `member.manage`. `member.manage` applies at each organization a grant covers and every organization below it.

### Behavior

- Retry: Safe to repeat: ends in the same state
- Audit log: Recorded

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.
- `user_id` (string, required): The member's user id.

### Response (200)

- `cache_clear_status` (one of the values below, or null): Sent when the change has to reach every region's cache: how far it got.
  - `ok`: Every region's cache has the change.
  - `failed`: A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  - `disabled`: This environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
- `cache_clear_message` (string or null): Sent with a `cache_clear_status` other than ok: what it means, for a person to read.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A query parameter it does not take, or one given twice. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The request carries a body other than nothing, `null` or `{}`: a delete takes none, and its options are query parameters; `parameter` names the body's first field, or `body`. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE` (cause `token_scope` or `no_privilege`) | You do not hold `member.manage`. The same refusal comes when the path names a workspace other than the token's own. | No |
| 403 | `APP_API_ERR_BEYOND_OWN_AUTHORITY` (cause `token_scope`) | The member holds access you do not hold yourself. `cause` is `token_scope` only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change. | No |
| 404 | `APP_API_ERR_RECORD_NOT_FOUND` | The user is not a member, or not one you can see. | No |
| 409 | `APP_API_ERR_LAST_ADMINISTRATOR` | The change would leave no administrator over every organization. Only a signed-in session meets this: no scope carries every privilege an Administrator holds, so an API token is refused with 403 first. | No |
| 413 | `APP_API_ERR_BODY_TOO_LARGE` | The body is larger than 1 MiB. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [List members](https://sparklogs.com/docs/api/reference/members.md#list-members)

### Example

Remove Sam, who holds his own grant and the helpdesk group's

```bash
curl -X DELETE \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/members/SamChenExampleUserId00000002" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "user removed from workspace",
  "cache_clear_status": "ok"
}
```

## Grant object

A grant gives one member, group or workspace token one role over a scope: every organization, selected organizations and everything below them, or the workspace itself.

- `id` (uuid): The grant's id; left out on a grant an invitation will become.
- `role_id` (string, required): The role the grant gives.
- `scope` (Scope, required): Which organizations the grant covers. With all, every organization and the workspace: the role's workspace-level privileges apply too. With selected, the organizations in `org_ids` and everything below them: the role's workspace-level privileges do not apply. With workspace, the workspace alone: only the role's workspace-level privileges apply. Your own grants show whole. Changing or removing a grant with `inherited` or `other_orgs` needs access over organizations you cannot see; without it the call returns 403 `APP_API_ERR_BEYOND_OWN_AUTHORITY`.

## Scope object

- `kind` (one of the values below, required): Which organizations. Required.
  - `all`: Every organization, those added later included.
  - `selected`: The organizations in `org_ids` and everything below them.
  - `workspace`: The workspace itself, no organization.
- `org_ids` (array of uuid): With selected, the topmost organizations you can see, sorted; empty otherwise. Every answer sends it. On a write, the organizations it covers: at least one with selected, none otherwise.
- `inherited` (boolean): True when one of `org_ids` sits below an organization the scope names that you cannot see. Read-only: every answer sends it, and a write ignores it.
- `other_orgs` (boolean): True when the scope covers organizations you cannot see, which are left out without an id or a count; with all, when you cannot see every organization. Read-only: every answer sends it, and a write ignores it.

## GroupRef object

- `id` (uuid, required): The group's id.
- `name` (string, required): The group's name.

---

Source: <https://sparklogs.com/docs/api/reference/members>
All SparkLogs documentation in Markdown: <https://sparklogs.com/llms.txt>
