Authentication
OAuth 2.1 with PKCE and dynamic client registration, organization-scoped tokens, and revocation.
The Vidext Operator MCP server authenticates with OAuth 2.1 — authorization code with PKCE, plus dynamic client registration. There are no long-lived API keys to provision or leak: clients register themselves, users authorize in the browser, and tokens are scoped and revocable.
The flow (what your client does for you)
Challenge
The first unauthenticated request returns a JSON-RPC 401 with a WWW-Authenticate bearer challenge pointing at the protected-resource metadata at /.well-known/oauth-protected-resource.
Discovery
The client follows the metadata to the authorization server descriptor at /api/auth/.well-known/oauth-authorization-server, which lists every endpoint below.
Registration
Clients without credentials register dynamically at /api/auth/mcp/register.
Authorization
The browser opens /api/auth/mcp/authorize; the user signs in and consents. If the user belongs to multiple organizations, they choose one here — the choice is bound to the authorization.
Tokens
The client exchanges the code (with its PKCE verifier) at /api/auth/mcp/token. Refresh tokens inherit the same organization scope.
Endpoint reference
| Endpoint | Path |
|---|---|
| Authorization server metadata | /api/auth/.well-known/oauth-authorization-server |
| Protected resource metadata | /.well-known/oauth-protected-resource |
| Authorize | /api/auth/mcp/authorize |
| Token | /api/auth/mcp/token |
| Dynamic client registration | /api/auth/mcp/register |
| User info | /api/auth/mcp/userinfo |
| JWKS (OAuth issuer) | /api/auth/mcp/jwks |
Two JWKS endpoints exist
/api/auth/mcp/jwks is the OAuth issuer's key set. The separate /.well-known/jwks.json serves the LTI integration — do not confuse them.
Organization scoping
A token is bound to one user in one organization, fixed at authorization time. It stays bound even if the user later switches their active workspace in the app — connect again to work in a different organization. Tool calls may pass organizationId explicitly, but the token's scope is the default and the boundary.
What tokens can and cannot do
- Tokens carry the user's roles and permissions — nothing more. There is no machine-only elevated scope.
mcp:operator.readpermits only read tools;ask_operatoris omitted from discovery and cannot be called.mcp:operator.writepermits write-capableask_operatoras well as reads.- Pending members (requesters) are rejected outright.
- Web app session cookies are not accepted as bearer shortcuts; only the OAuth flow mints valid tokens.
Revocation
Either side can end a connection at any time — from the AI client's connector settings, or from Vidext. Expired or revoked tokens get the 401 challenge again; well-behaved clients just re-run the flow.
Headless agents
An email-verification-based registration path for fully headless agents exists at /auth.md. It is rate-limited and intentionally minimal — the OAuth flow above is the supported integration path.
Last updated on