Permission Commands

Alongside the search QUERY command and the other commands, FSQL provides ten commands for managing and inspecting access control in your Query tenant.

GRANT, REVOKE, EXPLAIN GRANTS, and EXPLAIN GROUPS control who can do what: which groups can use or edit connectors and detections, who can create new resources or read the audit log, and who can manage column-masking rules.

CREATE GROUP, RENAME GROUP, DROP GROUP, ADD USER … TO GROUP, REMOVE USER … FROM GROUP, and EXPLAIN MEMBERS OF manage the groups themselves — see Group management below.

Unlike QUERY, these commands do not run a search. They are dispatched to Query's authorization service rather than the search engine. Every command here is scoped to the current tenant — the tenant of the authenticated caller — and there is no syntax for targeting another tenant.

📘

General notes

• Keywords are case-insensitive. GRANT, grant, and Grant are equivalent, as are the verb names (can_use, etc.).
• Multiple commands can be separated with ;.
• Comments use -- to the end of the line, either inline or on their own line.

How authorization works in Query

Before the syntax, a quick mental model of what you're granting, to whom, and over what.

Subjects — who you grant to. Permissions are granted to groups. Every tenant draws its groups from two sources:

• entra: — groups synced from your Entra ID / Active Directory directory.
• query: — Query-native groups, including the built-in admin and member groups.

Granting to a group lets you manage access for many people at once and keeps permissions in sync as directory membership changes. The syntax also accepts an individual user as the subject, but user grants are not enabled in the current release — see Current limitation.

Verbs — what you grant. There are two kinds of verb, and the kind determines whether the command needs an ON <resource> clause.

A resource verb names a specific connector or detection, so it requires an ON clause. A tenant verb applies to the whole tenant, so it must be used without ON. Using a resource verb without ON, or a tenant verb with ON, is a syntax error.

Objects — what a permission applies to. Resource verbs apply to a single connector or detection (see Resource references below). Tenant verbs apply to the tenant as a whole.

Resource references

A resource is CONNECTOR <ref>, DETECTION <ref>, or a #tag shortcut. A <ref> can be written four ways:

These forms apply equally to connectors and detections:

GRANT can_edit ON DETECTION brute-force      TO GROUP soc-analysts
GRANT can_edit ON DETECTION 'Brute force AD' TO GROUP detection-engineers

Tag shortcut. #<tag> expands to every connector currently carrying that tag at the moment the command runs:

GRANT can_use ON #siem TO GROUP soc-analysts

This writes one grant per matching connector. It is a point-in-time expansion, not a live rule: connectors tagged siem later are not retroactively granted, and connectors that lose the tag keep grants already issued. If no connector carries the tag, the command returns an error rather than silently doing nothing. Tag names are lowercase letters, digits, and /, 2–64 characters.

📘

The #tag shortcut applies to connectors only.

Use EXPLAIN CONNECTORS and EXPLAIN DETECTIONS to discover the aliases, display names, and IDs available in your tenant.

Identity references

The TO (for GRANT) and FROM (for REVOKE) clauses name the subject of the grant:

Group sources and ambiguity. As described above, groups come from the entra: and query: sources. If a bare group name matches in both sources, the command fails with an ambiguity error and you must add the entra: or query: prefix. If the name matches no group, the command fails with a "no group named … found" error. Use EXPLAIN GROUPS to discover the exact names available in your tenant.

Users. USER <email> is accepted wherever an identity is expected, and it is fully supported by the masking commands and by ADD USER / REMOVE USER below. For GRANT, REVOKE, and EXPLAIN GRANTS, however, a user subject is rejected at execution in the current release — see Current limitation.

To create, rename, delete, or populate the query: groups referenced here — as opposed to granting them permissions — see Group management below.

GRANT

Grants a permission to a group.

GRANT <resource-verb> ON <resource> TO USER|GROUP <identity>
GRANT <tenant-verb>                 TO USER|GROUP <identity>

Examples:

-- Resource-scoped
GRANT can_use  ON CONNECTOR splunk-prod         TO GROUP 'SOC Analysts'
GRANT can_edit ON CONNECTOR 550e8400-...-440000 TO GROUP soc-analysts
GRANT can_use  ON #siem                         TO GROUP soc-analysts
GRANT can_edit ON DETECTION 'Brute force AD'    TO GROUP entra:detection-engineers

