Skip to content

Getting started with Iris

Open Iris

Sign in to AtmanID and click the AI Assistant button in the bottom-right corner of any dashboard page, or press ⌘J (Ctrl+J on Windows and Linux). Shift+? also opens it, unless you have switched off Single-key shortcuts in the Appearance menu. The Iris panel opens with an input field and the placeholder “Ask about users, access, agents…”

Every signed-in role can open Iris. What it can answer depends on your role: an end_user gets help, their own access requests, access bundles and aggregate counts; managers add people, compliance and policy lookups; administrators, analysts, compliance officers and CISOs add the deeper tools. Each tool also checks your permissions when it runs. The tool catalog lists which roles are offered which tools.

Asked in plain English for FinanceAdmin on Financial ERP for seven days, Iris writes a request card — critical risk, the access, a justification and the time limit — that is filed only when you confirm.

Your first three queries

The three most common Iris query shapes — by frequency observed in production usage — are: counts, lists, and breakdowns. We’ll walk through one of each.

Query 1 — A count

Type into Iris:

how many users are active right now

Hit Enter. Iris responds with something like:

78 users are active.

BASED ON users · 78 rows

Three things worth noticing in this response:

  1. The number is concrete (“78”) not vague (“a lot”). Iris gives you actionable data, not impressionistic answers.
  2. The source is cited. The “Based on” footer lists the tables the answer was read from, the number of rows behind it and, where relevant, the time window. Table names link to the matching dashboard page so you can check the number yourself.
  3. A named tool answered it. Behind the scenes Iris used compose_metric with its active-users metric — a pre-built, tested query, not SQL the model wrote. The tools used are recorded in the audit log and shown in the agent activity feed.

Query 2 — A list

Type:

show me pending access requests

Iris responds with something like:

3 access requests are pending approval:

Request Requester Application Submitted
REQ-0231 Jane Park Salesforce 2 days ago
REQ-0228 Bob Lee GitHub 5 days ago
REQ-0219 Ana Ruiz Workday 14 days ago

This one was answered by a named lookup tool for access requests. Note the response is shaped for the question: rows, not just a number. If you’d asked “how many access requests are pending,” you’d get a count from compose_metric instead. Iris routes aggregation questions and listing questions to different tools, and checks afterwards that it picked the right kind.

Query 3 — A breakdown

Type:

break down users by department

Iris responds:

Users by department:

Department Count
Engineering 28
Sales 19
Operations 12
Unassigned 11
Marketing 8

Behind it: compose_metric — the total-users metric, broken down by department.

Two things to notice:

  1. Unassigned is shown explicitly. Missing values become their own bucket rather than being dropped — that’s a critical accuracy property for IAM data, where “users without a department” is itself an actionable signal.
  2. Breakdowns are a metric × dimension pair. Each metric allows the dimensions that make sense for it, and an invalid pair is refused rather than guessed. See the tool catalog.

Reading the response — three signals to check

Every Iris response gives you three things you can verify before trusting the answer:

  1. The numeric answer or row content. This is the “what.”
  2. The “Based on” footer. The tables or views the answer came from, the row count and the time window. For an iris_sql answer, a Query run disclosure shows the exact query that executed.
  3. Whether the source fits the question. If you asked about agents and the footer cites users, Iris read the wrong data.

If the source doesn’t match your intent, the answer might still be correct but you’ve likely found a routing miss. Ask Iris to rephrase: “I meant agents, not users — how many agents are active?” — Iris will route to the agents tool and re-answer.

When Iris asks a clarifying question

Sometimes your question is ambiguous, and Iris may ask before answering. Example:

show me access requests

Iris responds:

Do you mean:

  • All access requests in the last 30 days?
  • Pending access requests only?
  • Access requests for a specific app?
  • Access requests by status (count breakdown)?

Pick one or rephrase.

This is a feature, not a failure. It is the model’s judgement rather than a fixed rule, so Iris asks about some ambiguities and takes the most likely reading of others — typically when a status, a time window, or count-versus-list is unclear. The clarifying question tells you which piece Iris sees as missing. Pick the option that matches your intent and Iris re-routes.

When Iris doesn’t know

If neither the wording of your question, its meaning, nor the page you are on points to a family of tools, Iris is offered every tool your role allows and the model chooses. If none fits, Iris should say it can’t answer that rather than invent a number, and suggest a rephrasing.

For questions no named tool or metric covers, Iris can build a structured iris_sql query over one curated view (for roles that hold it). For the long tail, tell us — new tools and metrics are added from observed gaps. Browse the Iris tool catalog for the closest pre-built question.

When Iris gets it wrong (rare but real)

Iris’s tool selection is good but not perfect. The known failure modes:

  • Misroute on under-specified queries. “Show me access” might be read as access requests when you meant current access grants, or vice versa. Recovery: rephrase with the specific noun (“show me access GRANTS” or “show me access REQUESTS”).
  • Wrong tool for similar concepts. “How many apps do we have” might be answered with a count of applications with at least one active grant when you meant every registered application. Recovery: use the disambiguating term.
  • Timeout or row limits on large queries. iris_sql queries stop after 5 seconds and return at most 200 rows; list lookups such as the audit trail return at most 100. Recovery: add a tighter filter, or ask for a count or breakdown instead of every row.

Iris’s self-check catches one common miss — answering a count question with a listing tool. When it sees that, it makes one corrected call to the right kind of tool. This is invisible to you in the UI (you just get a better answer).

For the deep architecture of how routing works (and why it works), see How Iris stays accurate.

Iris as a developer

(Switch perspective. You’re now Dev Torres, a platform engineer integrating with AtmanID.)

Iris is built for the signed-in app. The endpoint behind the panel, POST /api/chat, authenticates with your browser session — it does not accept API keys and is not part of the published /api/v1 contract, so there is no supported way to call it from a script or server today. For programmatic access to the same data, use the /api/v1 API (users, access requests, agents, apps, entitlements, SoD violations, audit and more) with an API key. See Building on Iris.

Two things developers use Iris for in the app:

  1. Pre-flight data lookups during integration debugging. “Show me the pending access requests for Salesforce” lets a developer verify their integration is creating requests correctly without writing a custom dashboard.
  2. Ad-hoc reports for stakeholders. A PM asks “what’s our agent count by risk band?” — Iris produces the breakdown in seconds instead of waiting for someone to write a custom report.

For questions the catalog doesn’t cover, ask in plain language. If your role holds iris_sql, Iris describes a query over one curated view as a structure — view, columns, filters, grouping, ordering, limit — and the server checks every column name and builds the query itself. Iris does not run SQL text you paste in; if you paste a simple single-view SELECT, it translates it into that structure, and it tells you when the query needs joins or subqueries it can’t express. Each such query is audited as IRIS_SQL_EXECUTED (or IRIS_SQL_REJECTED) with the exact query text, and the answer shows it under Query run.

What’s next

© AtmanID · Privacy