Authentication

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.

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.

Only workspace admins can create or revoke keys, and only on the Scale plan or a custom plan. 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

Keys made in Settings carry both. A request that needs a scope the key does not have returns 403 insufficient_scope, naming the missing scope.

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

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.