Platform API

身份驗證

（以下內容均翻譯自英文版文件，最新資訊及內容敬請切換至英文語系參考原文）

 

BlendVision One的Platform API主要使用了Bearer Authentication。

在製作對 Platform APIs 的 API 呼叫或在我們的 API 參考文檔中搜尋路徑時，必須在呼叫的標頭部包含您的 API 令牌。API 令牌是將您的應用程式與我們的 API 整合的關鍵。獲得令牌後，您就可以在 API 請求中包含該令牌，以驗證和授權您對 API 資源的訪問。

 

請求 API 令牌

要使用 BlendVision One，必須擁有 BlendVision One 帳戶和有效的 API 令牌。建立帳戶後，您可以聯繫我們索取 API 令牌。除了 API 令牌，您還將收到您的組織 ID，這是您的組織在 BlendVision One 中的唯一標識碼。此信息對於驗證您的 API 請求和確保正確訪問 API 資源至關重要。

通過在 API 請求的標頭中包含 API 令牌和組織 ID，您可以安全地訪問 BlendVision One API 資源並與其互動：

Authorization: Bearer <token>
x-bv-org-id: <organization-id>

 

建立 API 令牌

或者，您也可以按照以下步驟手動建立具有特定有效期的 API 令牌：

  1. 使用電子郵件和密碼登入後，應使用以下 API 取得訪問令牌：

POST bv/account/v1/accounts/login

以下是請求主體的範例：

{
  "email": "string",
  "password": "string"
}
  1. 回應成功後，您將收到一個 access_token，可用於後續的 API 請求。
    此回應將包含其他資訊，如刷新令牌（ refresh_token ）、令牌的過期時間（expires_in）和令牌類型（token_type）。
{
  "access_token": "string",
  "refresh_token": "string",
  "expires_in": -2147483648,
  "token_type": "Bearer"
}

請記住，access_token 最終會過期，因此有必要使用回應中提供的 refresh_token 進行刷新。

  1. 取得訪問令牌後，您可以通過以下 API 建立 API 令牌：

/bv/account/v1/accounts/api-token

必填的參數如下：

  • name: 新 API 令牌的期望名稱。
  • expired_date: 所需的 ISO8601 格式的過期日期（如 "2023-12-31T23:59:59Z"）。如果留空，API 令牌將不會過期。

這將建立一個與您的帳戶相關聯的 API 令牌。重要的是，您需要擁有當前用於身份驗證的訪問令牌。

  1. 建立成功後，API 將回應生成的 API 令牌、其有效期和令牌類型。請安全儲存 token 值，因為它將用於授權您的 API 請求，如果設置了有效期，請不要忘記在有效期前更換令牌。
{
  "token": "my-api-token",
  "expired_date": "2024-08-24T14:15:22Z",
  "token_type": "Bearer"
}

 

取得貴組織的 ID

要取得當前組織的 ID，可以使用以下 API：
GET /bv/org/v1/organizations

以下範例說明如何使用 cURL 來實現這一功能：

curl --request GET \
  --url https://api.one.blendvision.com/bv/org/v1/organizations \
  --header 'Accept: application/json' \
  --header 'authorization: Bearer <your-api-token>'

成功的回應如下：

{
  "organization": {
    "id": "string",
    "name": "string",
    "parent_id": "string",
    "type": "ORGANIZATION_TYPE_BUSINESS",
    "status": "ORGANIZATION_STATUS_ACTIVATED",
    "description": "string",
    "owner_email": "string",
    "billing_cycle": 0,
    "contract_valid_start_time": "2019-08-24T14:15:22Z",
    "contract_months": 0,
    "contract_days": 0,
    "contract_valid_end_time": "2019-08-24T14:15:22Z",
    "has_sub_orgs": true,
    "parent_name": "string",
    "license_key": "string",
    "time_zone": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z"
  }
}

organization 物件中的 id 欄位即是貴組織的 ID。

 

最後，後續在發送 API 請求時，請在標頭中包含 API 令牌和組織 ID：

Authorization: Bearer <token>
x-bv-org-id: <organization-id>

 

下面的序列圖詳細說明了使用者和 API 之間的身份驗證流程。

authentication.png

更新於