apps API 方法
注册可用于获取 OAuth 令牌的客户端应用。
创建一个应用
POST /api/v1/apps HTTP/1.1
创建一个新的应用以获取 OAuth2 凭据。
client_id 和 client_secret 将不会被 Mastodon 实例识别。这种自动删除应用的机制已在 Mastodon 4.3 中移除。
对于低于 4.3 的 Mastodon 版本，解决方案之一是注册你的应用，然后立即请求一个 Client Credential 令牌，这将永久确保你的应用始终具有有效的访问令牌，并且不会被移除。
client_secret 和 client_secret_expires_at 属性。有关更多信息，请参见：OAuth 2 客户端类型
返回： CredentialApplication
OAuth： 公开
版本历史：
0.0.0 - 添加
2.7.2 - 现在返回 vapid_key
4.3.0 - 弃用 vapid_key，请参见 api/v2/instance
4.3.0 - 添加了对表单数据参数中多个 redirect_uris 的支持
4.3.0 - 添加了 redirect_uris 响应属性
4.3.0 - 弃用 redirect_uri 响应属性，因为若注册了多个 redirect_uris，这可能不是一个 URI，请改用 redirect_uris
4.3.0 - 将实体类型从 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 作用域。 - website
- 字符串。你的应用主页的 URL。
响应
200: OK
将 client_id 和 client_secret 存储在你的缓存中，因为这些将用于获取 OAuth 令牌。
client_id 和 client_secret 属性视为密码。我们建议你在存储在缓存中时对其进行加密，以防止凭据泄露。{
"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"
}
redirect_uri 属性被视为已被弃用，不应使用，而应使用 redirect_uris 属性。422: Unprocessable entity
若缺少必需的参数或格式不正确，则请求失败。
{
"error": "Validation failed: Redirect URI must be an absolute URI."
}
验证你的应用是否有效
GET /api/v1/apps/verify_credentials HTTP/1.1
确认应用的 OAuth2 凭据是否有效。
返回： Application
OAuth： 应用令牌
版本历史：
2.0.0 - 添加
2.7.2 - 现在返回 vapid_key
4.3.0 - 弃用 vapid_key，请参见 api/v2/instance
4.3.0 - 移除需使用 read 作用域才能访问此 API 的要求，现在可以使用任何有效的应用令牌
4.3.0 - 添加了 scopes 和 redirect_uris 属性
请求
标头
- Authorization
- 必需 提供此标头以及
Bearer <app_token>以获得对此 API 方法的访问授权。<app_token>可以是从/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"
}
另请参考
app/controllers/api/v1/apps_controller.rb app/controllers/api/v1/apps/credentials_controller.rb翻译状态： 本文是英文页面 apps API methods 的翻译，最后翻译时间：2025-04-21，点击这里可以查看翻译后页面的改动。