Integration Guide — BYO | Add Customer API Key Vault to Your App

Frontend — collect the key

Install byo-connect and use your publishable key to store customer API keys securely.

npm install byo-connect

import { createConnect } from 'byo-connect';

const connect = createConnect({
  baseURL: 'https://api.usebyo.com',
  publishableKey: 'byo_pk_live_...',
});

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

Publishable keys (byo_pk_) are safe for frontend use. They can only store provider keys — not proxy calls or revoke.

Custom OpenAI-compatible endpoints

Customers can connect keys for vLLM, OpenRouter, Ollama, Together AI, or any OpenAI-compatible server.

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

Trust badge

Place the <byo-badge> Web Component next to your key input form. Auto-registers when you import byo-connect.

<!-- Light theme (default) -->
<byo-badge></byo-badge>

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

<!-- Standalone import (badge only) -->
import 'byo-connect/badge';

Backend SDK

Use your secret key to proxy AI calls using the customer's stored key. The SDK mirrors each provider's API.

npm install byo-sdk

import { BYOK } from 'byo-sdk';

const byok = new BYOK({ apiKey: process.env.BYO_SECRET_KEY });

// OpenAI
const openai = byok.openai({ refId: 'customer_123' });
const response = await openai.responses.create({
  model: 'gpt-4.1',
  input: 'Hello!',
});

// Anthropic
const claude = byok.anthropic({ refId: 'customer_123' });
const message = await claude.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello!' }],
});

// Google AI Studio
const gemini = byok.google({ refId: 'customer_123' });
const result = await gemini.generateContent.create({
  model: 'gemini-2.0-flash',
  contents: [{ parts: [{ text: 'Hello!' }] }],
});

Key management

Validate and revoke stored keys from your backend.

// Validate a stored key (checks with the provider)
const { valid } = await byok.keys.validate({
  provider: 'openai',
  refId: 'customer_123',
});

// Revoke a key
await byok.keys.revoke({
  provider: 'openai',
  refId: 'customer_123',
});

Webhooks

Get notified when key lifecycle events happen. All payloads are HMAC-signed.

key.connected Provider key stored or updated

key.revoked Provider key revoked

key.disabled Provider key disabled

key.validation_failed Key fails provider validation during connect

// Verify webhook signature (Node.js)
const crypto = require('crypto');

function verifyWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

Check the X-BYO-Signature header against the HMAC-SHA256 digest of the raw body using your webhook secret.

Error handling

import { BYOKError, AuthenticationError } from 'byo-sdk';

try {
  await openai.responses.create({ model: 'gpt-4.1', input: 'Hello' });
} catch (err) {
  if (err instanceof AuthenticationError) {
    // Invalid or missing API key (401)
  } else if (err instanceof BYOKError) {
    console.error(err.message, err.statusCode);
  }
}

Key concepts

byo_pk_

Publishable key

Safe for frontend. Can only store provider keys via /keys/connect.

byo_sk_

Secret key

Backend only. Full access: connect, validate, revoke keys, and proxy AI calls.

refId

Reference ID

Your identifier for the customer (e.g., user_123, org_456). Links a provider key to your customer.

Integrate