Permissions

What your AI agent can access depends on the kind of token it uses:

• Full access token: the agent reaches exactly what the token’s creator can reach on the platform, as defined by their permissions. If the creator cannot see a layer, that layer does not appear in list_layers.
• Scoped token: the token has its own scope, per resource type and per tool, and it is always capped by what its creator can still reach. See Scoped tokens.

​

Token types and permission behavior

When you create a token (in the Access tokens section of the MCP Gateway page or through the Platform API), you choose between two scoping options, shown in the app as Full access and Custom scope. The choice determines how the token relates to platform permissions.

​

Full access tokens

A full access token inherits the permissions of the user who created it and stays in sync dynamically. If that user gains access to a new layer, the token immediately reflects it. If their access to a table is revoked, the token loses that access automatically, with no token rotation needed. A full access token can do everything its creator can, including writes: editing pipelines, granting permissions, and creating other tokens. It cannot be limited to certain tools. To limit what an agent can do, use a scoped token. Tokens created during the OAuth flow are full access tokens tied to the authenticating user.

​

Scoped tokens

A scoped token carries its own selection, chosen per resource type when you create it: which tables, which volumes, which secrets, which context-layer documents, which live connections, and which tools it may call. Each is independent: a token can name three tables and no secrets at all. That selection is not the last word. On every request it is narrowed to what the creating user can still access, so a scoped token can only ever be narrower than its creator:

• Access the creator loses is dropped from the token immediately. If their permission to trusted.customer_orders is revoked, the token stops seeing that table on its next call; no rotation, no editing.
• Access the creator gains is not added. The selection stays the selection. To widen a scoped token, edit it.

​

What a scoped token can reach

A scoped token reaches only surfaces where you can select what it sees:

• Tables: listing, searching, previewing, and querying the tables in its scope, and generating SQL over them.
• Context layer: get_semantic_context returns only the documents in its scope.
• Live Data: the live connections selected on it, and within each one the tools you chose.
• Layers, volumes, files, and context-layer folders and documents: browsing layers and volumes, reading and uploading files, and working with the context-layer folders and documents in its scope are available to a scoped token only when scoped-token browsing has been enabled for your workspace by Nekt support. Without it, these tools return an error for a scoped token.

Everything else is refused to a scoped token whatever its scope says: sources, destinations, Queries and Notebooks, triggers, runs, GitHub, creating layers, failure alerts, permission management, MCP token management, and the token access log. Those tools require a full access token.

​

Scoping on Starter and Free

Choosing individual resources is part of the permissions model, and permissions are enforced on Growth and Custom only. On Starter and Free a scoped token therefore works one whole resource type at a time: for each kind of resource you choose all of it or none of it. The five are independent. A token with All tables and All secrets on and the rest off reaches every table and every secret, and no volumes whatsoever: off means none, not “inherit”. Turning all five on is still a scoped token, not a full access one.

​

Who can create tokens, and how long they last

• Who can create tokens: in Access tokens, the Who can create tokens setting decides which roles can create and manage tokens in the workspace: everyone (the default), only Admins and Owners, or only Owners.
• Expiration: a token lasts one year from creation by default and can never be valid for more than a year. Rotating a token in the app renews it for the same period.
• A token depends on its creator: if the person who created a token is deactivated or removed from the workspace, the token stops working, whatever its scope. Before someone leaves, create replacement tokens for the automations that use theirs.
• Access log: every request a token makes is recorded in the token access log, including the SQL of each query, so you can see which tables an agent queried. It is available on Starter (7 days), Growth (30 days), and Custom (90 days), not on Free. Owners and Admins see every token; other members see the tokens they created.

​

Practical examples

​

Example 1: User receives Viewer access to an entire layer

Scenario: A member is granted Viewer access to the raw layer, which contains dozens of tables and several volumes. Action on the platform: An admin grants Viewer access to the raw layer under Workspace → Permissions. What to expect in the MCP:

• list_layers now includes the raw layer.
• list_volumes returns volumes inside raw.
• list_tables and get_relevant_tables_ddl include tables from raw.
• generate_sql and execute_sql can query those tables.

---

​

Example 2: Table permission is revoked for a specific user

Scenario: A member previously had Viewer access to trusted.customer_orders. That permission is now revoked directly on the table. Action on the platform: The permission is removed from the table: no group change is involved. What to expect in the MCP:

• execute_sql returns an error for any query that references trusted.customer_orders (if you use your own GCP cloud, it must be on cloud version 1.0.10 or later; see the note at the top of this page).
• get_table_preview returns an error for that table.
• get_relevant_tables_ddl no longer returns its schema.
• list_tables no longer includes it.

---

​

Example 3 (Troubleshooting): Group permission revoked but agent still has access

Scenario: An admin revokes the raw layer permission from a group. An AI agent using a full access token from a user in that group can still query tables in raw. Most likely causes:

1. Conflicting group permissions. If the user belongs to another group (including the built-in All group) that still has access to raw, Nekt grants the highest permission the user holds from any assignment. Revoking access from one group alone does not remove access if another group retains it.
2. Misconfigured change. Verify the permission was saved correctly in Workspace → Groups or on the layer’s Permissions tab.

​

How permissions apply to each tool

Most tools filter their output automatically to what the token can access. Tools that operate on resources outside the token’s scope return an error rather than partial results. A scoped token reads only the context-layer documents and folders it was scoped to, always capped by its creator’s access. Beyond get_semantic_context, the context-layer tools are available to a scoped token only when scoped-token browsing is enabled for the workspace.

​

Context layer permissions

The context layer (the context documents get_semantic_context reads) is organized into folders, each with its own access rules, and a token sees exactly what its user sees. Two consequences worth knowing when an agent comes back empty-handed:

• An empty get_semantic_context result is ambiguous. It can mean the question matched no document, or that the relevant documents are in folders this token’s user cannot read. Rephrasing fixes the first and never fixes the second, so the agent will say there may be documentation you don’t have access to instead of retrying.
• On Growth and Custom, creating a document needs a folder you can write to. A document created without one lands at the root of the context layer, which most users cannot write to. Agents call list_semantic_layer_folders(writable_only=True) first to choose a destination; an empty result there means the user cannot create documents anywhere and the agent should stop rather than retry.

​

Troubleshooting