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.
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:
- The number is concrete (“78”) not vague (“a lot”). Iris gives you actionable data, not impressionistic answers.
- 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.
- A named tool answered it. Behind the scenes Iris used
compose_metricwith 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:
Unassignedis 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.- 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:
- The numeric answer or row content. This is the “what.”
- The “Based on” footer. The tables or views the answer came from, the row count and the time window. For an
iris_sqlanswer, a Query run disclosure shows the exact query that executed. - 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_sqlqueries 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:
- 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.
- 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
- Want to see all the tools Iris has access to? Iris tool catalog
- Want to understand HOW Iris stays accurate at this scale? How Iris stays accurate — named tools, routing, the check on the tool Iris picked, and the bound that keeps any mistake inside your tenant
- Want the WHY? Concepts → Iris explained — the conceptual framing
- Want to use Iris for SOC 2 audit forensics? Set up an external auditor for SOC 2 evidence collection — Marcus’s perspective on Iris query patterns for compliance
© AtmanID · Privacy