BYO Connect

Browser helper for collecting provider API keys from your customers via BYO.

Installation

npm install byo-connect

Quick Start — Drop-in Form

The easiest way to collect keys. The <byo-connect-form> web component renders inside a cross-origin iframe — the raw key never touches your page's JavaScript context.

import 'byo-connect/form';

<byo-connect-form
  publishable-key="byo_pk_live_..."
  ref-id="customer_123"
  theme="dark"
></byo-connect-form>

Listen for events:

const form = document.querySelector('byo-connect-form');

form.addEventListener('byo:connected', (e) => {
  const { id, provider, refId, status } = e.detail;
  console.log('Key stored:', { id, provider, refId, status });
});

form.addEventListener('byo:error', (e) => {
  console.error('Connection failed:', e.detail.message);
});

Form Attributes

| Attribute | Type | Description | |-----------|------|-------------| | publishable-key | string | Your BYO publishable key (byo_pk_...) | | ref-id | string | Your identifier for the customer | | provider | string (optional) | Lock to a single provider | | providers | string (optional) | Comma-separated list of allowed providers | | theme | "light" | "dark" | Color theme (default: light) | | base-url | string (optional) | Override the BYO API URL |

Form Events

| Event | Detail | Description | |-------|--------|-------------| | byo:connected | { id, provider, refId, status, updated } | Key stored successfully | | byo:error | { message, statusCode } | Connection failed |

Or use it via a script tag (no bundler needed):

<script src="https://unpkg.com/byo-connect/dist/esm/form.js" type="module"></script>

Programmatic API

For full control over the UI, use createConnect directly:

import { createConnect } from 'byo-connect';

const connect = createConnect({
  publishableKey: 'byo_pk_live_...',
});

await connect({
  provider: 'openai',
  refId: 'customer_123',
  providerKey: 'sk-...',
});

Supported Providers

• openai
• anthropic
• google (Google AI Studio)
• azure-openai
• bedrock (AWS Bedrock)

Custom OpenAI-compatible Endpoint

Connect a key for any OpenAI-compatible server (vLLM, OpenRouter, Ollama, Together AI, etc.):

await connect({
  provider: 'openai',
  refId: 'customer_123',
  providerKey: 'key-...',
  providerConfig: { baseUrl: 'https://openrouter.ai/api/v1' },
});

HTTPS is required. HTTP is allowed for localhost only (for local development with Ollama, etc.).

Azure OpenAI & AWS Bedrock

These providers require additional configuration via providerConfig:

// Azure OpenAI
await connect({
  provider: 'azure-openai',
  refId: 'customer_123',
  providerKey: 'your-azure-api-key',
  providerConfig: {
    baseUrl: 'https://your-resource.openai.azure.com',
    deploymentName: 'gpt-4',
  },
});

// AWS Bedrock
await connect({
  provider: 'bedrock',
  refId: 'customer_123',
  providerKey: 'your-aws-secret-access-key',
  providerConfig: {
    accessKeyId: 'AKIA...',
    region: 'us-east-1',
  },
});

Parameters

| Parameter | Type | Description | |-----------|------|-------------| | provider | 'openai' \| 'anthropic' \| 'google' \| 'azure-openai' \| 'bedrock' | AI provider | | refId | string | Your identifier for the customer | | providerKey | string | The customer's API key | | providerConfig | object (optional) | Required for Azure OpenAI and AWS Bedrock. Optional for OpenAI (set baseUrl for custom endpoints) |

Error Handling

import { createConnect, ConnectError } from 'byo-connect';

try {
  await connect({ provider: 'openai', refId: 'customer_123', providerKey: 'sk-...' });
} catch (err) {
  if (err instanceof ConnectError) {
    console.error(err.message);    // error message
    console.error(err.statusCode); // HTTP status code
  }
}

Trust Badge

byo-connect ships a <byo-badge> Web Component that displays a "Secured by BYO" trust badge next to your key input. Works in any framework (React, Vue, Svelte, plain HTML).

The badge auto-registers when you import byo-connect:

import { createConnect } from 'byo-connect';

// <byo-badge> is now available in the DOM

Or import just the badge:

import 'byo-connect/badge';

Then use it in your HTML:

<byo-badge></byo-badge>
<byo-badge theme="dark"></byo-badge>

Customization

Style the badge with CSS custom properties:

byo-badge {
  --byo-badge-bg: #1a1a2e;
  --byo-badge-text: #e0e0e0;
  --byo-badge-accent: #4ade80;
  --byo-badge-border: #2d2d4a;
  --byo-badge-radius: 6px;
  --byo-badge-font-size: 12px;
}

| Property | Default (light) | Default (dark) | Description | |----------|----------------|----------------|-------------| | --byo-badge-bg | #f4f4f5 | #18181b | Background color | | --byo-badge-text | #27272a | #e4e4e7 | Text color | | --byo-badge-accent | #16a34a | #16a34a | Lock icon color | | --byo-badge-border | #e4e4e7 | #3f3f46 | Border color | | --byo-badge-radius | 6px | 6px | Border radius | | --byo-badge-font-size | 12px | 12px | Font size |

Attributes

| Attribute | Description | |-----------|-------------| | theme | "light" (default) or "dark" | | href | Override the badge link URL |

How It Works

byo-connect is a lightweight wrapper around the BYO /keys/connect endpoint. It uses your publishable key (byo_pk_...) to securely store the customer's provider API key in BYO's encrypted vault. Your backend never sees the raw key.

For backend proxy calls using stored keys, see byo-sdk.

License

FSL-1.1-MIT