快速开始 | 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。