OAuth API 方法

生成和管理 OAuth 令牌。

授权用户

GET /oauth/authorize HTTP/1.1

向用户显示授权表单。若获得批准，将创建并返回授权码，然后重定向到所需的 redirect_uri，或者若请求了 urn:ietf:wg:oauth:2.0:oob，则显示授权码。授权码可以在请求令牌并获得对用户级方法的访问权限时使用。

返回: 字符串（URL）或 HTML 响应
OAuth: 公开
版本历史记录:
0.1.0 - 添加
2.6.0 - 添加 force_login
3.5.0 - 添加 lang 4.3.0 - 添加 PKCE 参数支持

请求

查询参数

response_type: 必需字符串。应设置为等于 code。
client_id: 必需字符串。客户端 ID，在应用注册期间获得。
redirect_uri: 必需字符串。设置一个 URI 以将用户重定向到该 URI。若此参数设置为 urn:ietf:wg:oauth:2.0:oob，则将显示授权码。必须与应用注册期间声明的 redirect_uris 之一匹配。
scope: 字符串。请求的 OAuth 作用域列表，由空格分隔（若使用查询参数，则由加号分隔）。必须是应用注册期间声明的 scopes 的子集。若未提供，则默认为 read。
state: 字符串。任意值，用于在用户授权或拒绝授权请求时传递到你的服务。
code_challenge: 字符串。授权请求的 PKCE 代码质询。
code_challenge_method: 字符串。必须是 S256，因为这是 Mastodon 支持的唯一代码质询方法，用于 PKCE。
force_login: 布尔值。强制用户重新登录，这对于从同一实例使用多个帐户进行授权是必要的。
lang: 字符串。用于呈现授权表单的 ISO 639-1 双字符语言代码。

响应

200: OK

授权码将作为名为 code 的查询参数返回。

将 code 查询参数视为密码，你应确保它未记录在请求日志中。

redirect_uri?code=qDFUEaYrRK5c-HNmTCJbAzazwLRInJ7VHFat0wcMgCU

若使用了 state 参数，那么当客户端被重定向时，它也将出现在 URI 中。

redirect_uri?code=qDFUEaYrRK5c-HNmTCJbAzazwLRInJ7VHFat0wcMgCU&state=example

400: Client error

若授权码不正确或已被使用，则请求将失败。

{
  "error": "invalid_grant",
  "error_description": "提供的授权许可无效、已过期、已撤销、与授权请求中使用的重定向 URI 不匹配，或者已颁发给另一个客户端。"
}

获取令牌

POST /oauth/token HTTP/1.1

获取访问令牌，用于非公开 API 调用。

返回: 令牌
OAuth: 公开
版本历史记录:
0.1.0 - 添加 4.3.0 - 添加 PKCE 参数支持

请求

表单数据参数

grant_type: 必需字符串。若提供了 code 以获得用户级访问权限，则设置为等于 authorization_code。否则，设置为等于 client_credentials 以仅获得应用级别访问权限。
code: 必需字符串。用户授权码，从授权请求获得批准后的重定向中获得。若 redirect_uri 为 urn:ietf:wg:oauth:2.0:oob，则也可以选择向用户显示。
client_id: 必需字符串。客户端 ID，在应用注册期间获得。
client_secret: 必需字符串。客户端密钥，在应用注册期间获得。
redirect_uri: 必需字符串。必须与授权请求期间使用的 redirect_uri 匹配。
code_verifier: 字符串。若在授权请求期间使用了 PKCE，则为必填项。这是用于使用授权请求的 code_challenge_method 创建 code_challenge 的代码验证器。
scope: 字符串。当 grant_type 设置为 client_credentials 时，为请求的 OAuth 作用域列表，以空格分隔（若使用查询参数，则用加号分隔）。必须是在创建应用时请求的作用域的子集。若省略，则默认为 read。当 grant_type 为 authorization_code 时，无效。

响应

200: OK

存储此 access_token 以供以后与需要身份验证的方法一起使用。令牌应作为 HTTP Authorization 标头传递，值为 Bearer <access_token>。

将 access_token 视为密码。我们建议你在将其存储在缓存中时对其进行加密，以防止凭据泄露。

