---
title: 快速开始
description: 通过 Sudomimus Connect API 完成一次最小化的端到端集成。
editUrl: true
head: []
template: doc
sidebar:
  order: 3
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

import { CardGrid, LinkButton, LinkCard } from "@astrojs/starlight/components";

本页演示**最小可行集成**：让一个 Web 应用对接 Sudomimus，并取得一个经过验证的用户身份。

:::tip[推荐：使用官方 SDK]
最快的接入方式是使用官方 SDK。安装 [`@sudomimus/connect`](/zh-cn/reference/sdks/) 后，可以直接调用强类型方法（`establish`、`redeem`、`refresh`、`verifyAccessToken`），无需自行组装 HTTP 请求。

<LinkButton href="/zh-cn/reference/sdks/" variant="primary" icon="right-arrow">安装 SDK</LinkButton>
:::

:::note[正在使用 AI 编程助手？]
当助手需要直接操作 Sudomimus 时，请使用 Sudomimus CLI。它提供 shell 命令和 JSON 输出，同时仍通过 device authorization flow 在你的浏览器中完成登录。

<LinkButton href="/zh-cn/ai/cli/" variant="secondary" icon="right-arrow">让 AI 使用 CLI</LinkButton>
:::

不是 Web 应用？请选对应指南：

<CardGrid>
<LinkCard
    title="Sudomimus CLI"
    description="面向 AI agent、本地自动化和源码检出的命令行账户/开发者操作。"
    href="/zh-cn/ai/cli/"
/>
<LinkCard
    title="原生客户端"
    description="适用于桌面应用、Steam 游戏和使用 AccessKey 凭据的 CLI 工具，包括用于征求同意和补全资料的浏览器 Errand。"
    href="/zh-cn/native/overview/"
/>
<LinkCard
    title="OIDC 接入方"
    description="标准 OpenID Connect —— authorization_code + PKCE。"
    href="/zh-cn/oidc/flow/"
/>
</CardGrid>

## 先决条件

1. **在 [`with.sudomimus.com`](https://with.sudomimus.com) 创建或加入一个组织（Organization）。** 开发者自助门户以组织为单位：应用（Application）与扇区（Sector）都归属于某个组织，因此在创建应用之前你需要先拥有一个。大多数账户会当场创建自己的第一个组织（表单会预填一个建议名称）；如果同事已经在运行一个，请让他们邀请你加入。在你尚未归属任何组织之前，`/applications` 与 `/sectors` 页面会重定向到 `/organizations`。

2. **在该组织内创建你的应用。** 创建时你会拿到：
   - **`applicationAnchor`** —— 一个稳定的小写 kebab-case 应用锚点（例如 `my-app`），也是应用在 API 中的公开名称。
   - **client-auth 私钥** —— 创建时**只展示一次**，用于签名 `/establish` 请求。请像对待任何生产密钥一样妥善保管。
   - 应用的 **token-signing 公钥**。运行时也可以通过 `POST /info` 拉取，用于验证 access token。

3. **至少添加一条 `CALLBACK` 类型的 [返回规则](/zh-cn/application-rules/return-rules/)**，列出允许重定向回的 hostname。具体的 `callbackUrl` 在每次 `/establish` 时由应用提供；规则决定的是这个 URL 的 hostname 是否被允许。

4. **至少添加一条[认证规则](/zh-cn/application-rules/authentication-rules/)**（例如 `PASSKEY_USERNAMELESS`、`PASSKEY_REASONED` 或 `EMAIL_VERIFICATION`）和一条[身份准入规则](/zh-cn/application-rules/realize-rules/)（例如用于开放注册的 `EMAIL` + `allowedEmails: ["*"]`）。三层规则都采用**允许列表 + 默认拒绝**；任一层为空时，应用都无法完成登录。

## 四个阶段

每一次经过 Connect API 的身份认证往返都遵循同样的四个阶段：

1. **Establish（建立）** —— 应用后端请求 Connect 开启一次认证会话，并取回一对会话引用（`exposureKey` + `hiddenKey`）。
2. **Authenticate（认证）** —— 应用携带 `exposureKey` 把用户引导到 `via.sudomimus.com`；用户在那里完成通行密钥或邮箱验证码挑战。
3. **Redeem（兑换）** —— `via.sudomimus.com` 通过回调 URL 交还控制权，并在查询参数中附带 `exposure-key` 和 `confirmation-key`。应用后端将三个密钥提交给 Connect，换取签名的访问令牌和刷新令牌。
4. **Refresh（刷新）** —— 访问令牌临近过期时，应用后端使用刷新令牌换取新的访问令牌和轮换后的刷新令牌。

完整请求形状与 Connect、`via.sudomimus.com`、应用之间的协作关系见 [Connect 流程](/zh-cn/connect/flow/)。

## 下一步

<CardGrid>
<LinkCard
    title="Connect 流程"
    description="curl、Node.js、Python、Go 的端到端示例，覆盖 Connect API 各个阶段。"
    href="/zh-cn/connect/flow/"
/>
<LinkCard
    title="三密钥模型"
    description="一次登录如何通过 exposureKey、hiddenKey、confirmationKey 三把会话密钥相互证明合法。"
    href="/zh-cn/connect/three-key-model/"
/>
<LinkCard
    title="管理会话"
    description="Refresh、introspect、logout、revoke-all —— 登录之后的会话生命周期。"
    href="/zh-cn/guides/managing-sessions/"
/>
<LinkCard
    title="Sudomimus CLI"
    description="适合 AI 助手和本地自动化调用的命令行控制面。"
    href="/zh-cn/ai/cli/"
/>
</CardGrid>