> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spitzli.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace API and plugin MCP tools

> Call installed actions with workspace tokens or the existing OAuth resource.

Core exposes a workspace API for server automation and an OAuth-protected plugin surface for registered integrations. Mail keys, workspace API tokens and OAuth access tokens are separate credentials.

## Workspace API

Workspace owners and administrators can create a workspace API token in Console under **API tokens**, with read-only or read-and-change access and a lifetime from 30 days to one year. The `wdk_…` token is shown once; Core retains its hash. It acts within that workspace with the current authority of the member who created it. The token is not a platform-operator credential. Revocation and current membership still apply.

| Method | Path | Purpose |
| - | - | - |
| GET | `/v1/api/projects` | List accessible workspace projects |
| GET | `/v1/api/projects/{projectID}/plugins` | Discover installed plugins and actions |
| POST | `/v1/api/projects/{projectID}/actions` | Invoke an installed action |
| GET | `/v1/api/usage` | Read workspace usage |

Send `Authorization: Bearer <workspace-token>` from your server. These endpoints reject browser cookies and Origin headers. Use the API origin configured for your installation.

An action body uses the discovered plugin and action names:

```json theme={null}
{
  "plugin": "echo-demo",
  "action": "notes.create",
  "input": { "name": "My first note" },
  "idempotencyKey": "create-note-42"
}
```

This example requires an installed and granted Echo release, a read-and-change workspace token, and an enabled `note` offering with the `create-notes` feature and available capacity. The action must appear in the project's permitted discovery result. Echo's `demo.echo` action is operator-only and cannot be invoked with a customer workspace token. Preserve the same explicit idempotency key when retrying unchanged intent, especially for writes.

## Declared OAuth routes

A manifest can reference actions in `api` and `mcp` entries. Exact local API paths appear under:

```text theme={null}
/v1/plugins/{pluginID}/projects/{projectID}/api/{local-path}
```

This existing surface uses the [registered OAuth resource](https://docs.spitzli.cloud/developers/authentication.md) and registry scope family. GET routes reference read actions and accept one optional `input` JSON query parameter. Other methods accept JSON bodies; write actions require `Idempotency-Key`. Workspace API tokens use the workspace routes above, not this OAuth adapter.

MCP tools use names such as `plugin__managed_analytics__configuration`. Arguments include `projectID` and the declared action input. Write tools require an idempotency key. Discovery and invocation check current scopes, project permissions, plugin state and capabilities; a tool name is not an access grant.

## Runtime and host services

Core revalidates the actor, configuration, project grant and exact runtime generation. Native plugins use private gRPC with enrolled Unix or mutual-TLS peers. Existing Elysia protocol-v1 extensions retain separately enrolled private HTTPS handlers. Tokens and runtime credentials stay outside UI frames.

Named HTTP bindings are operator-owned and project-scoped. Core controls origin, pinned addresses, method, paths, query keys and credentials. Redirects are refused, exchanges have a ten-second deadline, and bodies are bounded to 1 MiB. The host checks live authority before and after a provider call. A revoked permission cannot undo an effect already accepted by a remote provider.

Source: workspace API (`crates/control-plane/src/api.rs`), OAuth plugin exposure (`crates/control-plane/src/plugin_exposure.rs`) and host service boundary (`crates/plugin-host`). See [release status](https://docs.spitzli.cloud/developers/plugin-releases.md) before treating a published image as available to customers.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.