# Get Agent Counts Source: https://docs.barndoor.ai/api-reference/agents/counts/getAgentCounts GET /api/agents/counts Get counts of agents grouped by type (internal vs external). # Delete Agent by Id Source: https://docs.barndoor.ai/api-reference/agents/deleteAgent DELETE /api/agents/{agent_id} Unregister an agent from Barndoor. This removes the agent's registration but does not delete the underlying application directory. The agent can be re-registered using the same application_directory_id. # GET Agent by Id Source: https://docs.barndoor.ai/api-reference/agents/getAgent GET /api/agents/{agent_id} Get details of a specific agent by ID, including its application directory configuration. # List Agents Source: https://docs.barndoor.ai/api-reference/agents/listAgents GET /api/agents List registered agents with pagination. # Register Agent Source: https://docs.barndoor.ai/api-reference/agents/registerAgent POST /api/agents Register a new agent with Barndoor. Agents represent AI applications that can access MCP servers through Barndoor. Each agent must be associated with an application directory (OAuth client configuration). # Delete connection Source: https://docs.barndoor.ai/api-reference/connections/deleteConnection DELETE /api/servers/{server_id}/connection Delete the current user's connection to this server. This will remove the connection record and clean up any stored OAuth credentials. The user will need to reconnect to use this server again. # Get Connection Status Source: https://docs.barndoor.ai/api-reference/connections/getConnectionStatus GET /api/servers/{server_id}/connection Get the user's connection status for a specific server. Used to poll connection status during OAuth flows. # Initiate OAuth connection Source: https://docs.barndoor.ai/api-reference/connections/initiateConnection POST /api/servers/{server_id}/connect Initiate OAuth connection flow for a server. Returns an authorization URL that the user should visit to complete the OAuth flow. The server must have OAuth configuration set up by an admin. # Get User Info Source: https://docs.barndoor.ai/api-reference/identity/getUserInfo POST /api/identity/userinfo Returns identity information for the user associated with a Barndoor API key. Pass your API key (beginning with `bdai_`) in the JSON request body — no `Authorization` header is required. Generate an API key from the Barndoor dashboard at **Settings → API Tokens**. This endpoint is useful for verifying which user and organization a token belongs to, especially when managing multiple test accounts or debugging authentication. # Barndoor API Reference Source: https://docs.barndoor.ai/api-reference/introduction ## Welcome Barndoor provides a robust API that allows developers to securely access their dashboard environment’s data and programmatically update settings relevant to their Barndoor organization. ## Authentication All API endpoints are authenticated using a user Bearer token or a Platform API key. * To obtain a platform API key, navigate to: [https://app.barndoor.ai/settings/tokens](https://app.barndoor.ai/settings/tokens) * To obtain a user token, use the Barndoor SDK's loginInteractive() method ```code theme={null} const sdk = await loginInteractive(); ``` See [here](/sdks/introduction) for more info. # Create an Org API Key Source: https://docs.barndoor.ai/api-reference/llm-gateway/api-keys/createApiKey api-reference/llm-gateway-openapi.yml post /admin/api-keys Creates a new `bd-...` gateway API key. The raw key is returned in this response and never again — copy it immediately. Either assign the key to a `user_id` or bind it to a `group_name`; not both. Creates an organization-managed `bd-…` API key for the LLM Gateway runtime (`/v1/chat/completions`, `/v1/messages`, `/v1/embeddings`, etc.). The full key value is returned **only in this response**. Barndoor stores a one-way hash and cannot reveal the raw key again — copy it immediately, e.g. into your secrets manager or CI environment. A key is either **assigned to a single user** or **bound to an IdP group**, not both. Use the binding to control scope of: * per-user/per-group [token budgets](/api-reference/llm-gateway/token-budgets/listBudgets) * per-user/per-group [rate limits](/api-reference/llm-gateway/rate-limits/listRateLimits) * per-user/per-group [model access policies](/api-reference/llm-gateway/model-access/listModelAccess) ## Example: a CI service-account key ```bash theme={null} curl -X POST https://app.barndoor.ai/api/llm-gateway/admin/api-keys \ -H "Authorization: Bearer $BARNDOOR_JWT" \ -H "Content-Type: application/json" \ -d '{ "name": "GitHub Actions runner", "group_name": "ci", "expires_at": "2026-12-31T23:59:59Z" }' ``` The response includes the raw `key`. From that point on, callers can use it as: ```bash theme={null} curl https://app.barndoor.ai/api/llm-gateway/v1/chat/completions \ -H "Authorization: Bearer bd-..." \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini", "messages": [...] }' ``` To rotate a key, create a new one and revoke the old one with [`DELETE /admin/api-keys/{id}`](/api-reference/llm-gateway/api-keys/revokeApiKey). # Get an API key Source: https://docs.barndoor.ai/api-reference/llm-gateway/api-keys/getApiKey api-reference/llm-gateway-openapi.yml get /admin/api-keys/{id} # List org API keys Source: https://docs.barndoor.ai/api-reference/llm-gateway/api-keys/listApiKeys api-reference/llm-gateway-openapi.yml get /admin/api-keys Lists every gateway API key in the organization (one entry per key). The raw key value is never returned — only its prefix and metadata. # Revoke an API key Source: https://docs.barndoor.ai/api-reference/llm-gateway/api-keys/revokeApiKey api-reference/llm-gateway-openapi.yml delete /admin/api-keys/{id} Revoking a key disables it for all future requests. # Create a Credential Source: https://docs.barndoor.ai/api-reference/llm-gateway/credentials/createCredential api-reference/llm-gateway-openapi.yml post /admin/connections Stores a new upstream credential. The plaintext `api_key` (or `credentials` object) is written to Barndoor's encrypted secret store and is never returned by any endpoint. Create a reusable upstream credential. One credential can back many providers (for example, a single OpenAI key shared across multiple environments or routes). ## Choosing the auth method The `model_provider` and `auth_type` together determine which fields are required: * **API key (`auth_type: api_key`)** — pass `api_key` with the upstream key. * **AWS Bedrock IAM role (`auth_type: aws_role`)** — pass `credentials` with `iam_role_arn` and `external_id`. Use [`POST /admin/connections/aws-role-validate`](/api-reference/llm-gateway/credentials/validateAwsRole) to confirm Barndoor can assume the role before saving. * **Google Vertex (`auth_type: google_adc`, `google_service_account`, `google_impersonation`)** — for service accounts, pass the JSON key fields under `credentials`. Use [`POST /admin/connections/google-vertex-validate`](/api-reference/llm-gateway/credentials/validateGoogleVertex) to confirm end-to-end access. * **Anthropic OAuth passthrough** — configured directly on a provider; this endpoint is not used for OAuth providers. The plaintext key (or `credentials` JSON) is written to Barndoor's encrypted secret store and is never returned by any subsequent API call. Update or rotate it later with [`PUT /admin/connections/{id}`](/api-reference/llm-gateway/credentials/updateCredential). ## Example ```bash theme={null} curl -X POST https://app.barndoor.ai/api/llm-gateway/admin/connections \ -H "Authorization: Bearer $BARNDOOR_JWT" \ -H "Content-Type: application/json" \ -d '{ "name": "OpenAI Production", "model_provider": "openai", "base_url": "https://api.openai.com/v1", "api_key": "sk-..." }' ``` For a guided walkthrough, see [Configure the Gateway](/how-tos/llm-gateway-quickstart#admin-configure-the-gateway). # Delete a credential Source: https://docs.barndoor.ai/api-reference/llm-gateway/credentials/deleteCredential api-reference/llm-gateway-openapi.yml delete /admin/connections/{id} # Get Barndoor's AWS principal Source: https://docs.barndoor.ai/api-reference/llm-gateway/credentials/getAwsRoleConfig api-reference/llm-gateway-openapi.yml get /admin/connections/aws-role-config Returns the AWS IAM principal customers should add to the trust policy of any role they hand out to Barndoor for AWS Bedrock IAM-role auth. # Get AWS trust info Source: https://docs.barndoor.ai/api-reference/llm-gateway/credentials/getAwsTrustInfo api-reference/llm-gateway-openapi.yml get /admin/connections/{id}/aws-trust-info Returns the Barndoor principal ARN and external ID for an AWS-role credential. Useful for re-auditing the trust policy after the fact. # Get a credential Source: https://docs.barndoor.ai/api-reference/llm-gateway/credentials/getCredential api-reference/llm-gateway-openapi.yml get /admin/connections/{id} # List credentials Source: https://docs.barndoor.ai/api-reference/llm-gateway/credentials/listCredentials api-reference/llm-gateway-openapi.yml get /admin/connections Returns every reusable credential configured in your organization. # Update a credential Source: https://docs.barndoor.ai/api-reference/llm-gateway/credentials/updateCredential api-reference/llm-gateway-openapi.yml put /admin/connections/{id} Patches a credential. Only fields you send are changed. If you include `api_key` or `credentials` the upstream secret is rotated. # Validate AWS role access Source: https://docs.barndoor.ai/api-reference/llm-gateway/credentials/validateAwsRole api-reference/llm-gateway-openapi.yml post /admin/connections/aws-role-validate Performs a real STS assume-role chain against the supplied role to confirm Barndoor can reach Bedrock. Returns the AWS error verbatim if validation fails — useful for iterating on the trust policy before saving the credential. # Validate Google Vertex access Source: https://docs.barndoor.ai/api-reference/llm-gateway/credentials/validateGoogleVertex api-reference/llm-gateway-openapi.yml post /admin/connections/google-vertex-validate Fetches a token via your chosen Vertex auth method and asks Vertex about a model, confirming end-to-end that both auth and model access work before saving the credential. # Get governance configuration Source: https://docs.barndoor.ai/api-reference/llm-gateway/governance/getGovernanceConfig api-reference/llm-gateway-openapi.yml get /admin/governance-config # Update governance configuration Source: https://docs.barndoor.ai/api-reference/llm-gateway/governance/updateGovernanceConfig api-reference/llm-gateway-openapi.yml put /admin/governance-config # LLM Gateway API Source: https://docs.barndoor.ai/api-reference/llm-gateway/introduction Programmatically configure and operate the Barndoor LLM Gateway: providers, model routes, pricing, governance, and gateway API keys. The LLM Gateway API is the same surface that powers the **LLM Management** hub (including its **Controls** sections) and **Settings → My Models** in the Barndoor portal — exposed so platform teams can script provisioning, run automated audits, and integrate with their own management tooling. These endpoints control how the gateway routes traffic. They are **distinct** from the runtime LLM endpoints (`/v1/chat/completions`, `/v1/messages`, `/v1/embeddings`, …) — those are documented in [Quickstart Guide](/how-tos/llm-gateway-quickstart#sending-requests). ## Base URL All requests are issued against your Barndoor instance. The administrative API sits under `/api/llm-gateway`: ``` https://app.barndoor.ai/api/llm-gateway ``` Replace `app.barndoor.ai` with your tenant host on Enterprise. ## Authentication Endpoints require a **JWT Bearer token** issued by your organization's identity provider — the same login flow you use for the Barndoor portal. The easiest way to obtain a token from a script is the Barndoor SDK: ```ts theme={null} import { loginInteractive } from "@barndoor/sdk"; const sdk = await loginInteractive(); // sdk includes the bearer token; pass it on every API call. ``` Send the token on every request: ```bash theme={null} curl https://app.barndoor.ai/api/llm-gateway/admin/providers \ -H "Authorization: Bearer eyJhbGciOi..." ``` The `bd-…` API keys you create through these endpoints are for the runtime proxy (`/v1/chat/completions`, `/v1/messages`, etc.) — they are **not** accepted on `/admin/...` or `/user/...` paths. Use a JWT for administration and a `bd-…` key for traffic. ## Permissions | Endpoint family | Required role | | --------------- | ---------------------------------------------------- | | `/admin/...` | `admin` (or higher) on the calling user | | `/user/...` | Any authenticated user (results scoped to that user) | ## Conventions * Every resource is automatically scoped to the caller's organization. There is no `org_id` parameter on any endpoint — it's resolved from your JWT. * All timestamps are RFC 3339 (`2026-06-12T18:30:00Z`). * All identifiers are UUIDv4. * `PUT` / update endpoints accept partial bodies — fields you omit are left unchanged. A handful of endpoints also distinguish **omitted** from **explicit `null`** on `Option`-typed columns; the affected fields are documented inline. ## Errors Errors come back with a stable JSON shape and an HTTP status code that matches the failure mode: ```json theme={null} { "error": "BadRequest", "message": "request_timeout_secs must be between 1 and 3600" } ``` | Status | Meaning | | ------ | ------------------------------------------------------------ | | `400` | Validation failure — fix the request body and retry | | `401` | Missing or invalid JWT | | `403` | The caller's role does not allow this action | | `404` | Resource does not exist (or belongs to another organization) | | `409` | Conflicts with existing data (rare; specifics in `message`) | | `5xx` | Transient gateway error | ## Resource map Reusable upstream credentials — API keys, AWS roles, Vertex service accounts. Named upstream providers backed by a credential and a model family. Map a client-facing alias to one or more provider/model pairs with failover. Per-million-token costs and history; powers usage and budget reporting. Requests-per-minute and tokens-per-minute caps. Daily, weekly, and monthly token / cost budgets with alert thresholds. Allow- and deny-list policies for models, providers, or aliases. Routing policies that pick a target model per-request. Org-wide gateway behavior toggles. Operational view of upstream ejection and recovery. Org-managed `bd-…` gateway API keys. Personal API keys and the model catalog scoped to the calling user. ## Where to next * New to the gateway? Read [Using the LLM Gateway](/how-tos/use-llm-gateway). * Looking for the runtime proxy reference (chat completions, messages, embeddings)? See the [Quickstart Guide](/how-tos/llm-gateway-quickstart). # Create a model access policy Source: https://docs.barndoor.ai/api-reference/llm-gateway/model-access/createModelAccess api-reference/llm-gateway-openapi.yml post /admin/model-access Either an allowlist (only listed targets are permitted) or a denylist (listed targets are blocked). Targets can specify a model alias, an upstream model, a provider, or a (provider, model) combination. # Delete a model access policy Source: https://docs.barndoor.ai/api-reference/llm-gateway/model-access/deleteModelAccess api-reference/llm-gateway-openapi.yml delete /admin/model-access/{id} # List model access policies Source: https://docs.barndoor.ai/api-reference/llm-gateway/model-access/listModelAccess api-reference/llm-gateway-openapi.yml get /admin/model-access # Update a model access policy Source: https://docs.barndoor.ai/api-reference/llm-gateway/model-access/updateModelAccess api-reference/llm-gateway-openapi.yml put /admin/model-access/{id} # Archive or cancel a pricing version Source: https://docs.barndoor.ai/api-reference/llm-gateway/model-pricing/archivePricing api-reference/llm-gateway-openapi.yml delete /admin/model-pricing/{id} Behavior depends on whether the targeted version is in the past or future: - Future-dated version → cancels that single scheduled change. - Current effective version → archives the rule entirely. Any pending scheduled changes are also cancelled, and the rule disappears from the active pricing list. The full history (including the archive event) remains queryable. # Create or Schedule Pricing Source: https://docs.barndoor.ai/api-reference/llm-gateway/model-pricing/createPricing api-reference/llm-gateway-openapi.yml post /admin/model-pricing - Omit (or `null`) `effective_from` to activate the price now. - Pass a future `effective_from` to schedule the change ahead of time. Creates a new pricing version for a model. Pricing drives every cost-aware feature on the platform — usage attribution, spend reporting, and [token budgets](/api-reference/llm-gateway/token-budgets/listBudgets) with a `cost_limit`. ## Activate now or schedule for later The `effective_from` field decides whether the change is immediate or scheduled: * **Omit (or `null`)** — the price activates immediately and replaces the current effective price for this rule. * **Future timestamp** — the price activates on that date, recorded as a scheduled change. Visible to admins via the [history](/api-reference/llm-gateway/model-pricing/getPricingHistory) endpoint and the **Scheduled** affordance in the portal. Past versions are immutable; to correct a mistake, create a new version with an immediate `effective_from`. ## Sync mode `sync_mode` controls whether Barndoor's seeded defaults can move this row later: * `pinned` (default for manually-created rules) — never auto-sync. * `tracking` — show the user a prompt when defaults change. * `auto` — silently follow the default. Useful when you want to outsource pricing maintenance entirely to Barndoor. ## Example ```bash theme={null} curl -X POST https://app.barndoor.ai/api/llm-gateway/admin/model-pricing \ -H "Authorization: Bearer $BARNDOOR_JWT" \ -H "Content-Type: application/json" \ -d '{ "model_provider": "openai", "model_pattern": "gpt-4o-mini", "input_cost_per_million_tokens": 0.15, "output_cost_per_million_tokens": 0.60, "sync_mode": "pinned", "change_reason": "Q1 2026 negotiated discount" }' ``` For wildcards, scheduling, and the four-tier resolution order, see [Manage Model Pricing](/how-tos/manage-model-pricing). # Get a pricing rule's history Source: https://docs.barndoor.ai/api-reference/llm-gateway/model-pricing/getPricingHistory api-reference/llm-gateway-openapi.yml get /admin/model-pricing/history Returns every version of a single rule (current, scheduled, archived, and prior live versions), newest first. # Look up a single pricing version Source: https://docs.barndoor.ai/api-reference/llm-gateway/model-pricing/getPricingVersion api-reference/llm-gateway-openapi.yml get /admin/model-pricing/version/{id} Returns one specific version of a pricing rule by id. Useful for resolving a `pricing_rule_id` recorded in an audit event when that version is no longer the current one. # Import default pricing Source: https://docs.barndoor.ai/api-reference/llm-gateway/model-pricing/importPricingDefaults api-reference/llm-gateway-openapi.yml post /admin/model-pricing/import-defaults Inserts entries from Barndoor's managed pricing catalog into your organization. Existing rows are not touched (use `sync-defaults` to update those). # List archived pricing rules Source: https://docs.barndoor.ai/api-reference/llm-gateway/model-pricing/listArchivedPricing api-reference/llm-gateway-openapi.yml get /admin/model-pricing/archived # List pricing rules Source: https://docs.barndoor.ai/api-reference/llm-gateway/model-pricing/listPricing api-reference/llm-gateway-openapi.yml get /admin/model-pricing One row per logical pricing rule, each with the currently-effective version, a `version_count`, and a `scheduled_count` of any future-dated changes waiting to activate. # List Barndoor's default pricing Source: https://docs.barndoor.ai/api-reference/llm-gateway/model-pricing/listPricingDefaults api-reference/llm-gateway-openapi.yml get /admin/model-pricing/defaults The default pricing catalog Barndoor maintains. Use as a starting point for `import-defaults` and `sync-defaults`. # Restore an archived pricing rule Source: https://docs.barndoor.ai/api-reference/llm-gateway/model-pricing/restorePricing api-reference/llm-gateway-openapi.yml post /admin/model-pricing/{id}/restore Resurrects a previously archived pricing rule. The id should be the archived version's id, as returned from `GET /admin/model-pricing/archived`. # Sync to default pricing Source: https://docs.barndoor.ai/api-reference/llm-gateway/model-pricing/syncPricingDefaults api-reference/llm-gateway-openapi.yml post /admin/model-pricing/sync-defaults Overwrites pricing rows in your org whose costs have drifted from the current Barndoor-managed defaults. Org-managed (`pinned`) rows are not touched. # Edit a scheduled pricing version Source: https://docs.barndoor.ai/api-reference/llm-gateway/model-pricing/updatePricing api-reference/llm-gateway-openapi.yml put /admin/model-pricing/{id} Updates a future-dated (scheduled) pricing version in place. Past versions are immutable — to change the active price create a new version via `POST /admin/model-pricing` instead. # Create a Model Route Source: https://docs.barndoor.ai/api-reference/llm-gateway/model-routes/createRoute api-reference/llm-gateway-openapi.yml post /admin/model-mappings Creates a model route. A 1:1 enablement (`model_alias == upstream_model`) for an existing provider/model pair will fold into the existing row rather than failing — this lets you re-issue the same create call idempotently from automation. A **Model Route** maps a client-facing alias to a (provider, upstream model) pair. Multiple routes can share the same `model_alias` — the gateway tries them in `priority` order (lowest first) and fails over to the next on upstream errors. ## Two kinds of routes * **1:1 enablement (`model_alias == upstream_model`)** — exposes the upstream model under its own name, addressable as `/`. Defaults to `bare_alias: false`. Re-issuing this call for an existing enablement folds into the existing row, making it idempotent. * **Custom alias (`model_alias != upstream_model`)** — exposes the model under a friendly alias (e.g. `team-coding-model`). Defaults to `bare_alias: true` so callers can use the plain name in `model`. Requires an existing 1:1 enablement on the same `(provider, upstream_model)` pair. ## Example: an alias with failover The simplest production setup is one alias backed by a primary route plus one or more failover routes: ```bash theme={null} # Route 1: primary (priority 0) curl -X POST https://app.barndoor.ai/api/llm-gateway/admin/model-mappings \ -H "Authorization: Bearer $BARNDOOR_JWT" \ -H "Content-Type: application/json" \ -d '{ "provider_id": "", "model_alias": "claude-opus-4-8", "upstream_model": "claude-opus-4-8", "priority": 0, "bare_alias": true }' # Route 2: failover on Bedrock (priority 1) curl -X POST https://app.barndoor.ai/api/llm-gateway/admin/model-mappings \ -H "Authorization: Bearer $BARNDOOR_JWT" \ -H "Content-Type: application/json" \ -d '{ "provider_id": "", "model_alias": "claude-opus-4-8", "upstream_model": "us.anthropic.claude-opus-4-8", "priority": 1, "bare_alias": true }' ``` For more on failover, retry policies, and bare aliases see [Define Model Routes](/how-tos/llm-gateway-quickstart#step-5-define-model-routes). # Delete a model route Source: https://docs.barndoor.ai/api-reference/llm-gateway/model-routes/deleteRoute api-reference/llm-gateway-openapi.yml delete /admin/model-mappings/{id} # List all model routes Source: https://docs.barndoor.ai/api-reference/llm-gateway/model-routes/listAllRoutes api-reference/llm-gateway-openapi.yml get /admin/model-mappings Returns every model route in the org, with their owning provider's name. # List a provider's model routes Source: https://docs.barndoor.ai/api-reference/llm-gateway/model-routes/listProviderRoutes api-reference/llm-gateway-openapi.yml get /admin/providers/{provider_id}/model-mappings # Reorder model routes Source: https://docs.barndoor.ai/api-reference/llm-gateway/model-routes/reorderRoutes api-reference/llm-gateway-openapi.yml put /admin/model-mappings/reorder Bulk-update the `priority` of multiple routes in one call. Used to change the failover order for routes that share an alias. # Update a model route Source: https://docs.barndoor.ai/api-reference/llm-gateway/model-routes/updateRoute api-reference/llm-gateway-openapi.yml put /admin/model-mappings/{id} # Create a Provider Source: https://docs.barndoor.ai/api-reference/llm-gateway/providers/createProvider api-reference/llm-gateway-openapi.yml post /admin/providers Creates a new named provider. Either supply a `connection_id` to share an existing credential, or supply `api_key` / `credentials` to create an inline secret as part of the request. Pass `models` to enable a list of upstream model names as 1:1 routes in the same call — equivalent to creating each route individually afterwards. A **Provider** is a named upstream that authenticates with one credential and serves a model family. Provider creation supports two modes: * **Inline credential** — pass `api_key` (or `credentials`) directly. Barndoor stores the secret in its encrypted secret store, scoped to this provider. * **Shared credential** — pass `connection_id` referencing an existing [Credential](/api-reference/llm-gateway/credentials/listCredentials). The provider's `auth_type`, `base_url`, and settings inherit from the shared record. ## Auto-enabling models in one call Pass a list of upstream model names in `models` and Barndoor will create a 1:1 [Model Route](/api-reference/llm-gateway/model-routes/listAllRoutes) for each one in the same call. The route's alias matches the upstream model name so callers can address it as `/`. Add bare-name aliases or failover routes afterwards via the Model Routes endpoints. ## Example ```bash theme={null} curl -X POST https://app.barndoor.ai/api/llm-gateway/admin/providers \ -H "Authorization: Bearer $BARNDOOR_JWT" \ -H "Content-Type: application/json" \ -d '{ "name": "OpenAI Production (US)", "model_provider": "openai", "base_url": "https://api.openai.com/v1", "connection_id": "4f8b2a3c-12ee-4d92-9c7b-e7d2f8b0a111", "models": ["gpt-4o-mini", "gpt-4o", "text-embedding-3-large"] }' ``` See the [Quickstart Guide](/how-tos/llm-gateway-quickstart#step-2-create-a-provider) for the full walkthrough. # Delete a provider Source: https://docs.barndoor.ai/api-reference/llm-gateway/providers/deleteProvider api-reference/llm-gateway-openapi.yml delete /admin/providers/{id} Deleting a provider also removes every model route that pointed at it. # Get a provider Source: https://docs.barndoor.ai/api-reference/llm-gateway/providers/getProvider api-reference/llm-gateway-openapi.yml get /admin/providers/{id} # List the provider catalog Source: https://docs.barndoor.ai/api-reference/llm-gateway/providers/listProviderCatalog api-reference/llm-gateway-openapi.yml get /admin/provider-catalog Read-only catalog of upstream providers Barndoor knows about. Use these entries as templates when creating providers — `slug`, `default_base_url`, `default_models`, and `auth_type` are pre-filled sensible defaults. # List providers Source: https://docs.barndoor.ai/api-reference/llm-gateway/providers/listProviders api-reference/llm-gateway-openapi.yml get /admin/providers # Update a provider Source: https://docs.barndoor.ai/api-reference/llm-gateway/providers/updateProvider api-reference/llm-gateway-openapi.yml put /admin/providers/{id} Patches a provider. To detach a provider from a shared credential and switch it back to an inline API key, send `connection_id: null` and the new `api_key` (or `credentials`) in the same request. # Create a rate limit Source: https://docs.barndoor.ai/api-reference/llm-gateway/rate-limits/createRateLimit api-reference/llm-gateway-openapi.yml post /admin/rate-limits # Delete a rate limit Source: https://docs.barndoor.ai/api-reference/llm-gateway/rate-limits/deleteRateLimit api-reference/llm-gateway-openapi.yml delete /admin/rate-limits/{id} # Get live rate-limit status Source: https://docs.barndoor.ai/api-reference/llm-gateway/rate-limits/getRateLimitStatus api-reference/llm-gateway-openapi.yml get /admin/rate-limits/status Returns each enabled rate-limit policy with its current 60-second window usage (requests and tokens). # List rate limits Source: https://docs.barndoor.ai/api-reference/llm-gateway/rate-limits/listRateLimits api-reference/llm-gateway-openapi.yml get /admin/rate-limits # Update a rate limit Source: https://docs.barndoor.ai/api-reference/llm-gateway/rate-limits/updateRateLimit api-reference/llm-gateway-openapi.yml put /admin/rate-limits/{id} # Get Route Health Source: https://docs.barndoor.ai/api-reference/llm-gateway/route-health/getRouteHealth api-reference/llm-gateway-openapi.yml get /admin/llm-gw/route-health Returns a per-route operational view of upstream health: which routes are currently healthy, half-open (probing), or ejected (cooling down), along with consecutive-failure counts and recent state transitions. Useful for dashboards and incident triage. Returns a per-route operational view of upstream health. Useful for dashboards, alerting integrations, and incident triage. ## Route states | State | Meaning | | ----------- | ----------------------------------------------------------------------------------------------------------------------------- | | `healthy` | The route is serving traffic normally. | | `half_open` | The route was recently ejected; the gateway is letting a small probe of traffic through to test recovery. | | `ejected` | The route has been temporarily removed from the failover loop. New traffic will skip it until `eject_remaining_secs` elapses. | `cooldown_reason` explains *why* a route is in cooldown: * `rolling_failures` — too many upstream errors in the rolling window. * `rate_limited` — the upstream returned 429s faster than the route's retry policy could absorb them. ## Recovery Routes recover automatically as cooldown windows expire and probe traffic succeeds. To force a route back to healthy immediately — for example after an upstream incident is resolved — call [`POST /admin/llm-gw/route-health/{provider_id}/reset`](/api-reference/llm-gateway/route-health/resetRouteHealth). # Reset a route to healthy Source: https://docs.barndoor.ai/api-reference/llm-gateway/route-health/resetRouteHealth api-reference/llm-gateway-openapi.yml post /admin/llm-gw/route-health/{provider_id}/reset Force a `(provider, upstream model)` route back to healthy, clearing any active cooldown both on the local pod and across the fleet. Useful after an upstream incident is resolved and you don't want to wait for natural recovery. # Create a smart-model policy Source: https://docs.barndoor.ai/api-reference/llm-gateway/smart-models/createSmartModel api-reference/llm-gateway-openapi.yml post /admin/smart-models # Delete a smart-model policy Source: https://docs.barndoor.ai/api-reference/llm-gateway/smart-models/deleteSmartModel api-reference/llm-gateway-openapi.yml delete /admin/smart-models/{id} # List smart-model policies Source: https://docs.barndoor.ai/api-reference/llm-gateway/smart-models/listSmartModels api-reference/llm-gateway-openapi.yml get /admin/smart-models # Preview a smart-model decision Source: https://docs.barndoor.ai/api-reference/llm-gateway/smart-models/previewSmartModel api-reference/llm-gateway-openapi.yml post /admin/smart-models/preview Dry-runs the determiner against an in-flight policy draft and a sample request body. Useful for checking how a new policy would route real traffic before saving it. # Update a smart-model policy Source: https://docs.barndoor.ai/api-reference/llm-gateway/smart-models/updateSmartModel api-reference/llm-gateway-openapi.yml put /admin/smart-models/{id} # Create a token budget Source: https://docs.barndoor.ai/api-reference/llm-gateway/token-budgets/createBudget api-reference/llm-gateway-openapi.yml post /admin/budgets # Delete a token budget Source: https://docs.barndoor.ai/api-reference/llm-gateway/token-budgets/deleteBudget api-reference/llm-gateway-openapi.yml delete /admin/budgets/{id} # Get live budget status Source: https://docs.barndoor.ai/api-reference/llm-gateway/token-budgets/getBudgetStatus api-reference/llm-gateway-openapi.yml get /admin/budgets/status Returns each budget with its current period's usage and percentage. # List token budgets Source: https://docs.barndoor.ai/api-reference/llm-gateway/token-budgets/listBudgets api-reference/llm-gateway-openapi.yml get /admin/budgets # Update a token budget Source: https://docs.barndoor.ai/api-reference/llm-gateway/token-budgets/updateBudget api-reference/llm-gateway-openapi.yml put /admin/budgets/{id} # Create a personal API key Source: https://docs.barndoor.ai/api-reference/llm-gateway/user/createUserApiKey api-reference/llm-gateway-openapi.yml post /user/api-keys Creates an API key owned by the authenticated user. Equivalent to the Settings - My Models flow in the Barndoor portal. # List my API keys Source: https://docs.barndoor.ai/api-reference/llm-gateway/user/listUserApiKeys api-reference/llm-gateway-openapi.yml get /user/api-keys Lists the gateway API keys created by the authenticated user. # List models I can call Source: https://docs.barndoor.ai/api-reference/llm-gateway/user/listUserModels api-reference/llm-gateway-openapi.yml get /user/models Returns every model the authenticated user is allowed to call, filtered by your organization's model-access policies and the user's IdP groups and roles. Use the `display_model` field as the value of the `model` parameter on `/v1/...` requests. # Revoke one of my API keys Source: https://docs.barndoor.ai/api-reference/llm-gateway/user/revokeUserApiKey api-reference/llm-gateway-openapi.yml delete /user/api-keys/{id} # MCP server proxy endpoint Source: https://docs.barndoor.ai/api-reference/mcp/proxyMcpRequest get /mcp/{mcp_server_name} Proxies MCP JSON-RPC requests to third-party servers with automatic authentication. This endpoint supports both regular Streamable HTTP requests and Server-Sent Events (SSE) for real-time MCP protocol communication. ## Usage - **JSON-RPC**: Send MCP protocol requests as JSON - **SSE Streaming**: Use `Accept: text/event-stream` for real-time communication - **Session Management**: Include `x-mcp-session-id` header for session tracking ## Authentication Flow 1. User must first connect to the server via `/api/servers/{server_id}/connect` 2. Complete OAuth flow for the third-party service 3. Use this endpoint to proxy MCP requests with automatic credential injection # Clone Policy Source: https://docs.barndoor.ai/api-reference/policies/clonePolicy POST /api/v2/policies/{policy_id}/clone Clone an existing policy, creating a new policy with the same configuration but with a modified name (appending " Copy") and DRAFT status. # Create or Update Policy Source: https://docs.barndoor.ai/api-reference/policies/createPolicy POST /api/policy This endpoint creates a policy in the v2 policy service. ## v2 request shape The v2 API accepts a single policy object. It no longer uses the old `policies[].resourcePolicy` wrapper. Important fields: * `name`: unique policy name within the organization * `mcp_server_id`: target MCP server * `application_ids`: agents/applications this policy applies to * `status`: `DRAFT`, `ACTIVE`, `INACTIVE`, or `ARCHIVED` * `rules`: array of rule objects using `authorized`, `actions`, `roles_groups`, and optional `condition` Example: ```json theme={null} { "name": "Slack outbound policy", "description": "Default outbound Slack controls for the support agent.", "support_contact": "platform@company.com", "tags": ["slack", "support"], "status": "DRAFT", "mcp_server_id": "server_123", "application_ids": ["agent_456"], "rules": [ { "name": "allow_all", "authorized": true, "actions": ["*"], "roles_groups": ["*"] }, { "name": "block_general_channel", "authorized": false, "actions": ["tools/call:chat_postMessage"], "roles_groups": ["*"], "condition": { "match": { "all": { "of": [ { "expr": "request.resource.attr.channel == \"general\"" } ] } } } } ] } ``` For a comprehensive guide, see [Manage Access Policies](/how-tos/manage-policies). # Disable Restriction Source: https://docs.barndoor.ai/api-reference/policies/disableRestriction PUT /api/policies/restrictions/disable/{restriction_name} # Enable Restriction Source: https://docs.barndoor.ai/api-reference/policies/enableRestriction PUT /api/policies/restrictions/enable/{restriction_name} # Get Filter Definitions Source: https://docs.barndoor.ai/api-reference/policies/getFilterDefinitions GET /api/v2/policies/filter-definitions Return filter categories for the policies list UI. Static filter options for status, plus dynamic filters for MCP servers and agents based on the organization's registry. # Get Policies Summary Source: https://docs.barndoor.ai/api-reference/policies/getPoliciesSummary GET /api/v2/policies/summary Return summary counts of policies by status. # Get Policy Source: https://docs.barndoor.ai/api-reference/policies/getPolicy GET /api/v2/policies/{policy_id} # List Policies Source: https://docs.barndoor.ai/api-reference/policies/listPolicies GET /api/v2/policies # List Policy Revisions Source: https://docs.barndoor.ai/api-reference/policies/listPolicyRevisions GET /api/v2/policies/{policy_id}/revisions List all revisions for a given policy with pagination. Uses the same authorization as get_policy - if a user can read a policy, they can view its revision history. Args: changes_summary: Include human-readable change descriptions in response # Reload Policy Cache Source: https://docs.barndoor.ai/api-reference/policies/reloadCache POST /api/reload-cache # Update Policy Source: https://docs.barndoor.ai/api-reference/policies/updatePolicy PATCH /api/v2/policies/{policy_id} # Validate Policy Source: https://docs.barndoor.ai/api-reference/policies/validatePolicy POST /api/v2/policies/validate Validate a policy before creation or update. Checks for duplicate names and overlapping MCP server/agent combinations. When exclude_policy_id is provided (edit mode), that policy is excluded from validation. # Create MCP Server Source: https://docs.barndoor.ai/api-reference/servers/createServer POST /api/servers Create a new MCP server instance from a server directory template. The server will be created in `pending` status until OAuth credentials are configured. If `client_id` and `client_secret` are provided, the server will be set to `active` status. # Delete Server by Id Source: https://docs.barndoor.ai/api-reference/servers/deleteServer DELETE /api/servers/{server_id} Delete an MCP server and all associated connections. This will: - Remove all user connections to this server - Clean up stored OAuth credentials - Delete the server configuration For custom server types, this will also delete the associated server directory. # Get Server by Id Source: https://docs.barndoor.ai/api-reference/servers/getServer GET /api/servers/{server_id} Get detailed information about a specific MCP server. Returns extended information including MCP URL if available. # List MCP servers Source: https://docs.barndoor.ai/api-reference/servers/listServers get /api/servers List all MCP servers available to the caller's organization. Returns paginated results with server details including connection status. # Update MCP Server Source: https://docs.barndoor.ai/api-reference/servers/updateServer PUT /api/servers/{server_id} Update an existing MCP server's configuration. You can update the name, slug, OAuth credentials, and metadata. If updating OAuth credentials, provide the actual values (not obfuscated). # SSE server proxy endpoint Source: https://docs.barndoor.ai/api-reference/sse/proxySSERequest get /sse/{mcp_server_name} Server-Sent Events proxy endpoint for real-time streaming communication with third-party servers. This endpoint provides dedicated SSE streaming capabilities separate from the MCP protocol, allowing for custom event streaming and real-time data flows. ## Usage - **SSE Streaming**: Optimized for `text/event-stream` communication - **Real-time Events**: Custom event types and data streaming - **Session Management**: Include `x-mcp-session-id` header for session tracking ## Authentication Flow 1. User must first connect to the server via `/api/servers/{server_id}/connect` 2. Complete OAuth flow for the third-party service 3. Use this endpoint for real-time event streaming with automatic credential injection # Adding Your Agents Source: https://docs.barndoor.ai/how-tos/add-an-agent Step-by-step guide for adding an agent in Barndoor. Adding your agents to Barndoor **Prerequisites** * Admin privileges in your Barndoor organization. * Application details for your agent, including application type (guidance below) and OAuth callback URL(s) ## Step-by-step guide 1. Go to **AI Agents**: [https://app.barndoor.ai/agents](https://app.barndoor.ai/agents). 2. Click **Add Agent** button (top-right).
This opens the **Add AI agent** registration form. Add AI agent modal with fields for name, description, application type, and allowed logout URLs > Tip: If you don't see the button, ensure your user has admin access. ## Fill out the registration form 1. **Name**
Clear, human-readable name (e.g., `Snowflake Assistant`, `Sales Ops Agent`). 2. **Description**
Short sentence on what the agent does and which services it connects to. 3. **Application Type**
Choose one that matches how your agent will run: * **Regular Web Application** – Server-rendered web apps that keep secrets on the server. * **Single Page Application (SPA)** – Front-end only apps; tokens handled in the browser. * **Native Application** – Desktop or mobile apps running on user devices. * **Machine to Machine** – Autonomous agent, backend services or daemons without user interaction. 4. *Callback URLs*\* 5. *Callback URLs*\* Enter one or more URLs where Barndoor should send callbacks after users sign in through your Identity Provider or authorize Barndoor to access an MCP server. 6. **Allowed Logout URLs**
One or more URLs where users can be safely redirected after logging out (press **Enter** after each URL). When you're done, click **Register agent**. Upon successful agent creation, you'll be presented your agents credentials. These credentials are required for authenticating your application to make authorized requests to Barndoor operations. ## Your Agent Credentials Agent Credentials print out ## What happens next? * Your new agent appears in the **All Agents** list. * From there you can: * Configure **access policies** for the agent by adding the agent to the scope of MCP servers such as Snowflake, Salesforce, and Notion in Access Control Center. * For Machine to Machine or Autonomous Agents, you can directly connect them to MCPs with service account credentials. * Manage **auth settings** and rotate credentials if your application type requires it. * Monitor **Active users** and **Monitored actions** over time. ## Machine to Machine Agent Configuration Agents configured with the "Machine to Machine" agent type can connect directly to MCPs without requiring per-user authorization. Instead, they use service accounts registered in the underlying systems of the MCPs you want your autonomous agent to access. **To configure a Machine to Machine agent:** 1. Select the agent from the **All Agents** list. 2. (Recommended) Turn off **ToolIQ Write Confirmations** so the agent can operate without a human in the loop. Be sure to test thoroughly before allowing it to make system updates. 3. Click **Manage Connections**. 4. Click **Connect** for each MCP the agent needs access to. 5. When prompted, authenticate to the underlying system using the appropriate service account credentials. Your agent now has MCP credentials configured, and these will be used each time it connects to the underlying system. **Next step:** Create an [access control policy](https://docs.barndoor.ai/how-tos/manage-policies) for the agent to fine-tune which tools it can use and define any exception conditions that should limit its behavior. ## Troubleshooting * **"Register agent" is disabled**
Ensure **Name**, **Application Type**, and at least one **Allowed Logout URL** are provided. * **Not sure which application type to pick?**
Use **Regular Web Application** for server-based apps, **SPA** for purely browser apps, **Native** for desktop/mobile clients, and **Machine to Machine** for backend jobs with no user login. * **Can't access Agents page**
Ask an org admin to grant you the necessary permissions or create the agent on your behalf. *** **Next steps:** After creating the agent, head to **Connected Services** to connect MCP servers your agent will use. # Registering MCP Servers Source: https://docs.barndoor.ai/how-tos/add-an-mcp-server Step-by-step guide to register a new MCP server in Barndoor. One of the first steps to getting started with Barndoor is to register your MCP servers. You can register servers that are built and hosted by Barndoor, curated by Barndoor but hosted by third parties, or hosted internally on your own infrastructure. ### Prerequisites Before getting started with Register an MCP server in Barndoor, you’ll need: * A Barndoor account with **admin privileges** for your organization * Credentials from your MCP provider to authenticate a Barndoor connection **Tip:** To learn how to authenticate Barndoor to an MCP provider, visit the [MCP Servers Catalog](/mcp-servers/servers), select an MCP server, and follow the **Setup Instructions**. **For example:** [here](/mcp-servers/atlassian#setup-instructions) is how to connect Atlassian's Rovo MCP server. ### Understanding MCP Server Types When adding a MCP server, you'll choose from one of three categories. | Server Type | Description | | :-------------------- | :----------------------------------------------------------------------------- | | **Barndoor Managed** | Secure, turnkey MCP servers built, managed, and hosted by Barndoor. | | **Official (Remote)** | Remotely hosted third-party MCP servers offered by the SaaS/platform provider. | | **Custom Servers** | Any remotely hosted MCP servers created/registered by your organization. | ### How to Register an MCP Server 1. In the Barndoor web UI, navigate to the **Admin** > **MCP Servers** section (left nav). 2. Click **"Add a Server"**. 3. Select the type of MCP server to add: Barndoor Managed, Official (third-party remote), or Custom (created by your organization). #### **Option A: Add a Barndoor Managed or Official (remote) MCP server** This is the simplest method, used for adding MCP servers for common enterprise services/platforms. 1. Select either **"Barndoor Managed"** or **"Official (remote) servers"**. 2. Find the server you wish to add (e.g., *Salesforce*, *GitHub*, *Atlassian*, etc.). 3. Click **"Add New"** (or "Enable") next to the server 4. Provide configuration details for the MCP server. Foo * Server Name: Unique name for the new MCP server. * Slug: A URL friendly identifier that will be appended to an endpoint URL for connecting to the server. * OAuth Base URL Override (optional): Allows you to change the root URL used when the OAuth 2.0 authentication flow is performed. * OAuth Credentials: Client ID and secret for the MCP server that was registered with upstream service. When connecting an OAuth Client, you must ensure your OAuth Client has allowlisted your Barndoor Trial hostname to avoid a redirect URI mismatch error. You are allowed to create multiple instances of MCP server registrations within Barndoor. #### **Option B: Add a Custom internal or other public remote MCP server** Use this method to register a server hosted on your own infrastructure, or any other remotely accessible MCP server that isn't already in our lists. Adding a custom MCP server that hasn't been vetted by Barndoor or by your own security team is not recommended. 1. Select the **"Internal Servers"** option from the prompt. 2. You will see a list of internal servers you have already defined. 3. To add a new one, click the **"Add Custom MCP"** (or "Define New Server") button. 4. Provide connection information for the MCP server: Foo * **Server Source:** Choose Internal if hosted and managed on your own infrastructure, or 3rd Party if the server is hosted and managed by an outside provider. * **MCP Server URL:** The full URL where the Barndoor Gateway can reach this server (e.g., `https://mcp.somecompany.com`). 5. After clicking "Add Server" provide configuration details fo the MCP server: Add Custom MCP Server - Config Details (1 of 2) Add Custom MCP Server - Config Details (2 of 2) * **Server Source:** Same as last step. * **Name:** Unique name for the new MCP server. * **Description:** Useful verbose description for this server. * **Icon:** Optional icon that's displayed next to server within Barndoor. * **Server URL:** The full URL where the Barndoor Gateway can reach this server (e.g., `https://mcp.somedomain.com`). * **Protocol:** Choose MCP (Streamable HTTP) or SSE (Server-Sent Events). While SSE is supported, please note that it has been deprecated. * **Issuer:** The unique URL of the authorization server for this MCP server. * **Authorization Endpoint:** The authorization server's endpoint URL where a user will be redirected to log in and grant consent. This can either be a relative path to the Issuer URL above, or an absolute (full) endpoint URL. * **Token Endpoint:** The authorization server's endpoint URL that Barndoor will use to exchange an authorization code for an access token. This can either be a relative path to the Issuer URL above, or an absolute (full) endpoint URL. * **Allow OAuth Override:** Allows the issuer (base URL) to be overridden per instance of this MCP server. * **Scopes:** A list of OAuth scopes (permissions) that Barndoor will request during the authentication flow (e.g., "read:profile read:issues write:comments") * **Categories:** Select one or more categories for this MCP server which is used to improve server discovery. * **Additional Metadata (JSON):** Optional field of additional metadata to be passed between MCP clients and servers. When connecting an OAuth Client, you must ensure your OAuth Client has allowlisted your Barndoor Trial hostname to avoid a redirect URI mismatch error. # Adding Your Agents Source: https://docs.barndoor.ai/how-tos/agent-profile/add-an-agent Step-by-step guide for adding an agent in Barndoor. Adding your agents to Barndoor **Prerequisites** * Admin privileges in your Barndoor organization. * Application details for your agent, including application type (guidance below) and OAuth callback URL(s) ## Step-by-step guide 1. Go to **AI Agents**: [https://app.barndoor.ai/agents](https://app.barndoor.ai/agents). 2. Click **Add Agent** button (top-right).
This opens the **Add AI agent** registration form. Add AI agent modal with fields for name, description, application type, and allowed logout URLs > Tip: If you don't see the button, ensure your user has admin access. ## Fill out the registration form 1. **Name**
Clear, human-readable name (e.g., `Snowflake Assistant`, `Sales Ops Agent`). 2. **Description**
Short sentence on what the agent does and which services it connects to. 3. **Agent Owner**
Name of person or team that is responsible for the agent (optional) 4. **Owner Contact Information**
Email address, slack channel, or other contact information for the Agent Owner (optional) 5. **Callback URLs**\* Enter one or more URLs where Barndoor should send callbacks after users sign in through your Identity Provider or authorize Barndoor to access an MCP server. 6. **Allowed Logout URLs**
One or more URLs where users can be safely redirected after logging out (press **Enter** after each URL). When you're done, click **Register agent**. Upon successful agent creation, you'll be presented your agents credentials. These credentials are required for authenticating your application to make authorized requests to Barndoor operations. ## Your Agent Credentials Agent Credentials print out ## What happens next? * Your new agent appears in the **All Agents** list. * From there you can: * Configure **access policies** for the agent by adding the agent to the scope of MCP servers such as Snowflake, Salesforce, and Notion in Access Control Center. * For Machine to Machine or Autonomous Agents, you can directly connect them to MCPs with service account credentials or LLM models with their virtual keys. See [AgentProfiles](https://docs.barndoor.ai/how-tos/agent-profile/overview) * Manage **auth settings** and rotate credentials if your application type requires it. * Monitor **Active users** and **Monitored actions** over time. **Next step:** Create an [access control policy](https://docs.barndoor.ai/how-tos/manage-policies) for the agent to fine-tune which tools it can use and define any exception conditions that should limit its behavior. # Agent Profiles Source: https://docs.barndoor.ai/how-tos/agent-profile/overview Configuring agents that operate with their own access credentials to MCPs and LLMs and provides visibility to what your agents are doing and what their models costs are. ## Overview AgentProfile: one record covering data access policies, per-agent spend, LLM access, budget guardrails, MCP access, and human manager Every agent in Barndoor has an **AgentProfile,** a single record where your agents may be registered and used for enabling access controls. It may be a commercial agents such as Anthropic Claude, OpenAI ChatGPT, Codex, Gemini, Cursor and so on. Or it may be custom developed agents. For your custom agents, **AgentProfile** may be further used for configuration and ongoing management, especially in cases where the agent is autonomous and you utilize both Barndoor's LLM gateway and MCP gateway. You may configure the **AgentProfile** with the virtual keys it needs to make model API calls as well as grant it specific credentials, such as services account credentials, for the MCP's of systems it requires access to. By doing so, your **AgentProfile** ties together its access controls and credentials in one place, and provides visibility into it's ongoing AI token model costs, policy enforcement logs, error rates, and so on. This binds together the LLM Gateway and MCP Gateway product modules. AgentProfile is the central object for both governed tool traffic and LLM usage especially useful for custom agents. ## Configuring an Autonomous Agent with AgentProfile **To configure your autonomous agent:** 1. Select and open the agent from the **AI Agents** list. [https://app.barndoor.ai/agents](https://app.barndoor.ai/agents) 2. Select the Edit action to open the agent configuration modal 3. If the agent is to contain its own credentials to your MCP servers, enable the MCP Connections feature 4. If the agent is to contain its own LLM keys, enable the LLM Gateway Enabled feature 5. (Recommended) Turn off **ToolIQ Write Confirmations** so the agent can operate without a human in the loop. Be sure to test thoroughly before allowing it to make system updates. From this point, configure access to tools the agent should have to in the [Access Control Center](https://app.barndoor.ai/policies). ## Enabling MCP Server Connections on an agent Agents may be given its own service account credentials to the MCP Servers it needs access to. This is most valuable when creating custom agents that do not work explicitly on behalf of a user's own login credentials. On the Edit AI Agent modal, the **MCP Connections Enabled** toggle controls whether this feature is enabled for the agent. * **Default:** off for new agents. * **When enabled:** the agent can be given access credentials for each MCP server available in Barndoor. * **When disabled:** the agent must utilize MCP user login credentials found otherwise in your agent application or through the user connection flows in Barndoor My Apps. Once the feature is enabled, select the **Manage Connections** action from the agent details page. You are then able to add the MCP server connections that the agent is to have access to. ## Enabling LLM Gateway on an agent Most agents will interact with an AI model via the LLM gateway. If you are managing agentic access to models with Barndoor's LLM gateway, this process will bind a virtual key to the agent so you can manage what models it may access and track its token spend. On the Edit AI Agent modal, the **LLM Gateway Enabled** toggle controls whether this feature is enabled for the agent. * **Default:** off for new agents. * **When enabled:** the agent can be bound to LLM Gateway keys, and Barndoor starts routing and tracking its model calls. * **When disabled after keys are bound:** a confirmation dialog warns you that bindings will be preserved but disabled. Turning the toggle back on automatically reactivates them. ### Managing key bindings Once LLM Gateway is enabled, a **Manage keys** action appears on the agent detail page kebab menu (`⋮`). It opens a dedicated screen listing keys you're authorized to bind or you may provision a new key. An agent may have more than one model key, but each key may only be bound to a single agent. #### Bind a key Keys that have been created already may be bound to the agent if they have not been used with other agents. #### Creating a key from this screen **Create new key** opens a key-creation form. The resulting key is automatically bound to the current agent as part of the same action. #### Managing an existing key binding Keys may be unbound from an agent through the **Unbind** button. All event history is preserved against the agent, but new activity using the key will not be associated to the agent. Keys may be subsequently bound to a new or existing agent. # Lock Down Claude Enterprise to One Barndoor URL Source: https://docs.barndoor.ai/how-tos/claude-enterprise-barndoor-universal-url How to configure Claude with Barndoor to manage the MCP access of your organization's users. If you are a Claude Team or Enterprise admin, the Barndoor ToolIQ MCP simplifies your users' experience accessing your organization's business systems while giving IT the access-control and governance tooling to ensure AI is adopted safely. Instead of configuring, exposing, and managing a separate connector MCP for every system your organization uses — and training users on when to enable or disable each one — you configure a single Barndoor ToolIQ URL and let the Barndoor platform handle all the downstream access control and interactions. Your users then connect through that single entry point, while Barndoor decides which MCP servers, tools, and policies apply to them at runtime. **Best For**: Enterprise teams that want one controlled Claude connector, centralized policy enforcement, and a simpler rollout and experience for users. ## What This Achieves With this setup: * Claude Enterprise admins add one Barndoor connector to the Claude organization * Claude users connect to the single connector instead of needing to select individual app connectors per prompt, command, or skill * Barndoor controls which MCP servers and tool calls are available by user, group or role * Fine-grained access policies are enforced in Barndoor * New MCP servers and policy changes can be rolled out via Barndoor without requiring any change in Claude ## Before You Begin Before setting this up, make sure you have: * Claude Enterprise owner or admin access with permission to manage organization connectors * Your Barndoor ToolIQ MCP URL from the [Barndoor AI Client Setup](https://app.barndoor.ai/settings/ai-client-setup) page * At least one registered Barndoor agent * At least one connected MCP server in Barndoor * Production policies prepared or in draft for the users and agents you plan to roll out This guide assumes you want Claude users to enter through one Barndoor-controlled MCP endpoint. The governance model lives in Barndoor, so Claude stays simple while Barndoor handles server access, policy enforcement, and auditability. ## Step 1: Prepare Barndoor First Before touching Claude, confirm the Barndoor side is ready. * Your production MCP servers are registered and connected * The Barndoor ToolIQ URL is available in your setup page * The correct Barndoor agent is registered * Policies are created in `DRAFT` or `ACTIVE` as appropriate * Tool access has been reviewed for the MCP servers included in launch * Test users or pilot users are identified If these pieces are not in place first, Claude users may connect successfully but see the wrong tools or fail policy checks later. References: * [Registering MCP Servers](/how-tos/add-an-mcp-server) * [Adding Your Agents](/how-tos/add-an-agent) * [Managing Policies](/how-tos/manage-policies) ## Step 2: Copy the Barndoor ToolIQ URL Go to your Barndoor AI Client Setup page and copy the ToolIQ MCP endpoint for your organization. This will be the single connector URL you want Claude Enterprise to expose to users. Do not create one Claude connector per downstream system unless you have a special exception. The point of this pattern is to centralize Claude access behind one Barndoor-controlled MCP. ## Step 3: Add the Connector in Claude Enterprise In Claude Enterprise, the organization owner adds the connector once for the whole organization. In Claude, go to **Organization Settings > Connectors**. Click **Add custom connector**. Give it a recognizable name, such as **Barndoor**. Paste your Barndoor MCP URL, for example: ```text theme={null} https://your-org.platform.barndoor.ai/mcp ``` You won't need to configure any Claude-side OAuth credentials — only the Barndoor URL is required. Save the connector so it becomes available to your Claude organization. At this point, Claude has one approved enterprise connector, and that connector points to Barndoor rather than directly to a single downstream MCP server. ## Step 4: Expose the Connector to Claude Org Users After the owner adds the connector, Claude users can connect to it individually. Users go to **Settings > Connectors** in Claude. Users find the Barndoor connector that was added by the Claude Enterprise admin. It will appear under the organization connectors section, distinct from any personal or directory connectors. Users click **Connect** and complete the authentication flow to Barndoor. Users start a new Claude conversation with the approved Barndoor connector enabled. Users are connecting to one Claude-approved Barndoor entry point. They are not managing separate Salesforce, Slack, Notion, Snowflake, etc. connectors inside Claude. ## Step 5: Validate the Runtime Experience Before broad rollout, test the connector with pilot users. The pilot users should have the "User" role in Claude. * Confirm the Claude org sees only the approved Barndoor connector * Confirm users cannot add custom connectors in their customization settings * Confirm users can connect successfully * Confirm the expected Barndoor-managed tools are exposed in Claude * Confirm that for a system with both a Barndoor route and a native connector, Claude chooses the Barndoor route * Confirm tools not allowed by policy do not appear or are denied correctly * Confirm at least one allowed workflow succeeds end to end * Confirm at least one denied workflow is blocked correctly * Confirm the enforcement result is visible in Barndoor logs References: * [Go-Live Checklist](/how-tos/go-live-checklist) * [Managing Policies](/how-tos/manage-policies) Once pilot validation is complete: * Roll the connector out to the rest of the Claude organization * Keep the connector URL stable * Add or remove MCP server access in Barndoor as needed * Update policies in Barndoor without retraining users on connector setup * Use Barndoor logs and policy summary views to monitor adoption and enforcement This gives you a clean enterprise model: one Claude connector, one Barndoor ToolIQ URL, many governed downstream systems. ## Advanced Bypass Prevention settings ### Network-Level Enforcement The most reliable way to ensure all MCP traffic routes through Barndoor is to enforce it at the network layer. * Allowlist only your Barndoor production URL at the corporate firewall or proxy * Block outbound connections to known MCP endpoints for systems like Salesforce, Slack, Snowflake, and others that are governed by Barndoor * This ensures that even if a user adds a direct connector in Claude, the connection will fail at the network boundary This approach does not require changes inside Claude and applies uniformly across Claude.ai, Claude Desktop, and Claude Code. ### Managed MCP Configuration (Claude Desktop & Claude Code) ***Enterprise accounts only*** 2026 06 11 12 26 24 2026 06 11 12 26 24 For organizations using **Claude Desktop** or **Claude Code**, a managed `managed-mcp.json` file takes *exclusive* control of MCP connections on the machine. This is the strongest client-side lockdown: it removes the user's ability to define their own MCP servers, parameters, paths, or environment variables entirely — not just filter them. #### Claude Desktop Create and deploy a `managed-mcp.json` file that defines only the Barndoor URL: ```json theme={null} { "mcpServers": { "barndoor": { "type": "http", "url": "https://your-org.platform.barndoor.ai/mcp", "description": "All MCP access through Barndoor" } } } ``` When this file is deployed, users cannot add, modify, or remove MCP servers through Claude Desktop. Only the servers defined in the managed config are available. #### Claude Code (absolute lockdown) A soft control — an allowlist or an organization instruction — can still be worked around. A determined user might point Claude at an unauthorized MCP server that happens to match a generic naming convention or allowlist string. To remove that possibility entirely on Claude Code, deploy a system-level `managed-mcp.json`. Drop a standalone `managed-mcp.json` file into the system config directory for the platform: | OS | Path | | ----------- | ------------------------------------------ | | macOS | `/Library/Application Support/ClaudeCode/` | | Linux / WSL | `/etc/claude-code/` | | Windows | `C:\Program Files\ClaudeCode\` | Define the exact Barndoor endpoint, and only that: ```json theme={null} { "mcpServers": { "barndoor": { "type": "http", "url": "https://your-org.platform.barndoor.ai/mcp" } } } ``` Once this file is present, Claude Code switches to a strict "only load what is explicitly defined here" state: * Users cannot add, modify, or use any other MCP server — including plugin-provided servers. * Any user-defined local parameters, paths, or environment variables for those connections are discarded. * Native claude.ai connectors are **suppressed by default** (unless an admin explicitly sets `"allowAllClaudeAiMcps": true`), which directly closes the "Claude reaches for a native connector on its own" gap. Verify the deployment on a managed machine: ```bash theme={null} # Should list only the Barndoor server claude mcp list # Should fail with an enterprise-config error claude mcp add --transport http test https://example.com/mcp ``` Roll `managed-mcp.json` out at fleet scale with your device management tooling — Jamf or a configuration profile on macOS, Group Policy or Intune on Windows. Anthropic publishes starter MDM templates at [github.com/anthropics/claude-code/tree/main/examples/mdm](https://github.com/anthropics/claude-code/tree/main/examples/mdm). Pair the rollout with spend-limit controls to cap API token consumption. Managed MCP configuration applies to the Claude Desktop and Claude Code clients on managed machines. It does not control connectors added through the Claude.ai web interface or mobile apps. Pair this with network controls (Option 1) for full coverage. ### Steer Claude with Organization Instructions This control targets the second bypass vector — Claude defaulting to a native connector even when Barndoor is enabled. Claude Team and Enterprise admins can set organization-wide custom instructions under **Organization Settings > Organization and Access**. Well-crafted instructions push Claude to route through Barndoor first and treat native connectors only as a fallback. **This is a behavioral steer, not a hard control.** Claude generally follows clear instructions, but model adherence is not guaranteed. Layer it on top of network or desktop enforcement (Options 1 and 2) rather than relying on it alone. In the Organization Instructions box, add language such as the below: ```text theme={null} When accessing any external service (Jira, Confluence, Slack, Salesforce, Google, etc.), always route calls through the connector using its execute_tool tool. Never call stock/native Claude connectors (e.g., Atlassian Rovo, Gmail, etc.) directly. Only fall back to a stock connector if is explicitly unavailable or returns a connection error. ``` Replace `` with the exact name of your Barndoor connector as it appears in Claude (for example, `Barndoor`). **Why this phrasing works:** * **Say "always," not "prefer."** Soft verbs like "prefer," "optimize by using Barndoor," or "use Barndoor when available" produce inconsistent results — sometimes Claude routes through Barndoor, sometimes it overrules and uses the native connector. Absolute "always" / "never" framing is far more reliable. * **Name the `execute_tool` tool explicitly.** Pointing Claude at the specific tool it should call removes ambiguity about *how* to route through Barndoor. * **Broaden the scope beyond one system.** Listing several services (Jira, Confluence, Slack, Salesforce, Google) rather than naming just one signals that the rule applies to all external access, not a single integration. * **Include explicit fallback language.** Telling Claude to fall back to a stock connector only when Barndoor is unavailable keeps it functional for systems Barndoor doesn't yet govern, instead of failing when a service isn't behind Barndoor. Validate this in your environment as many organizations have additional text for Organization Instructions. Run a few prompts that target systems with both a Barndoor route and a native connector, and confirm Claude chooses Barndoor. Re-test after any major Claude model update, since steering behavior can shift between versions. ### Acceptable Use Policy For organizations that cannot enforce controls at the network or desktop level, pair your rollout with a clear acceptable use policy that: * Requires all Claude MCP connections to route through the approved Barndoor URL * Prohibits adding custom MCP connectors that connect directly to governed systems * Uses Barndoor enforcement logs to detect unexpected tool usage patterns ### Summary: Layered Defense For a complete lockdown, combine these approaches: | Layer | Control | Coverage | Strength | | ------------- | ------------------------------------------------- | -------------------------------- | ------------------ | | Network | Firewall allowlist for Barndoor URL only | Claude.ai, Desktop, Code, Mobile | Hard | | Client config | `managed-mcp.json` deployment | Claude Desktop & Claude Code | Hard | | Instructions | Org-wide custom instructions steering to Barndoor | Claude.ai, Code, workspace | Soft (best-effort) | | Policy | Acceptable use policy + Barndoor audit logs | All surfaces | Soft | ## Operational Best Practices * Use one Claude Enterprise connector per Barndoor environment, not per downstream app * Keep production users on the production Barndoor URL only * Test policy changes in `DRAFT` before activating them * Use Barndoor policies to control access instead of relying on user behavior inside Claude * Keep the Claude connector rollout narrow at first, then expand by user group or team * Use Barndoor enforcement logs to investigate denied or unexpected actions * Set organization instructions (**Settings > General**) to steer Claude toward the Barndoor connector, and re-validate the wording after major Claude model updates ## Troubleshooting Check Barndoor first. The most common causes are: * the wrong MCP servers are connected * policies are still in `DRAFT` * the user or agent is out of scope for the active policy * the allowed tools were not enabled in the policy model Review the active Barndoor policies and enforcement logs. Confirm whether the denial is expected and which policy caused it. Keep the single connector model and separate access in Barndoor through server selection, user identity, group mapping, and policies. Do not solve this by creating many duplicate Claude connectors unless you have a strict org-level reason. You can keep the same Claude connector and expand the governed systems behind it in Barndoor, as long as you update server connectivity and policies before rollout. ## Next Steps * Review the [Go-Live Checklist](/how-tos/go-live-checklist) before organization-wide release * Finalize your v2 policies in [Managing Policies](/how-tos/manage-policies) * Use [Connect AI clients to Barndoor](/how-tos/connecting-barndoor-to-agents) for the broader multi-client connection guide # Connecting Accounts to Barndoor Source: https://docs.barndoor.ai/how-tos/connected-accounts Step-by-step guide for connecting external accounts (like Salesforce) in Barndoor. Barndoor lets you connect MCP servers to your user workspace. Once connected, Barndoor can securely use your authorized credentials when executing **MCP server tool calls** on your behalf. ## How It Works Behind the Scenes When you connect an account, Barndoor uses OAuth 2.0 to perform a secure handshake with the provider. * After you log in, the provider (e.g., Salesforce) sends Barndoor an **access token**. * Barndoor securely stores this JWT token and uses it whenever an **MCP server tool call** needs to act on your behalf — for example, retrieving Salesforce data or updating records. The JWT token will live for 60 minutes and can always be refreshed. * Tokens can be revoked at any time through your provider’s account settings or through our API/SDK. *** ## Video Walkthrough