docs-mastodon/content/zh-cn/methods/apps.md

title	description	menu	aliases
apps API 方法	注册可用于获取 OAuth 令牌的客户端应用。	docs weight name parent identifier 10 apps methods methods-apps	/methods/apps /api/methods/apps

创建一个应用

POST /api/v1/apps HTTP/1.1

创建一个新的应用以获取 OAuth2 凭据。

{{< hint style="danger" >}} 在 4.3 之前的 Mastodon 版本中，OAuth 应用可能会在特定条件下被“清理”并从数据库中移除，这意味着你的应用的 client_id 和 client_secret 将不会被 Mastodon 实例识别。
这种自动删除应用的机制已在 Mastodon 4.3 中移除。

对于低于 4.3 的 Mastodon 版本，解决方案之一是注册你的应用，然后立即请求一个 [Client Credential]({{< relref "client/Token#flow" >}}) 令牌，这将永久确保你的应用始终具有有效的访问令牌，并且不会被移除。 {{< /hint >}}

{{< hint style="info" >}} 目前，Mastodon 仅支持配置机密客户端，也就是说，你始终会在 [CredentialApplication]({{< relref "entities/Application#CredentialApplication" >}}) 实体中收到 client_secret 和 client_secret_expires_at 属性。

有关更多信息，请参见：[OAuth 2 客户端类型]({{< relref "spec/oauth#client-types" >}}) {{< /hint >}}

返回： [CredentialApplication]({{< relref "entities/Application#CredentialApplication" >}})
OAuth： 公开
版本历史：
0.0.0 - 添加
2.7.2 - 现在返回 vapid_key
4.3.0 - 弃用 vapid_key，请参见 [api/v2/instance]({{< relref "methods/Instance#v2">}})
4.3.0 - 添加了对表单数据参数中多个 redirect_uris 的支持
4.3.0 - 添加了 redirect_uris 响应属性
4.3.0 - 弃用 redirect_uri 响应属性，因为若注册了多个 redirect_uris，这可能不是一个 URI，请改用 redirect_uris
4.3.0 - 将实体类型从 [Application]({{< relref "entities/Application">}}) 更改为 [CredentialApplication]({{< relref "entities/Application#CredentialApplication">}})

请求

请求示例：

POST /api/v1/apps HTTP/1.1
Content-Type: application/json

{
  "client_name": "Test Application",
  "redirect_uris": ["https://app.example/callback", "https://app.example/register"],
  "scopes": "read write push",
  "website": "https://app.example"
}

表单数据参数

client_name

{{}} 字符串。你的应用的名称。

redirect_uris

{{}} 字符串或字符串数组。授权后用户应重定向到的位置。要向用户显示授权码，而不是重定向到网页，请在此参数中使用 urn:ietf:wg:oauth:2.0:oob。

scopes

字符串。以空格分隔的作用域列表。若未提供，则默认为 read。有关可能的作用域列表，请参见 [OAuth 作用域]({{< relref "api/oauth-scopes" >}})。

website

字符串。你的应用主页的 URL。

响应

200: OK

将 client_id 和 client_secret 存储在你的缓存中，因为这些将用于获取 OAuth 令牌。

{{< hint style="warning" >}} 将 client_id 和 client_secret 属性视为密码。我们建议你在存储在缓存中时对其进行加密，以防止凭据泄露。 {{< /hint >}}

{
  "id": "563419",
  "name": "Test Application",
  "website": "https://app.example",
  "scopes": ["read", "write", "push"],
  "redirect_uri": "urn:ietf:wg:oauth:2.0:oob",
  "redirect_uris": ["urn:ietf:wg:oauth:2.0:oob"],
  "client_id": "TWhM-tNSuncnqN7DBJmoyeLnk6K3iJJ71KKXxgL1hPM",
  "client_secret": "ZEaFUFmF0umgBX1qKJDjaU99Q31lDkOU8NutzTOoliw"
}

或者使用多个重定向 URI：

{
  "id": "563419",
  "name": "Test Application",
  "website": "https://app.example",
  "scopes": ["read", "write", "push"],
  "redirect_uri": "https://app.example/callback\nhttps://app.example/register",
  "redirect_uris": [
    "https://app.example/callback",
    "https://app.example/register"
  ],
  "client_id": "TWhM-tNSuncnqN7DBJmoyeLnk6K3iJJ71KKXxgL1hPM",
  "client_secret": "ZEaFUFmF0umgBX1qKJDjaU99Q31lDkOU8NutzTOoliw"
}

{{< hint style="info" >}} 自 4.3.0 起，以上示例中的 redirect_uri 属性被视为已被弃用，不应使用，而应使用 redirect_uris 属性。 {{< /hint >}}

422: Unprocessable entity

若缺少必需的参数或格式不正确，则请求失败。

{
  "error": "Validation failed: Redirect URI must be an absolute URI."
}

---

验证你的应用是否有效

GET /api/v1/apps/verify_credentials HTTP/1.1

确认应用的 OAuth2 凭据是否有效。

返回： [Application]({{< relref "entities/application" >}})
OAuth： 应用令牌
版本历史：
2.0.0 - 添加
2.7.2 - 现在返回 vapid_key
4.3.0 - 弃用 vapid_key，请参见 [api/v2/instance]({{< relref "methods/Instance#v2">}})
4.3.0 - 移除需使用 read 作用域才能访问此 API 的要求，现在可以使用任何有效的应用令牌
4.3.0 - 添加了 scopes 和 redirect_uris 属性

请求

标头

Authorization

{{}} 提供此标头以及 Bearer <app_token> 以获得对此 API 方法的访问授权。<app_token> 可以是从 [/oauth/token]({{< relref "methods/oauth#token" >}}) 返回的 client_credential 或 access_token。

响应

200: OK

若 Authorization 标头提供了有效的令牌，你应该看到你的应用作为 Application 实体返回。

{
  "name": "Test Application",
  "website": "https://app.example",
  "scopes": ["read", "write", "push"],
  "redirect_uris": [
    "https://app.example/callback",
    "https://app.example/register"
  ]
}

401: Unauthorized

若 Authorization 标头包含无效的令牌、格式不正确或不存在，则将返回提示授权失败的错误。

{
  "error": "The access token is invalid"
}

---

另请参考

{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/apps_controller.rb" caption="app/controllers/api/v1/apps_controller.rb" >}}

{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/apps/credentials_controller.rb" caption="app/controllers/api/v1/apps/credentials_controller.rb" >}}

{{< translation-status-zh-cn raw_title="apps API methods" raw_link="/methods/apps/" last_translation_time="2025-04-21" raw_commit="6addd5cf525adec1859f48c52dafcfe1f96e558a">}}