Workspace tokens

Sites and AI tools do not sign in as people. They read a workspace through a workspace token: a secret string that belongs to one workspace and can read it. This page is for admins, who create tokens, and for developers, who use them. You create a token, put it where the tool can find it, and revoke it when it is no longer needed.

What a token can do

• A token belongs to one workspace. It cannot see any other.
• By default it can only read. It never changes anything in the workspace.
• It has an access level, chosen when it is created. You can edit it later.
• It can have extra permissions, all off unless you tick them: Can report AI usage, Can import Markdown and, together with importing, Can publish.
• It works for the read API at /api/lake/<short name>/... and for the MCP server at /mcp. It does not work for the editor’s own API.

Tokens look like mdl_<prefix>_<secret>. The prefix is 8 letters or digits and is shown in the list so that you can tell tokens apart. The CMS stores only a hash of the token. The secret is shown once, when you create the token, and cannot be read again.

Access levels

Choose Published content unless you run a preview server. Asking a Published content token for a draft is refused.

Create a token

You need to be an admin.

1. Open the workspace and choose Workspace settings in the header.
2. Scroll to AI and API access. The page lists the existing tokens, or says “No tokens yet. Create one to connect a site build or an AI tool.”
3. Choose New token. The dialog New token opens.
4. Fill in Name. Say what the token is for, for example “Production build” or “Anna’s laptop”. Up to 100 characters.
5. Under Access, choose Published content or Published content and drafts.
6. Under Expires after, choose 30 days, 90 days, 365 days or No expiry. The default is 90 days. The setting Tokens:DefaultExpiryDays changes the default. If it is set to a number other than 30, 90 or 365, that number is added to the list and marked “(default)”. Set to 0, it makes No expiry the default.
7. Tick the permissions you need:
   • Can report AI usage: lets the builder report the AI tokens it used for this workspace. The lake stays read-only. Suggested for developer tokens.
   • Can import Markdown: lets the token upload a zip of Markdown files and create or update draft documents and media, as you. Nothing is deleted, and nothing is published unless you also tick Can publish. Only for tools you trust.
   • Can publish: appears once Can import Markdown is ticked. Lets the token publish what it imports, without anyone reading it first. Each document becomes a commit in the workspace’s Git repository.
8. Choose Create token. The dialog Copy your token opens.
9. Choose Copy token, and store the secret somewhere safe, such as a password manager or the site’s .env file.
10. Choose I have copied it.

The dialog cannot be closed in any other way. This is on purpose, because the secret exists in readable form only now. If you lose it, revoke the token and make a new one.

The new token appears in the list with its name, access level, badges (Reports usage, Can import Markdown, Can publish), the first part of the token (mdl_<prefix>_…), who created it and when, when it was last used (“Never used” at first) and when it expires.

Read the list

Each row shows one of these states:

The “last used” time is updated at most once a minute, so it can lag slightly.

Edit a token

Editing changes what a token may do and keeps the token itself, so whatever uses it goes on working and there is nothing to replace.

1. In AI and API access, choose Edit on the token’s row.
2. Change the Name, the Access, the Expiry or the permissions.
3. Choose Save changes.

The change applies from the token’s next request. No secret is shown, because it has not changed.

Under Expiry, Keep as it is leaves the date alone. A number of days counts from today, not from when the token was created. No expiry removes the date.

• An expired token can be edited. Give it a new expiry and the same token works again. This is the way to renew a token without touching the site or tool that uses it.
• A revoked token cannot be edited. Revoking is final, so its row has no Edit.
• Imports still run as the admin who created the token, also when another admin ticks Can import Markdown. The dialog names that person. If they are no longer an active admin, editing does not help. Create a new token.

To replace a secret that may have leaked, editing is not enough. Revoke the token and create a new one.

Revoke a token

Revoke a token when someone leaves, when a laptop is lost, or when the secret was pasted somewhere it should not be.

1. In AI and API access, choose Revoke on the token’s row.
2. Read Revoke token? and choose Revoke token.

