Getting started

Authentication

How API keys work, what they can do, and how to rotate or revoke them.

API keys

Every request carries a key as a bearer token. Keys start with vidrys_sk_, are created on the Developers page by an admin of the workspace, and are shown exactly once — we store only a hash, so a lost key is replaced, never recovered.

curl --request GET \
  --url "https://api.vidrys.com/v1/plan" \
  --header "Authorization: Bearer $VIDRYS_API_KEY"

A missing, malformed, unknown, revoked or expired key answers 401 unauthorized with a WWW-Authenticate: Bearer header.

A key acts as the person who made it

A key is not a workspace-wide identity. It carries the membership of the admin who created it, and it can never do more than that person can do in the dashboard. So it stops working the moment:

that member leaves the workspace or is deactivated,
the key is revoked, or
the plan drops below Grow, or the workspace stops being approved.

Their role caps it too. Move the creator to viewer — the read-only login — and a read-and-write key quietly becomes read-only on the very next request, answering 403 write_not_allowed. A credential can never do through the API what the person behind it can’t do in the dashboard.

Every request re-reads the key, the member and the plan from the database and deliberately skips the 30-second cache the rest of the platform uses. Revoking a key or removing a member bites on the next call, not half a minute later.

Because a key is tied to a person, create it from an account that will outlive the integration — a key made by a departing colleague stops with them.

Read and read-and-write

Access	Can do	Needs
`read`	Every GET in this reference.	Grow, Scale or Custom
`write`	Reads, plus adding and editing prompts, moving content opportunities and queue tasks, and generating drafts — which spends credits.	Scale or Custom, and a member who can write

A read key that attempts a write answers 403 write_not_allowed. Ask for a read-and-write key only where you need one: most integrations — digests, dashboards, alerting — are reads.

Rotating and revoking

Plans allow 1 active key on Grow, 2 on Scale and 10 on Custom. With two slots you can rotate without downtime: create the new key, deploy it, then revoke the old one. With one slot, revoke first and create the replacement immediately — anything using the old key fails with 401 in between.

Creating and revoking a key are both recorded in the workspace’s activity log.

Treat a key like a password

It reads everything your dashboard shows for the whole workspace. Keep it on a server or in a secrets manager, never in a browser, a mobile app or a public repository. If one leaks, revoke it first and investigate afterwards.

What a key is not

It is not a dashboard session. Session tokens don’t authenticate /v1, and API keys don’t authenticate the dashboard’s own internal API — which returns fields this surface withholds.
It is not the only credential the MCP server takes. /mcp accepts keys and, where your workspace has it switched on, a sign-in connection instead. See MCP authentication.