Skip to main content
创建应用就是注册它。配置应用才让它真正工作。 本页按你应填写的顺序，逐一讲解应用编辑器中的四个标签页，并解释每个字段实际控制的内容。在构建 authorize 流程之前先把这些配好——大多数 OAuth 集成失败源自配置不匹配，而不是代码问题。
通过开发者控制台中的 “Your apps” 进入编辑器，或直接访问 https://fluz.app/for-developers/overview/{appId}。内嵌小部件使用相同的标签页，并额外多一个 Installation 标签页——见 配置应用小部件。
从 Your apps 中选择要配置的应用

​
各标签页包含什么

​
Overview 标签页

这里有两类内容，服务于完全不同的受众。

​
你的凭证

Client ID 与 Client Secret 在此标签页。本文其余页面中凡是要求用 Authorization: Basic base64(client_id:client_secret) 认证请求的，指的就是这两个值。API Key 和 API Secret 也在这里——它们是另一对、承担不同的职责。关于各凭证用途见 OAuth Applications。将它们拷入你的机密管理器。绝不要放进浏览器打包产物、移动端二进制或源代码管理。

​
你的公共身份

名称、副标题、描述、头像和标志是用户在同意屏上看到的内容，他们将据此决定是否把资金访问权限交给你的应用。把这些当作产品文案，而非内部标签。
即使你认为在创建时已填写好，也请复查此标签页。创建向导会收集三个文本字段，容易填个占位符就继续——然后就出现在上线的同意屏上。

​
Permissions 标签页

该页设置你的权限上限（scope ceiling）：你的应用将来可从任一用户请求的最大权限集合。它不等同于任何单个用户实际授予你的权限。 Permissions 标签页中的权限选择

​
选中的权限如何呈现给用户

用户不会看到原始枚举值。你勾选的权限会被归并到可读的顶层分组，同意屏展示并征求用户授权的是该分组。未勾选的权限不会出现在同意请求中——你的应用也将永远无法请求它们。 分组后的权限在同意屏上的呈现方式

​
必需权限

某些权限对你正在配置的应用或小部件类型是强制性的——缺少它们流程将无法运行。它们被归集在标签页底部，且用户在同意屏无法取消勾选。你会在此看到它们；你无需自行选择。

​
如何选择权限

从眼前这条流程所需出发，而不是未来可能会需要的。 完整参考：应用权限。
权限越少，转化越好。 同意屏是你集成中流失最高的步骤，而其长度由此标签页决定。更窄的上限也能在令牌泄露时缩小影响范围。只请求当下流程需要的；当你构建下一个功能时再扩大上限。

​
你无法自行选择的权限

PCI_COMPLIANCE 由 Fluz 在应用层面管理，仅授予已证明符合 PCI DSS 的开发者，生成令牌时无法请求。如果你需要自行处理原始卡数据，请联系你的 Fluz 客户经理。如果你不想处理，这正是内嵌小部件的用途——它们将卡片录入保留在 Fluz 的 PCI 范畴内。

​
之后变更权限

权限模型是应用级上限与每个用户授予的交集，这带来两个实际后果：
  • 在此处新增权限，并不会追溯地赋予已签发给你的用户令牌。现有用户必须重新授权，新权限才会对他们生效。
  • 在此处移除权限，会立即收窄所有用户的有效访问，不受其过去批准内容影响。
将权限变更当作架构迁移来规划，而非配置小改。

​
OAuth 标签页

OAuth 标签页中的重定向 URI 配置

​
Origin

承载该流程的域名——如 example.com、app.example.com。对内嵌小部件来说，这是小部件渲染的页面，必须匹配，否则小部件不会加载。

​
重定向 URI

用户批准或拒绝后，我们的授权服务器被允许将其发送到哪里。
  • 必须是我们的服务器可达的公共 URL。
  • 注册的 URI 上不要包含查询参数。请改用 state 参数携带上下文。
  • 按需注册任意多个——每个环境一个，每种流程变体一个。
  • 你在 /authorize 使用的 URI 必须已在此注册，且你发给 /token/exchange 的 URI 必须与 /authorize 使用的 URI 字节级完全一致。
对授权服务器来说，以下四个 URI 各不相同：
选定一个规范形式，将其存为单一常量，并在授权与交换两个步骤中都使用该常量。将其硬编码两次最容易造成不匹配。
明确注册你的本地回调——例如 http://localhost:3035/oauth/finalize。未在列表中将无法工作，且不应在生产应用上保留 localhost URI。

​
Webhook URL

从 Fluz 接收事件的公共 REST 端点——无需轮询即可得知转账完成、用户关闭了模态框、或验证已处理等信息。
  • 可按需添加任意数量的 URL。
  • 为每个 URL 订阅特定事件，从而将不同事件族路由至不同服务。
  • 未选择任何事件的 URL 将成为兜底，接收所有事件。开发期方便，生产环境会很嘈杂。
你的端点应快速确认并异步处理。仅做接收事件所需的最小工作，然后交给队列——缓慢的 webhook 处理会演变为投递问题。

​
构建前的自检

在这里花 5 分钟，可省去一下午调试 authorize 流程的时间。
1

凭证已从控制台转移到你的机密存储

Client ID、Client Secret、API Key、API Secret。确认没有进到被 git 跟踪的 .env 中。
2

同意屏文案可读、对用户友好

名称、副标题、描述、头像、标志均已填写，并面向用户撰写。
3

代码将调用的每个权限在 Permissions 中都已勾选

逐一过你计划调用的 API，确认其所需的每个权限均已启用。你请求但未在此启用的权限会被静默丢弃，而非被拒绝——因此该错误会在后续以令人困惑的权限问题暴露出来。
4

你的重定向 URI 以完全规范形式完成注册

包括协议、主机大小写和尾随斜杠。
5

手工构建一个 authorize URL 并打开它

使用 response_type=code、你的 client_id、你已注册的 redirect_uri，以及你的权限组装 /authorize，然后在浏览器中加载。若同意屏按预期展示你的品牌与权限，则配置正确。若报错，消息会指出不匹配项——你已在写代码前发现问题。→ 面向客户端的 OAuth 授权流程

​
预发布与生产是独立应用

不同环境不共享配置。生产应用需单独注册，拥有独立的 Client ID、Client Secret、API Key 和 API Secret，以及指向线上主机的独立重定向 URI 和 webhook 端点。 预发布环境的任何内容都不会自动沿用到生产——包括权限选择。上线前请基于你的生产应用重新核对整页内容。参见 部署到生产。

​
疑难排查

​
后续步骤

面向客户端的授权流程

构建 authorize URL 并处理回调。

交换授权码

将 code 转换为 access token 与 refresh token。

应用权限

完整的权限参考。

部署到生产

面向线上主机重新注册并上线。