Getting Started

Install the SDK, get an API key, connect a user, and execute your first tool — all in under 5 minutes.

Go to connect.nin.in and sign in with Google
Navigate to API Keys in the sidebar
Click Create Key and copy the raw key — it's shown only once

Your key looks like nk_live_... and is used to authenticate all SDK and API calls.

2. Install the SDK

npm install @nin.in/core

3. Initialize

import { Nin } from "@nin.in/core";

const nin = new Nin({
  apiKey: process.env.NIN_API_KEY!, // your nk_live_... key
});

The SDK points to https://connect.nin.in by default. For self-hosted instances, pass baseUrl.

4. Browse Available Plugins

const plugins = await nin.getPlugins();

for (const plugin of plugins) {
  console.log(`${plugin.name} (${plugin.slug}) — ${plugin.toolCount} tools`);
}
// Gmail (gmail) — 5 tools
// Stripe (stripe) — 8 tools
// Slack (slack) — 4 tools

5. Connect a User

Before your users can execute tools, they need to connect their account to the relevant service. The easiest way is to generate a hosted connect URL and redirect the user there.

Hosted Connect URL (recommended)

const session = nin.session("user_123");

const { connectUrl } = await session.initiateConnection({
  plugin: "gmail",
  redirectUrl: "https://your-app.com/callback",
});

// redirect or link the user to connectUrl
// the hosted page shows all available auth methods for this plugin
// (OAuth button, API key form, etc.)
// after connecting, user is redirected to your redirectUrl with ?status=success

You can render connectUrl as a button in your UI — "Connect your Gmail" etc. When authMethod is omitted, the page shows all options. Pass authMethod: "oauth2" to skip the hosted page and go straight to the provider.

Direct Credentials (server-side)

If you already have the credentials (e.g. from your own settings page):

const session = nin.session("user_123");

await session.createConnection({
  plugin: "openai",
  authMethod: "api_key",
  credentials: { api_key: "sk-..." },
});

6. Execute a Tool

const session = nin.session("user_123");

const result = await session.execute("GMAIL_SEND_EMAIL", {
  to: "hello@example.com",
  subject: "Hello from my AI agent",
  body: "This was sent through NIN Connect.",
});

if (result.success) {
  console.log("Sent!", result.data);
} else {
  console.error("Failed:", result.error);
}

That's it. NIN resolved the tool, decrypted the user's Gmail OAuth tokens, injected Authorization: Bearer ..., called the Gmail API, and returned the result.

7. Get Tool Definitions (for AI Agents)

If you're building an AI agent that needs to discover tools dynamically:

const session = nin.session("user_123");

const tools = await session.getTools({ plugins: ["gmail", "slack"] });

for (const tool of tools) {
  console.log(`${tool.slug}: ${tool.description}`);
  console.log("Input schema:", JSON.stringify(tool.inputSchema));
}

Pass these definitions to your LLM so it can decide which tools to call.

Framework Examples

Vercel AI SDK (v5)

import { generateText, tool, jsonSchema, stepCountIs } from "ai";
import { openai } from "@ai-sdk/openai";
import { Nin } from "@nin.in/core";

const nin = new Nin({ apiKey: process.env.NIN_API_KEY! });
const session = nin.session("user_123");
const ninTools = await session.getTools({ plugins: ["gmail"] });

// AI SDK v5 uses inputSchema (renamed from parameters)
const tools: Record<string, ReturnType<typeof tool>> = {};
for (const t of ninTools) {
  tools[t.slug] = tool({
    description: t.description,
    inputSchema: jsonSchema(
      t.inputSchema ?? { type: "object", properties: {} }
    ),
    execute: async (params) => session.execute(t.slug, params),
  });
}

const result = await generateText({
  model: openai("gpt-4o"),
  prompt: "Send an email to hello@example.com saying hi",
  tools,
  stopWhen: stepCountIs(10),
});

Next Steps

SDK Reference — all methods, options, and types
REST API — HTTP endpoints if you prefer raw API calls
Architecture — how the proxy and auth model works
Self-Host — run NIN Connect on your own infrastructure

Getting Started

On this page