createCredential.md

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:

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

Example

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 '{\n    "name": "OpenAI Production",\n    "model_provider": "openai",\n    "base_url": "https://api.openai.com/v1",\n    "api_key": "sk-..."\n  }'

OpenAPI

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 <token>`. Use the Barndoor SDK's
        `loginInteractive()` helper to obtain a token in scripts and notebooks.