Documentation → Reference

API keys, scopes and projects

mapbench's management API takes two kinds of credential: an API key you mint and paste, and an OAuth connector an agent obtains by sending you through an approval screen. Both act as you, in one project, with the scopes they were granted — never more.

The two credential kinds

	API key	OAuth connector
looks like	`tp_…` in an `Authorization: Bearer` header	a connection you approve in the agent's UI
for	scripts, Claude Code, anything you run yourself	hosted agents that sign in on your behalf
you see the grant	when you mint it	on an approval screen, every time
can publish share links	no — not in any preset	yes, if you approved it
revoke from	Account → API keys	Account → connectors

Both are minted and revoked on your Account page. Both are shown once — mapbench keeps no copy it can show you again. Lose one and you revoke it and mint another.

Scopes

A scope is a permission. Scopes only ever narrow what you could already do: a credential can never reach further than the person who created it, and it loses access the moment they do.

Scope	Grants
`read`	See your datasets, models and maps, and run read-only SQL over them
`datasets:write`	Add and change datasets, their styling and folders
`models:write`	Create and change SQL models
`maps:write`	Create and change maps and their layers
`jobs:write`	Cancel queued processing jobs
`delete`	Delete datasets, models and maps
`share:write`	Create and revoke public share links to maps and datasets
`projects:write`	Create and rename projects, and move this connection between the projects you can write

How they are enforced

Reading needs read, everywhere.
Writing needs the write scope for what you are writing — changing a map needs maps:write whatever else you hold.
Deleting needs delete as well as the write scope. Two exceptions, both deliberate: removing a layer from a map (composition, not destruction — the dataset is untouched) and revoking a share link (which destroys a public URL rather than data, and must never be harder than minting one).
Anything unrecognised is refused. A new part of the API is not reachable by a credential until a rule says which scope governs it, so nothing becomes agent-writable by accident.
Reading share listings needs share:write, not just read — a listing returns live share tokens, and a token is a public URL in waiting.

Key presets

The mint form offers these. Anything outside them is a deliberate act by whoever operates your deployment, not a checkbox.

Preset	Scopes
Read only	`read`
Full agent	`read` `datasets:write` `models:write` `maps:write` `jobs:write`
Full agent + delete	`read` `datasets:write` `models:write` `maps:write` `jobs:write` `delete`

No key preset can publish a share link, and none can switch projects. Both are omitted on purpose. A key is a silent, long-lived credential, so turning revocable in-org access into an unauthenticated public URL stays a decision someone makes explicitly rather than a permission a key carries by default. If a script genuinely needs it, your operator can mint a key with that scope named.

What a connector is granted

An OAuth connector asks for these, and the approval screen names each one in plain language before you accept:

Scope
`read`
`datasets:write`
`models:write`
`maps:write`
`jobs:write`
`share:write`
`projects:write`

Note what is not there: delete. mapbench offers a connected agent no delete tool at all. An agent can archive a dataset or a map — which you can undo — and that is as far as it goes.

Sharing and project-switching are there, which is the difference from a key: the permission is named on a screen you read, and the whole grant is revocable from your account page in one click. A key has neither property.

A credential acts in exactly one project

Projects are the boundary inside your organisation: datasets, models and maps all belong to one. A credential is pinned to a single project and acts only there — it never follows whatever project you happen to have open in the app.

You choose the project when you mint a key. A connector starts in your default project.
You can re-point a credential from your Account page at any time, without disconnecting and starting over.
A credential holding projects:write can move itself — but only to a project you may write. It can never reach further than you can.
Content never crosses a project boundary via a credential. Moving a dataset or a map between projects stays a manual, audited action by a person. Standing somewhere else is navigation; dragging data across the boundary is what the boundary is for.
If you lose access to the project a credential is pinned to, it fails closed — 403 no_project_access — rather than quietly falling back to another project. It is not auto-revoked, so past activity stays attributable to it.

Using a key

Send it as a bearer token:

curl -H "Authorization: Bearer tp_…" \
  https://mapbench.app/tilesets

Most people never write these requests by hand — the same credential drives the MCP server at https://mapbench.app/mcp, which is what Claude and other agents speak. See Connect Claude to mapbench.

Keys are refused on the control plane — your account page, organisation settings, the admin — whatever scopes they hold. A credential manages data, never credentials or membership.

Rate limits

120 requests per minute per key.
20 processing jobs per hour per key, on top of your organisation's queue cap.

Both answer 429 with a Retry-After header. Formats, limits and quotas has every other ceiling.

Everything a credential does is attributed

Work done through a key or a connector is recorded as that credential's, not as yours-in-a-browser: the activity history for a dataset or map shows which credential made each change, when, and whether a person or an agent did it. That is the reason to issue a credential rather than share a login — a shared password makes every change look like the same person.

Revoking a credential ends its access immediately and keeps its history. The record of what it already did is the point.