Personal API Tokens and scopes

A Personal API Token (gsp_…) lets a script, an AI assistant, or a BI tool act as you without your password. Each token carries permission scopes, which decide what kind of access it has, and can carry agent scopes, which limit it to some pipelines and agents. Core Hub enforces both on every request.

A token never has more access than your role. Scopes can only narrow it.

Create a token

  1. Open the user menu → Settings → Account → Personal API Tokens.

  2. Select New token.

  3. Enter a Token name and choose an Expiry: 7, 30, or 90 days, or Never.

  4. Under Permission scopes, select only the scopes the token needs. At least one is required.

  5. Select Create, then copy the token. It is shown only once: Core Hub stores only a hash of it.

The Query Forge connection wizard creates tokens too: it gives them the gluesync.jdbc_gateway scope, and can limit them to the agents you pick.

Through the REST API, POST /api-tokens takes a name, an optional expiresInDays, the permissionScopes list, and an optional scopes list of { "pipelineId", "agentId" } pairs. A request without a permission scope, or with an unknown one, is refused with HTTP 400.

Permission scopes

Scope Label in the Control Plane What the token may do

gluesync.api

Full API

The whole REST API, including changes, with your role’s permissions.

gluesync.api_read

API read

REST GET requests that change nothing. The few GET requests with side effects count as changes and are refused: adding an agent (GET /pipelines/{pipelineId}/agents/add), completing a remote MCP sign-in (the OAuth callback), and refreshing the AI price list (/ai-studio/providers/pricing?refresh=true). Queries it runs are read-only.

gluesync.mcp

MCP server

The MCP server with every tool, including the ones that change pipelines, settings, and data. It is not read-only. The token cannot call the REST API directly.

gluesync.mcp_read

MCP server (read-only)

The MCP server with the read-only tools only. A tool that changes something answers with an error naming the scope, queries run read-only, and company tools are not offered. The token cannot call the REST API directly.

gluesync.jdbc_gateway

JDBC gateway

The Query Forge JDBC gateway only: list agents, browse schemas, run queries, and ask gluesync.ai. Always read-only.

A token may hold several scopes; it then has the access of each. A request a token’s scopes do not allow is refused with HTTP 403 and a message that names the token’s scopes and the scope the request needs.

Tokens without permission scopes

A token stored without permission scopes, created before they were required, keeps the access it had: everything your role allows. The token list shows it as Full access (legacy), and a notice titled Tokens with full access appears above the list. Replace each such token with a new one that has only the scopes it needs, then revoke the old one.

From 2.3.0.1, a token that already carried permission scopes, such as one created by the Query Forge wizard with gluesync.jdbc_gateway, is held to them.

Read-only scopes

gluesync.api_read, gluesync.mcp_read, and gluesync.jdbc_gateway are read-only scopes. A query sent with one of them runs in Query Studio’s read-only mode, whatever the request asks: a query request with readOnly: false is refused with HTTP 403.

What every token can and cannot do

  • A token can identify itself: GET /authentication/me and GET /api-tokens/current-scope (its permission and agent scopes) work with any scope.

  • No token can create, revoke, or delete tokens, whatever its scopes. Manage tokens from a Control Plane session, so that a leaked narrow token cannot mint itself a broad one.

  • A token can cancel only queries that its own user started, on agents in its scope. Any other query is reported as not found.

Agent scopes

A token with agent scopes reaches only the (pipeline, agent) pairs it lists. Without agent scopes, it reaches every agent your role can see. Agent scopes apply to every request, whatever the permission scopes:

  • A request about one agent needs that exact pair.

  • A request about a whole pipeline (starting or stopping it, changing it, its entities) needs every agent of that pipeline in the token’s scope. Reading a pipeline (GET /pipelines, GET /pipelines/{pipelineId}, GET /pipelines/{pipelineId}/agents) works with some of its agents, and hides the others.

  • Lists, saved queries, query history, and gluesync.ai check the agents themselves and show or accept only those in scope.

  • Searching the Gluesync documentation and support knowledge (GET /documentation/search, GET /support-knowledge/search) works, because it reads nothing of any pipeline or agent. The token still needs a permission scope that allows it.

  • Every other request that is not tied to a pipeline or agent is refused, for example Visualize, data comparison, configuration bundles, saving a query from history, and AI conversations.

  • An MCP session opened with an agent-limited token offers no company tools.

MCP sessions

An MCP session belongs to the token and the user that opened it. A request that names an existing session with a different token or user is answered with HTTP 404, so a read-only token cannot borrow a session opened with a broader one. This applies to both transports, Server-Sent Events and streamable HTTP.

classify_table and classify_schema store the PII verdicts they find, so they count as changes: a gluesync.mcp_read token cannot call them, and AI SQL (gluesync.ai through Query Forge) offers only read tools. When Core Hub cannot read a session’s token scopes, the session gets only the read-only tools and no company tools.

See Core Hub MCP server.

JDBC gateway

Query Forge accepts a token with gluesync.jdbc_gateway, or a legacy token without permission scopes. Any other token is refused when it connects, with SQLState 28000 and a message that names the missing scope. Agent scopes apply to discovery, queries, paging, and gluesync.ai: a request for an agent outside the scope fails with SQLState 42501. See Query Forge.

gluesync.ai answers with the read-only tools of the agents in the token’s scope: their database read tools, the execution plan, and table DDL. Core Hub runs these tools for the question it was asked. The token cannot call them through the REST API directly, and they run read-only.

EXPLAIN

Query Studio’s execution plan (GET /query-studio/pipelines/{pipelineId}/agents/{agentId}/explain) accepts a single read-only query and is available to gluesync.api_read tokens. It is not one of the JDBC gateway’s requests, so gluesync.jdbc_gateway tokens cannot call it directly. gluesync.ai can still use it to answer such a token’s question. See Reviewing execution plans.

Recommendations

  • Give each client its own token, with only the scopes it needs: gluesync.jdbc_gateway for a BI tool, gluesync.mcp_read for an AI assistant that only reads, gluesync.api_read for a monitoring script.

  • Limit tokens to the agents they need.

  • Set an expiry, and revoke tokens you no longer use.

  • Replace Full access (legacy) tokens.

  • Read-only scopes stop writes that Core Hub can recognise. Also give each agent’s database user only the privileges it needs: see Least privilege for the agent’s database user.

Related pages