Installation

Install the package in your backend and create one reusable Vinkius instance. The client stores application-level configuration, not per-user state, so the same instance can serve requests for many users.

Prerequisites

• Node.js 18 or later, or another server runtime that provides fetch (Node 18+, Bun, Deno, and edge runtimes)
• A Vinkius App ID beginning with vk_app_
• A Vinkius Application Key beginning with vk_app_sk_

Get your API credentials

Vinkius Connect authenticates with two values from a Vinkius Cloud Application:

To create them in the Vinkius Cloud dashboard:

1. Open Build AI Apps (/ai-agents) and click New AI Application. Give it a name (for example Acme Copilot) and create it.
2. Open the application. Your App ID (vk_app_...) is shown under the app name and in the page URL. Copy it into appId.
3. Go to the App Keys tab and click New Key. Select the permissions your backend needs, then Create Key.
4. The Application Key (vk_app_sk_...) is shown once, in a "Copy this key now" dialog. Copy it into apiKey. It cannot be retrieved afterward.

You can rotate or revoke a key anytime from the same App Keys tab. Rotating invalidates the old key immediately and reveals the new one once.

Install the package

The package lives on npm and the source on GitHub:

npm install @vinkius/connect

Equivalent commands are pnpm add @vinkius/connect, yarn add @vinkius/connect, and bun add @vinkius/connect. The package ships dual ESM + CommonJS with bundled TypeScript types and has zero runtime dependencies.

Configure server environment variables

VINKIUS_APP_ID=vk_app_xxxxxxxxxxxxxxxx
VINKIUS_APP_KEY=vk_app_sk_xxxxxxxxxxxxxxxxxxxxxxxx

Create a server-only module

// lib/vinkius.ts — import this module only from server code
import { Vinkius } from '@vinkius/connect';

function required(name: 'VINKIUS_APP_ID' | 'VINKIUS_APP_KEY'): string {
  const value = process.env[name];
  if (!value) throw new Error(`Missing ${name}`);
  return value;
}

export const vinkius = new Vinkius({
  appId: required('VINKIUS_APP_ID'),
  apiKey: required('VINKIUS_APP_KEY'),
});

The constructor checks the App ID and key prefixes, parses baseUrl when supplied, and requires a fetch implementation. It makes no request. It does not perform runtime range validation for every optional number or callback, so keep timeoutMs, maxRetries, hooks, and custom naming functions under application control.

If your runtime has no global fetch, pass a compatible implementation:

const vinkius = new Vinkius({
  appId,
  apiKey,
  fetch: customFetch,
});

Client options

new Vinkius({
  appId: 'vk_app_...',
  apiKey: 'vk_app_sk_...',
  baseUrl: 'https://api.vinkius.com', // default
  timeoutMs: 30_000, // default
  maxRetries: 2, // default (idempotent requests only)
  fetch: globalThis.fetch, // override for tests/edge
  userAgent: 'acme-ai/1.0', // appended to the default User-Agent
  namespaceCapability: (connector, name) => `${connector}__${name}`, // default
  hooks: {
    onRequest: ({ method, url }) => {}, // headers/body are redacted
    onResponse: ({ status, requestId }) => {},
  },
});

Verify credentials with a request

A handle-only check does not contact the API. Use a catalog read for a real smoke test:

import { VinkiusError } from '@vinkius/connect';
import { vinkius } from './lib/vinkius';

async function checkVinkiusConnection(): Promise<void> {
  try {
    const page = await vinkius.catalog.list({ page: 1 });
    console.log(`Vinkius API reachable; received ${page.data.length} connectors`);
  } catch (error: unknown) {
    if (error instanceof VinkiusError) {
      console.error({
        code: error.code,
        status: error.status,
        requestId: error.requestId,
      });
    }
    throw error;
  }
}

await checkVinkiusConnection();

This check verifies that the runtime can reach the API and that the application credentials are accepted. A local ConfigError occurs before any request; AuthError represents an HTTP 401 or 403 response.

Create a user handle

const user = vinkius.user('alice_123');

user() makes no request. The ID must be your application's stable user identifier: 1 to 255 characters, not beginning with vk_app_user_, and without whitespace, slashes, or backslashes.

Next steps

• Run the connect-to-execute quickstart
• Bind externalId to an authenticated session
• Discover what the platform does behind every call