Connect with an identity API key

OAuth with user sign-in and S256 PKCE is the preferred connection method. BOS also supports an optional identity API key for clients that securely store and attach a single token.

A BOS operator provisions the key through local GCP tooling using the existing platform key lifecycle. The user enters the supplied key directly in the client's secure credential card or vault. Agents use the authenticated connection; credentials stay in secure transport and storage.

Configure auth_scheme: api_key, placement: bearer_header, and api_hosts: ["dfsm.ai"]. Requests carry Authorization: Bearer <key>. The endpoint is https://dfsm.ai/mcp/apps/bos/platform.

One key authenticates your BOS identity. Access follows current active organization memberships, app installations, roles and enabled plugins. Organization creation and permission changes use the normal BOS membership index. The key carries no static organization or app list.

Choose a target on each request

Call bos_get_context to discover current contexts. The client selects the requested organization, app and role, then supplies its context_handle to bos_list_context_tools and bos_execute. Each operation rechecks current permissions. Resource reads use the exact discovered context-bound URI.

The deterministic Lead Director API takes its application and organization in the discovered request path and the selected context in X-BOS-Context-Handle. Use its Describe response for exact routes and fields.

Client transport example

// secureVault is your platform's credential store, populated by the user.
async function mcpRequest(secureVault, method, params = {}) {
  const key = await secureVault.read("bos");
  const response = await fetch("https://dfsm.ai/mcp/apps/bos/platform", {
    method: "POST",
    headers: {"Authorization": `Bearer ${key}`,
      "Content-Type": "application/json",
      "Accept": "application/json, text/event-stream"},
    body: JSON.stringify({jsonrpc: "2.0", id: crypto.randomUUID(), method, params})
  });
  if (response.status === 401) throw new Error("BOS credential unavailable");
  return response; // Handle MCP JSON/SSE according to Content-Type.
}
// Complete MCP initialize + notifications/initialized before discovery.
// tools/call: bos_get_context, arguments: {}
// tools/call: bos_list_context_tools, arguments: {context_handle: selectedHandle}
// tools/call: bos_execute, arguments: {
//   context_handle: selectedHandle, tool_name: discoveredTool, arguments: businessInput
// }

Key lifecycle

bos_list_api_keys returns metadata for your latest 100 keys. bos_revoke_api_key({key_id}) revokes one exact owned key. bos_logout({}) revokes only the credential used by the current connection. Expiration is optional; revocation and permission removal also apply to resumed and background work.

Keys contain 32 random bytes encoded with URL-safe base64. BOS stores SHA-256 hashes. Client names and platforms are descriptive metadata. Existing integration keys retain their original contracts.

Machine-readable client contract · OAuth discovery and client example