Build Your Own Extension

Any platform can become a Buddy extension. You implement the same four layers — embed, identity, operations, actions — against the Extension API. The JavaScript and PHP SDKs handle the signing for you.

1. Get an Extension API Key

In Studio, open your agent → Extensions → generate a key (bxk_…). Keep it server-side.

2. Connect & register operations

import { BuddyClient } from '@buddy/extension-sdk';

const client = new BuddyClient({ apiKey: process.env.BUDDY_EXTENSION_API_KEY });

const connection = await client.connect({ siteUrl: 'https://example.com' });
// connection.identity.secret → mint identity tokens
// connection.widget.token    → public widget token for the embed

await client.registerOperations({
  allowWrites: false,
  operations: [{
    category: 'orders', operationId: 'get_order', name: 'Get an order',
    description: 'Fetch one order by id.', method: 'GET',
    urlTemplate: '/orders/{id}', isWrite: false,
    paramsSchema: { type: 'object', required: ['id'], properties: { id: { type: 'string' } } },
    sensitivityRules: { default: 'summarize_only', fields: [] },
  }],
  apiAuth: { header: 'Authorization', credential: process.env.MY_API_TOKEN, baseUrl: 'https://api.example.com' },
});

3. Mint identity tokens (server-side)

import { mintIdentityToken } from '@buddy/extension-sdk';

// secret = connection.identity.secret (stays on your server)
const token = mintIdentityToken(
  { id: user.id, email: user.email, attributes: { plan: user.plan } },
  secret
);
// hand token to the browser, then: window.BuddyWidget.setAuthToken(token)

4. Embed the widget

<script src="https://app.buddy.ui.pe/app/embed.js" data-token="WIDGET_TOKEN" async></script>

The signing scheme

If you'd rather not use the SDK, every Extension API request needs:

• Authorization: Bearer <bxk_…>
• x-extension-timestamp: <unix seconds>
• x-extension-signature: base64url(HMAC-SHA256(canonical, key)) where canonical = "{METHOD}\n{PATH}\n{timestamp}" (path without query string).

The identity token format is:

token = base64url(JSON payload) + "." + base64url(HMAC-SHA256(payloadB64, secret))

The payload must include exp (unix seconds) and should include iat; the platform enforces a 10-minute lifetime ceiling.

SDKs

• JavaScript: npm install @buddy/extension-sdk
• PHP: composer require buddy/extension-sdk

Testing checklist

• Connect returns an agent and a widget token.
• A minted token verifies in the live console (method: signed session token).
• Operations appear under the agent's API categories and can be toggled.
• Anonymous visitors load the widget without identity; logged-in users are recognised.