授权头

每个对 Edge Function 的请求都会经过两层认证。首先，在你的代码执行之前，会进行平台级检查（verify_jwt）。然后，一旦请求到达你的处理器，你可以决定如何处理调用方发送的凭证。本页是两层认证的参考。至于基于它们的实用模式，请参见 Securing Edge Functions 。

🌐 Every request to an Edge Function passes through two layers of auth. First, a platform-level check (verify_jwt) runs before your code executes. Then, once the request reaches your handler, you decide what to do with the credentials the caller sent. This page is the reference for both layers. For the practical patterns built on top of them, see Securing Edge Functions.

了解授权头 #

🌐 Understanding authorization headers

Edge Functions 关心两个请求头。在错误的头里发送错误的凭证是导致 401 错误最常见的原因。

🌐 Edge Functions care about two request headers. Sending the wrong credential in the wrong header is the most common source of 401 errors.

一个常见的错误是把可发布的或私密的密钥作为承载令牌发送：Authorization: Bearer sb_publishable_...。新的 API 密钥不是 JWT。平台检查无法验证它们，你的处理程序也无法将它们作为 JWT 验证。相反，把 API 密钥放在 apikey 头里。

🌐 A common mistake is sending a publishable or secret key as a bearer token: Authorization: Bearer sb_publishable_.... The new API keys are not JWTs. The platform check can't validate them, and your handler can't verify them as JWTs either. Instead, put API keys in the apikey header.

你可以一起发送两个头。例如，通过 supabase-js 调用你的函数的已登录用户，会在 Authorization 中发送他们的会话 JWT，并在 apikey 中发送项目的可发布密钥。

🌐 You can send both headers together. A signed-in user calling your function through supabase-js, for example, sends their session JWT in Authorization and the project's publishable key in apikey.

verify_jwt#

🌐 The verify_jwt platform check

当启用 verify_jwt（默认情况下）时，平台会在你的函数运行之前检查每个请求的 Authorization 头。它期望有一个有效的用户 JWT。如果头缺失、格式错误，或者使用了不同的密钥签名，平台会返回 401 错误，你的代码根本不会执行。

🌐 When verify_jwt is enabled (the default), the platform inspects the Authorization header of every request before your function runs. It expects a valid user JWT. If the header is missing, malformed, or signed with a different key, the platform returns a 401 error, and your code never executes.

该检查验证传统的 HS256 JWT 和使用新的非对称签名密钥签署的 JWT。

🌐 The check validates legacy HS256 JWTs and JWTs signed with the new asymmetric signing keys.

这个检查不接受 API 密钥。可发布和密钥并不是 JWT，所以那些在 Authorization 头中发送它们的调用者会在请求到达你的处理器之前就被检查失败。

🌐 The check does not accept an API key. Publishable and secret keys are not JWTs, so callers that send one in the Authorization header fail the check before their request reaches your handler.

使用 verify_jwt 标志来匹配函数的调用方式：

🌐 Use the verify_jwt flag to match how the function is called:

• 保持 verify_jwt 开启 适用于仅通过用户 JWT 调用的函数，例如通过 supabase.functions.invoke 从客户端调用的函数。平台会在请求到达你的代码之前拒绝未认证的请求，因此你的处理程序可以信任 JWT 是有效的。
• 关闭 verify_jwt 用于那些在没有 Authorization 头的情况下调用的函数，比如来自外部提供商的 webhooks，或者使用 API 密钥进行认证的服务间调用。这些模式在 保护 Edge 函数 中有介绍。

在 supabase/config.toml 中为每个函数设置标志：

🌐 Set the flag per function in supabase/config.toml:

1
[functions.stripe-webhook]
2
verify_jwt = false

关于 401 故障模式及如何诊断它们，请参见 Edge Function 401 错误响应。

🌐 For 401 failure modes and how to diagnose them, see Edge Function 401 error response.