Skip to main content

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

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.

iduuid

The grant's id; left out on a grant an invitation will become.

role_idstringrequired

The role the grant gives.

scopeScoperequired

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.

Give a grant​

POST/workspaces/{workspace_id}/grants
Preview

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.

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"      ]    }  }'

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_iduuidrequired

The workspace's id.

Request body

granteeGranteerequired

Who the grant is given to. Required.

role_idstringrequired

The role the grant gives. Required.

scopeScoperequired

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. 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_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_PARAMETERSgrantee names no kind or id, or a grant names a role the workspace does not have, or a malformed scope.No
400APP_API_ERR_MISSING_PARAMETERThe grant names no role.No
403APP_API_ERR_NO_PRIVILEGEtoken_scopeno_privilegeYou do not hold grant.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 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.No
404APP_API_ERR_RECORD_NOT_FOUNDThe grantee is not in the workspace, or not one you can see.No
413APP_API_ERR_BODY_TOO_LARGEThe body is larger than 1 MiB.No

Plus the errors every call can return.

Related

Replace a grant​

PUT/workspaces/{workspace_id}/grants/{id}
Preview

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.

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"      ]    }  }'

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_iduuidrequired

The workspace's id.

iduuidrequired

The grant's id.

Request body

role_idstringrequired

The role the grant gives. Required.

scopeScoperequired

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. 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_BAD_PARAMETERSA grant names a role the workspace does not have, or a malformed scope.No
400APP_API_ERR_MISSING_PARAMETERThe grant names no role.No
403APP_API_ERR_NO_PRIVILEGEtoken_scopeno_privilegeYou do not hold grant.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 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.No
404APP_API_ERR_RECORD_NOT_FOUNDNo such grant, or one you cannot 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

Remove a grant​

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

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.

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"

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_iduuidrequired

The workspace's id.

iduuidrequired

The grant'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 grant.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 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.No
404APP_API_ERR_RECORD_NOT_FOUNDNo such grant, or one you cannot 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

Change a grantee's grants together​

POST/workspaces/{workspace_id}/grants/batch
PreviewDestructive

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.

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"    ]  }'

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_iduuidrequired

The workspace's id.

Request body

granteeGranteerequired

Whose grants change. Required.

removearray of uuid or null

The ids of the grants to remove.

updatearray of GrantUpdate or null

The grants to change, each by id.

addarray of GrantRequest or null

The grants to add.

Response 200

removedarray of uuidrequired

The ids of the grants removed.

updatedarray of uuidrequired

The ids of the grants changed.

addedarray of uuidrequired

The ids of the grants added, in the order add named them.

cache_clear_statusone of the values belowrequired

How far the change got into every region's cache.

  • 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_PARAMETERSgrantee 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.No
400APP_API_ERR_MISSING_PARAMETERremove, update and add are all empty, or a grant names no role.No
403APP_API_ERR_NO_PRIVILEGEtoken_scopeno_privilegeYou do not hold grant.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 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.No
404APP_API_ERR_RECORD_NOT_FOUNDThe grantee, or a grant in remove or update, is missing, belongs to another grantee or is outside your reach; parameter names it.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