-- Tenant-scoped (no ON clause)
GRANT can_create_connector TO GROUP soc-leads
GRANT can_create_detection TO GROUP detection-engineers
GRANT can_read_audit       TO GROUP query:compliance-readers
GRANT can_mask             TO GROUP compliance-team

Re-granting an existing permission is idempotent — it succeeds rather than complaining that the grant already exists. When a tag expands to several connectors, each grant is written independently; the result reports how many connectors were affected and lists any per-connector failures.

REVOKE

Mirrors GRANT, with FROM in place of TO.

REVOKE <resource-verb> ON <resource> FROM USER|GROUP <identity>
REVOKE <tenant-verb>                 FROM USER|GROUP <identity>

Examples:

REVOKE can_use  ON CONNECTOR splunk-prod FROM GROUP soc-analysts
REVOKE can_use  ON #siem                 FROM GROUP soc-analysts
REVOKE can_edit ON DETECTION brute-force FROM GROUP detection-engineers
REVOKE can_create_detection              FROM GROUP soc-leads
REVOKE can_mask                          FROM GROUP compliance-team

Revoking a permission that isn't currently in effect is a no-op success, not an error. For the #tag form, REVOKE removes grants from the connectors that carry the tag now — a connector granted under #siem that has since been untagged needs an explicit per-connector REVOKE.

EXPLAIN GRANTS

Lists the grants configured in the current tenant. Both filters are optional and can be combined.

EXPLAIN GRANTS [ON <resource>] [TO USER|GROUP <identity>]

Examples:

EXPLAIN GRANTS                                              -- all grants in this tenant
EXPLAIN GRANTS ON CONNECTOR splunk-prod                     -- grants on one connector
EXPLAIN GRANTS ON DETECTION 'Brute force AD'                -- grants on one detection
EXPLAIN GRANTS TO GROUP soc-analysts                        -- grants held by one group
EXPLAIN GRANTS ON CONNECTOR splunk-prod TO GROUP soc-analysts

Each row shows the subject (rendered as a group display name where known), the object (the connector or detection display name, or tenant for tenant-scoped grants), the relation, who granted it, and when. The relation column can show grants beyond the six verbs above (for example, admin) when they exist in the authorization model.

EXPLAIN GROUPS

Lists the groups available to grant to in the current tenant — the discovery surface for finding the names to use in GRANT … TO GROUP.

EXPLAIN GROUPS [LIKE '<pattern>']

The optional LIKE pattern is a glob (shell-style wildcards: * matches any run of characters, ? matches one), matched case-insensitively against the display name. The quotes are required.

EXPLAIN GROUPS                 -- every group in this tenant
EXPLAIN GROUPS LIKE 'soc*'     -- groups whose name starts with "soc"

Each row shows the group's source (entra / query), its id, its display name, and — for the built-in Query groups — its system kind (admin / member).

Current limitation

GRANT/REVOKE TO/FROM USER parses successfully but is rejected at execution time in the current release: granting or revoking a resource or tenant verb directly to a user by email returns "Granting to a specific user is not yet supported." (EXPLAIN GRANTS TO USER … as a filter hits the same gate.) Group grants are the supported path today for GRANT/REVOKE.

This limitation is specific to the grant verbs (can_use, can_edit, can_create_connector, can_create_detection, can_read_audit, can_mask) — it does not apply to column masking, where MASK/UNMASK/EXPLAIN MASKS FOR fully support USER identities today, nor to the ADD USER / REMOVE USER membership commands below.

Group management

Beyond granting permissions to groups, FSQL provides six commands for creating and administering the groups themselves:

CREATE GROUP '<name>'
RENAME GROUP [source:]<name> TO '<new-name>'
DROP GROUP [source:]<name>
ADD USER <email> TO GROUP [source:]<name>
REMOVE USER <email> FROM GROUP [source:]<name>
EXPLAIN MEMBERS OF [source:]<name>

All six are scoped to the current tenant, and the five mutating commands require tenant-admin authorization, just as GRANT and REVOKE do.

Only query:-source groups can be created, renamed, deleted, or have their membership managed. Recall from How authorization works in Query that groups come from two sources — entra: groups synced from your directory, and query: Query-native groups. Entra groups are a read-only projection of Microsoft Graph, kept in sync by Query's Entra sync worker; they are permanently read-only everywhere in Query, not just from FSQL — to add or remove an Entra group or its members, make the change in Entra itself.

A command that resolves its target to an entra: group parses successfully but is rejected when it runs:

DROP GROUP entra:'SOC Analysts'
-- ERROR: Entra groups are read-only; manage them in Entra.

