Tạo BYOK key

Tạo một BYOK upstream key cho tổ chức và đồng bộ danh mục model ngay lập tức. apiKey upstream chỉ xuất hiện dạng rõ trong yêu cầu này — được mã hóa khi lưu và sau đó chỉ trả về dạng che (keyMask). Thành công trả 201 kèm đối tượng khóa và kết quả đồng bộ (sync).

POST/api/v1/management/byok-keys

Xác thực

Authorizationbắt buộc

string · header

API key dưới dạng bearer token trong header Authorization.

Body

namebắt buộc

string

Tên hiển thị của khóa.

1-200 chars

baseUrlbắt buộc

string

Base URL API của nhà cung cấp upstream. Địa chỉ riêng tư/nội bộ bị từ chối (400).

1-2000 chars, public HTTPS endpoint

apiKeybắt buộc

string

API key của nhà cung cấp upstream dạng rõ. Chỉ xuất hiện trong yêu cầu này; mã hóa khi lưu, sau đó chỉ trả keyMask.

1-2000 chars

protocol

string

Giao thức API của upstream; mặc định openai.

openaianthropic

Example: "openai"

fallbackMode

string

Hành vi khi upstream lỗi: seamless (mặc định) quay về định tuyến nền tảng; strict không quay về mà trả lỗi.

seamlessstrict

Example: "seamless"

disabledCanonicalIds

string[]

Danh sách model (canonical id) cần tắt khi tạo; sau đồng bộ các model này không đi qua khóa này.

≤2000 items

scopedApiKeyIds

string[]

Giới hạn BYOK này chỉ áp dụng cho các API key nền tảng cụ thể (theo id). Rỗng/bỏ qua = áp dụng mọi khóa của tổ chức. Chứa id không thuộc về bạn sẽ bị từ chối (400).

≤200 items; must be your own keys

POST /api/v1/management/byok-keys

1
2
3
4
5
6
7
8
9
10
curl https://bazaarlink.ai/api/v1/management/byok-keys \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "team-upstream",
    "baseUrl": "https://api.example-upstream.com/v1",
    "apiKey": "'$UPSTREAM_API_KEY'",
    "protocol": "openai",
    "fallbackMode": "seamless"
  }'

Ví dụ phản hồi

Đã tạo. key là đối tượng khóa (chỉ keyMask); sync báo kết quả đồng bộ danh mục: matched (số model khớp danh mục nền tảng), unmatched (id model upstream không có trong danh mục), stale (có cần đồng bộ lại sau không).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
  "key": {
    "id": "byok_abc123",
    "ownerType": "org",
    "userId": null,
    "organizationId": "org_abc123",
    "name": "team-upstream",
    "baseUrl": "https://api.example-upstream.com/v1",
    "keyMask": "sk-abc…wxyz",
    "protocol": "openai",
    "enabled": true,
    "fallbackMode": "seamless",
    "modelsStale": false,
    "lastVerifiedAt": "2026-07-29T00:00:00.000Z",
    "lastErrorAt": null,
    "lastErrorCode": null,
    "errorCount1h": 0,
    "createdAt": "2026-07-29T00:00:00.000Z",
    "updatedAt": "2026-07-29T00:00:00.000Z",
    "models": [
      {
        "canonicalId": "openai/gpt-4o",
        "upstreamModelId": "gpt-4o",
        "enabled": true
      }
    ],
    "scopedApiKeyIds": []
  },
  "sync": {
    "matched": 12,
    "unmatched": [
      "internal-model-x"
    ],
    "stale": false
  }
}