Architecture

Overview

NIN Connect is an API proxy with managed authentication. Your app talks to NIN via the SDK (or REST API), and NIN handles credential management, auth injection, and the actual API call to the external service.

┌──────────────────┐         ┌──────────────────┐         ┌──────────────────┐
│   Your App /     │  SDK    │  NIN Connect     │  HTTP   │  External API    │
│   AI Agent       │────────▶│  connect.nin.in  │────────▶│  (Gmail, Stripe) │
│                  │         │                  │         │                  │
│  session.execute │         │  ─ resolve tool  │         │                  │
│  ("TOOL", params)│         │  ─ decrypt creds │         │                  │
│                  │◀────────│  ─ inject auth   │◀────────│                  │
│  { data, status }│  result │  ─ proxy request │  response                 │
└──────────────────┘         │  ─ log execution │         └──────────────────┘
                             └──────────────────┘

What Happens When You Execute a Tool

1. Your app calls session.execute("GMAIL_SEND_EMAIL", { to, subject, body })
2. The SDK sends POST /api/v1/tools/execute with your API key and user ID
3. NIN resolves the tool definition (HTTP method, path, input schema)
4. Finds the user's connection for the plugin (Gmail)
5. Decrypts the stored credentials (AES-256-GCM encrypted at rest)
6. Injects auth into the request — e.g. Authorization: Bearer {access_token}
7. If the OAuth token is expired, auto-refreshes it
8. Builds the HTTP request and calls the Gmail API
9. Returns { success, data, status, latencyMs } to your app
10. Logs the execution for your dashboard

Connection Model

Before executing tools, your end-users need a connection to the relevant plugin. There are two patterns:

OAuth (redirect-based)

For services like Gmail, Slack, GitHub:

Your App → session.initiateConnection({ plugin: "gmail", redirectUrl })
         → NIN returns connectUrl
         → User authorizes at Google
         → NIN exchanges code for tokens, encrypts, stores
         → User redirected back to your app

Direct Credentials

For API-key-based services like OpenAI, Anthropic:

Your App → session.createConnection({
             plugin: "openai",
             authMethod: "api_key",
             credentials: { api_key: "sk-..." }
           })
         → NIN encrypts and stores the key

MCP Tool Execution

For plugins with toolSource set to "mcp" or "both", tool execution routes through the MCP server instead of a direct REST proxy:

┌──────────────────┐         ┌──────────────────┐         ┌──────────────────┐
│   Your App /     │  SDK    │  NIN Connect     │  MCP    │  MCP Server      │
│   AI Agent       │────────▶│  connect.nin.in  │────────▶│  (Notion, etc.)  │
│                  │         │                  │         │                  │
│  session.execute │         │  ─ resolve tool  │         │                  │
│  ("TOOL", params)│         │  ─ decrypt MCP   │         │                  │
│                  │◀────────│    access token   │◀────────│                  │
│  { data, status }│  result │  ─ call MCP tool │  result │                  │
└──────────────────┘         │  ─ log execution │         └──────────────────┘
                             └──────────────────┘

1. Your app calls session.execute("NOTION_SEARCH", { query: "..." })
2. NIN resolves the tool from mcpToolCache — identifies it as an MCP tool
3. Finds the user's MCP connection for the plugin
4. Decrypts the MCP access token (auto-refreshes if expired via PKCE)
5. Connects to the MCP server using the Streamable HTTP transport
6. Calls the tool via the MCP protocol (tools/call)
7. Returns the result to your app and logs the execution

Tool Discovery

MCP tools are discovered in realtime when getTools() is called with a connected user:

getTools({ plugins: ["notion"] })
  → NIN connects to Notion MCP with user's token
  → Calls listTools()
  → Returns fresh tool definitions
  → Syncs to mcpToolCache as fallback

If the user isn't connected or the live fetch fails, NIN falls back to the cached tool definitions from mcpToolCache.

See the MCP Integration guide for full details.

Auth Is Transparent

You never see or handle the user's credentials. NIN:

• Encrypts them at rest (AES-256-GCM)
• Decrypts only at execution time
• Auto-refreshes expired OAuth tokens
• Never exposes credentials in API responses, SDK responses, or logs

Supported Auth Types

Rate Limits & Monitoring

Each API key has a configurable rate limit (default: 1,000 requests). Every tool execution is logged with:

• Success/error status
• Latency in milliseconds
• Error messages (for failed calls)
• User ID and tool slug

View logs in the dashboard or query them programmatically.

Self-Hosting

NIN Connect can be self-hosted if you need full control. See the Platform docs for setup instructions, database schema, and internal architecture details.