This applies to the four mutating commands that name an existing group (RENAME/DROP GROUP and ADD/REMOVE USER … TO/FROM GROUP). CREATE GROUP accepts no source: prefix at all — it always creates a query: group, so CREATE GROUP entra:'SOC Analysts' is a syntax error rather than a command that parses and then fails. EXPLAIN MEMBERS OF is the read exception: reading membership isn't a mutation, so it works against groups from either source.

Group name resolution follows the same rules as Identity references above: a bare name that matches groups in both sources is ambiguous and needs an entra:/query: prefix; a name that matches no group fails with a "no group named … found" error.

📘

Why ADD/REMOVE, not DROP, for membership?

CREATE GROUP, RENAME GROUP, and DROP GROUP manage the group object — parallel to SQL's CREATE/DROP. ADD USER … TO GROUP and REMOVE USER … FROM GROUP manage membership, the elements of that group's member set — a different layer, with its own verb pair. Membership removal deliberately uses REMOVE, not DROP: DROP USER would read as deleting the user's account, a much more dangerous operation than removing them from one group.

CREATE GROUP

Creates a new, empty query: group in the current tenant.

CREATE GROUP '<name>'

CREATE GROUP 'analysts'

The name must be a quoted display name — single or double quotes both work, and new groups don't get a separate alias the way connectors and detections do. The group starts with no members and no grants.

Unlike GRANT, CREATE GROUP is not idempotent: if a group with that display name already exists in the tenant (matched case-insensitively), the command fails with group already exists rather than succeeding as a no-op. If you're not sure whether a group already exists, check with EXPLAIN GROUPS first; to fix a naming mistake, use RENAME GROUP or DROP GROUP rather than retrying CREATE GROUP.

RENAME GROUP

Renames an existing query: group.

RENAME GROUP [source:]<name> TO '<new-name>'

RENAME GROUP 'analysts' TO 'soc-tier1'
RENAME GROUP query:analysts TO 'soc-tier1'

The existing group is referenced the same way as in Identity references — bare name, source-prefixed, or quoted display name; the new name must be a quoted display name. As with all group-management mutations, a name that resolves to an entra: group parses but is rejected at execution:

RENAME GROUP entra:'SOC Analysts' TO 'x'
-- ERROR: Entra groups are read-only; manage them in Entra.

DROP GROUP

Deletes a query: group, including its membership.

DROP GROUP [source:]<name>

DROP GROUP 'analysts'
DROP GROUP query:analysts
DROP GROUP entra:'SOC Analysts'    -- parses, but fails at execution (Entra groups are read-only)

If the group is currently the subject of one or more active grants (something has run GRANT … TO GROUP naming it), DROP GROUP fails rather than silently orphaning those grants — for example, group has 3 active grants; revoke them first. REVOKE the grants first (see EXPLAIN GRANTS TO GROUP <name> to find them), then retry DROP GROUP.

ADD USER TO GROUP

Adds a user to a query: group's membership.

ADD USER <email> TO GROUP [source:]<name>

ADD USER [email protected] TO GROUP 'soc-tier1'

The group must resolve to a query: group; targeting an entra: group is rejected with Entra groups are read-only; manage them in Entra. — add the user in Entra instead.

REMOVE USER FROM GROUP

Removes a user from a query: group's membership.

REMOVE USER <email> FROM GROUP [source:]<name>

REMOVE USER [email protected] FROM GROUP 'soc-tier1'

Like REVOKE, this is idempotent: removing a user who isn't currently a member succeeds silently rather than erroring, since the desired end state — that user not being in that group — is already true. As with ADD USER, the target must resolve to a query: group.

EXPLAIN MEMBERS OF

Lists the members of a group — the one command in this family that reads from either source.

EXPLAIN MEMBERS OF [source:]<name>

EXPLAIN MEMBERS OF 'soc-tier1'                 -- a query-native group
EXPLAIN MEMBERS OF entra:'SOC Analysts'        -- an Entra-synced group

Note there's no GROUP keyword here — OF <group> already implies it. An ambiguous bare name still requires the entra:/query: prefix, exactly as elsewhere on this page.

The member rows differ slightly by source: query: members are resolved and shown with their name and email, same as elsewhere in Query; entra: members come back exactly as Microsoft Graph reports them for that group. If Query can't reach Microsoft Graph while reading an Entra group's members, the command reports that failure explicitly rather than returning an empty member list.