Authentication Guide

Method 1: OAuth client credentials (for integrations)

This is what the REST API v1 requires. Nothing else authenticates it.

1. Go to Business → Profile → API & Integrations and turn on Enable API/MCP Access
2. Open API apps (it appears under Developers in the sidebar once access is on) and create an app
3. Copy the client_id and client_secret. The secret is shown once and never again

Exchange them for an access token:

curl -X POST https://api.buildstability.com/api/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

# {"access_token":"...","token_type":"Bearer","expires_in":3600,"scope":"read write"}

Then call the API with it:

curl https://api.buildstability.com/api/v1/clients \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Tokens last one hour. To refresh, make the same token call again — that is the programmatic refresh, and it needs no human. Scopes are read and write; omit scope to get everything the app was granted.

Method 2: Copy Token (personal token, for MCP)

When API access is enabled for your business:

1. Go to Business → Profile → API & Integrations
2. Turn on Enable API/MCP Access if needed
3. Click Copy Token — your JWT is copied to the clipboard

Use it as Authorization: Bearer <token> for MCP. It does not work on /api/v1/*, which needs Method 1.

Method 3: Browser / Local Storage (quick test only)

1. Log in to BuildStability at https://www.buildstability.com/login
2. Open browser DevTools (F12) → Application → Local Storage
3. Find sb-<project-id>-auth-token
4. Copy the access_token value

Method 4: In Code (Using Your Token)

Copy your token (Method 2), store it in an environment variable, and send it as a Bearer header:

const accessToken = process.env.BUILDSTABILITY_ACCESS_TOKEN;

const response = await fetch('https://api.buildstability.com/api/mcp', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' })
});

Server-to-server sign-in

Use Method 1. OAuth client credentials are the server-to-server flow: no email, no password, no browser, and a fresh token whenever you ask for one. There is no separate programmatic sign-in to apply for.

MCP Requests

curl -X POST https://api.buildstability.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{ ... }'

REST Data API Requests

The REST Data API is generated from the database schema and takes the same personal token. Row Level Security filters every query to the businesses you belong to, and no database credentials are exposed.

It is not read-only, and it is not metered. The personal token can insert, update and delete wherever your account can, these calls do not pass through our API so they are not counted against the allowance shown on your Business page, and the token is your login rather than a scoped key. It is a good tool for your own queries and a poor one to hand to anybody else. For that, use OAuth client credentials and the REST API v1.

Detailed technical documentation (hosts, endpoints, schemas) is available to registered developers. Enable API access in Business → Profile → API & Integrations.

See REST Data API Guide for detailed usage.

Refreshing a Token

For a personal token, click Copy Token again in Business → Profile → API & Integrations. For a server-to-server integration there is nothing to click: repeat the/api/oauth/token call from Method 1 with the same client ID and secret. That is the whole refresh story, which is why an integration should never be built on a personal token.

Automatic Refresh (Logged-In Session)

While you are logged in to the BuildStability web app, your session token refreshes automatically in the background. The token in local storage (Method 2) is always the current one.

1. Never Commit Tokens

# .gitignore
.env
*.token
secrets.json

2. Use Environment Variables

const accessToken = process.env.BUILDSTABILITY_ACCESS_TOKEN;

3. Store Tokens Securely

• Server-side: Use environment variables or a dedicated secrets manager
• Client-side: Use secure storage (not localStorage for sensitive apps)
• Mobile: Use Keychain (iOS) or Keystore (Android)

4. Rotate Tokens Regularly

If a token is compromised, log out of the session it came from. Logging out revokes the refresh token, and the access token itself expires within an hour.

5. Use HTTPS Only

Always use https:// endpoints. Never send tokens over HTTP.

"Business context required" Error

• Your token is missing or invalid
• Token has expired (refresh it)
• You're not authenticated
• API access not enabled for your business

"Invalid Request" Error

• Check your JSON-RPC format
• Verify jsonrpc: "2.0" is present
• Ensure method and id are included

"Method not found" Error

• Check the method name spelling
• Verify you're using the correct endpoint (/api/mcp)
• Review available methods with tools/list