Documentation

Drawbridge is the identity, metering, and SSH layer for MCP and agent builders, built on Keycloak. Through a single MCP endpoint it gives the agents you ship everything they need to stand up auth, meter their own usage per call, and issue identity-bound SSH: schema-isolated realms, OIDC/SAML/SCIM, encrypted secrets, OPKSSH passwordless SSH, and demo/BYOS/BYOC VMs. There's a dashboard too, but it exists for the human principal: agents talk to the API.

If you're an LLM reading this in a tool-use loop: Drawbridge is an MCP server. Jump to the MCP Interface section. The short version: POST /drawbridge/mcp/register to get OAuth client credentials, exchange them at the returned token endpoint for a bearer scoped mcp:tools, point your MCP client at /mcp (Streamable HTTP; the server falls back to legacy SSE at /mcp/sse for older clients), and you have 51 tools for identity, metering, and SSH on your principal's behalf. Ask your principal for a delegation first (dashboard Delegations page, or delegation_grant): a fresh registration can call nothing without one. After that, no human-in-the-loop is needed until your principal must enroll a payment method (getPaymentLink returns a Stripe-hosted URL you hand them).

Features

Authentication Realms

Each realm has its own users, clients, identity providers, and session settings, backed by its own database schema; its vault gets a dedicated schema and encryption key of its own. When you create a realm, Drawbridge automatically:

• Creates a Keycloak realm with secure defaults and a dedicated database schema
• Configures OPKSSH client and groups for SSH access control
• Provisions an AES-256-GCM vault encryption key
• Enables event tracking for activity analytics and billing
• Creates an admin user with a temporary password

Each realm supports:

• OIDC & SAML: Standard protocols for single sign-on
• Social Login: Google, LinkedIn, and other identity providers
• Custom Themes: Upload a Keycloak theme JAR to fully brand the login experience
• SCIM Provisioning: Sync users and groups from your existing identity provider
• Event Forwarding: Forward the realm's Keycloak login and admin events, each signed with a per-realm HMAC, to your own HTTPS sink (paid plan)
• Daily Login Tracking: See unique logins per day and per month
• Rename: Change a realm's identifier later from the dashboard's Rename realm action. The realm URL is re-issued, so existing OIDC tokens are invalidated and external apps must be updated to the new issuer; historical invoices and audit-log entries keep their original name.

Secrets Vault

Every realm includes an encrypted secrets vault for storing sensitive application data:

• Encryption: AES-256-GCM envelope encryption with per-realm managed keys (auto-provisioned at realm creation)
• Secret Types: Key-value pairs, TOTP seeds (with live code generation), SSH keys, and file attachments
• Groups: Organize secrets into groups with claim-based access control
• Audit Log: Every create, read, update, and delete is logged with actor, IP, and timestamp (immutable)
• Import: Bulk import from 1Password, Bitwarden, and CSV exports
• Consumer API: Applications read secrets at runtime via /vault-api/{realmName}/secrets

SCIM Provisioning

Connect your existing identity provider to automatically sync users and groups into your realm:

• Enable with one click from the realm overview or via MCP
• Bearer token auth: token is BCrypt-hashed in the database and stored encrypted in the vault
• Guided setup: step-by-step Azure AD instructions provided in the UI
• Supports Okta, Azure AD, OneLogin, JumpCloud, and any SCIM 2.0-compliant provider
• Real-time sync: adds, updates, and deactivations flow automatically

Passwordless SSH (OPKSSH)

Replace static SSH keys with identity-based access. Three deployment models:

Demo Containers

Try it instantly. Drawbridge provisions an ephemeral VM with OPKSSH pre-configured. The user authenticates through your realm, gets a short-lived SSH key, and connects. Containers auto-terminate 30 minutes after creation, active or not.

Bring Your Own Server (BYOS)

Add identity-based SSH to existing Linux and Windows servers (Windows Server 2019 or later):

• Generate an install token from the dashboard or MCP
• Run the one-liner on your server; it installs OPKSSH and connects to your realm
• Existing SSH keys and configuration are not modified
• A sync daemon keeps authorized identities up to date
• Two access tiers: infrastructure (SSH + sudo) and realm-admin (SSH only)
• Windows enrollment runs a PowerShell installer in an elevated session: it enables the Windows OpenSSH server capability when missing, installs OPKSSH v0.14.0, and registers a SYSTEM scheduled task that keeps access rules in sync
• On Windows, admin access follows the local Administrators group (no sudo companion accounts), and the sync task cannot run more often than every 60 seconds (a Task Scheduler limit), so revocations propagate on the next poll

Bring Your Own Cloud (BYOC)

Provision VMs with OPKSSH in your own AWS or Azure account:

