認證與 API Key 設定

API 認證方式

Asgard 使用 X-API-KEY Header 進行 API 認證。所有 API 請求必須包含有效的 API Key。

Request Header

POST /generic/ns/{namespace}/bot-provider/{bot_provider_name}/message/sse
Content-Type: application/json
X-API-KEY: your-api-key-here

取得 API Key

1. 登入 Asgard 平台
2. 進入目標 Project
3. 前往 Integration > App 設定頁面
4. 建立或複製現有的 API Key

安全提醒

API Key 等同於存取憑證，請勿將其暴露在前端程式碼、版本控制系統或公開環境中。

LLM Provider API Key

Asgard 支援多家 LLM Provider，您需要在平台中設定對應的 API Key：

Provider	說明	文件連結
OpenAI	GPT-4, GPT-3.5 系列	OpenAI API Keys
Azure AI	Azure OpenAI Service	Azure Portal
Anthropic	Claude 系列	Anthropic Console
Mistral	Mistral 系列	Mistral Platform
Gemini	Google Gemini 系列	Google AI Studio
Voyage	Embedding 模型	Voyage AI

設定步驟

1. 前往 AI Brain > Completion Model 或 Embedding Model
2. 選擇目標 Provider
3. 輸入對應的 API Key 與 Endpoint（Azure 需額外設定）
4. 測試連線確認設定正確

詳細設定教學請參考 Completion Model 設定 與 Embedding Model 設定。

SDK 認證設定

JavaScript SDK

import { AsgardClient } from '@asgard-js/core';

const client = new AsgardClient({
  baseUrl: 'https://api.asgard-ai.com',
  namespace: 'your-namespace',
  botProviderName: 'your-bot-provider',
  apiKey: 'your-api-key', // 建議從環境變數讀取
});

React SDK

import { AsgardProvider } from '@asgard-js/react';

function App() {
  return (
    <AsgardProvider
      config={{
        baseUrl: 'https://api.asgard-ai.com',
        namespace: 'your-namespace',
        botProviderName: 'your-bot-provider',
        apiKey: process.env.REACT_APP_ASGARD_API_KEY,
      }}
    >
      <YourApp />
    </AsgardProvider>
  );
}

安全最佳實踐

環境變數管理

將 API Key 儲存在環境變數中，避免硬編碼：

# .env
ASGARD_API_KEY=your-api-key-here

const apiKey = process.env.ASGARD_API_KEY;

後端代理模式

在正式環境中，建議透過後端服務轉發 API 請求，避免在前端暴露 API Key：

Key Rotation（金鑰輪替）

定期更換 API Key 以降低安全風險：

1. 在 Asgard 平台建立新的 API Key
2. 更新應用程式中的 API Key 設定
3. 確認新 Key 運作正常後，停用舊 Key

Rate Limits

限制項目	數值
API 請求頻率	5 requests/sec (每個 Endpoint)
最大執行時間	3 分鐘 (每次請求)
最大步驟數	30 步 (每次請求)

詳細限制請參考 配額與限制。

下一步

• 發送訊息 API — API 端點詳細規格
• SDK 使用指南 — SDK 安裝與進階用法
• 程式碼範例 — 常見整合範例