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."

# Show available profiles and select the appropriate one
omni config show
# If multiple profiles exist, ask the user which to use, then switch:
omni config use <profile-name>

# Confirm the active profile is authenticated and inspect your permissions:
omni whoami whoami

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:

omni <command> --base-url "$OMNI_BASE_URL" --token "$OMNI_API_TOKEN"

Discovering Commands

omni scim --help             # User and group management
omni schedules --help        # Schedule operations
omni connections --help      # Connection management
omni documents --help        # Document permissions
omni folders --help          # Folder permissions
omni ip-allowlist --help     # Organization IP allowlist (CLI ≥ 1.5.0)
omni scim users-create --schema   # Print a command's args, flags, body schema + example, and response shape (no token)

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

# List connections
omni connections list

# Schema refresh schedules
omni connections schedules-list <connectionId>

# Connection environments (create, update <id>, delete <id>)
omni connections connection-environments-create --schema

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.

# Rotate a connection's dbt commit signing key
omni connections dbt-rotate-signing-key <connectionId>

# Rotate a model's git commit signing key
omni models git-rotate-signing-key <modelId>

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.

# List users
omni scim users-list

# Find by email
omni scim users-list --filter 'userName eq "user@company.com"'

# Create user
omni scim users-create --body '{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "newuser@company.com",
  "displayName": "New User",
  "active": true,
  "emails": [{ "primary": true, "value": "newuser@company.com" }]
}'

# Deactivate user
omni scim users-update <userId> --body '{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "Operations": [{ "op": "replace", "path": "active", "value": false }]
}'

# Delete user
omni scim users-delete <userId>

Group Management (SCIM 2.0)

# List groups
omni scim groups-list

# Create group
omni scim groups-create --body '{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "Analytics Team",
  "members": [{ "value": "user-uuid-1" }]
}'

# Add members
omni scim groups-update <groupId> --body '{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "Operations": [{ "op": "add", "path": "members", "value": [{ "value": "new-user-uuid" }] }]
}'

User Attributes

# List attributes (system + custom)
omni user-attributes list

# Create a custom attribute definition (CLI ≥ 1.4.0)
omni user-attributes create --body '{
  "name": "region",
  "label": "Region",
  "type": "String",
  "description": "User region for row-level security filtering",
  "default_value": "us-east"
}'

omni user-attributes update <id> --body '{ "default_value": "us-west" }'
omni user-attributes delete <id>

# Find the user by email before setting an attribute
omni scim users-list --filter 'userName eq "user@company.com"'

# Set attribute on user (via SCIM)
omni scim users-update <userId> --body '{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "Operations": [{
    "op": "replace",
    "path": "urn:omni:params:1.0:UserAttribute:region",
    "value": "West Coast"
  }]
}'

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, create it with omni user-attributes create (CLI ≥ 1.4.0) and confirm the create before assigning values; do not keep retrying SCIM paths or claim the value was set from an empty User attributes set: {} response.

Managing definitions needs the Manage User Attributes permission; the naming and type rules are in --help and fail loudly. Two behaviors do not:

• delete <id> reaches past the definition, and the response does not say so. Every user value goes with it, embed SSO logins still passing the name fail outright (an embed lockout), model SQL referencing it breaks, and a connection selecting its environment by that name silently falls back to the default connection. Search the model for the name and confirm with the user first.
• Number values are stored as strings, and a JSON number past 2^53 - 1 is silently rounded on the way in — a default_value of 9007199254740993 is stored, and returned, as "9007199254740992". Send large numbers as strings.

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.

Switchable attribute values (CLI ≥ 1.5.0)

An attribute can be provisioned so a user or group may switch between a curated list of values at runtime (dynamic shared extensions, access filters, connection environment routing). The caller's chosen value then drives those features exactly as an assigned value would — so provisioning cannot grant access the user does not already have access to.

# Admin: list / set the values a user or group may switch to.
# GET uses --user-id or --group-id flags; the PUT body carries user_id or group_id (not both).
omni user-attributes user-attribute-selectable-values-get <attributeId> --user-id <membershipId>
omni user-attributes user-attribute-selectable-values-update <attributeId> --body '{
  "user_id": "<membershipId>",
  "values": ["us-east", "us-west"],
  "allow_any_value": false
}'