• AWS: Deploy a CloudFormation stack to create an IAM cross-account role, then provision VMs
• Azure: Authorize Drawbridge via admin consent, deploy an ARM template for the service principal, then provision VMs
• VMs are configured with OPKSSH, a sync daemon, and a fallback SSH key stored in the vault
• Configurable lifetime from 1 hour to 90 days, or no expiry (defaults to 30 days)
• Full resource cleanup on termination (instances, security groups, NICs, public IPs)
• Health monitoring with automatic status checks

Custom Themes

Upload Keycloak theme JAR files to customize login, registration, and account pages:

• Instant deployment with automatic cache invalidation
• Secure storage in AWS S3 with SHA-256 integrity verification
• Security scanning for FreeMarker injection, class files, and blocked patterns
• Download the current theme at any time
• Free accounts: one custom theme across all realms (you can replace it); a payment method unlocks unlimited themes

Billing

Pay only for what you use with graduated per-call pricing. See the Pricing page for current rates.

An API call includes any realm-scoped request: authentication events, SCIM syncs, vault operations, MCP tool invocations, SAML assertions, and REST API calls.

• First 5,000 calls/month: Free
• 5,001-500,000 calls/month: $3 per 1,000 calls ($0.003 per call)
• 500,001+ calls/month: $2 per 1,000 calls ($0.002 per call)

Billing features:

• Multiple payment methods (credit/debit cards via Stripe)
• Automatic monthly invoicing with itemized per-realm breakdown
• Full invoice history with refund support
• Multiple billing addresses
• Pipeline health monitoring with automatic alerts

MCP Interface

Drawbridge exposes a full MCP server with 51 tools, 2 resources, and an onboarding prompt. Connect from Claude Code, Cursor, Windsurf, or any MCP-compatible client.

Account & Billing:

• getAccountInfo, closeAccount -- account management
• listPaymentTokens, getPaymentLink, checkPaymentStatus, deletePaymentToken -- payments
• createAddress, listAddresses, deleteAddress -- billing addresses
• getInvoiceHistory, getPricingTiers, estimateCost -- billing info

Realm Management:

• listRealms, createRealm, deleteRealm, getAvailableRealmNames -- realm CRUD
• resetRealmAdminPassword -- rotate a still-unclaimed realm admin's temporary password (shown once)
• enableScim, disableScim, regenerateScimToken -- SCIM provisioning
• uploadTheme, deleteTheme, getThemeInfo -- custom themes
• getEventForwarder, configureEventForwarder, verifyEventForwarder, sendEventForwarderTestEvent, removeEventForwarder -- forward realm events to your HTTPS sink (paid plan)

SSH & Infrastructure:

• createContainer, listActiveContainers, terminateContainer -- demo containers
• generateServerInstallToken, listServers, removeServer -- BYOS servers
• createAwsCredential, listCredentials, validateCredential, deleteCredential -- BYOC credentials
• provisionVM, listCloudVMs, terminateVM, getVMEvents -- BYOC VMs

Secrets Vault:

• storeSshKey, listSshKeys, deleteSshKey -- SSH key management

Agent Management (human-only: an agent caller is denied these regardless of its scopes):

• agent_register, agent_list, agent_revoke -- register an agent with its own Keycloak client (client secret shown once), list your agents with status and live delegation, revoke permanently
• delegation_grant, delegation_list, delegation_revoke -- grant an agent its capability scopes and expiry, list delegations, revoke immediately

Resources:

• drawbridge://getting-started -- full onboarding guide
• drawbridge://pricing-tiers -- current pricing data

Prompts:

• accountSetupWalkthrough -- step-by-step setup guide for AI agents

Token lifetime: client_credentials tokens expire on the TTL Keycloak gives you (5 minutes by default). Re-mint by re-posting to the token endpoint. The clientSecret from registration is stable; you only re-register if your principal asks you to start fresh.

Retries and idempotency: All read tools are idempotent. createRealm is not: re-calling with a name you already own creates a suffixed realm (for example acme-2), so check listRealms instead of blindly retrying. enableScim on an already-enabled realm returns a conflict, not a second token (use regenerateScimToken to rotate). SSH key generation mints a new keypair on every call, so cache the result and don't loop on it.

Agents and delegations: Registering an agent provisions a dedicated Keycloak client, so the agent always authenticates as itself; it never holds your password or your token. Registration grants no authority by itself: an agent can call a tool only while a live delegation covers it. A delegation names the agent's capability scopes from a fixed vocabulary of 22, with an expiry clamped to 90 days; one delegation is active per agent, and a new grant supersedes the old one. The platform enforces the delegation on every tool call and fails closed: an unregistered, revoked, expired, or out-of-scope call is denied before it runs, and the denial is audited. Tools outside the grant are also hidden from the agent's tools/list. Revocation and key rotation take effect on the agent's next call; rotation invalidates the old secret immediately, and tokens already issued age out within their 5-minute lifetime. The audit trail (who authorized, what was delegated, every denial) is readable per delegation from the dashboard and the REST API, and security events are stored append-only with hash chaining, so tampering is detectable. Agents are capped at 10 per account and share the 60-calls-per-minute rate limit with human callers. Three realm-credential tools (createRealm, deleteRealm, resetRealmAdminPassword) are human-only outright: no delegation can grant them.

