Skip to main content

Members

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

Belongs to: Users

Member object​

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

user_idstringrequired

The member's user id.

emailemailrequired

The member's email address.

full_namestring or nullrequired

The member's full name.

display_namestring or nullrequired

The name the app shows for the member.

is_selfbooleanrequired

Whether the member is you.

created_atdate-timerequired

When the member joined the workspace.

deleted_atdate-time or nullrequired

When the person's account was deleted; null while it is active.

grantsarray of Grantrequired

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_grantsbooleanrequired

True when the member holds a grant you are not shown.

groupsarray of GroupRefrequired

The groups the member is in that group.read shows you; on your own row, every group you are in.

List members​

GET/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.

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

Access

Works with
Signed-in person, Personal token, OAuth token, Workspace token
Scope
any of admin:readadmin: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_iduuidrequired

The workspace's id.

Query parameters

emailstring

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.

limitinteger

How many members a page holds: 1 to 5000, 1000 by default.

Default: 10001 to 5000

cursorstring

The next_cursor of the previous page, with the same filters.

Response 200

membersarray of Memberrequired

The members you are shown, deleted accounts included, oldest membership first.

next_cursorstring or nullrequired

Null on the last page. Otherwise pass it as cursor, with the same filters, for the next page.

messagestringrequired

What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

Errors

StatusCodeWhenSend again?
400APP_API_ERR_BAD_PARAMETERSA query parameter it does not take, or one given twice.No
400APP_API_ERR_BAD_PARAMETERSA 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
400APP_API_ERR_BAD_PARAMETERSlimit is not 1 to 5000, or cursor cannot be read or was sent with other filters.No
403APP_API_ERR_NO_PRIVILEGEtoken_scopeno_privilegeYou do not hold member.read. The same refusal comes when the path names a workspace other than the token's own.No

Plus the errors every call can return.

Related

Remove a member​

DELETE/workspaces/{workspace_id}/members/{user_id}
PreviewDestructive

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.

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

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_iduuidrequired

The workspace's id.

user_idstringrequired

The member's user id.

Response 200

cache_clear_statusone 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_messagestring or null

Sent with a cache_clear_status other than ok: what it means, for a person to read.

messagestringrequired

What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

Errors

StatusCodeWhenSend again?
400APP_API_ERR_BAD_PARAMETERSA query parameter it does not take, or one given twice.No
400APP_API_ERR_BAD_PARAMETERSThe 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
403APP_API_ERR_NO_PRIVILEGEtoken_scopeno_privilegeYou do not hold member.manage. The same refusal comes when the path names a workspace other than the token's own.No
403APP_API_ERR_BEYOND_OWN_AUTHORITYtoken_scopeThe 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
404APP_API_ERR_RECORD_NOT_FOUNDThe user is not a member, or not one you can see.No
409APP_API_ERR_LAST_ADMINISTRATORThe 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
413APP_API_ERR_BODY_TOO_LARGEThe body is larger than 1 MiB.No

Plus the errors every call can return.

Related