Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Connect Your App with OAuth

Use OAuth when your product acts for many Vev users, each with their own account. Each user clicks Connect Vev in your app, approves access on a Vev consent screen, and your server receives a token. With that token your server calls the MCP tools as that user and sees only their projects.

If your integration only ever acts as you, skip OAuth and create an API key instead.

Kopla's Build in Vev connection uses this flow.

How it works

Vev runs OAuth 2.1 with the authorization code grant and PKCE (S256). Clients are public: there is no client secret, and the PKCE verifier is what proves your server asked for the code.

RegistrationPOST https://api.vev.design/v2/oauth/register
Consent screenhttps://editor.vev.design/oauth/authorize
TokenPOST https://api.vev.design/v2/oauth/token
RevocationGET https://api.vev.design/v2/api-key/revoke
Discoveryhttps://api.vev.design/.well-known/oauth-authorization-server
Scopeslist:project, create:project

The access token is a Vev API key. It has no expiry and there is no refresh token. It stays valid until the user revokes it in their user profile, where it is listed as MCP: [your client name], or until you revoke it.

1. Register your app

Register once for each redirect URI you use (production, staging, local). Registration is open and needs no credentials:

curl https://api.vev.design/v2/oauth/register \
  --header "Content-Type: application/json" \
  --data '{
    "client_name": "Acme Sites",
    "client_uri": "https://acme.example",
    "redirect_uris": ["https://app.acme.example/api/vev/callback"],
    "token_endpoint_auth_method": "none"
  }'
{
  "client_id": "q8J3xv1n2RkqC6m0YpZ9w4bT7hLs5dEa_fGuIoNe2Wc",
  "client_id_issued_at": 1779270400,
  "client_name": "Acme Sites",
  "redirect_uris": ["https://app.acme.example/api/vev/callback"],
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "scope": "list:project create:project"
}

Store the client_id in your configuration. It isn't secret, because it appears in the consent URL.

  • redirect_uris: 1–10 URIs, each at most 2000 characters, with no #fragment. They must be https, except that http is allowed on localhost, 127.0.0.1 and [::1] for development. The URI in each request must match a registered one exactly.
  • client_name: shown on the consent screen as "Connect [name] to Vev", and in the name of the user's key. Defaults to MCP client.
  • A client cannot be edited or deleted. If you need a different redirect URI, register a new client.

2. Send the user to the consent screen

For each connect, your server makes a random state and a PKCE verifier, and remembers both for the browser that asked, for example in a short-lived, HttpOnly cookie. It then sends the browser to the consent screen, as a redirect or in a popup:

https://editor.vev.design/oauth/authorize
  ?response_type=code
  &client_id=q8J3xv1n2RkqC6m0YpZ9w4bT7hLs5dEa_fGuIoNe2Wc
  &redirect_uri=https%3A%2F%2Fapp.acme.example%2Fapi%2Fvev%2Fcallback
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &scope=list%3Aproject%20create%3Aproject
  &state=af0ifjsldkj
Parameter
response_typecode
client_idFrom registration
redirect_uriOne of the registered URIs, exactly
code_challengeBASE64URL(SHA256(verifier)), 43 characters
code_challenge_methodS256, the only method supported
scopeSpace-separated. Ask for list:project to read, and add create:project to create content or import sections. Omitting it grants both.
stateYour random value. It comes back unchanged.

The user must already be signed in to Vev in that browser. If they aren't, the consent screen asks them to sign in and reload the page. Mention this next to your Connect button.

TypeScript (Node)
import { createHash, randomBytes } from 'node:crypto';
 
export function startVevConnect() {
  const verifier = randomBytes(32).toString('base64url'); // 43 characters
  const state = randomBytes(16).toString('base64url');
  const challenge = createHash('sha256').update(verifier).digest('base64url');
  const url = new URL('https://editor.vev.design/oauth/authorize');
  url.search = new URLSearchParams({
    response_type: 'code',
    client_id: process.env.VEV_CLIENT_ID!,
    redirect_uri: process.env.VEV_REDIRECT_URI!,
    code_challenge: challenge,
    code_challenge_method: 'S256',
    scope: 'list:project create:project',
    state,
  }).toString();
  // Keep verifier + state for THIS browser (e.g. an HttpOnly cookie) and redirect to url.
  return { url: url.href, verifier, state };
}

3. Handle the callback

When the user allows access, Vev redirects the browser to your URI:

https://app.acme.example/api/vev/callback?code=Zb7Kq...&state=af0ifjsldkj

When they deny it, the redirect carries an error instead:

https://app.acme.example/api/vev/callback?error=access_denied&state=af0ifjsldkj

Check that state matches the one you kept for this browser before doing anything else. Then exchange the code straight away. A code is valid for 10 minutes and can be used once: any attempt, even one that fails, uses it up.

curl
curl https://api.vev.design/v2/oauth/token \
  --header "Content-Type: application/json" \
  --data '{
    "grant_type": "authorization_code",
    "code": "Zb7Kq...",
    "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
    "client_id": "q8J3xv1n2RkqC6m0YpZ9w4bT7hLs5dEa_fGuIoNe2Wc",
    "redirect_uri": "https://app.acme.example/api/vev/callback"
  }'
{ "access_token": "eyJhbGciOi...", "token_type": "bearer", "scope": "list:project create:project" }

The token endpoint also accepts the body form-encoded (application/x-www-form-urlencoded). A failed exchange returns 400 with a standard OAuth error:

{ "error": "invalid_grant", "error_description": "Authorization code is invalid, expired, or already used" }
errorCause
invalid_requestcode or code_verifier missing
unsupported_grant_typeNot authorization_code
invalid_grantUnknown, expired or used code, wrong client_id or redirect_uri, or a verifier that doesn't match the challenge

4. Call tools as the user

Send the token as a bearer token. x-vev-key works too, since the token is an API key:

curl https://api.vev.design/v2/mcp \
  --header "Authorization: Bearer eyJhbGciOi..." \
  --header "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"find_projects","arguments":{"search":"landing"}}}'

You can check a token, and see the user and scopes it acts as, with the introspection endpoint:

curl https://api.vev.design/v2/api-key/introspection --header "x-vev-key: eyJhbGciOi..."

When a call returns 401, the user has revoked the key. Mark them as disconnected and offer to connect again.

5. Disconnect

When a user disconnects, revoke their token so it disappears from their Vev profile. The key must be sent in x-vev-key, not as a bearer token:

curl https://api.vev.design/v2/api-key/revoke --header "x-vev-key: eyJhbGciOi..."

A successful revoke returns 200 with { "success": true, "data": null }. After that, the token gets 401 everywhere.

Every consent creates a new key. When a user connects again, store the new token and revoke the old one, or their profile fills up with keys.

Security checklist

  • Keep tokens on your server, encrypted at rest. Never send them to the browser.
  • Bind state to the browser that started the connect, for example with an HttpOnly, SameSite=Lax cookie. Without that, an attacker can hand someone a consent link and have that person's Vev access saved under the attacker's account.
  • Redirect only to paths on your own site after the callback.
  • Keep each connection personal. The token acts as one Vev user, so sharing it with teammates gives them that user's projects.
  • Ask for list:project alone if you only read.