Documentation

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 45 tools for identity, metering, and SSH on your principal's behalf. No human-in-the-loop is needed until your principal must enroll a payment method (getPaymentLink returns a Stripe-hosted URL you hand them).

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.

Overview

Instead of asking your principal to deploy and operate Keycloak, you get one endpoint and these capabilities:

• Realms: Realms with dedicated database schemas, OIDC, SAML, social login, and custom themes. One tool call per realm.
• Vault: AES-256-GCM encrypted storage for API keys, credentials, TOTP seeds, and SSH keys. Claim-gated reads. Every access audit-logged.
• SCIM: Automatic user and group sync from Okta, Azure AD, or any SCIM 2.0 IdP. Enable per realm; tokens are bcrypt-hashed in the DB and stored encrypted in the vault.
• Passwordless SSH: OPKSSH-based identity-bound SSH access. Short-lived keys, automatic revocation when the underlying user is deactivated.
• Bring Your Own Server (BYOS): Add identity-based SSH to your principal's existing Linux servers with a one-liner install token.
• Bring Your Own Cloud (BYOC): Provision VMs with OPKSSH in your principal's AWS or Azure account using a cross-account role / service principal they grant you.
• Demo Containers: Ephemeral 30-minute VMs for end-to-end testing — call createContainer, get an SSH command, hand it to your principal.
• MCP-native: 45 tools, 2 resources, an onboarding prompt. Streamable SSE transport, OAuth2 client_credentials, public registration.
• Per-call metering: First 5,000 API calls free every month, then graduated per-call pricing. Your principal pays via a Stripe-hosted card form; you never touch the PAN.

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 after 30 minutes of inactivity.

Bring Your Own Server (BYOS)

Add identity-based SSH to existing Linux servers:

• 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)

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: 24 hours, 7 days, 30 days, 90 days, or forever
• 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
• One theme per realm (Free tier), unlimited themes (Standard+)

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 45 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

Resources:

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

Prompts:

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

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, 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 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>. 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