快速開始 | AppForges Developer Center

1. 準備合法用戶授權

本例讀取當前用戶檔案。先按用戶 OAuth 授權流程獲取包含 user:profile:read 的用戶 access token。client_credentials 得到的服務憑據不能替代用戶身份。API Key 也必須滿足端點的身份與權限合同，詳見API Key。

應用和 OAuth client 是兩個對象。在應用列表創建應用，再進入該應用的 Credentials 創建 Public 或 Confidential client，登記自己的回調 URI 和允許的 scope。Public client 使用 PKCE，不持有 client_secret。

2. 選擇環境並配置憑據

環境	OAuth issuer	API base URL
staging	`https://accounts-staging.appforges.com`	`https://api-staging.appforges.com`
production	`https://accounts.appforges.com`	`https://api.appforges.com`

將用戶 access token 放入本地環境變量 APPFORGES_ACCESS_TOKEN；不要提交到 Git、貼入日誌或前端源碼。環境 issuer 與 API 必須匹配。以下示例默認 staging；調用生產前用生產 issuer 獲取獨立授權。

export APPFORGES_API_BASE_URL=https://api-staging.appforges.com

3. 安裝正式 SDK

以下三個安裝命令分別用於對應語言項目。SDK 包版本 0.59.4 與 API 日期版本 2026-04-01 是兩個不同維度。

npm install @appforges/sdk@0.59.4
python -m pip install appforges==0.59.4
go get github.com/appforges/appforges-sdk-go@v0.59.4

4. 發起一次只讀調用

將 TS 示例保存為 .mts，通過 TypeScript 編譯後用 Node 運行；Python 保存為 .py；Go 放入已初始化的 module。首次檢查關閉重試，便於明確觀察一次請求；正常 SDK 默認最多兩次重試。

TypeScript

import { AppForges } from "@appforges/sdk";
import { BearerAuth } from "@appforges/sdk/runtime/auth/bearer";
 
const client = new AppForges({
  baseURL: process.env.APPFORGES_API_BASE_URL || "https://api-staging.appforges.com",
  auth: new BearerAuth(process.env.APPFORGES_ACCESS_TOKEN!),
  retry: { maxRetries: 0 },
});
const profile = await client.users.getProfile({
  headers: { "X-AppForges-Api-Version": "2026-04-01" },
});
console.log(profile.user_id);

Python

import os
from appforges import AppForges, BearerAuth
 
with AppForges(
    base_url=os.environ.get("APPFORGES_API_BASE_URL", "https://api-staging.appforges.com"),
    auth=BearerAuth(os.environ["APPFORGES_ACCESS_TOKEN"]),
    max_retries=0,
) as client:
    profile = client.users.get_profile(
        headers={"X-AppForges-Api-Version": "2026-04-01"},
    )
    print(profile.user_id)

Go

package main
 
import (
    "context"
    "fmt"
    "log"
    "os"
    appforges "github.com/appforges/appforges-sdk-go"
    "github.com/appforges/appforges-sdk-go/runtime"
)
 
func main() {
    base := os.Getenv("APPFORGES_API_BASE_URL")
    if base == "" { base = "https://api-staging.appforges.com" }
    client, err := appforges.NewClient(
        runtime.WithBaseURL(base),
        runtime.WithBearerToken(os.Getenv("APPFORGES_ACCESS_TOKEN")),
        runtime.WithMaxRetries(0),
    )
    if err != nil { log.Fatal(err) }
    defer client.Close()
    profile, err := client.Users.GetProfile(context.Background(),
        runtime.WithHeader("X-AppForges-Api-Version", "2026-04-01"))
    if err != nil { log.Fatal(err) }
    userID, ok := profile.UserId.Get()
    if !ok { log.Fatal("missing user_id") }
    fmt.Println(userID)
}

響應字段保持 wire snake_case，沒有自動 camelCase 轉寫。響應是平坦用戶檔案，下面只展示部分字段：

{ "user_id": "example-user", "phone_number": "example-phone" }

也可用 curl：

curl --fail-with-body "${APPFORGES_API_BASE_URL}/v1/users/me" \
  -H "Authorization: Bearer ${APPFORGES_ACCESS_TOKEN}" \
  -H "X-AppForges-Api-Version: 2026-04-01"

5. 檢查響應與錯誤

診斷使用 X-Request-Id、X-Trace-Id；生效版本查看 X-AppForges-Resolved-Api-Version。限流頭是 X-RateLimit-Limit-Short / X-RateLimit-Remaining-Short / X-RateLimit-Reset-Short 及對應 -Long，額度以實際響應為準。429 時遵守 Retry-After，不要通過突發請求驗證額度。

遇到 401，先確認憑據、issuer 和有效期；遇到 403，檢查主體與 scope。參見錯誤與重試、版本升級、SDK。