> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meoo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速接入

本页帮助你完成第一次 API 调用。系统集成统一推荐团队版，通过团队 AK/SK 为 Owner 或虚拟成员签发短期 Token；面向已有 Meoo 用户提供授权服务时使用 OAuth；用户 API Key 仅用于个人测试、临时调试和个人 CLI。

个人授权场景使用 OAuth。团队系统集成使用团队 AK/SK，为已有 Owner 或新建托管成员签发短期 Token，详见[团队系统集成指南](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/8b2e4f11-3395-4dd1-b58e-2e6935dd1392)。用户 API Key 不作为系统集成方案。第三方 OAuth 应用仍需联系客服完成注册和配置。

## 1. 准备服务地址

```text theme={null}
export MEOO_BASE_URL="https://meoo.com"
```

联调时将其替换为 Meoo 对接人员提供的环境地址。

## 2. 选择接入方式

### 2.1 OAuth：第三方应用代用户访问

联系 Meoo 客服创建第三方应用，并提供应用名称、应用描述、HTTPS 图标地址、回调地址、应用类型和需要的 Scope。Web 应用会获得：

```text theme={null}
client_id=meoo_app_xxx
client_secret=meoo_sec_xxx
```

每次授权都生成新的 `state`、`code_verifier` 和 `code_challenge`：

```text theme={null}
import crypto from 'node:crypto';

const state = crypto.randomBytes(32).toString('base64url');
const codeVerifier = crypto.randomBytes(48).toString('base64url');
const codeChallenge = crypto
  .createHash('sha256')
  .update(codeVerifier, 'ascii')
  .digest('base64url');
```

将这些值临时保存在服务端会话中，然后把用户浏览器跳转到：

```text theme={null}
{MEOO_BASE_URL}/oauth/authorize
  ?client_id=meoo_app_xxx
  &redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback
  &response_type=code
  &scope=project.read
  &state=RANDOM_STATE
  &code_challenge=PKCE_CODE_CHALLENGE
  &code_challenge_method=S256
```

实际 URL 不包含换行。回调收到 `code` 和 `state` 后，必须先一次性校验并消费 `state`，再由服务端兑换 Token：

```text theme={null}
curl --request POST \
  --url "${MEOO_BASE_URL}/oauth/token" \
  --user "${CLIENT_ID}:${CLIENT_SECRET}" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=${AUTHORIZATION_CODE}" \
  --data-urlencode "redirect_uri=${REDIRECT_URI}" \
  --data-urlencode "code_verifier=${CODE_VERIFIER}"
```

成功后返回 `access_token`、`refresh_token`、`expires_in`、`scope` 和当前 Client 隔离的 `openid`。

### 2.2 API Key：仅限个人测试和自己的自动化

用户在 Meoo 设置页创建 API Key，并选择具体 Scope 或“全部权限”。明文只展示一次：

```text theme={null}
export MEOO_API_KEY="meoo_ak_xxx"
```

API Key 直接作为 Bearer Token 使用，不需要 OAuth 回调。它适合个人测试、临时调试和个人 CLI，不推荐用于第三方系统集成：

```text theme={null}
curl --request GET \
  --url "${MEOO_BASE_URL}/open/v1/projects?page_size=20" \
  --header "Authorization: Bearer ${MEOO_API_KEY}"
```

### 2.3 团队系统集成

如果接入方以一个团队账号承载多个外部用户，不需要为每位用户执行 OAuth。现阶段由接入方提供团队账号、秒悟团队创建测试 AK/SK；获得凭证后，接入方在可信服务端完成：

```text theme={null}
AK/SK（HMAC）→ 创建 member_id → 签发短期成员 Token → Bearer 调用业务 API
```

AK/SK 不直接作为 Bearer Token 使用；完整签名和 curl 示例见[团队系统集成指南](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/8b2e4f11-3395-4dd1-b58e-2e6935dd1392)。

## 3. 发起第一个资源请求

OAuth 和 AK 只在 Bearer 值上不同，业务接口完全一致：

```text theme={null}
curl --request GET \
  --url "${MEOO_BASE_URL}/open/v1/projects?page_size=20" \
  --header "Authorization: Bearer ${ACCESS_TOKEN_OR_API_KEY}"
```

响应示例：

```text theme={null}
{
  "projects": [
    {
      "url_id": "public_url_id",
      "name": "AI 助手",
      "type": "web",
      "created_at": 1789468200000
    }
  ],
  "next_page_token": "opaque_token"
}
```

请完整保存并原样使用 `url_id`、Token 和 `next_page_token`，不要尝试解析其结构。

## 4. 下一步

* 要创建项目、驱动 AI 生成并读取会话历史：申请 `project.write agent.run agent.read`，从 [Agent 接入指南](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/902f9879-a028-41dc-829e-6ad2525780a3) 开始，字段索引见 [Agent OpenAPI](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/0cacadf2-712b-4a08-9c29-550e056ef249)。
* 要上传自定义 Skill：申请 `skill.write`，上传成功后只需 `agent.run` 即可在 Run 中使用，参见 [Skills API](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/7b25c37b-1a42-40e8-8ae8-6196a592c345)。
* 要读取 Storage：申请 `cloud.storage.read`。
* 要发布 Web 项目当前的生成结果：申请 `release.write`，并为发布请求生成 `Idempotency-Key`。App 安装包和小程序平台发布暂未通过 OpenAPI 开放。
* 上线前完成 [运行与安全检查](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/e2b9545e-e018-428a-adeb-b4c9cdf7222c)。