# Caller self-service: list switchable attributes, switch one, or clear the switch
omni user-attributes user-attribute-selections-list
omni user-attributes user-attribute-selection-update --body '{ "user_attribute_id": "<attributeId>", "values": ["us-west"] }'
omni user-attributes user-attribute-selection-delete --user-attribute-id <attributeId>

user-attribute-selection-update / -delete change the caller's own switch. An org API key acts as its creator, so an admin cannot switch another user's value with them; the call succeeds and changes the admin's own value.

Sending an empty values array with allow_any_value: false removes the provisioning entirely, which also stops honouring any switch the user has already made. Confirm with the requester before clearing provisioning on a user who relies on the switched value for row-level security.

Model Roles & Caller Access

Before deciding where a model or content change goes, run omni whoami whoami --model-id <modelId> and decide from the permissions in rolesByModel[<id>].permissions, since a role can appear under a custom name or an internal code: QUERY_FULL_MODEL is the signal that the caller can create a branch, UPDATE that they can merge to the shared model (without it, open a PR or request a merge), and USE_WORKBOOKS that they can create content. A caller with USE_WORKBOOKS and no QUERY_FULL_MODEL (a Restricted Querier) can change only existing views in the document's workbook model and must build every tile on a topic, so do not plan topic, join, or access-grant changes for them. The full permission table, the decision rules, and the role-assignment commands (keyed by membership id, with the body key roleName) are in references/model-roles.md.

Document Permissions

# Check effective permissions for a user (userId required)
omni documents get-permissions <documentId> --user-id <userId>

# List document access principals
omni documents access-list <documentId>

# Add direct access for a group
omni documents add-permits <documentId> --body '{
  "permissions": [{ "type": "group", "id": "group-uuid", "access": "view" }]
}'

# Add direct access for a user
omni documents add-permits <documentId> --body '{
  "userIds": ["user-uuid"],
  "role": "EDITOR"
}'

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

Access Boost

Access Boost lets Viewer and Restricted Querier roles see a dashboard's non-topic tiles (raw SQL or a bare base-view query) on the dashboard; the workbook stays restricted. It loosens access controls: confirm intent with the requester, naming the users or groups and what the tiles expose, and prefer specific users or groups over organizationAccessBoost. The org prerequisite, the commands, and how boost interacts with access grants: references/access-boost.md.

Folder Permissions

# Get
omni folders get-permissions <folderId>

# Set
omni folders add-permissions <folderId> --body '{
  "userGroupIds": ["group-uuid"],
  "role": "VIEWER"
}'

Schedules

# List schedules
omni schedules list

# Create schedule (default entity is "dashboard", so omitting it delivers the dashboard)
omni schedules create --body '{
  "identifier": "dashboard-identifier",
  "name": "Weekly Dashboard - Monday 9am PT",
  "schedule": "0 9 ? * MON *",
  "timezone": "America/Los_Angeles",
  "destinationType": "email",
  "format": "pdf",
  "subject": "Weekly dashboard",
  "recipients": ["team@company.com"]
}'

# Deliver a workbook tab instead of the dashboard (CLI ≥ 1.5.0).
# Set entity: "workbook" and pass the tab via queryIdentifierMapKey; default stays entity: "dashboard".
# `schedules update` does not take entity, so changing what a schedule delivers means creating a new one.
# filterConfig, containerPages and singleColumnLayout apply to dashboard deliveries only.
# Find these later with: omni schedules list --content-type "workbook tab"
omni schedules create --body '{
  "identifier": "document-identifier",
  "name": "Weekly Pipeline Tab",
  "schedule": "0 9 ? * MON *",
  "timezone": "America/Los_Angeles",
  "destinationType": "email",
  "entity": "workbook",
  "queryIdentifierMapKey": "<tabKey>",
  "format": "xlsx",
  "subject": "Pipeline tab",
  "recipients": ["team@company.com"]
}'

# Manage recipients for an existing schedule
omni schedules recipients-get <scheduleId>

omni schedules add-recipients <scheduleId> --body '{ "recipients": ["team@company.com"] }'

