Grants
A grant gives a member, a group or a workspace token a role over a scope of organizations; give, change and remove them.
Belongs to: Roles
- POST
Give a grant/workspaces /{workspace_id} /grants - PUT
Replace a grant/workspaces /{workspace_id} /grants /{id} - DELETE
Remove a grant/workspaces /{workspace_id} /grants /{id} - POST
Change a grantee's grants together/workspaces /{workspace_id} /grants /batch
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.
iduuidThe grant's id; left out on a grant an invitation will become.
role_id stringrequiredThe role the grant gives.
scopeScoperequiredWhich 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.
Give a grant
/workspaces/{workspace_id}/grants Gives a member, a group or a workspace token a role over a scope. Needs grant.write across the scope and over everything the role reaches; a grant on a group also needs group.write there, and one on a workspace token workspace_token.manage there and workspace_token.view to see the token, which a token holds only with admin:delegate. A workspace token never changes its own grants. The grantee must sit inside your reach. A grantee you cannot see gets the same response as one that does not exist. 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.
- Request
- Response
- curl
- PowerShell
- Python
curl -X POST \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/grants" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "grantee": { "id": "SamChenExampleUserId00000002", "kind": "user" }, "role_id": "engineer", "scope": { "kind": "selected", "org_ids": [ "0a9e0000-0000-4000-8000-000000000101" ] } }'$body = @{ grantee = @{ id = "SamChenExampleUserId00000002" kind = "user" } role_id = "engineer" scope = @{ kind = "selected" org_ids = @( "0a9e0000-0000-4000-8000-000000000101" ) }}Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/grants" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" } ` -ContentType "application/json; charset=utf-8" ` -Body ($body | ConvertTo-Json -Depth 10)import os import requests response = requests.post( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/grants" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "grantee": { "id": "SamChenExampleUserId00000002", "kind": "user", }, "role_id": "engineer", "scope": { "kind": "selected", "org_ids": [ "0a9e0000-0000-4000-8000-000000000101", ], }, },)response.raise_for_status(){ "message": "grant created", "id": "6a170000-0000-4000-8000-000000000502", "cache_clear_status": "ok"}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
admin:write- Privilege
grant.write
Needs grant.write. grant.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_id uuidrequiredThe workspace's id.
Request body
granteeGranteerequiredWho the grant is given to. Required.
role_id stringrequiredThe role the grant gives. Required.
scopeScoperequiredWhich 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. Required.
Response 200
iduuidrequiredThe id of the row the call created or changed.
cache_clear_status one of the values below, or nullSent when the change has to reach every region's cache: how far it got.
okEvery region's cache has the change.failedA region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.disabledThis 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 nullSent with a cache_clear_status other than ok: what it means, for a person to read.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS The URL carries a query parameter, which a write does not take: its fields come from its body.NoAPP_API_ERR_BAD_PARAMETERS The 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.NoAPP_API_ERR_BAD_PARAMETERS grantee names no kind or id, or a grant names a role the workspace does not have, or a malformed scope.NoAPP_API_ERR_MISSING_PARAMETER The grant names no role.No403APP_API_ERR_NO_PRIVILEGE token_scopeno_privilegeYou do not hold grant.write. The same refusal comes when the path names a workspace other than the token's own.NoAPP_API_ERR_BEYOND_OWN_AUTHORITY token_scopeThe change gives or takes away access you do not hold yourself, or a workspace token would change its own grants. 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.No404APP_API_ERR_RECORD_NOT_FOUND The grantee is not in the workspace, or not one you can see.No413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.NoPlus the errors every call can return.
Related
Replace a grant
/workspaces/{workspace_id}/grants/{id} Replaces a grant's role and scope. Needs grant.write over both the grant as stored and as replaced, judged as giving a grant is. A grant you cannot see returns 404, as one that does not exist does. 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.
- Request
- Response
- curl
- PowerShell
- Python
curl -X PUT \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/grants/6a170000-0000-4000-8000-000000000502" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "role_id": "engineer", "scope": { "kind": "selected", "org_ids": [ "0a9e0000-0000-4000-8000-000000000101", "0a9e0000-0000-4000-8000-000000000105" ] } }'$body = @{ role_id = "engineer" scope = @{ kind = "selected" org_ids = @( "0a9e0000-0000-4000-8000-000000000101", "0a9e0000-0000-4000-8000-000000000105" ) }}Invoke-RestMethod -Method Put ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/grants/6a170000-0000-4000-8000-000000000502" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" } ` -ContentType "application/json; charset=utf-8" ` -Body ($body | ConvertTo-Json -Depth 10)import os import requests response = requests.put( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/grants/6a170000-0000-4000-8000-000000000502" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "role_id": "engineer", "scope": { "kind": "selected", "org_ids": [ "0a9e0000-0000-4000-8000-000000000101", "0a9e0000-0000-4000-8000-000000000105", ], }, },)response.raise_for_status(){ "message": "grant replaced", "id": "6a170000-0000-4000-8000-000000000502", "cache_clear_status": "ok"}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
admin:write- Privilege
grant.write
Needs grant.write. grant.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_id uuidrequiredThe workspace's id.
iduuidrequiredThe grant's id.
Request body
role_id stringrequiredThe role the grant gives. Required.
scopeScoperequiredWhich 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. Required.
Response 200
iduuidrequiredThe id of the row the call created or changed.
cache_clear_status one of the values below, or nullSent when the change has to reach every region's cache: how far it got.
okEvery region's cache has the change.failedA region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.disabledThis 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 nullSent with a cache_clear_status other than ok: what it means, for a person to read.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS The URL carries a query parameter, which a write does not take: its fields come from its body.NoAPP_API_ERR_BAD_PARAMETERS id is not a UUID.NoAPP_API_ERR_BAD_PARAMETERS The 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.NoAPP_API_ERR_BAD_PARAMETERS A grant names a role the workspace does not have, or a malformed scope.NoAPP_API_ERR_MISSING_PARAMETER The grant names no role.No403APP_API_ERR_NO_PRIVILEGE token_scopeno_privilegeYou do not hold grant.write. The same refusal comes when the path names a workspace other than the token's own.NoAPP_API_ERR_BEYOND_OWN_AUTHORITY token_scopeThe change gives or takes away access you do not hold yourself, or a workspace token would change its own grants. 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.No404APP_API_ERR_RECORD_NOT_FOUND No such grant, or one you cannot see.No409APP_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.No413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.NoPlus the errors every call can return.
Related
Remove a grant
/workspaces/{workspace_id}/grants/{id} Removes a grant. Needs grant.write over it, judged as giving it is. It removes the whole grant; to drop one organization from a selected grant, update it with the rest. A grant you cannot see returns 404, as one that does not exist does, and so does a repeat once it 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.
- Request
- Response
- curl
- PowerShell
- Python
curl -X DELETE \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/grants/6a170000-0000-4000-8000-000000000502" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Delete ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/grants/6a170000-0000-4000-8000-000000000502" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.delete( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/grants/6a170000-0000-4000-8000-000000000502" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "message": "grant deleted", "cache_clear_status": "ok"}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
admin:write- Privilege
grant.write
Needs grant.write. grant.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_id uuidrequiredThe workspace's id.
iduuidrequiredThe grant's id.
Response 200
cache_clear_status one of the values below, or nullSent when the change has to reach every region's cache: how far it got.
okEvery region's cache has the change.failedA region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.disabledThis 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 nullSent with a cache_clear_status other than ok: what it means, for a person to read.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS A query parameter it does not take, or one given twice.NoAPP_API_ERR_BAD_PARAMETERS id is not a UUID.NoAPP_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.No403APP_API_ERR_NO_PRIVILEGE token_scopeno_privilegeYou do not hold grant.write. The same refusal comes when the path names a workspace other than the token's own.NoAPP_API_ERR_BEYOND_OWN_AUTHORITY token_scopeThe change gives or takes away access you do not hold yourself, or a workspace token would change its own grants. 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.No404APP_API_ERR_RECORD_NOT_FOUND No such grant, or one you cannot see.No409APP_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.No413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.NoPlus the errors every call can return.
Related
Change a grantee's grants together
/workspaces/{workspace_id}/grants/batch Removes, changes and adds a grantee's direct grants in one transaction: every change is judged as the single-grant calls judge it, and any refusal writes 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.
- Request
- Response
- curl
- PowerShell
- Python
curl -X POST \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/grants/batch" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "add": [ { "role_id": "analyst_no_raw_logs", "scope": { "kind": "all", "org_ids": [] } } ], "grantee": { "id": "9a0b0000-0000-4000-8000-000000000401", "kind": "group" }, "remove": [ "6a170000-0000-4000-8000-000000000503" ] }'$body = @{ add = @( @{ role_id = "analyst_no_raw_logs" scope = @{ kind = "all" org_ids = @() } } ) grantee = @{ id = "9a0b0000-0000-4000-8000-000000000401" kind = "group" } remove = @( "6a170000-0000-4000-8000-000000000503" )}Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/grants/batch" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" } ` -ContentType "application/json; charset=utf-8" ` -Body ($body | ConvertTo-Json -Depth 10)import os import requests response = requests.post( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/grants/batch" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "add": [ { "role_id": "analyst_no_raw_logs", "scope": { "kind": "all", "org_ids": [], }, }, ], "grantee": { "id": "9a0b0000-0000-4000-8000-000000000401", "kind": "group", }, "remove": [ "6a170000-0000-4000-8000-000000000503", ], },)response.raise_for_status(){ "message": "grants changed", "removed": [ "6a170000-0000-4000-8000-000000000503" ], "updated": [], "added": [ "6a170000-0000-4000-8000-000000000505" ], "cache_clear_status": "ok"}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
admin:write- Privilege
grant.write
Needs grant.write. grant.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_id uuidrequiredThe workspace's id.
Request body
granteeGranteerequiredWhose grants change. Required.
removearray of uuid or nullThe ids of the grants to remove.
updatearray of GrantUpdate or nullThe grants to change, each by id.
addarray of GrantRequest or nullThe grants to add.
Response 200
removedarray of uuidrequiredThe ids of the grants removed.
updatedarray of uuidrequiredThe ids of the grants changed.
addedarray of uuidrequiredThe ids of the grants added, in the order add named them.
cache_clear_status one of the values belowrequiredHow far the change got into every region's cache.
okEvery region's cache has the change.failedA region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.disabledThis 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 nullSent with a cache_clear_status other than ok: what it means, for a person to read.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS The URL carries a query parameter, which a write does not take: its fields come from its body.NoAPP_API_ERR_BAD_PARAMETERS The 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.NoAPP_API_ERR_BAD_PARAMETERS grantee is malformed, a grant id comes twice across remove and update, or a grant names a role the workspace does not have, or a malformed scope.NoAPP_API_ERR_MISSING_PARAMETER remove, update and add are all empty, or a grant names no role.No403APP_API_ERR_NO_PRIVILEGE token_scopeno_privilegeYou do not hold grant.write. The same refusal comes when the path names a workspace other than the token's own.NoAPP_API_ERR_BEYOND_OWN_AUTHORITY token_scopeThe change gives or takes away access you do not hold yourself, or a workspace token would change its own grants. 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.No404APP_API_ERR_RECORD_NOT_FOUND The grantee, or a grant in remove or update, is missing, belongs to another grantee or is outside your reach; parameter names it.No409APP_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.No413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.NoPlus the errors every call can return.