createApiKey.md
Create an Org API Key
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.).
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
- per-user/per-group rate limits
- per-user/per-group model access policies
Example: a CI service-account key
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:
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}.
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/api-keys:
post:
tags:
- API Keys
summary: Create an org API key
description: |
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.
operationId: createApiKey
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateApiKeyRequest'
responses:
'200':
description: The newly created key (only response that contains the raw `key`)
content:
application/json:
schema:
$ref: '#/components/schemas/CreateApiKeyResponse'
'400':
$ref: '#/components/responses/BadRequest'
components:
schemas:
CreateApiKeyRequest:
type: object
required:
- name
properties:
name:
type: string
user_id:
type: string
format: uuid
description: >-
Assign the key to a specific user. Mutually exclusive with
`group_name`.
user_email:
type: string
description: Optional override for the email recorded on the key
scopes:
type: array
items:
type: string
group_name:
type: string
description: |
Bind the key to an IdP group. Members of the group share the
group-scoped budgets, rate limits, and access policies.
Mutually exclusive with `user_id`.
expires_at:
type: string
format: date-time
nullable: true
CreateApiKeyResponse:
type: object
required:
- id
- name
- key_prefix
- key
- scopes
- created_at
properties:
id:
type: string
format: uuid
name:
type: string
key_prefix:
type: string
key:
type: string
description: |
The raw API key. Returned only at creation time and never stored
in plaintext — copy it immediately. Use this value as
`Authorization: Bearer <key>` (or `x-api-key: <key>`) on requests
to `/v1/chat/completions`, `/v1/messages`, and friends.
example: bd-abcd1234ef56...
scopes:
type: array
items:
type: string
group_name:
type: string
nullable: true
expires_at:
type: string
format: date-time
nullable: true
created_at:
type: string
format: date-time
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'
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.
```