Skip to main content
Every Workspace API request sends two headers:
  • 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 as acme-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 with pat_. 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.
A Parable token expires only when Parable sets an expiry as it creates the token. MCP tokens and SQL tokens also:
  • 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.
MCP tokens also need Allow external agents, on the same page. It is off in every Workspace until a person who manages sign-in turns it on. While it is off, the Workspace refuses every MCP token with code 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 scope data: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, and GET /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, and GET /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, and GET /api/api-tokens/mine.
An MCP token does not work on:
  • 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, and GET /api/api-tokens/workspace. The request fails with 403 and code WA-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 with 403.
With an MCP token, 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.

Errors