Skip to main content

Groups

A group gives its grants to every member in it; list, create, rename and delete groups and set who is in them.

Group object​

A group is a set of members who all hold the group's grants.

iduuid

The group's id.

namestring

The group's name.

created_atdate-time

When the group was created.

updated_atdate-time

When the group last changed.

grantsarray of Grant

The group's grants you are shown.

other_grantsboolean

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

member_countinteger

How many members are in the group.

membersarray of GroupMember

Everyone in the group, name and email only, as read-group shows them: sent only when fields names it, then a list, empty for a group with no members.

List groups​

GET/workspaces/{workspace_id}/groups
Preview

Returns the workspace's groups, each with its grants and how many members it has, a page at a time, oldest first. Needs group.read; you see the groups your reach contains.

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

Access

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

Needs group.read. group.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

namestring

Only the group of this name: the way to find the group a refused create names as taken. Matched exactly, ignoring case; every match you can see is returned. Spaces around the value are ignored.

limitinteger

How many groups 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.

fieldsarray of string

Comma-separated top-level fields of each object to return instead of the default set.

Sent by default: idnamecreated_atupdated_atgrantsother_grantsmember_count

Sent only when named in fields: members

Response 200

groupsarray of Grouprequired

The groups on this page.

next_cursorstring or nullrequired

Null on the last page. Otherwise pass it as cursor 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, one given twice, or fields naming a field it does not have.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 group.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

Read a group​

GET/workspaces/{workspace_id}/groups/{id}
Preview

Returns one group with everyone in it, whatever your reach, so the membership read can be sent back whole. Needs group.read. A group you cannot see returns 404, as one that does not exist does.

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

Access

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

Needs group.read. group.read applies at each organization a grant covers and every organization below it.

Behavior

Retry
Safe to send again

Path parameters

workspace_iduuidrequired

The workspace's id.

iduuidrequired

The group's id.

Response 200

groupGroupDetailrequired

The group.

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_PARAMETERSid is not a UUID.No
403APP_API_ERR_NO_PRIVILEGEtoken_scopeno_privilegeYou do not hold group.read. The same refusal comes when the path names a workspace other than the token's own.No
404APP_API_ERR_RECORD_NOT_FOUNDNo such group, or one you cannot see.No

Plus the errors every call can return.

Related

Create a group​

POST/workspaces/{workspace_id}/groups
Preview

Creates a group with its grants and, optionally, its members. Needs group.write, and grant.write over each grant it names; a group with no grants needs group.write over every organization. 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 POST \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "grants": [      {        "role_id": "analyst_no_raw_logs",        "scope": {          "kind": "selected",          "org_ids": [            "0a9e0000-0000-4000-8000-000000000101",            "0a9e0000-0000-4000-8000-000000000105"          ]        }      }    ],    "name": "Helpdesk Tier 1",    "user_ids": [      "SamChenExampleUserId00000002"    ]  }'

Access

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

Needs group.write. group.write applies at each organization a grant covers and every organization below it.

Behavior

Retry
Read before sending again
Audit log
Recorded

Path parameters

workspace_iduuidrequired

The workspace's id.

Request body

namestringrequired

The group's name. Cleaned, as every name is. Required.

at most 128 characters

grantsarray of GrantRequest or null

The group's grants. A group with none needs group.write over every organization.

user_idsarray of string or null

Members to put in the group, each one you are shown.

Response 200

iduuidrequired

The id of the row the call created or changed.

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_PARAMETERSThe URL carries a query parameter, which a write does not take: its fields come from its body.No
400APP_API_ERR_BAD_PARAMETERSThe body is not a JSON object, is not sent as application/json, names a field the call does not take, or a field has the wrong type; parameter names the field, or Content-Type.No
400APP_API_ERR_BAD_PARAMETERSname is empty, a member in user_ids is not one you can see, or a grant names a role the workspace does not have, or a malformed scope.No
400APP_API_ERR_MISSING_PARAMETERA grant names no role.No
400APP_API_ERR_PARAMETER_TOO_LONGname is longer than 128 characters.No
403APP_API_ERR_NO_PRIVILEGEtoken_scopeno_privilegeYou do not hold group.write. The same refusal comes when the path names a workspace other than the token's own.No
403APP_API_ERR_BEYOND_OWN_AUTHORITYtoken_scopeA grant reaches beyond what you may grant, or the group has no grants and you do not hold group.write over every organization. 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
409APP_API_ERR_ALREADY_TAKENAnother group in the workspace has this name; parameter is name.No
413APP_API_ERR_BODY_TOO_LARGEThe body is larger than 1 MiB.No

Plus the errors every call can return.

Related

Rename a group​

PATCH/workspaces/{workspace_id}/groups/{id}
Preview

Renames a group. Needs group.write over it. A group you cannot see returns 404, as one that does not exist does.

curl -X PATCH \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups/9a0b0000-0000-4000-8000-000000000402" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "name": "Field Engineers"  }'

