> ## Documentation Index
> Fetch the complete documentation index at: https://docs.barndoor.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a Credential
> 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).
## OpenAPI
````yaml api-reference/llm-gateway-openapi.yml post /admin/connections
openapi: 3.1.0
info:
title: Barndoor LLM Gateway API
version: 1.0.0
description: >
REST API for the Barndoor LLM Gateway: configure providers, model routes,
pricing, governance, and operate a multi-provider LLM platform
programmatically.
All endpoints in this document are scoped to your organization. They are the
same APIs powering the Barndoor portal under **LLM Configuration**,
**LLM Controls**, and **Settings - My Models**, exposed for teams that
prefer scripting over the UI.
## Base URL
All requests are issued against your Barndoor instance:
```
https://app.barndoor.ai/api/llm-gateway
```
Replace `app.barndoor.ai` with your tenant host if you run on Enterprise.
## Authentication
Endpoints accept a JWT Bearer token issued by your Barndoor identity
provider. Tokens can be obtained interactively via the Barndoor SDK:
```ts
const sdk = await loginInteractive();
```
The token must be sent in the `Authorization` header on every request:
```
Authorization: Bearer eyJhbGciOi...
```
Note: the `bd-...` API keys you create through these endpoints are for
runtime LLM traffic (`/v1/chat/completions`, `/v1/messages`, etc.), not for
administrative calls. Administrative endpoints require a user/admin JWT.
## Permissions
Most endpoints require an `admin` (or higher) role on the calling user.
Read-only endpoints are typically accessible by all authenticated users.
Read-only listings under `/user/...` are scoped to the authenticated user.
## Errors
Errors are returned as JSON with a stable shape:
```json
{ "error": "BadRequest", "message": "request_timeout_secs must be between 1
and 3600" }
```
contact:
name: Barndoor Support
url: https://barndoor.ai
servers:
- url: https://{host}/api/llm-gateway
description: >-
Production / Trial (Barndoor SaaS). The gateway lives on your Barndoor
control-plane host. For Enterprise or self-hosted deployments, replace the
host with your portal hostname — the authoritative value is shown on
Settings → My Models in the portal.
variables:
host:
description: Your Barndoor control-plane (portal) hostname
default: app.barndoor.ai
- url: https://app.barndooruat.com/api/llm-gateway
description: UAT
- url: https://app.barndoordev.com/api/llm-gateway
description: Dev
security:
- BearerAuth: []
tags:
- name: Credentials
description: >-
Reusable upstream credentials (API keys, AWS roles, Vertex service
accounts)
- name: Providers
description: Named upstream providers backed by credentials and a model family
- name: Provider Catalog
description: Read-only catalog of supported upstream provider templates
- name: Model Routes
description: Map client-facing aliases to one or more upstream provider/model pairs
- name: Model Pricing
description: Per-million-token input/output costs for usage and budget reporting
- name: Rate Limits
description: Requests-per-minute and tokens-per-minute caps
- name: Token Budgets
description: Daily, weekly, or monthly token and cost ceilings
- name: Model Access
description: Allowlist or denylist policies for models, providers, or aliases
- name: Smart Models
description: Routing policies that pick a target model based on the request
- name: Governance Configuration
description: Org-wide behavior toggles for the LLM Gateway
- name: Route Health
description: Operational view of upstream route ejection and recovery
- name: API Keys
description: Org-managed gateway API keys (the `bd-...` keys callers send on `/v1/...`)
- name: User
description: Self-service endpoints for the authenticated user
paths:
/admin/connections:
post:
tags:
- Credentials
summary: Create a credential
description: |
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.
operationId: createCredential
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCredentialRequest'
responses:
'200':
description: The newly created credential
content:
application/json:
schema:
$ref: '#/components/schemas/Credential'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
components:
schemas:
CreateCredentialRequest:
type: object
required:
- name
- model_provider
- base_url
properties:
name:
type: string
example: OpenAI Production
model_provider:
$ref: '#/components/schemas/ModelProviderSlug'
auth_type:
allOf:
- $ref: '#/components/schemas/AuthType'
description: |
Optional. Defaults to the conventional auth type for the provider
(`api_key` for most vendors, `aws_role` for Bedrock, `google_adc`
for Vertex, etc.).
base_url:
type: string
format: uri
example: https://api.openai.com/v1
api_key:
type: string
format: password
description: |
Plaintext upstream API key. Required when `auth_type` is `api_key`
(or any vendor-specific key flavor like `bedrock_api_key`). Not
required when `auth_type` is role- or service-account-based — pass
the role/SA fields under `credentials` instead.
example: sk-xxxxxxxxxxxxxxxxxxxx
credentials:
type: object
description: >
Provider-specific credentials. Use this for non-API-key auth schemes
(AWS keys, Google service-account JSON fields, Bedrock
role+external_id).
The shape mirrors what the provider expects; consult the
corresponding
How-To guide for each provider's required keys.
additionalProperties: true
settings:
type: object
description: >
Non-secret provider settings (region, project_id, api_version,
etc.).
additionalProperties: true
Credential:
type: object
description: |
A reusable upstream credential, called *Credentials* in the portal UI.
One credential can back multiple providers (e.g. a single OpenAI key
used by several routes).
required:
- id
- org_id
- name
- model_provider
- auth_type
- base_url
- settings
- created_at
- updated_at
properties:
id:
type: string
format: uuid
example: 4f8b2a3c-12ee-4d92-9c7b-e7d2f8b0a111
org_id:
type: string
format: uuid
description: The organization that owns this credential
name:
type: string
example: OpenAI Production
model_provider:
$ref: '#/components/schemas/ModelProviderSlug'
auth_type:
$ref: '#/components/schemas/AuthType'
base_url:
type: string
format: uri
description: |
Upstream base URL the credential points at. Defaults to the public
provider URL but can be overridden for self-hosted or proxy setups.
example: https://api.openai.com/v1
settings:
type: object
description: |
Provider-specific settings that aren't sensitive (e.g. AWS region,
Vertex project id, Azure API version). Sensitive credentials live
in the encrypted secret store and are never returned by the API.
additionalProperties: true
example:
region: us-east-1
model_api_family: anthropic_messages
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
ModelProviderSlug:
type: string
description: Slug of the upstream model provider this resource speaks to
enum:
- openai
- anthropic
- azure_openai
- google_ai
- bedrock
- vertex
- groq
- together
- mistral
- cohere
- xai
- fireworks
- perplexity
- openrouter
- deepseek
- custom
example: openai
AuthType:
type: string
description: >
The authentication scheme this credential or provider uses to talk to
the upstream model provider. Valid values depend on `model_provider`:
for OpenAI/Anthropic-style vendors this is typically `api_key`; for AWS
Bedrock it is one of `aws_role`, `aws_keys`, or `bedrock_api_key`; for
Google Vertex it is `google_adc`, `google_service_account`, or
`google_impersonation`; Anthropic OAuth passthrough uses
`oauth_passthrough`.
example: api_key
Error:
type: object
required:
- error
- message
properties:
error:
type: string
description: A short machine-readable error code
example: BadRequest
message:
type: string
description: A human-readable description of what went wrong
example: request_timeout_secs must be between 1 and 3600
responses:
BadRequest:
description: The request body or query parameters were invalid
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Missing or invalid authentication
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: Authenticated, but the caller's role does not allow this action
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: |
JWT obtained through Barndoor's authentication flow. Pass the token
verbatim in `Authorization: Bearer `. Use the Barndoor SDK's
`loginInteractive()` helper to obtain a token in scripts and notebooks.
````