Authentication

Every programmatic request authenticates with a bearer token that resolves to a vvd account. There is one resolver behind all of it; the token can come from three places.

API keys

Create a key in Settings → API keys. Use it as a bearer token:

Authorization: Bearer vvd_live_…

Keys act as your account, don't expire, and are killed by revoking them. Each key shows its last-used time so you can spot stale ones. This is the right choice for scripts, servers, CI, and headless servers.

The connect flow ("log in with vvd")

Tools that can open a browser don't need you to paste a key. They start a device flow and send you to vvd.world/connect, where you sign in and approve. A key is minted behind the scenes and appears in Settings → API keys like any other. This is how vvd login and MCP setup work.

OAuth 2.1 (connectors)

MCP connectors that can't send a custom header authenticate with OAuth 2.1 — a standard authorization-code flow (PKCE) against:

• Discovery: /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server
• Authorize: /api/oauth/authorize
• Token: /api/oauth/token
• Dynamic registration: /api/oauth/register

The consent screen is the same vvd.world/connect page. Access tokens are short-lived and refresh automatically — you approve once and stay connected until you revoke it.

Permissions

However you authenticate, the credential acts as you. World membership and role are the only authority: you can read a world if you're a member, and write it if you're an editor. There are no separate API scopes to manage in v1 — your access to a world through the API is exactly your access to it in the app.

Your plan sets what a credential may do with world content: building tools and apps is free on every plan, while reading or editing a world's content from outside the app needs the world to be on Pro or Studio.