Skip to main content

​
这里为什么需要 OAuth

你的应用已经可以在你自己的账户上完成 Fluz API 提供的一切能力。你用 API key 铸造一个令牌就可以调用——参见 Authentication 和 API credentials。 当账户不属于你时，你就需要一个 OAuth 应用。 当你想在客户的钱包上开卡、从他们关联的银行账户扣款、读取他们的交易，或向他们付款时，你需要该用户的明确授权——并且需要一种 Fluz 可验证、可限定范围、可过期、可撤销的形式。这就是 OAuth 应用的作用：为你的软件注册一个身份，加上一套同意机制，把用户的批准转换成你服务器可使用的令牌。
一旦你持有了以客户为作用域的令牌，API 是完全一致的。用你自己的令牌调用 createVirtualCard 会在你的钱包上创建卡；用客户令牌进行同样的 mutation 会在他们的钱包上创建。OAuth 改变的是_你操作的账户归属_，而不是你能做什么。

​
你是否需要一个？

你在自己的 Fluz 账户内发卡、购买礼品卡或划转资金：拨付引擎、批量制卡、内部消费工具、ERP 同步。使用你的应用 API key 直接调用 generateUserAccessToken。不需要 OAuth 应用、无需同意页、无需重定向。从这里开始：API credentials。

​
三组凭证，各司其职

本节最常见的困惑在于，一个 Fluz 应用携带不止一对凭证，而且它们不可互换。
这里的每个 secret 都能铸造权限。泄露 apiSecret 将让他人以你的平台身份签署交易；泄露 client_secret 将让他人以你的应用身份交换代码。两者都应仅保存在服务器端，勿进浏览器打包、移动端二进制、或版本控制。

​
权限模型

Fluz 在两个层级上强制权限，一个应用的有效访问是这两者的交集。
1

应用级授权——上限

在你的应用 Permissions 选项卡中设置。这是你的应用在任何用户无关的前提下所能请求的最大范围。若你在 authorize URL 中包含了未在此处启用的 scope，将被静默忽略——请求不会报错，但该 scope 不会被授予。某些 scope 由 Fluz 管理而非自助选择。PCI_COMPLIANCE 仅在应用级授予，授予给已证明符合 PCI DSS 合规的开发者，且在生成令牌时无法请求。
2

用户级授权——下限

由终端用户在同意页上设置。他们会看到你请求的 scopes——以可读的顶层分组呈现，而非原始枚举值——并予以批准。任何他们拒绝的内容都不会被授予。
3

两者都必须有效

在 generateUserAccessToken 处验证，而非在调用时验证。两类授权都必须存在且未过期。因此被撤销或失效的授权会表现为令牌生成失败，而不是流程中途的权限错误——这通常是当一个之前正常的集成突然失效时首要检查之处。
按能力划分的 scopes： 使用 getApplicationScopes 读取当前已授予的内容。完整参考：Application Scopes。
少即是多。 更短的同意页转化更高，更窄的令牌在泄露时风险更小。只请求当前流程所需的范围，需要更多时再铸造新令牌。

​
全流程生命周期

下面每一步都有对应的深入页面。此处是地图；那些页面是领地。
1

创建应用

在开发者控制台选择 Browse templates 并添加 OAuth Integration 模板。为其命名、副标题、描述——这三项将出现在用户的同意页上，因此写给人看，而不是写给你的问题跟踪器。→ Create an OAuth App
2

进行配置

在 Permissions 选项卡选择你的 scope 上限。在 OAuth 选项卡设置你的 Redirect URIs（公开、无查询参数、数量不限）以及 Webhook URLs（每个可选订阅特定事件；未选任何事件的 URL 作为兜底）。在 Overview 添加头像和标志——没有它们同意页会显得不完整。→ Configure OAuth App
3

引导用户授权

重定向到 /authorize，携带 response_type=code、你的 client_id、一个已注册的 redirect_uri、以空格分隔的 scopes 列表，以及可选的 state 值（将原样返回给你）。→ Client-facing OAuth grant flow
4

接收代码

获批后，Fluz 会重定向到你的 redirect_uri，附带 code 以及你原始的 state。若配置有误，重定向会带上描述不匹配项的错误消息。
5

用代码交换令牌

调用 /token/exchange，携带该 code 和完全相同的 redirect_uri，并使用 Authorization: Basic base64(client_id:client_secret) 进行认证。你将获得 accessToken、refreshToken、过期时间戳，以及确认的 scope 数组。→ Exchanging an OAuth authorization code
6

刷新，不要重提权限

使用 refresh_token 调用 /token/refresh，并使用相同的 Basic 认证头。访问令牌有意设置为短期有效——大约十分钟——而刷新令牌大约可维持一个月。请在后台静默刷新；仅当刷新令牌本身过期或授权被撤销时，再让用户走一遍同意流程。→ Refreshing an OAuth accessToken
7

上线

预发布与生产是独立的环境，拥有独立的应用与凭证。两者不会互通——你需要在生产主机上重新注册应用、重配重定向 URI 和 webhook 端点。→ Deploying to Production

​
易踩的规则

在开始前值得内化，因为这些问题往往悄无声息或表现含糊。
你发往 /authorize 的 redirect_uri 必须已在应用上注册，而发往 /token/exchange 的必须与 /authorize 使用的那一个字节级完全一致。结尾斜杠、http 与 https、主机大小写都算差异。不要在 URI 本身注册查询参数——使用 state 承载上下文。
如果你请求了在 Permissions 选项卡上未勾选的 scope，授权请求仍会成功——该 scope 会被丢弃。始终读取交换响应中的 scope 数组，并以它为准，而不是你的请求。
立刻在服务器端交换且只交换一次。如果你的重定向处理器可能被重放——例如用户刷新回调页、或链接预取——确保第二次尝试不会破坏状态。
Authorization: Basic <base64(client_id + ":" + client_secret)>。对拼接后的字符串编码。交换步骤的大多数集成失败都在这里。
重定向是一次全新的浏览器导航。如果你需要知道是哪个用户、哪个流程、或要返回哪个页面，把签名的或可在服务器端查询的引用放进 state。不要放敏感信息——它会经过用户浏览器。
如果 generateUserAccessToken 开始对昨天还正常的用户失败，在检查你的代码之前，先确认应用级授权或用户级授权是否过期或被撤销。

​
OAuth 应用与 widget 的区别

两者都是应用。都使用上述权限模型。区别在于由谁来构建同意界面。 你可以混合使用：通过 API 完成用户注册与 KYC，然后仅为同意与敏感信息采集打开 widget。混合模式参见 Embedded Widgets。

​
下一步

创建一个 OAuth 应用

从 OAuth Integration 模板注册你的应用。

配置 OAuth 应用

Scopes、重定向 URI、webhooks、品牌化。

面向客户端的授权流程

构建 authorize URL 并处理回调。

交换授权码

将 code 转换为 access token 与 refresh token。

刷新访问令牌

在不重新提示用户的情况下保持授权。

部署到生产环境

在生产主机上重新注册并上线。
正在构建一个让你的每位客户都拥有 Fluz 账户的平台？Build a platform 端到端讲解整个模式，并且 API Features 上的每项能力在已连接账户上都可同样使用。