When you connect an AI agent or a tool like 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_sql runs SQL on your engines and lets a client use browse at the catalogs, schemas, tables or columns level — exactly what your own roles and grants already allow.
  • query_engines:list only lists your engines: their names, where to reach them, whether they’re running. It reads no data.
  • metadata:read searches 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:read lists repositories and refs and fetches objects from the repository named in a Git credential. git:write creates 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:compile lists 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 — not query_engines:execute_sql.
  • semantic:suggest files 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 MCP suggest_metric tool needs, and it is distinct from semantic:author (which can change the vocabulary, not just suggest).
  • apps:publish publishes 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, so dip app push can 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:install installs 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 to dip. 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:publish does not imply it, and it implies no publication or data-query permission. A client you approve can install without asking you again: dip confirms each app’s access and code trust with you first, and other clients are not required to.
  • apps:publish_confined lets your AI publish a page it built as a read-only app and install it, acting as you, through the MCP app_publish tool. 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 not apps:publish or apps:install, and neither of those implies it.
  • integrations:read / integrations:write list, 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:write and secrets:bind cover the secret store. secrets:read lists secrets and shows their names, kinds, statuses, versions, bindings and who holds which privilege; it never returns a value, because no scope can. secrets:write stores, generates and requests values, rotates, disables and deletes secrets, and changes who may use or manage each; it also grants secrets:read. secrets:bind attaches a secret to an app or removes that binding. It is separate from secrets:write in both directions, because binding is what makes a credential usable by a consumer, and it does not include secrets:read. None of the three is in a default dip login; your roles and your privileges on each secret still decide every action.
  • query_engines:write creates, 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:write and files:read cover plane files: any file you put in your tenant’s object storage. files:write uploads and deletes, files:read lists and downloads. They reach only your own files and are separate from workspace_db:write, so holding one never gives the other.
  • workspace_db:write creates, renames, shares and deletes your workspace databases, including workspace_db_share actions share, unshare and list. 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:read lists your registered pipelines, their runs and the results each run produced. It also lets dip read 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:manage changes pipeline settings, starts and cancels runs, assigns the service user a pipeline runs as, and deletes pipelines where your role allows it. It also grants pipelines:read. A run executes transformation code using that service user’s rights and compute.
  • pipelines:publish publishes a pipeline image and registers its pipeline declaration. A hosted image push also needs apps:publish to sign in to the registry. dip login can be consented to it by name, so you can publish as yourself. This scope does not grant permission to operate the registered pipeline; request pipelines:manage separately.
  • pipelines:report is 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:invite invites a person to your tenant with a role, through MCP invite_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 only account_admin can invite.
  • governance:manage grants 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 only account_admin can make them.
  • semantic:author / ontology:author create, 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:manage lists, opens, edits and deletes saved queries, to the extent your roles already allow.
  • data_planes:administer registers 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. A dip login asks for it only when you run dip plane install, in a browser consent that adds just this scope; your roles still decide (registering needs a role such as data_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:write can’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:write still can’t create an engine for a viewer who holds no QueryEngine·create grant. 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.

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.