Authorization: Bearer <token>, with your personal access token.X-Tenant: <workspace-slug>, with the Workspace the request acts in. The slug is the name in your Workspace’s address, such asacme-corp.
$PARABLE_API_URL is https://api.parable.work, the Workspace API address.
Every operation path starts with /api/. This address serves /api and
paths under /api/. Other paths, including /login and /healthz, return
404. Sign in through your Workspace app.
Send X-Tenant on every request. On this address, a Parable token that names
no Workspace acts in the first Workspace that GET /api/auth/me lists for its
owner. The request gets no error, so a script that leaves out the header can
change the wrong Workspace.
A few operations need neither header, such as the Provider catalog
operations. The API reference lists them.
Personal access tokens
A personal access token starts withpat_. There are three kinds.
Use a Parable token to call an operation that changes something, such as
inviting a person or stopping a Tap. An MCP token is enough for scripts that
only read, and for MCP hosts such as Claude Code. A SQL token is for the
Parable Data Engine. An MCP host can also sign in with OAuth and
hold no token at all. See Connect an MCP host.
To create an MCP token or a SQL token, open Protection → Access Tokens in
the Workspace app and select Create token. Choose MCP or SQL in
Use it for, then name the token and choose when it expires. MCP is
available only while the Workspace allows external agents. A request that a
token makes cannot create a token (code
WA-PAT-004).
Every token:
- Acts as one person. Each request runs with the roles that the owner holds in the named Workspace when the request is made. When the owner loses a role, the next request that needs that role fails.
- Has no session. A request made with a token cannot create another token.
- Is shown once. Parable stores only a SHA-256 hash of the token. You cannot recover a lost token. Get a new one instead.
- Can be revoked. Revoking a token does not sign its owner out of the app.
- Work in one Workspace. The request must name the Workspace where the token was created.
- Expire. A token expires after 90 days, unless its creator chooses 1 to 365 days.
- Are visible to administrators. People who manage the Workspace’s members see and revoke every member’s token.
- Can be turned off. People who manage sign-in for the Workspace can turn personal access tokens off in Protection → Access Tokens. The Workspace then refuses every MCP token and SQL token, and nobody can create a new one. SQL over Flight also refuses Parable tokens. The Workspace API still accepts a Parable token.
WA-PAT-006, and
nobody can create one. Turning it off revokes nothing. SQL tokens and Parable
tokens do not depend on it.
What an MCP token reaches
An MCP token reads. It holds the scopedata:read, and works on each
operation that Parable opens to agents with that scope. A token whose creator
turned on Change and publish Parables, and send Pings also holds
parables:write. A token whose creator turned on Start and change
Problems also holds problems:write, one whose creator turned on Use
Ponder also holds ponder, and one whose creator turned on Change Provider
connections and data streams also holds connections:write. Only the Parable
MCP server uses these scopes: through it, the agent can change Parables, publish
them and send Pings (tools), start and change
Problems (tools), use Ponder
(tools), and change data streams and uploaded files
(tools). Sent to the Workspace API
itself, every MCP token holds data:read alone. Each operation page
in the API reference says whether an MCP token can
call it. The open operations include:
- Your membership and the Workspace’s people and roles:
GET /api/users/me,GET /api/users/users,GET /api/users/user, andGET /api/roles/roles. - Provider connections, Taps, and connector requests: the reads under
/api/vendors/that name your connections,/api/tenant-connector-taps/,/api/connectors/, and/api/connector-requests/. - The data catalog:
GET /api/v2/catalog, its table statistics and Provider notes, and the table quality reads under/api/catalog/. - SQL over HTTP:
POST /api/provider-pool/search,POST /api/provider-pool/describe-table,POST /api/provider-pool/plan,POST /api/provider-pool/query, andGET /api/provider-pool/guidance. See SQL over HTTP. - Published Plots and Plot data:
GET /api/parable/plots/published,GET /api/parable/plots/{plotId}/published, and the Plot data reads under/api/parable/authoring/primaries/{rootRefId}/plots/data. - Uploaded files: the reads under
/api/artifacts/. - Powers, the model policy, and your own tokens:
GET /api/agent-skills,GET /api/model-policy, andGET /api/api-tokens/mine.
- An operation that changes something, or a read that Parable does not open
to agents, such as
GET /api/provider-policies,GET /api/ingest-tokens,GET /api/devices, andGET /api/api-tokens/workspace. The request fails with403and codeWA-PAT-005. - SQL over Flight. Use a SQL token.
- A route that streams its answer, such as the Arrow stream of
POST /api/parables/immediate-plot-query. The request fails with403.
GET /api/v2/catalog lists only the tables in the Pools
that its owner can query with SQL. When the owner can query no Pool, the
catalog is empty.
Parable keeps an audit record of each request that an MCP token makes,
allowed or refused. The record names the method, the route, the status, and
the client. The client is the value of the X-Parable-Client header, or the
User-Agent header when X-Parable-Client is absent. Send
X-Parable-Client: <your integration's name> so that the record names your
integration.
Manage tokens
These operations list and revoke the MCP tokens and SQL tokens of a Workspace, and turn tokens on or off. They never return a token’s value. Parable tokens are not in these lists. To revoke a Parable token, ask your Parable representative. Create a token in the app.
Each listed token has its
id, name, prefix (the first 12 characters),
audience (flight_sql or mcp), createdAt, lastUsedAt, expiresAt,
and revokedAt. Parable updates lastUsedAt at most once a minute, so it
can be up to two minutes behind the token’s newest use.
A revoke takes effect at once on the Workspace API. SQL over Flight refuses
the token within 30 seconds. Revoking a revoked token succeeds. A token that
is not yours, or not in the Workspace, is not found (code WA-PAT-001).
Send a revoke with a Parable token. An MCP token can list its owner’s tokens
but cannot revoke one, because a revoke changes something. This script
revokes every token of a person who left:
Sessions and tokens
Signing in to the Parable app creates a short-lived browser session. Use a token for scripts, SDKs, and BI tools. Use the app for interactive work.Keep tokens safe
- Keep tokens in a secret manager, not in code or configuration files.
- Use one token for each integration, so that you can revoke each one alone.
- Revoke a token when a teammate leaves or an integration retires.
- If a token leaks, revoke it immediately. The Workspace API refuses a revoked token on its next request.