dip to your tenant, it asks for a set of
scopes — named capabilities, not roles. A scope is a platform-level ceiling: holding
query_engines:execute_sql never lets a client run a statement your own roles and grants wouldn’t
already let you run yourself. See Scopes and consent for how the consent
screen and MCP connection flow use these.
The scopes
What a new connection asks for by default
The default consent is the set of scopes a new connection asks for when it names none of its own: the scopes marked Advertised above. It is what a member needs to read their data, write their own sandbox databases and draft definitions:query_engines:execute_sql,
query_engines:list, metadata:read, semantic:suggest, workspace_db:write, pipelines:read,
members:invite, apps:publish_confined and offline_access. Claude, Codex, Cursor and claude.ai ask for it through MCP, and
dip login asks for it too, together with the scopes its own commands need. It never includes a
certify action or a scope reserved for API keys. members:invite is the one administrator
capability in it: it lets a tenant admin invite from the chat or the dip CLI, and for anyone else it does nothing,
because your roles still decide whether you may invite.
A client that wants less can name a narrower set. With dip, pass
dip login --scope "<names>"; see dip login.
What each grant actually lets a client do
query_engines:execute_sqlruns SQL on your engines and lets a client usebrowseat the catalogs, schemas, tables or columns level — exactly what your own roles and grants already allow.query_engines:listonly lists your engines: their names, where to reach them, whether they’re running. It reads no data.metadata:readsearches your catalog metadata (only objects your roles already let you see) and the query history, the same as the Query history page: your own queries, or the whole tenant’s if your role may audit them. It runs no SQL.git:readlists repositories and refs and fetches objects from the repository named in a Git credential.git:writecreates repositories and updates refs. Neither scope implies the other, and your tenant role still decides which operation is allowed. Git credentials are also bound to one tenant, repository, host, and an expiry of no more than 15 minutes.semantic:compilelists the metric definitions you can see and turns a metric question into SQL — it doesn’t run that SQL. It also reads your business vocabulary (ontology). This is what the MCP semantic and ontology READ tools (list_semantic_models,get_semantic_model,get_ontology,ontology_query) require — notquery_engines:execute_sql.semantic:suggestfiles a metric or a verified query (a question plus the query that answers it) into your review queue. It changes, certifies and adds nothing; a steward decides on the pending suggestion. Because a suggestion names models and engines, it also carries the read tier (semantic:compile) and engine inventory (query_engines:list) under it, so a key holding only this scope can still reach the MCP endpoint and compile a suggestion before filing it. This is the least privilege the MCPsuggest_metrictool needs, and it is distinct fromsemantic:author(which can change the vocabulary, not just suggest).apps:publishpublishes data apps to your registry and manages their versions, acting as you; the push is still checked against your own roles. It also lists your tenant’s data planes and the images pushed to its registry, with whether each one registered, sodip app pushcan choose a registry and report whether your push registered. To mint an API key with this scope, your roles must permit creating apps or updating all apps in the tenant. Update permission alone does not permit creating a new app.apps:installinstalls data apps and changes the installed version and access used by people opening them. Your current role and ownership still decide what you may install. Any public OAuth client can request it by name and ask you to approve; it is not exclusive todip. It is not included in the default MCP consent, paired automatically or available on API keys. It uses the tenant’s management address, not a registry or engine token.apps:publishdoes not imply it, and it implies no publication or data-query permission. A client you approve can install without asking you again:dipconfirms each app’s access and code trust with you first, and other clients are not required to.apps:publish_confinedlets your AI publish a page it built as a read-only app and install it, acting as you, through the MCPapp_publishtool. That tool is the only thing that can use it: the token endpoint and the tenant’s management address refuse it, so a client holding it cannot push an image, install some other app or change an installation’s access. A page published this way runs only its own files and writes nothing. That is enforced by the tenant, not only by the tool: the registry stores only a static, read-only app for a publish made with this permission, and an install or version change made with it accepts only static, read-only versions, even for an admin or data engineer. People who open the app see only the rows their own access allows, within what the app declares it reads. Your role must let you publish your own apps. It is notapps:publishorapps:install, and neither of those implies it.integrations:read/integrations:writelist, or register/change/delete/test, your connected data sources. Neither one ever returns a stored credential value — only non-secret settings, the names of the secrets a source stores, whether one is stored, and how the last saved test of each source ended.secrets:read,secrets:writeandsecrets:bindcover the secret store.secrets:readlists secrets and shows their names, kinds, statuses, versions, bindings and who holds which privilege; it never returns a value, because no scope can.secrets:writestores, generates and requests values, rotates, disables and deletes secrets, and changes who may use or manage each; it also grantssecrets:read.secrets:bindattaches a secret to an app or removes that binding. It is separate fromsecrets:writein both directions, because binding is what makes a credential usable by a consumer, and it does not includesecrets:read. None of the three is in a defaultdip login; your roles and your privileges on each secret still decide every action.query_engines:writecreates, reconfigures and deletes engines. Applying a new catalog set or changing settings restarts the engine and interrupts queries running on it at that moment.files:writeandfiles:readcover plane files: any file you put in your tenant’s object storage.files:writeuploads and deletes,files:readlists and downloads. They reach only your own files and are separate fromworkspace_db:write, so holding one never gives the other.workspace_db:writecreates, renames, shares and deletes your workspace databases, includingworkspace_db_shareactionsshare,unshareandlist. It invites or removes members who can write to one, and mints or revokes the write credential (a Quack token) for connecting to it directly.pipelines:readlists your registered pipelines, their runs and the results each run produced. It also letsdipread which features your tenant includes, so it can hide pipelines where your tenant does not have them. It runs no SQL and reads no data from your query engines.pipelines:managechanges pipeline settings, starts and cancels runs, assigns the service user a pipeline runs as, and deletes pipelines where your role allows it. It also grantspipelines:read. A run executes transformation code using that service user’s rights and compute.pipelines:publishpublishes a pipeline image and registers its pipeline declaration. A hosted image push also needsapps:publishto sign in to the registry.dip logincan be consented to it by name, so you can publish as yourself. This scope does not grant permission to operate the registered pipeline; requestpipelines:manageseparately.pipelines:reportis reserved for reporting run results from an external orchestrator for pipelines owned by the service user. The external reporting flow is not available yet. This scope does not grant permission to read or operate pipelines.members:inviteinvites a person to your tenant with a role, through MCPinvite_member,dip member invite, or the API, and returns the one-time invite link. In an AI chat, the AI provider keeps the chat history and the data plane serving the chat sees the link. In the dip CLI, or with an API key, the link is printed in your terminal. Anyone holding it can join as the person invited until it is used or expires. It reaches nothing else: not roles, grants, filters or masks, and not the member list. Holding it is not enough on its own: in the built-in roles onlyaccount_admincan invite.governance:managegrants and revokes role privileges, sets and removes row filters and column masks, and reads any member’s effective access and the member list. A change applies to everyone holding the role, on their next query. Holding the scope is not enough on its own: your roles still decide each change, and in the built-in roles onlyaccount_admincan make them.semantic:author/ontology:authorcreate, edit and propose changes to metric definitions or business concepts. Neither one can certify or deprecate — that stays a human,data_admin, decision, so an agent holding either scope can propose but never bless its own proposal.saved_queries:managelists, opens, edits and deletes saved queries, to the extent your roles already allow.data_planes:administerregisters a data plane (dip plane install), requests a binding for one and proves possession of its credential: the step that attaches compute to your tenant. Adip loginasks for it only when you rundip plane install, in a browser consent that adds just this scope; your roles still decide (registering needs a role such asdata_admin).
Effective access is three things intersected
Holding a scope is necessary but never sufficient. What a token can actually do is:- Scope narrows by capability — a token without
query_engines:writecan’t create an engine no matter what your roles say. - Your roles and grants narrow by what you personally may do — a token holding
query_engines:writestill can’t create an engine for a viewer who holds noQueryEngine·creategrant. See Roles and permissions matrix. - Audience narrows by which door the token was issued for — a token minted for your tenant’s MCP endpoint can’t be replayed against an engine’s own endpoint, and vice versa. See Addresses and hostnames.
A token’s scopes are fixed at issue time
Scopes are chosen when a connection is authorized and don’t change afterward, even if your tenant later turns on a capability the client would now like to use. If you connect an agent before your tenant enables a feature it needs, ask it to authenticate again so the new authorization can request the wider scope. A connection may ask for any scope in the default consent this way, and the consent screen names the ones it did not have before; a scope outside the default consent needs a client set up to ask for it by name.offline_access
This isn’t a capability — holding it authorizes nothing by itself. It’s a request for a refresh
token, so the connection keeps working without asking you to sign in again, until you revoke it or
30 days pass (a tenant may configure a shorter or longer window). A connection that didn’t
ask for offline_access stops working the moment its access token expires.
documents:write lets an approved client upload files as you into Documents folders you may add to.
Uploads are parsed and indexed and remain private to you unless you separately approve automatic
sharing or manually share them in the console. Existing grants and refreshed credentials retain this
uploader-only behavior.
documents:share_uploads is an additional, separate approval to share new agent uploads with eligible
folder readers on tenants using Documents access to manage folder permissions, when the tenant’s
automatic-sharing setting is on. It implies no other scope and does
not replace the required documents:write approval. Readers are checked again before publication;
later folder readers are not automatically added. Turning the setting off keeps new uploads private.
On the support-managed Documents setup, new agent uploads stay private to you while you retain
folder and classification access, even with sharing approved. The upload returns a note explaining
that automatic sharing is unavailable. You can manually share the file in Documents using Share…
from its row menu. Existing files are unchanged. See agent upload sharing.
The upload token audience is altimate:docsearch-upload:<tenant>. Its docs_scope is ["upload"]
for uploader-only consent and ["upload", "share_uploads"] only for separate sharing consent.
Neither token grants document reads, deletion, ACL editing or settings access. Both permissions are
human-only, requested by name, and require Documents to be enabled for your tenant.
Related
Roles and permissions matrix
The built-in roles Dippr ships with and what each one can do.
Addresses and hostnames
Which hostname a token’s audience is scoped to.
Publishing agents
agents:publish lets a client register agents, read their manifests, publish versions, and delete
registry entries where your roles allow. It does not install agents, change consent, or launch tasks.
Your workspace needs the agents entitlement. Installation changes require a signed-in browser
session and a role with the corresponding Agent installs permission; a custom role can carry it.
An installation keeps a frozen version and a consent ceiling. A consent ceiling is the set of data
and external hosts the installation may request; it never grants a user access they do not already
have. Consent updates can remove permissions but cannot add them back. To consent to a larger set,
delete the installation and create a new one. Publishing a version does not move existing installations.
agents:run lets a client acting for a signed-in person start tasks, send messages, answer an agent’s
questions, cancel tasks and view task history where that person’s role allows. It cannot decide a
review: approving, rejecting or requesting changes to a proposed write needs agents:review. A
connection granted agents:run alone, and every token an MCP connection or data plane exchanges for
another, cannot approve what an agent proposes. A client that explicitly requests agents:review and
is granted it on the consent screen, such as dip login, can.
agents:review is that approval authority. A client gets it only by asking for it by name and
showing it on the consent screen as Approve changes agents propose; it is never in the default
set, never on an API key, and never copied into a token one service exchanges for another, so an AI
connection’s token cannot be traded for one that approves. Normal dip login requests it. A dip
sign-in made before this scope existed lacks it until you run dip login <workspace-url> again;
refreshing a sign-in never adds a scope. The console approves on your signed-in session and needs
no scope. Your role and the task’s launcher rules still decide every review. Creating a task requires the ID of the query engine it will use; the task keeps that engine choice for its conversation. A service-user API key can carry the scope but cannot run Phase A tasks because it has no human launcher.
Every task keeps the launcher’s data access for its whole conversation, even
when another person sends a follow-up. A write proposal waits for a launcher or data admin to review
it. The message records the verified uploader for audit while the task keeps the launcher’s data view. A follow-up writer receives a message upload URL but cannot read the task’s private metadata
unless they are its launcher or a data admin. The agents console is not available in this release.
Agent manifests accept a per-turn timeoutMin of 1–14 minutes. Task engine tokens last at most
15 minutes and are issued once per turn; a turn ends before its token expires. An installation
created with an older, longer timeout is also limited to 14 minutes per turn.
agents:run also permits dismissing your own never-activated pending routine drafts and restoring your dismissed drafts to pending activation. It does not bypass confirmation.