Security & Authentication

Authentication Guide

How to authenticate with BuildStability's MCP server and API

Overview

BuildStability uses JWT-based authentication. All API requests require a valid JWT (JSON Web Token) in the Authorization header.

Getting Your Access Token

Method 1: Copy Token (Easiest)

When API access is enabled for your business:

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

Use it as Authorization: Bearer <token> in MCP, the REST Data API, or any API client.

Method 2: Browser / Local Storage (Quick Test)

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

Method 3: In Code (Using Your Token)

Copy your token (Method 1), 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' })
});

Method 4: Server-to-Server Sign-In

Programmatic sign-in with email and password is available to registered developers. Detailed technical documentation (endpoints, schemas, authentication) is provided once API access is enabled in Business Settings → API & Integrations.

There is no /api/auth/login endpoint. Backend auth routes (/api/auth/native-*, /api/auth/web-*, /api/auth/magic-link-*) are gated by origin, user-agent, and Turnstile for first-party apps only.

What a JWT Looks Like

A JWT has three base64url-encoded segments separated by dots: header.payload.signature. The header describes the algorithm; the payload holds claims (e.g. sub, email, exp); the signature ensures integrity. Tokens are usually 200–500+ characters.

Example format (always use your own from Copy Token—tokens are user-specific and expire in 1 hour):

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJZT1VSLVVTRVItSUQiLCJlbWFpbCI6InlvdUBleGFtcGxlLmNvbSIsInJvbGUiOiJhdXRoZW50aWNhdGVkIiwiZXhwIjo5OTk5OTk5OTk5fQ.EXAMPLE_SIGNATURE_NOT_A_REAL_TOKEN

What to do with it: Put it in the Authorization: Bearer <your-token> header for MCP (POST /api/mcp), the REST Data API, or any BuildStability API that uses JWT auth.

Using the Token

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 (auto-generated from the database schema) uses the same JWT tokens - no database credentials exposed. RLS automatically filters to your business data.

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

See REST Data API Guide for detailed usage.

Token Expiration

Access tokens expire after 1 hour. Refresh tokens are valid for 30 days.

Refreshing a Token

The quickest refresh is to click Copy Token again in Business Settings → API & Integrations. Programmatic refresh for server-to-server integrations is documented for registered developers once API access is enabled.

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.

Security Best Practices

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.

Multi-Tenancy & API Access

BuildStability uses business-level isolation with explicit API opt-in:

Security Model

API Access Must Be Enabled: Your business administrator must enable API access before MCP endpoints work.
Business Isolation: You can only access data for your business. All queries are automatically filtered by business_id.
Multi-Business Support: If you belong to multiple businesses, use the X-Business-ID header to specify which business to access.

Enabling API Access

Business administrators can enable API access:

Go to Business Settings → API & Integrations
Toggle Enable API Access and save if needed
Click Copy Token to copy your JWT to the clipboard

Multi-Business Users

If you belong to multiple businesses with API access enabled:

# Specify which business to access
curl -X POST https://api.buildstability.com/api/mcp \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Business-ID: your-business-uuid" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Without the X-Business-ID header, the system uses your first API-enabled business.

API Keys vs Access Tokens

Access Token (JWT): User-specific, expires after 1 hour. Use for MCP and authenticated API calls.
Anon Key: Public by design, never expires. Grants limited unauthenticated access to the REST Data API (details for registered developers).

For MCP, always use the Access Token.

Troubleshooting

"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

View Raw Markdown Developer Portal