omni-admin

Omni Admin

Manage your Omni instance — connections, users, groups, user attributes, permissions, schedules, and schema refreshes.

Tip: Most admin endpoints require an Organization API Key (not a Personal Access Token).

Prerequisites

# Verify the Omni CLI is installed — if not, ask the user to install it
# See: https://github.com/exploreomni/cli#readme
command -v omni >/dev/null || echo "ERROR: Omni CLI is not installed."

Auth: a profile authenticates with an API key or OAuth. If whoami (or any call) returns 401, hand off — ask the user to run ! omni config login <profile> (OAuth 2.1 browser flow; it blocks ~2 min on the browser). Don't run config login yourself in a headless/CI session (no browser → timeout); on a local interactive machine you may. See the omni-api-conventions rule for profile setup (omni config init --auth oauth) and discovering command and request-body shapes with --schema.

If no CLI profile exists but the environment provides credentials, pass them explicitly:

Discovering Commands

Tip: Use -o json to force structured output for programmatic parsing, or -o human for readable tables. The default is auto (human in a TTY, JSON when piped).

Safe Admin Defaults

• For create operations, first try the requested create. If the API returns a conflict because the resource already exists, look it up and verify it exactly matches the requested state before reporting success.
• Prefer read-after-write checks that inspect the specific created or changed resource, not just a successful status response.
• Use the role names returned by Omni permission APIs (VIEWER, EXPLORER, EDITOR, MANAGER) when updating content access.

Connections

Commit Signing Key Rotation (CLI ≥ 1.1.2)

Rotating invalidates the previous key — confirm with the user before running, and re-register the new public key wherever the old one was trusted.

User Management (SCIM 2.0)

The --body blocks below are worked examples. For the authoritative field list (types, required, enums), run the command with --schema — e.g. omni scim users-create --schema — rather than relying on these shapes to be exhaustive.

Group Management (SCIM 2.0)

User Attributes

User attributes work with access_filters in topics for row-level security. SCIM can set values only for attribute definitions that already exist. Use omni user-attributes list to confirm the requested attribute definition exists before setting a value, but do not use it as proof that a specific user's value changed. If the definition is missing, report that it must be created in Admin -> User Attributes before values can be assigned; do not keep retrying SCIM paths or claim the value was set from an empty User attributes set: {} response.

When the user explicitly asks to set or update a user attribute, converge the user record with a SCIM update even if the initial user lookup already shows the requested value. This keeps the operation idempotent while still honoring the requested admin action. After the update, read back the same user and verify the value under urn:omni:params:1.0:UserAttribute.

Model Roles & Caller Access

Determining what a caller can do — run before deciding where model/content changes live

This is the canonical access check other skills defer to (e.g. omni-content-builder / omni-model-builder deciding whether a new field goes on a branch vs a workbook model). Run omni whoami whoami --model-id <modelId> and read rolesByModel[<id>].permissions. Gate on the presence of permissions, not the role name — names can be renamed custom roles and surface as internal codes (e.g. QUERY_TOPICS):

Decision shortcuts:

• Where should a new model field live? QUERY_FULL_MODEL present → a shared-model branch (merge it yourself if you also have UPDATE, otherwise open a PR / request a merge — a Querier can branch and modify but not promote); QUERY_FULL_MODEL absent but USE_WORKBOOKS present (Restricted Querier) → the document's workbook model (extension). A Viewer can't author content, so they never reach this choice.
• What a Restricted Querier can change in the workbook model — view-scoped only: add dimensions/measures to an existing view (extension mode) and edit decorations on existing fields (label/format/description/hidden/synonyms). They cannot modify a topic in any way (expose a field, change joins/topic config, create a topic) or change access grants / other governance — those need QUERY_FULL_MODEL on a shared-model branch. So don't plan a topic-scope, join, or grant change for a restricted querier's workbook model; it 403s mid-build and can leave the document half-modeled.
• What a Restricted Querier can query — topics only. QUERY_TOPICS without QUERY_FULL_MODEL means every query they author must be topic-based (table = the topic's base view + join_paths_from_topic_name). A bare base-view query or a raw-SQL userEditedSQL tile needs QUERY_FULL_MODEL (full-model + SQL access) — so it isn't an option for a restricted-querier author; build every tile on a topic. (Distinct from visibility: even a Querier-authored non-topic tile is hidden from restricted/Viewer audiences unless Access-Boosted.)
• A shared-model-scoped whoami does not list branch ability as its own entry — branch create/use is a separate capability granted to Querier+ — so use QUERY_FULL_MODEL as the proxy. (Holds for base roles; a custom role could grant one without the other — confirm when it matters.)

Assigning roles

Resolving another user's membershipId needs the org key. whoami → user.membershipId is self-only. For someone else, omni scim users-list --filter 'userName eq "them@company.com"' returns the membership as its id (which is the membershipId — not the user's user.id). But the SCIM API accepts only the org-level API key: a user-scoped PAT/OAuth is rejected with "User-scoped API keys are not allowed to access the SCIM API." The get/assign-model-role calls above work with a user PAT — only this lookup needs the org key.

• The body key is roleName (not role), and the path id is the membership id (a user id returns 404).
• roleName is a server-validated, instance-specific string — base roles (e.g. QUERY_TOPICS, QUERIER, CONNECTION_ADMIN) plus any org custom roles. The valid set is not discoverable via --schema (the field is a bare string, no enum) or any list command; an unknown value returns 422 "Invalid role". Discover a valid code by reading get-model-roles on a membership that already holds the target role.
• There is no un-assign command — to revert an override, re-assign the prior role.