schedules update is a full replacement, not a patch, and it returns "success": true either way. Any optional property you leave out is reset to its default — filter values cleared, the alert condition removed, maxRowLimit and the presentation flags back to defaults. --help lists every property that resets.

You cannot round-trip schedules get into it. The read shape is not the write shape: the GET nests presentation options under metadata and recipients under destinations[], while the update body wants subject, maxRowLimit, recipients and destinationType flat — feeding the GET straight back 400s on destinationType. Build the body from omni schedules update --schema and carry across every value you mean to keep.

Email-only users are the recipients that exist only to receive deliveries: omni users list-email-only / create-email-only / create-email-only-bulk, and delete-email-only-bulk (CLI ≥ 1.4.0). The bulk delete is partially successful by design — a 200 carries deleted[] alongside notFound: {emails: [], userIds: []}, so check those two arrays, not the status, before reporting it done.

AI Credits

The omni ai credit-controls-* commands read and update AI credit controls for the organization, for users, and for entity groups; the omni ai credit-usage-* commands read usage for the current billing period, and credit-usage-users-read takes membership ids. Required permissions, CLI versions, feature flags, and examples: references/ai-credits.md.

Color Palettes

omni color-palettes manages the organization's custom chart palettes (CLI ≥ 1.3.1); writes need the Manage Config permission. An update recolors every chart that uses the palette, a delete sends those charts back to the org default palette, and neither reports which charts changed. Examples and naming rules: references/color-palettes.md.

Uploads

omni uploads lists, creates, replaces, and deletes the CSV and spreadsheet files users upload to query alongside warehouse data; create and replace-data take the file path with --file. replace-data keeps the upload id, so views and document tabs serve the new data without model or document changes; compare headers first, because renamed or removed columns can break content that uses them. Flags, the --body form, and examples: references/uploads.md.

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

# After creating or updating a user, verify they exist with correct state
omni scim users-list --filter 'userName eq "newuser@company.com"'

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

After Group Operations

# After creating a group or modifying members, verify membership
omni scim groups-list

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

After Permission Changes

# After setting document permissions, verify the principal and role
omni documents access-list <documentId>

# For a specific user, also check effective permissions
omni documents get-permissions <documentId> --user-id <userId>

# After setting folder permissions, verify
omni folders get-permissions <folderId>

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

After User Attribute Changes

# Verify the user's assigned attribute value was set
omni scim users-list --filter 'userName eq "user@company.com"'

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.

After a definition change (user-attributes create / update / delete), read it back with omni user-attributes list — Number defaults come back as strings, so compare them as strings.

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

omni query run --body '{ "query": { ... }, "userId": "<target-user-uuid>" }'

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

After Schedule Operations

# Verify schedule was created with correct settings
omni schedules list -o json

# Verify recipients were added
omni schedules recipients-get <scheduleId>

Check that: the created schedule id appears in the list and the returned fields match the requested schedule cron, timezone, destinationType, entity, format, and document 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.

IP Allowlist (CLI ≥ 1.5.0)

omni ip-allowlist get / update read and write the organization's IP allowlist — whether it's enforced, the support and SCIM bypasses, and the allowed addresses with their notes. Requires organization admin access. The update is refused if it would leave the allowlist enabled with no entries, or enabled with a list that blocks the caller's own address — a locked-out org cannot be fixed by API.

omni ip-allowlist get
# Every field is optional; `entries` replaces the whole list.
omni ip-allowlist update --body '{
  "enabled": true,
  "entries": [
    { "address": "203.0.113.0/24", "note": "office" },
    { "address": "198.51.100.42",  "note": "VPN exit" }
  ]
}'

Confirm the current state with get before an update, and name the addresses being added or removed when you report back — a bad entry can lock out every non-support user, and the server will accept the write that strands them.

Cache and Validation

omni models cache-reset resets a model's cache policy, omni models content-validator-get finds broken field references across dashboards and tiles (with --branch-id, it shows what a branch change would break), and omni models git-get returns a model's git configuration. Examples and the full-validation flag: references/cache-and-validation.md.

Docs Reference

Omni docs pages for each admin area: references/docs-links.md.

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