Access

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

Needs group.write. group.write 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.

iduuidrequired

The group's id.

Request body

namestringrequired

The new name. Cleaned, as every name is. Required.

at most 128 characters

Response 200

iduuidrequired

The id of the row the call created or changed.

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_PARAMETERSThe URL carries a query parameter, which a write does not take: its fields come from its body.No
400APP_API_ERR_BAD_PARAMETERSid is not a UUID.No
400APP_API_ERR_BAD_PARAMETERSThe body is not a JSON object, is not sent as application/json, names a field the call does not take, or a field has the wrong type; parameter names the field, or Content-Type.No
400APP_API_ERR_BAD_PARAMETERSname is empty.No
400APP_API_ERR_PARAMETER_TOO_LONGname is longer than 128 characters.No
403APP_API_ERR_NO_PRIVILEGEtoken_scopeno_privilegeYou do not hold group.write. The same refusal comes when the path names a workspace other than the token's own.No
403APP_API_ERR_BEYOND_OWN_AUTHORITYtoken_scopeThe group holds grants beyond your reach. 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_FOUNDNo such group, or one you cannot see.No
409APP_API_ERR_ALREADY_TAKENAnother group in the workspace has this name; parameter is name.No
413APP_API_ERR_BODY_TOO_LARGEThe body is larger than 1 MiB.No

Plus the errors every call can return.

Related

Set a group's members​

PUT/workspaces/{workspace_id}/groups/{id}/members
PreviewDestructive

Sets who is in a group: the list sent is the whole membership, so a member left out is removed. A member added must be one your member list shows. Needs group.write, and the group must sit inside your own access: for each of its grants, grant.write, group.write and every privilege of the grant's role across the grant's whole scope, as giving that grant would need, or 403 APP_API_ERR_BEYOND_OWN_AUTHORITY, even when the list sent changes nothing. other_grants and the scope markers on a read of the group show grants outside your reach, but a group can be refused without them. A group you cannot see returns 404. Sending the members it already has changes nothing. 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 PUT \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups/9a0b0000-0000-4000-8000-000000000401/members" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "user_ids": [      "SamChenExampleUserId00000002",      "AlexRiveraExampleUserId00001"    ]  }'

Access

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

Needs group.write. group.write 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.

iduuidrequired

The group's id.

Request body

user_idsarray of stringrequired

Everyone who is in the group from now on; an empty list empties it. Required.

Response 200

iduuidrequired

The id of the row the call created or changed.

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_PARAMETERSThe URL carries a query parameter, which a write does not take: its fields come from its body.No
400APP_API_ERR_BAD_PARAMETERSid is not a UUID.No
400APP_API_ERR_BAD_PARAMETERSThe body is not a JSON object, is not sent as application/json, names a field the call does not take, or a field has the wrong type; parameter names the field, or Content-Type.No
400APP_API_ERR_MISSING_PARAMETERuser_ids is left out, null or not a list of strings.No
400APP_API_ERR_BAD_PARAMETERSA member added is not one you can see.No
403APP_API_ERR_NO_PRIVILEGEtoken_scopeno_privilegeYou do not hold group.write. The same refusal comes when the path names a workspace other than the token's own.No
403APP_API_ERR_BEYOND_OWN_AUTHORITYtoken_scopeYou do not hold grant.write, group.write and every privilege of each of the group's grants across that grant's whole scope, as giving the grant would need; a group with no grants needs group.write over every organization. A list that changes nothing is refused the same way. 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_FOUNDNo such group, or one you cannot see.No
413APP_API_ERR_BODY_TOO_LARGEThe body is larger than 1 MiB.No

Plus the errors every call can return.

Related

Delete a group​

DELETE/workspaces/{workspace_id}/groups/{id}
PreviewDestructive

Deletes a group and its grants; its members lose what they held through it. Needs group.write, and the group must sit inside your own access: for each of its grants, grant.write, group.write and every privilege of the grant's role across the grant's whole scope, as giving that grant would need, or 403 APP_API_ERR_BEYOND_OWN_AUTHORITY. other_grants and the scope markers on a read of the group show grants outside your reach, but a group can be refused without them. A group you cannot see returns 404, and so does a repeat once the group 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/groups/9a0b0000-0000-4000-8000-000000000402" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"

Access

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

Needs group.write. group.write 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.

iduuidrequired

The group's 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_PARAMETERSid is not a UUID.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 group.write. The same refusal comes when the path names a workspace other than the token's own.No
403APP_API_ERR_BEYOND_OWN_AUTHORITYtoken_scopeYou do not hold grant.write, group.write and every privilege of each of the group's grants across that grant's whole scope, as giving the grant would need; a group with no grants needs group.write over every organization. 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_FOUNDNo such group, or one you cannot see.No
413APP_API_ERR_BODY_TOO_LARGEThe body is larger than 1 MiB.No

Plus the errors every call can return.

Related