Roles
The roles a grant can give: the standard roles and the workspace's own, each with its privileges.
Contains: Grants
Role object
A role is a named set of privileges a grant gives. Standard roles come with SparkLogs; a workspace can define its own.
idstringThe role's id.
kindone of the values belowWho defines the role.
standardA role SparkLogs defines.customA role this workspace defines.
descriptionstring or nullWhat the role is for.
recommended_scope one of the values below, or nullThe scope a grant of this role is usually given; null when there is none.
allEvery organization.selectedSome organizations.workspaceThe workspace itself.
sort_order integerWhere the role sorts in a list of roles.
privilegesarray of RolePrivilegeEvery privilege the role holds.
List roles
/workspaces/{workspace_id}/roles Returns every role a grant in the workspace can name, the standard roles and the workspace's own, each with its privileges, in sort order.
- Request
- Response
- curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/roles" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/roles" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/roles" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "message": "roles retrieved", "roles": [ { "id": "admin", "kind": "standard", "description": "Administrator with rights to everything, including managing users in the workspace and their roles", "recommended_scope": "all", "sort_order": 10, "privileges": [ { "id": "workspace.read", "level": "self", "category": null, "access_kind": "view" }, { "id": "workspace.write", "level": "workspace", "category": "organizations", "access_kind": "manage" }, { "id": "member.read", "level": "org", "category": "people", "access_kind": "view" }, { "id": "member.manage", "level": "org", "category": "people", "access_kind": "manage" }, { "id": "group.read", "level": "org", "category": "people", "access_kind": "view" }, { "id": "group.write", "level": "org", "category": "people", "access_kind": "manage" }, { "id": "grant.write", "level": "org", "category": "people", "access_kind": "manage" }, { "id": "auditlog.query", "level": "org", "category": "activity_log", "access_kind": "view" }, { "id": "organization.read", "level": "org", "category": "organizations", "access_kind": "view" }, { "id": "organization.create", "level": "org", "category": "organizations", "access_kind": "manage" }, { "id": "organization.write", "level": "org", "category": "organizations", "access_kind": "manage" }, { "id": "organization.move", "level": "org", "category": "organizations", "access_kind": "manage" }, { "id": "organization.delete", "level": "org", "category": "organizations", "access_kind": "manage" }, { "id": "agent.read", "level": "org", "category": "agents", "access_kind": "view" }, { "id": "agent.write", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "agent.delete", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "agent_policy.write", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "agent_policy.assign", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "agent_policy.rule_write", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "agent_policy.enforce", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "agent_tag.define", "level": "workspace", "category": "agents", "access_kind": "manage" }, { "id": "agent_tag.attach", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "ingest_key.create", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "ingest_key.reveal", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "ingest_key.rotate", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "registration_token.create", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "registration_token.read", "level": "org", "category": "agents", "access_kind": "view" }, { "id": "registration_token.reveal", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "registration_token.revoke", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "archive.config.read", "level": "org", "category": "organizations", "access_kind": "view" }, { "id": "archive.config.write", "level": "org", "category": "organizations", "access_kind": "manage" }, { "id": "event.query", "level": "org", "category": "event_data", "access_kind": "view" }, { "id": "device.read", "level": "org", "category": "event_data", "access_kind": "view" }, { "id": "event.read", "level": "org", "category": "raw_logs", "access_kind": "view" }, { "id": "analytics.query", "level": "org", "category": "raw_logs", "access_kind": "view" }, { "id": "ingestion.read", "level": "org", "category": "billing", "access_kind": "view" }, { "id": "finance.admin", "level": "workspace", "category": "billing", "access_kind": "manage" }, { "id": "user_token.create_own", "level": "self", "category": null, "access_kind": "manage" }, { "id": "user_token.manage_own", "level": "self", "category": null, "access_kind": "manage" }, { "id": "user_token.view_all", "level": "org", "category": "people", "access_kind": "view" }, { "id": "user_token.manage_any", "level": "org", "category": "people", "access_kind": "manage" }, { "id": "workspace_token.create", "level": "org", "category": "people", "access_kind": "manage" }, { "id": "workspace_token.view", "level": "org", "category": "people", "access_kind": "view" }, { "id": "workspace_token.manage", "level": "org", "category": "people", "access_kind": "manage" }, { "id": "app_registration.create", "level": "workspace", "category": "people", "access_kind": "manage" }, { "id": "app_registration.view", "level": "workspace", "category": "people", "access_kind": "view" }, { "id": "app_registration.manage", "level": "workspace", "category": "people", "access_kind": "manage" } ] }, { "id": "organization_admin", "kind": "standard", "description": "Delegated administrator of its organizations, with no workspace rights", "recommended_scope": "selected", "sort_order": 20, "privileges": [ { "id": "workspace.read", "level": "self", "category": null, "access_kind": "view" }, { "id": "member.read", "level": "org", "category": "people", "access_kind": "view" }, { "id": "member.manage", "level": "org", "category": "people", "access_kind": "manage" }, { "id": "group.read", "level": "org", "category": "people", "access_kind": "view" }, { "id": "group.write", "level": "org", "category": "people", "access_kind": "manage" }, { "id": "grant.write", "level": "org", "category": "people", "access_kind": "manage" }, { "id": "auditlog.query", "level": "org", "category": "activity_log", "access_kind": "view" }, { "id": "organization.read", "level": "org", "category": "organizations", "access_kind": "view" }, { "id": "organization.create", "level": "org", "category": "organizations", "access_kind": "manage" }, { "id": "organization.write", "level": "org", "category": "organizations", "access_kind": "manage" }, { "id": "organization.move", "level": "org", "category": "organizations", "access_kind": "manage" }, { "id": "organization.delete", "level": "org", "category": "organizations", "access_kind": "manage" }, { "id": "agent.read", "level": "org", "category": "agents", "access_kind": "view" }, { "id": "agent.write", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "agent.delete", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "agent_policy.write", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "agent_policy.assign", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "agent_policy.rule_write", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "agent_tag.attach", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "ingest_key.create", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "ingest_key.reveal", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "ingest_key.rotate", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "registration_token.create", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "registration_token.read", "level": "org", "category": "agents", "access_kind": "view" }, { "id": "registration_token.reveal", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "registration_token.revoke", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "archive.config.read", "level": "org", "category": "organizations", "access_kind": "view" }, { "id": "archive.config.write", "level": "org", "category": "organizations", "access_kind": "manage" }, { "id": "event.query", "level": "org", "category": "event_data", "access_kind": "view" }, { "id": "device.read", "level": "org", "category": "event_data", "access_kind": "view" }, { "id": "event.read", "level": "org", "category": "raw_logs", "access_kind": "view" }, { "id": "analytics.query", "level": "org", "category": "raw_logs", "access_kind": "view" }, { "id": "ingestion.read", "level": "org", "category": "billing", "access_kind": "view" }, { "id": "user_token.create_own", "level": "self", "category": null, "access_kind": "manage" }, { "id": "user_token.manage_own", "level": "self", "category": null, "access_kind": "manage" }, { "id": "user_token.view_all", "level": "org", "category": "people", "access_kind": "view" }, { "id": "user_token.manage_any", "level": "org", "category": "people", "access_kind": "manage" }, { "id": "workspace_token.create", "level": "org", "category": "people", "access_kind": "manage" }, { "id": "workspace_token.view", "level": "org", "category": "people", "access_kind": "view" }, { "id": "workspace_token.manage", "level": "org", "category": "people", "access_kind": "manage" } ] }, { "id": "engineer", "kind": "standard", "description": "Engineer who can fully manage organizations, deploy agents, and query event data", "recommended_scope": null, "sort_order": 100, "privileges": [ { "id": "workspace.read", "level": "self", "category": null, "access_kind": "view" }, { "id": "organization.read", "level": "org", "category": "organizations", "access_kind": "view" }, { "id": "organization.create", "level": "org", "category": "organizations", "access_kind": "manage" }, { "id": "organization.write", "level": "org", "category": "organizations", "access_kind": "manage" }, { "id": "organization.delete", "level": "org", "category": "organizations", "access_kind": "manage" }, { "id": "agent.read", "level": "org", "category": "agents", "access_kind": "view" }, { "id": "agent.write", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "agent.delete", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "ingest_key.create", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "ingest_key.reveal", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "ingest_key.rotate", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "registration_token.create", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "registration_token.read", "level": "org", "category": "agents", "access_kind": "view" }, { "id": "registration_token.reveal", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "registration_token.revoke", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "archive.config.read", "level": "org", "category": "organizations", "access_kind": "view" }, { "id": "archive.config.write", "level": "org", "category": "organizations", "access_kind": "manage" }, { "id": "event.query", "level": "org", "category": "event_data", "access_kind": "view" }, { "id": "device.read", "level": "org", "category": "event_data", "access_kind": "view" }, { "id": "event.read", "level": "org", "category": "raw_logs", "access_kind": "view" }, { "id": "analytics.query", "level": "org", "category": "raw_logs", "access_kind": "view" }, { "id": "ingestion.read", "level": "org", "category": "billing", "access_kind": "view" }, { "id": "user_token.create_own", "level": "self", "category": null, "access_kind": "manage" }, { "id": "user_token.manage_own", "level": "self", "category": null, "access_kind": "manage" } ] }, { "id": "analyst", "kind": "standard", "description": "Analyst who can only view and query data but not change anything", "recommended_scope": null, "sort_order": 110, "privileges": [ { "id": "workspace.read", "level": "self", "category": null, "access_kind": "view" }, { "id": "organization.read", "level": "org", "category": "organizations", "access_kind": "view" }, { "id": "agent.read", "level": "org", "category": "agents", "access_kind": "view" }, { "id": "archive.config.read", "level": "org", "category": "organizations", "access_kind": "view" }, { "id": "event.query", "level": "org", "category": "event_data", "access_kind": "view" }, { "id": "device.read", "level": "org", "category": "event_data", "access_kind": "view" }, { "id": "event.read", "level": "org", "category": "raw_logs", "access_kind": "view" }, { "id": "analytics.query", "level": "org", "category": "raw_logs", "access_kind": "view" }, { "id": "ingestion.read", "level": "org", "category": "billing", "access_kind": "view" }, { "id": "user_token.create_own", "level": "self", "category": null, "access_kind": "manage" }, { "id": "user_token.manage_own", "level": "self", "category": null, "access_kind": "manage" } ] }, { "id": "analyst_no_raw_logs", "kind": "standard", "description": "Analyst who can query counts, patterns and device health but not raw logs", "recommended_scope": null, "sort_order": 120, "privileges": [ { "id": "workspace.read", "level": "self", "category": null, "access_kind": "view" }, { "id": "organization.read", "level": "org", "category": "organizations", "access_kind": "view" }, { "id": "agent.read", "level": "org", "category": "agents", "access_kind": "view" }, { "id": "archive.config.read", "level": "org", "category": "organizations", "access_kind": "view" }, { "id": "event.query", "level": "org", "category": "event_data", "access_kind": "view" }, { "id": "device.read", "level": "org", "category": "event_data", "access_kind": "view" }, { "id": "ingestion.read", "level": "org", "category": "billing", "access_kind": "view" }, { "id": "user_token.create_own", "level": "self", "category": null, "access_kind": "manage" }, { "id": "user_token.manage_own", "level": "self", "category": null, "access_kind": "manage" } ] }, { "id": "deployment_manager", "kind": "standard", "description": "Deploys and manages organizations, agents, agent policy and enrollment, with no data access", "recommended_scope": null, "sort_order": 130, "privileges": [ { "id": "workspace.read", "level": "self", "category": null, "access_kind": "view" }, { "id": "organization.read", "level": "org", "category": "organizations", "access_kind": "view" }, { "id": "organization.create", "level": "org", "category": "organizations", "access_kind": "manage" }, { "id": "organization.write", "level": "org", "category": "organizations", "access_kind": "manage" }, { "id": "organization.delete", "level": "org", "category": "organizations", "access_kind": "manage" }, { "id": "agent.read", "level": "org", "category": "agents", "access_kind": "view" }, { "id": "agent.write", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "agent.delete", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "agent_policy.write", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "agent_policy.assign", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "agent_policy.rule_write", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "agent_tag.attach", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "ingest_key.create", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "ingest_key.reveal", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "ingest_key.rotate", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "registration_token.create", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "registration_token.read", "level": "org", "category": "agents", "access_kind": "view" }, { "id": "registration_token.reveal", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "registration_token.revoke", "level": "org", "category": "agents", "access_kind": "manage" }, { "id": "user_token.create_own", "level": "self", "category": null, "access_kind": "manage" }, { "id": "user_token.manage_own", "level": "self", "category": null, "access_kind": "manage" } ] }, { "id": "auditor", "kind": "standard", "description": "Reads access and configuration, with no data access", "recommended_scope": "all", "sort_order": 140, "privileges": [ { "id": "workspace.read", "level": "self", "category": null, "access_kind": "view" }, { "id": "member.read", "level": "org", "category": "people", "access_kind": "view" }, { "id": "group.read", "level": "org", "category": "people", "access_kind": "view" }, { "id": "auditlog.query", "level": "org", "category": "activity_log", "access_kind": "view" }, { "id": "organization.read", "level": "org", "category": "organizations", "access_kind": "view" }, { "id": "agent.read", "level": "org", "category": "agents", "access_kind": "view" }, { "id": "registration_token.read", "level": "org", "category": "agents", "access_kind": "view" }, { "id": "archive.config.read", "level": "org", "category": "organizations", "access_kind": "view" }, { "id": "ingestion.read", "level": "org", "category": "billing", "access_kind": "view" }, { "id": "user_token.create_own", "level": "self", "category": null, "access_kind": "manage" }, { "id": "user_token.manage_own", "level": "self", "category": null, "access_kind": "manage" }, { "id": "user_token.view_all", "level": "org", "category": "people", "access_kind": "view" }, { "id": "workspace_token.view", "level": "org", "category": "people", "access_kind": "view" }, { "id": "app_registration.view", "level": "workspace", "category": "people", "access_kind": "view" } ] }, { "id": "finance_admin", "kind": "standard", "description": "Fully manage all financial data and functions, with read access to organizations and no access to event data", "recommended_scope": "all", "sort_order": 400, "privileges": [ { "id": "workspace.read", "level": "self", "category": null, "access_kind": "view" }, { "id": "organization.read", "level": "org", "category": "organizations", "access_kind": "view" }, { "id": "ingestion.read", "level": "org", "category": "billing", "access_kind": "view" }, { "id": "finance.admin", "level": "workspace", "category": "billing", "access_kind": "manage" }, { "id": "user_token.create_own", "level": "self", "category": null, "access_kind": "manage" }, { "id": "user_token.manage_own", "level": "self", "category": null, "access_kind": "manage" } ] } ]}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
workspace:read- Privilege
workspace.read
Needs workspace.read. Any grant in the workspace carries workspace.read.
Behavior
- Retry
- Safe to send again
Path parameters
workspace_id uuidrequiredThe workspace's id.
Query parameters
fieldsarray of stringComma-separated top-level fields of each object to return instead of the default set.
Sent by default: idkinddescriptionrecommended_scopesort_orderprivileges
Response 200
Every one of the roles you can see.
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, one given twice, or fields naming a field it does not have.No403APP_API_ERR_NO_PRIVILEGE token_scopeno_privilegeYou do not hold workspace.read. The same refusal comes when the path names a workspace other than the token's own.NoPlus the errors every call can return.