Authentication

Secure your connection to the FrontDeskOS MCP Server with API keys or OAuth 2.0.

API Keys

API keys are the simplest way to authenticate with FrontDeskOS. Each key is scoped to a workspace and can be configured with fine-grained permissions.

Key Types

Parameter	Type	Description
`sk_live_*`required	`Live Key`	Production API key with full access to your workspace data. Use in production environments.
`sk_test_*`	`Test Key`	Sandbox API key that operates on test data only. Safe for development and testing.
`sk_restricted_*`	`Restricted Key`	Key with limited permissions. Configure allowed tools and resources in the dashboard.

Using API Keys

Pass your API key via the FRONTDESK_API_KEY environment variable:

Environment variablebash

export FRONTDESK_API_KEY="sk_live_abc123def456"
export FRONTDESK_WORKSPACE_ID="ws_your_workspace"

For HTTP/SSE transport, include the key in the Authorization header:

HTTP Headerbash

curl -H "Authorization: Bearer sk_live_abc123def456" \
     -H "X-Workspace-ID: ws_your_workspace" \
     https://mcp.frontdeskos.com/v1/sse

Keep Keys Secure

Never commit API keys to source control or share them in client-side code. Use environment variables or a secrets manager.

OAuth 2.0

For applications that act on behalf of users, FrontDeskOS supports OAuth 2.0 with PKCE. This is ideal for multi-tenant applications where each user connects their own workspace.

Authorization Flow

1. Redirect to authorizetypescript

const authUrl = new URL("https://auth.frontdeskos.com/authorize");
authUrl.searchParams.set("client_id", "your_client_id");
authUrl.searchParams.set("redirect_uri", "https://yourapp.com/callback");
authUrl.searchParams.set("response_type", "code");
authUrl.searchParams.set("scope", "tools:read tools:write resources:read");
authUrl.searchParams.set("code_challenge", codeChallenge);
authUrl.searchParams.set("code_challenge_method", "S256");

// Redirect the user
window.location.href = authUrl.toString();

2. Exchange code for tokenstypescript

const response = await fetch("https://auth.frontdeskos.com/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    grant_type: "authorization_code",
    client_id: "your_client_id",
    code: authorizationCode,
    redirect_uri: "https://yourapp.com/callback",
    code_verifier: codeVerifier,
  }),
});

const { access_token, refresh_token, expires_in } = await response.json();

Available Scopes

Parameter	Type	Description
`tools:read`	`scope`	Read-only access to all tools (list calls, view schedules).
`tools:write`	`scope`	Write access to tools (create appointments, update leads).
`resources:read`	`scope`	Read access to MCP resources (business info, staff list).
`analytics:read`	`scope`	Access call analytics, lead reports, and dashboards.
`admin:write`	`scope`	Administrative actions (manage users, configure workspace).
`webhooks:manage`	`scope`	Create, update, and delete webhook subscriptions.

Key Rotation

API keys can be rotated from the FrontDeskOS dashboard without downtime. When you create a new key, the old key remains valid for a configurable grace period (default: 24 hours).

Rotating keys programmaticallytypescript

// Using the FrontDeskOS Admin API
const newKey = await frontdesk.admin.rotateApiKey({
  keyId: "key_current_id",
  gracePeriodHours: 48, // old key valid for 48 more hours
});

console.log("New key:", newKey.secret); // sk_live_new_key_here

Best Practices

Rotate your API keys every 90 days. Set up alerts in the dashboard to get notified before keys expire.