跳至主要内容

REFERENCE

開發者參考

認證、API、SDK、Flow Agent 處理節點與參數取值的完整參考。

認證與 API Key 設定

Asgard API 認證方式、API Key 管理與安全設定

  1. 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 等同於存取憑證，請勿將其暴露在前端程式碼、版本控制系統或公開環境中。

  2. LLM Provider API Key​

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

    Provider說明文件連結
    OpenAIGPT-4, GPT-3.5 系列OpenAI API Keys
    Azure AIAzure OpenAI ServiceAzure Portal
    AnthropicClaude 系列Anthropic Console
    MistralMistral 系列Mistral Platform
    GeminiGoogle Gemini 系列Google AI Studio
    VoyageEmbedding 模型Voyage AI

    設定步驟​

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

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

  3. SDK 認證設定​

    JavaScript SDK（@asgard-js/core）​

    import { AsgardServiceClient } from '@asgard-js/core';
     
    const client = new AsgardServiceClient({
      botProviderEndpoint:
        'https://api.asgard-ai.com/ns/{namespace}/bot-provider/{botProviderId}',
      apiKey: 'your-api-key', // 建議從環境變數讀取
    });

    憑證有兩種帶法：Direct Connect 模式直接帶 apiKey；若走 Backend Relay 或自訂驗證，改用 customHeaders（例如 Authorization: Bearer <token>）。詳見 前端 SDK 使用指南。

    React SDK（@asgard-js/react）​

    React 直接使用 <Chatbot> 元件，把憑證放進 config：

    import { Chatbot } from '@asgard-js/react';
    import '@asgard-js/react/style';
     
    function App() {
      return (
        <Chatbot
          config={{
            botProviderEndpoint:
              'https://api.asgard-ai.com/ns/{namespace}/bot-provider/{botProviderId}',
            apiKey: process.env.REACT_APP_ASGARD_API_KEY, // 建議從環境變數讀取
          }}
          customChannelId="user-123"
        />
      );
    }

  4. 安全最佳實踐​

    環境變數管理​

    將 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

  5. Rate Limits​

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

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

  6. 下一步​

準備好開始了嗎？

想知道 Asgard 怎麼用在你的團隊？跟我們聊聊。

聯絡我們