The token stops working at once. Anything that uses it, such as a site build or an AI tool, loses access until you give it a new token. This cannot be undone. Revoking a token that is already revoked does nothing.

An expired, revoked, unknown or malformed token gets a plain 401 with no hint about the reason.

The extra permissions

Can report AI usage

The builder uses Claude. With this permission, the builder reports how many tokens each call used, and the CMS adds them to the workspace’s AI usage ledger next to the editor’s own suggestions. Admins see the total under AI usage in the account menu. Without the permission the builder works the same and nothing is reported. See Cost and the usage ledger.

The report goes to POST /api/lake/<short name>/usage. Without the permission the answer is 403 with the reason usage-not-allowed.

Can import Markdown

With this permission the token can send a zip of Markdown files to POST /api/lake/<short name>/import. The import arrives as drafts, exactly as if the admin who created the token had imported it in the editor. Nothing is deleted. The token acts as the admin who created it. If that person is no longer an active admin, the import is refused with import-owner-gone. Without the permission, it is refused with import-not-allowed.

Use it for a CI job that mirrors a documentation repository into a workspace. This guide is published that way. Rotate the token like any other secret. See Importing content.

Can publish

A token with Can import Markdown only creates drafts, and someone publishes them from the CMS. With Can publish as well, it can add publish=true to the import, and what the import creates or updates is published without anyone reading it first. Without the permission, asking for that is refused with publish-not-allowed. Tokens created before this permission existed don’t have it.

Use a token

The Connect tools to this workspace box under the token list shows three guides with this workspace’s values filled in and a copy button on every line.

1. Claude Code with the mdlake builder

This is the normal route for developers. The steps are in Install the builder. In short:

1. Install the plugin once.

2. Create a token. For development choose Published content with Can report AI usage. For a draft preview server choose Published content and drafts.

3. Put two lines in the site’s .env file:

   MDLAKE_API_URL=https://cms.example.com/api/lake/acme
   MDLAKE_TOKEN=mdl_abcd1234_the-secret-you-copied

4. Restart Claude Code in the site folder. The lake tools appear.

To preview drafts on the real site, put a Published content and drafts token in the .env, then run the preview server and set the site’s Preview address in Workspace settings to http://localhost:4400:

npx mdlake preview --port 4400

npx mdlake preview --port 4400

See Preview drafts and Previews.

2. Other AI tools

Cursor, VS Code and other tools that speak MCP over HTTP can connect directly:

1. Add a remote MCP server with the URL https://cms.example.com/mcp.
2. Send the HTTP header Authorization: Bearer <token>. Use a Published content token.

For Claude Code without the builder:

claude mcp add --transport http mdlake https://cms.example.com/mcp --header "Authorization: Bearer <token>"

claude mcp add --transport http mdlake https://cms.example.com/mcp --header "Authorization: Bearer <token>"

The MCP server offers eight read-only tools: lake_info, lake_manifest, search_documents, get_document, document_shape, query_collection, list_assets and get_asset.

3. AI suggestions in the editor

This is not a token. It is the setting that switches on the Suggest buttons in the editor. It is described in Create a workspace.

The read API

Every route is a GET that answers JSON, with Authorization: Bearer <token>. The short name in the address must be the token’s own workspace. Any other answers 404.

curl -H "Authorization: Bearer $MDLAKE_TOKEN" https://cms.example.com/api/lake/acme/manifest

curl.exe -H "Authorization: Bearer $env:MDLAKE_TOKEN" https://cms.example.com/api/lake/acme/manifest

Lists are paged with limit (default 50, at most 200) and offset. Each token may make 300 requests a minute for the read API and MCP together. Over that, the answer is 429 with Retry-After. The setting Tokens:RequestsPerMinute changes the limit. Other settings are Tokens:SignedUrlMinutes (15), which is how long a signed link to an unpublished file works, and Tokens:BuilderMarketplace, which is the address the setup guide shows for /plugin marketplace add.

If something goes wrong

What’s next

• Set up Claude Code with the plugin: Install the builder.
• See how a site reads the lake: How sites work.