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.
The checklist
| Step | What | Page |
|---|---|---|
| 1 | Add the product to PRODUCTS in @buun-group/core, with its id, name and home page | Building a product |
| 2 | Register the product's own client in the staff console: a Buun Group product, its redirect addresses, its scopes | Clients |
| 3 | Send people to /oauth/authorize with PKCE, trade the code at /oauth/token, and check the tokens | The sign-in flow |
| 4 | Read the person's plan from /oauth/plans whenever it matters | Plans |
| 5 | Make the product's MCP server accept Buun Identity tokens whose aud is its own MCP address | Accepting Buun Identity tokens |
| 6 | Add the product to the gateway's catalogue, marked acceptsIdentityTokens, and its MCP server as a resource server | How the gateway works |
| 7 | Approve the product's tools in the staff console | Tool review |
| 8 | Test the whole path on one machine | Local development |
The smallest working sign-in
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.