API

API authentication

By the MapsData team · Last updated October 16, 2026

Every request carries an API key in an Authorization header. There is no OAuth flow, no session, and no signing to implement. A key identifies your workspace, and everything it does counts against your workspace's allowance.

Authorization: Bearer mdk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Creating a key

Keys are made in Settings, under API keys. Give the key a name that says where it runs, because that name is all you will have to go on when you are deciding which one to revoke a year from now.

The key is shown exactly once. We store a SHA-256 hash of it, never the key itself, so there is no way for us to show it again, and no support request can recover it. Copy it when it is created. If you lose it, revoke it and make another.

Only workspace admins can create or revoke keys, and only on a paid plan: Starter, Pro, Scale or custom. On other plans the section is visible but the create form is replaced with an upgrade link.

Key format

Keys look like mdk_live_ followed by 43 random characters. The prefix is fixed and greppable on purpose: it makes keys easy to spot in a codebase, in a log, or in an automated secret scan. Settings shows only the first few characters of each key, which is enough to identify one in a support conversation without revealing it.

Scopes

Scope	Allows
`scrape:read`	Reading jobs, usage, categories, regions, clients, and download links
`scrape:write`	Submitting and cancelling scrapes

You choose the scope when you create the key in Settings. The default is both. A read-only key is the right choice for anything that should look at your scrapes without being able to spend your allowance, an AI assistant most of all. A request that needs a scope the key does not have returns 403 insufficient_scope, naming the missing scope.

Scope is fixed at creation. To change it, create a new key and revoke the old one.

Keeping a key safe

Treat it like a password. A key carries your workspace's entire scraping quota. Anyone holding it can spend it.
Never put one in browser code. There is no origin restriction and no CORS allowance that would make that safe. Call the API from your server.
Keep it out of version control. Read it from an environment variable or a secret store.
Use one key per integration. Then revoking a leaked key breaks one thing rather than everything.

Revoking

Revoke from Settings. It takes effect on the very next request, with no deploy and no delay, and the key's usage history is kept so you can still see when it was last used.

Keys created by a workspace member are revoked automatically when that member is removed. Removing someone is a decision to end their access, and a key they made would otherwise outlive it.

Spotting a misconfigured integration

Settings shows a last-used time for every key, and never used in place of it when a key has never authenticated. That is almost always the fastest way to tell that a deployment picked up the wrong environment variable, or that an integration you thought was live never shipped.

What the errors mean

Code	Status	Meaning
`invalid_api_key`	401	No key, a malformed one, or one we do not recognise
`key_revoked`	401	The key was revoked
`key_expired`	401	The key passed its expiry
`insufficient_scope`	403	Valid key, but it lacks the scope this call needs
`api_not_available_on_plan`	403	The workspace is not on a plan that includes API access

Every 401 also carries a WWW-Authenticate header pointing at our resource metadata document, which is what lets standards-aware clients discover how to authenticate.

Build on MapsData

The REST API and the MCP server are included on every paid plan, with the same allowance as the app. Subscribe or start a trial, then create a key in Settings.

See plans and API access