Backbone connector API

Overview

Backbone is inventory software for independent shops. This API lets an AI assistant, such as Meta’s Muse, work with one business’s Backbone account, as the person who connected it and with that person’s Backbone permissions.

It can read stock levels, products, low-stock alerts, purchase orders, the last stock count and stock reports. It can make exactly two kinds of change: adjust a stock count and receive a delivery against a purchase order. Both are prepared first and applied only after the person confirms. A stock count change can be undone the same way. There is no shopping or checkout surface.

The same 12 tools are available three ways: over MCP (the primary transport), as tool calls by name, and as REST endpoints.

Connecting: OAuth 2.0 with PKCE

1. Register your client with Dynamic Client Registration (RFC 7591): POST https://app.backbonesolutions.ai/api/connector/oauth/register. Clients are public (no client secret).
2. Send the person to authorize: https://app.backbonesolutions.ai/api/connector/oauth/authorize with response_type=code, your client_id and redirect_uri, a state, the scope you need, and a PKCE code_challenge with code_challenge_method=S256 (required).
3. The person signs in to Backbone, picks exactly one business, reads the permissions in plain English and approves (or denies).
4. Exchange the code at https://app.backbonesolutions.ai/api/connector/oauth/token with grant_type=authorization_code and your code_verifier.
5. Call the API with Authorization: Bearer <access_token>. Access tokens last one hour by default. Use grant_type=refresh_token to renew; refresh tokens rotate on every use and last 30 days by default. After a refresh, switch to the new access token: the earlier ones stop working 60 seconds later.

Server metadata (RFC 8414): https://app.backbonesolutions.ai/.well-known/oauth-authorization-server. Protected-resource metadata (RFC 9728): https://app.backbonesolutions.ai/.well-known/oauth-protected-resource. Revoke a token (RFC 7009): POST https://app.backbonesolutions.ai/api/connector/oauth/revoke.

Scopes

MCP endpoint

POST https://app.backbonesolutions.ai/api/connector/mcp speaks MCP over Streamable HTTP in stateless mode (protocol 2025-06-18). Send each JSON-RPC message as its own POST with Content-Type: application/json (any other content type is refused with 415) and Accept: application/json, text/event-stream; a batch (a JSON array of messages) is refused with 400. Answers normally come back as plain JSON; Backbone may instead answer a POST as a short event stream (Content-Type: text/event-stream, one message event carrying the same JSON-RPC answer, then the stream closes), as the MCP specification allows, so handle both. There is no session, so GET and DELETE answer 405, and the older HTTP+SSE transport (a GET event stream plus a separate message endpoint) is not offered.

• Without a valid token the endpoint answers 401 with a WWW-Authenticate header whose resource_metadata points to https://app.backbonesolutions.ai/.well-known/oauth-protected-resource/api/connector/mcp. That is where an MCP client starts OAuth.
• tools/list returns only the tools this connection’s scopes allow, no change tools while the business owner has turned changes through Muse off, and no change tool the person’s Backbone permissions could never complete (a view-only member sees only the read tools). Backbone still checks every change on its own side.
• Read tools carry readOnlyHint: true. confirm_change is the one tool marked destructiveHint: true.
• A failed tools/call comes back as a tool result with isError: true and the same plain-English message and next step as the REST error envelope.

REST and tool calls

Base URL: https://app.backbonesolutions.ai/api/connector/v1. Every request needs the bearer token. Responses are JSON and never cached (Cache-Control: no-store).

• Tool call: POST /tools/{name} with the tool input as the JSON body, for any tool below.
• REST: the same tools at the paths below. GET inputs go in the query string; POST inputs in the JSON body; path parts are named after the input field they fill.

Changing stock: preview, then confirm

1. Prepare. Call adjust_inventory_count, receive_purchase_order or undo_change. Nothing changes. You get a one-sentence summary and a preview_token.
2. Ask. Show the person the summary.
3. Confirm. Only if they clearly say yes, call confirm_change with the preview_token and an Idempotency-Key.

1. Prepare

POST /api/connector/v1/tools/adjust_inventory_count
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "sku": "CHR-2IN",
  "location_id": "5f1d2c3b-4a59-4e68-8d7c-6b5a49382716",
  "counted_qty": 9,
  "reason": "damaged"
}

{
  "preview_token": "bbp1.eyJ2IjoxLCJhIjoi…",
  "action_id": "9b2f6c1e-2d7a-4f0e-9a51-3c8d1e7f4a20",
  "summary": "Set 'Chrome Emblem 2in' at Front Rack from 12 to 9 (-3). Reason: damaged.",
  "before": {
    "item": "Chrome Emblem 2in",
    "sku": "CHR-2IN",
    "location": "Front Rack",
    "qty_available": 12
  },
  "after": {
    "qty_available": 9,
    "qty_delta": -3
  },
  "expires_at": "2026-09-27T18:10:00.000Z"
}

3. Confirm

POST /api/connector/v1/changes/confirm
Authorization: Bearer <access_token>
Idempotency-Key: 3c9e1f7a-adjust-chrome-2in
Content-Type: application/json

{
  "preview_token": "bbp1.eyJ2IjoxLCJhIjoi…"
}

{
  "action_id": "9b2f6c1e-2d7a-4f0e-9a51-3c8d1e7f4a20",
  "action": "adjust_inventory_count",
  "status": "applied",
  "summary": "Set 'Chrome Emblem 2in' at Front Rack from 12 to 9 (-3). Reason: damaged.",
  "after": {
    "qty_available": 9,
    "qty_delta": -3
  },
  "applied_at": "2026-09-27T18:01:12.000Z",
  "result": {
    "inventory_event_ids": [
      "5e0c…"
    ],
    "qty_delta": -3
  },
  "reversible": true,
  "request_id": "7f3c2a9e-1b4d-4c55-9e61-0a8b2d3c4e5f"
}

Undo: undo_change with the action_id of an applied stock count change prepares the reversing change; confirm_change applies it. Received deliveries cannot be undone through Muse (not_reversible); a manager records a correction in Backbone instead. A change can be undone once. list_recent_changes shows what was changed and what can still be undone.

Retries and Idempotency-Key

• Send Idempotency-Key as a header on REST, or idempotency_key in the input (the only way on MCP and tool calls). If you send both, they must match.
• Any value of 1 to 255 printable ASCII characters. Keys are scoped to the connection and kept at least 24 hours.
• Same key, same preview: you get the first response again, byte for byte, including its request_id. Nothing is applied twice.
• Same key, different preview: 409 idempotency_conflict, nothing applied.
• A confirm that failed stores nothing under its key.

Rate limits

Over a connector limit you get 429 rate_limited with retry_after (seconds) and a Retry-After header. Registration, token and revoke calls answer 429 in the OAuth error shape (temporarily_unavailable) with a Retry-After header: wait and retry; the refresh token is still good. List tools return at most 50 rows per call.

Errors

Every connector error has the same shape. The message is written for the shop owner and what_to_do is one next step; neither ever contains database, vendor or stack text.

{
  "error": "stale_preview",
  "message": "The numbers changed after this change was prepared, so Backbone did not apply it.",
  "what_to_do": "Ask Muse to prepare the change again with the latest numbers.",
  "request_id": "7f3c2a9e-1b4d-4c55-9e61-0a8b2d3c4e5f",
  "retryable": false
}

Tools