此外，你应确保不记录 code 参数。

{
  "access_token": "ZA-Yj3aBD8U8Cm7lKUp-lm9O9BmDgdhHzDeqsY8tlL0",
  "token_type": "Bearer",
  "scope": "read write follow push",
  "created_at": 1573979017
}

400: Client error

若你尝试请求注册应用时未包含的作用域，则请求将失败。

{
  "error": "invalid_scope",
  "error_description": "请求的作用域无效、未知或格式不正确。"
}

401: Unauthorized

若 client_id 和 client_secret 不匹配或无效，则请求将失败。

{
  "error": "invalid_grant",
  "error_description": "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client."
}

撤销令牌

POST /oauth/revoke HTTP/1.1

撤销访问令牌，使其不再有效。

返回: 空
OAuth: 公开
版本历史记录:
0.1.0 - 添加

请求

表单数据参数

client_id: 必需字符串。客户端 ID，在应用注册期间获得。
client_secret: 必需字符串。客户端密钥，在应用注册期间获得。
token: 必需字符串。先前获得的令牌，将被设置为无效。

响应

200: OK

若你拥有提供的令牌，则 API 调用将提供一个空响应。此操作是幂等的，因此多次调用此 API 仍将返回 OK。

{}

403: Forbidden

若你提供了一个你并未拥有的令牌，或者根本没有提供任何令牌，则 API 调用将返回 403 错误。

{
  "error": "unauthorized_client",
  "error_description": "You are not authorized to revoke this token"
}

发现 OAuth 实例配置

GET /.well-known/oauth-authorization-server HTTP/1.1

返回 Mastodon 实例的 OAuth 2 授权实例元数据，按 RFC 8414 规范要求定义。

我们包括了 app_registration_endpoint 的附加非标准属性，该属性是指 POST /api/v1/apps 端点，因为我们目前不支持用于动态客户端注册的标准 registration_endpoint 端点。

此端点公开的属性可以帮助你更好地与 Mastodon API 集成，例如允许协商不同 Mastodon 版本中的 scopes。

示例: 你希望使用 profile 作用域，但也想支持没有该作用域且需要 read:accounts 的旧版 Mastodon 实例。你可以通过向此端点发出请求来发现实例是否支持该作用域。

返回: 如上所述的 JSON
OAuth: 公开
版本历史记录:
4.3.0 - 添加

响应

200: OK

{
  "issuer": "https://social.example/",
  "service_documentation": "https://docs.joinmastodon.org/",
  "authorization_endpoint": "https://social.example/oauth/authorize",
  "token_endpoint": "https://social.example/oauth/token",
  "app_registration_endpoint": "https://social.example/api/v1/apps",
  "revocation_endpoint": "https://social.example/oauth/revoke",
  "scopes_supported": [
    "read",
    "write",
    "write:accounts",
    "write:blocks",
    "write:bookmarks",
    "write:conversations",
    "write:favourites",
    "write:filters",
    "write:follows",
    "write:lists",
    "write:media",
    "write:mutes",
    "write:notifications",
    "write:reports",
    "write:statuses",
    "read:accounts",
    "read:blocks",
    "read:bookmarks",
    "read:favourites",
    "read:filters",
    "read:follows",
    "read:lists",
    "read:mutes",
    "read:notifications",
    "read:search",
    "read:statuses",
    "follow",
    "push",
    "profile",
    "admin:read",
    "admin:read:accounts",
    "admin:read:reports",
    "admin:read:domain_allows",
    "admin:read:domain_blocks",
    "admin:read:ip_blocks",
    "admin:read:email_domain_blocks",
    "admin:read:canonical_email_blocks",
    "admin:write",
    "admin:write:accounts",
    "admin:write:reports",
    "admin:write:domain_allows",
    "admin:write:domain_blocks",
    "admin:write:ip_blocks",
    "admin:write:email_domain_blocks",
    "admin:write:canonical_email_blocks"
  ],
  "response_types_supported": ["code"],
  "response_modes_supported": ["query", "fragment", "form_post"],
  "code_challenge_methods_supported": [
    "S256"
  ],
  "grant_types_supported": [
    "authorization_code",
    "client_credentials"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post"
  ]
}