获取客户端应用访问权限

身份验证和授权

到目前为止，我们一直在处理公开可用的信息，但并非所有信息都是公开的。某些信息在查看之前需要获得许可，以便审计谁在请求该信息（并可能撤销或拒绝访问）。

这就是 OAuth 发挥作用的地方。OAuth 是一种生成访问令牌的机制，该令牌可用于 验证 请求来自特定客户端，并确保请求的操作已获得服务器访问控制策略的 授权。

创建应用

我们需要做的第一件事是注册一个应用，以便稍后能够生成访问令牌。可以像这样创建应用：

curl -X POST \
	-F 'client_name=Test Application' \
	-F 'redirect_uris=urn:ietf:wg:oauth:2.0:oob' \
	-F 'scopes=read write push' \
	-F 'website=https://myapp.example' \
	https://mastodon.example/api/v1/apps

在上面的示例中，我们指定了客户端名称和网站，如果适用，它们将显示在状态中。但更重要的是，请注意以下两个参数：

• redirect_uris 被设置为“非常规”令牌生成，这意味着任何生成的令牌都必须手动复制和粘贴。该参数之所以称为 redirect_uris，是因为可以定义多个重定向 URI，但是在生成令牌时，我们需要提供一个包含在此列表中的 URI。
• scopes 允许我们定义稍后可以请求的权限。但是，稍后请求的范围需要是这些已注册范围的子集。有关更多信息，请查看 OAuth 范围。

你还可以将 JSON 请求体 POST 到同一端点来创建应用，如POST /api/v1/apps 中所述。

我们应该看到返回了一个 CredentialApplication 实体，但目前，我们只关心 client_id 和 client_secret。

client_id 和 client_secret 值将用于生成访问令牌，因此应将其缓存以供以后使用。有关注册应用程序的更多详细信息，请查看 POST /api/v1/apps。

身份验证代码示例

现在我们有了一个应用，让我们获取一个访问令牌，该令牌将以刚创建好的应用的身份令服务端验证我们的请求。为此，请使用 POST /oauth/token 如下所示：

curl -X POST \
	-F 'client_id=your_client_id_here' \
	-F 'client_secret=your_client_secret_here' \
	-F 'redirect_uri=urn:ietf:wg:oauth:2.0:oob' \
	-F 'grant_type=client_credentials' \
	https://mastodon.example/oauth/token

请注意以下事项：

• 注册应用时，client_id 和 client_secret 已在响应体中提供。
• redirect_uri 必须是在注册应用时定义的 URI 之一。
• 我们正在请求 client_credentials 的 grant_type，默认情况下会为我们提供 read 范围。

此方法的响应是一个 Token 实体。我们将需要 access_token 值。获得访问令牌后，将其保存在你的本地缓存中。

要在请求中使用它，请将 HTTP 标头 Authorization: Bearer <access_token> 添加到任何需要 OAuth 的 API 调用（即，不可公开访问的 API 调用）。

让我们通过调用 GET /api/v1/apps/verify_credentials 来验证我们获得的凭据是否有效：

curl \
	-H 'Authorization: Bearer <access_token>' \
	https://mastodon.example/api/v1/apps/verify_credentials

如果我们已经获得了我们的令牌并正确格式化了我们的请求，我们应该看到我们的详细信息通过 Application 实体返回给我们（不包括 client_secret 属性）。

我们可以用身份验证做什么

通过经过身份验证的客户端应用程序，我们可以查看帐户之间的关系，例如 GET /api/v1/accounts/:id/following 和 GET /api/v1/accounts/:id/followers。此外，某些实例可能要求对本来可以公开访问的方法进行身份验证，因此如果你之前在尝试使用公共方法时遇到任何身份验证错误，这些方法现在应该可以工作了。

最后更新于 April 21, 2025 · 改进此页面
也可在此找到： English