Getting Started

1. Create Your Account

Sign up at drawbridge.sh with Google or LinkedIn. No credit card required -- the free tier includes two realms, a secrets vault, SCIM, and a demo SSH container.

2. Create a Realm

From the Realms page, click Create New Realm and enter a unique name (lowercase letters, digits, and hyphens). Your realm is provisioned instantly with an admin user and a vault encryption key. Use the temporary password to access the Keycloak admin console, or manage everything from the Drawbridge dashboard.

3. Configure Your Realm

From the realm detail page:

• Overview: Issuer URL, user count, login stats, admin credentials
• Theme: Upload a custom Keycloak theme JAR
• SCIM: Enable user sync from your identity provider
• Secrets Vault: Store secrets, configure groups and access control
• Containers: Launch a demo container to try passwordless SSH

4. Add Servers or Cloud VMs (Optional)

From the Servers tab:

• BYOS: Generate an install token (Linux or Windows platform), run the command on your server
• BYOC: Add an AWS or Azure credential, provision VMs in your own cloud account
• Both options configure OPKSSH for identity-based SSH using your realm

5. Connect an MCP Agent (Optional)

The easiest way is the one-line installer, which detects your client (Claude Code, Cursor, Windsurf, VS Code) and configures it to authenticate via a browser login:

curl -fsSL https://api.drawbridge.xorfox.sh/drawbridge/mcp/install | node

To configure Claude Code manually (uses the pre-registered public client and a browser login, with no token to copy):

claude mcp add drawbridge -- npx -y mcp-remote@0.8.5 https://api.drawbridge.xorfox.sh/mcp \
  --static-oauth-client-info '{"client_id":"mcp-remote"}'

For autonomous agents on new accounts (no human, no browser), register via POST /drawbridge/mcp/register, exchange the returned credentials with the client_credentials grant, and pass the resulting token as Authorization: Bearer <token>. A freshly registered agent holds no delegation and can call nothing until your principal grants one (delegation_grant, or the Delegations page on the dashboard). Registration is limited to email addresses that do not already have an account; existing customers use the browser login flow above (or contact support).

6. Add a Payment Method (When Needed)

The free tier covers 5,000 API calls per month. When you need more, go to Billing and add a payment method, or use the getPaymentLink MCP tool.

API Reference

All API endpoints require authentication via Keycloak OAuth 2.0. Include the JWT access token in the Authorization header:

Authorization: Bearer <access_token>

Realms

SCIM

Secrets Vault

Vault Consumer API

Your applications use the consumer API to read secrets at runtime. Authenticate with a JWT from the realm itself (not the drawbridge realm). The token's issuer must match the realm, and the caller's claims must satisfy the secret's group requirements.

Example: Read a secret from your application

Step 1. Get a token from your realm's OIDC endpoint:

TOKEN=$(curl -s -X POST https://sso.drawbridge.xorfox.sh/realms/YOUR_REALM/protocol/openid-connect/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_APP_CLIENT_ID" \
  -d "client_secret=YOUR_APP_CLIENT_SECRET" \
  | jq -r '.access_token')

Step 2. Read the secret by name:

curl -s https://api.drawbridge.xorfox.sh/vault-api/YOUR_REALM/secrets/by-name/DATABASE_PASSWORD \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "id": 42,
  "name": "DATABASE_PASSWORD",
  "secretType": "KEY_VALUE",
  "value": "s3cret-passw0rd",
  "version": 1
}

For TOTP secrets, the response includes a live code and countdown:

{
  "id": 43,
  "name": "GITHUB_TOTP",
  "secretType": "TOTP",
  "totpCode": "482931",
  "totpSecondsRemaining": 17,
  "version": 1
}

Note: Access is controlled by the secret's group claims. If your JWT doesn't have the required claims for a secret's group, the API returns 403 Forbidden. Secrets in the default group are accessible to all authenticated realm users.

BYOS (Bring Your Own Server)

BYOC (Bring Your Own Cloud)

Payment Tokens

Themes

Invoices

Demo Containers

Account

Account Closure

Go to Billing and scroll to the Danger Zone. Account closure is permanent and deletes:

• All realms, users, and authentication settings
• All secrets vault contents and encryption keys
• All themes, SCIM configurations, and demo containers
• All BYOS server connections and BYOC cloud credentials/VMs
• All billing information and payment history
• Your Drawbridge account and Keycloak user

Last updated: Aug 22, 2026