Document Permissions

role is one of NO_ACCESS, VIEWER, EDITOR, MANAGER.

Access Boost

Access Boost lets Viewer / Restricted Querier roles view a dashboard built on non-topic content — a raw-SQL (userEditedSQL) tile or a bare base-view query — which those roles otherwise can't see. (Model access grants still apply unless the grant sets access_boostable: true.)

Dashboard-only: Access Boost lifts the restriction on the dashboard view of those tiles. It does not extend to the underlying workbook — a restricted role still can't open the workbook's non-topic or SQL tabs (or see the query behind the tile) regardless of Access Boost.

⚠️ Confirm before boosting — it loosens access controls. Access Boost deliberately exposes content that restricted roles can't otherwise see, and non-topic / raw-SQL tiles bypass topic-scoped governance (access filters, always_where) — so boosting can surface data those controls would normally withhold. Do not apply Access Boost autonomously or as a reflexive fix for "they can't see it." First:

1. Understand what the document exposes — what data the boosted tiles show, at what grain, and whether any of it is sensitive.
2. Confirm intent with the requester — that they really mean to grant these specific Viewer / Restricted Querier users or groups visibility into that content. State the implication back to them and get an explicit go-ahead before running the command.
3. Prefer the narrowest scope — boost specific users/groups (add-permits) over the org-wide organizationAccessBoost; reach for org-wide only when that's explicitly what's wanted.
4. Note the governance interaction — model access grants still apply unless a grant sets access_boostable: true; don't treat that as a safety net, confirm intent regardless.

Prerequisite (org capability, not in the CLI): the org must have allowsDocumentAccessBoost enabled (and allowsMemberToProvisionAccessBoost for non-admins to grant it). This is an instance/admin setting — if it's off, the document-level flags below are silently cleared. It's a gate; it does not itself turn Access Boost on anywhere.

Once you've confirmed intent, there are two activation levers, both scoped to a single document:

update-permission-settings (PUT) also carries the document's other toggles — canDownload, canDrill, canSchedule, canUpload, canUseDashboardAi, canUseTimezoneOverride, canViewWorkbook, requirePullRequestToPublish. Note organizationAccessBoost boosts the org-default principal on this document only — it is not an org-wide switch.

Folder Permissions

Schedules

AI Credits

Read and manage AI credit controls and usage (entity-group commands and usage reads require CLI ≥ 1.1.2). Org-level controls require the AI-admin permission; per-user controls and usage require manage-user-attributes; entity-group controls and usage require add/remove-users. Per-user and per-entity-group limits are also behind instance feature flags.

Gotcha: credit-usage-users-read takes membership ids (the user's membership in this organization), not base user ids — an unknown id 404s the whole request, naming the offending id. At most 1000 ids per request, no duplicates; users with no usage report 0.

Uploads

Manage CSV/spreadsheet uploads (the files users upload to query alongside warehouse data). create and replace-data are multipart file uploads: pass the CSV path with --file and the other fields as flags. Run either with --schema for the full field list. (On CLI < 1.2.0 these flags don't exist — the same fields go through --body as multipart fields, with file paths as the binary values.)

replace-data fully replaces the upload's data while its id stays stable — views and document tabs reference the upload by id, so they serve the new data with no model or document changes. Column renames/removals may break content referencing the old columns, so compare headers before replacing. For uploads list --model-id: shared models return connection uploads; workbook models return their own uploads.

Flags vs. --body: --file takes a path, not file contents, and --branch-id / --branch-name are mutually exclusive. --file and --model-id are required on create (--file on replace-data) unless you supply the same fields through --body, which on these two commands carries multipart fields — binary values are still file paths, not inline data.

Verification After Changes

Admin operations can silently fail or partially apply. Always read back the state after any write to confirm the change took effect.

After User Operations

Check that: active matches what you set, displayName is correct, and the user ID was returned (not an error).

After Group Operations

Check that: the group exists with the expected displayName, and members array contains the expected user UUIDs.

After Permission Changes

Check that: the principal is listed and the role matches what you set (VIEWER, EDITOR, etc.).

After User Attribute Changes

Check that: the response contains the target user, the user's urn:omni:params:1.0:UserAttribute object includes the requested attribute name, and the value exactly matches what you set. omni user-attributes list only verifies that the attribute definition exists.

If the attribute is used for row-level security (access_filters), test it by running a query as the target user:

Verify the results are correctly filtered — the user should only see rows matching their attribute value.

After Schedule Operations

Check that: the created schedule id appears in the list and the returned fields match the requested schedule cron, timezone, destinationType, content, format, and dashboard identifier. If the list/get response shape is not parseable, report that schedule setting verification was inconclusive instead of silently treating an empty parser result as success. Always verify recipients with recipients-get.

Verification Checklist

Cache and Validation

Docs Reference

• Connections · Users (SCIM) · Groups (SCIM) · User Attributes · Document Permissions · Folder Permissions · Schedules · Schedule Recipients · Content Validator · API Authentication

Related Skills

• omni-model-builder — edit the model that access controls apply to
• omni-content-explorer — find documents before setting permissions
• omni-content-builder — create dashboards before scheduling delivery
• omni-embed — manage embed users and user attributes for embedded dashboards