Buun Group Developers
Pages

Quick start

What a new Buun Group product does to sign people in with Buun Identity and to be reachable through the MCP gateway, in the order it does it.

Markdown

The checklist

StepWhatPage
1Add the product to PRODUCTS in @buun-group/core, with its id, name and home pageBuilding a product
2Register the product's own client in the staff console: a Buun Group product, its redirect addresses, its scopesClients
3Send people to /oauth/authorize with PKCE, trade the code at /oauth/token, and check the tokensThe sign-in flow
4Read the person's plan from /oauth/plans whenever it mattersPlans
5Make the product's MCP server accept Buun Identity tokens whose aud is its own MCP addressAccepting Buun Identity tokens
6Add the product to the gateway's catalogue, marked acceptsIdentityTokens, and its MCP server as a resource serverHow the gateway works
7Approve the product's tools in the staff consoleTool review
8Test the whole path on one machineLocal development

The smallest working sign-in

ts
const base64url = (bytes: Uint8Array): string => btoa(String.fromCharCode(...bytes)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')


// 1. Send the browser to Buun Identity.
const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)))
const challenge = base64url(new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier))))
const state = base64url(crypto.getRandomValues(new Uint8Array(16)))
const authorize = new URL('https://id.buungroup.com/oauth/authorize')
authorize.search = new URLSearchParams({
  response_type: 'code',
  client_id: 'cli_your_product',
  redirect_uri: 'https://app.your-product.dev/auth/callback',
  scope: 'openid profile email offline_access',
  state,
  code_challenge: challenge,
  code_challenge_method: 'S256',
}).toString()


// 2. On the way back, check `state` and `iss`, then trade the code.
const tokens = await fetch('https://id.buungroup.com/oauth/token', {
  method: 'POST',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({ grant_type: 'authorization_code', client_id: 'cli_your_product', code, redirect_uri: 'https://app.your-product.dev/auth/callback', code_verifier: verifier }),
}).then((response) => response.json())

Keep the verifier and the state in a cookie of your own, for one sign-in, and refuse a return whose state does not match.