Management API

Manage your Supabase organizations and projects programmatically.

Authentication#

All API requests require an access token to be included in the Authorization header: Authorization Bearer <access_token>.

There are two ways to generate an access token:

1. Personal access token (PAT): PATs are long-lived tokens that you manually generate to access the Management API. They are useful for automating workflows or developing against the Management API. PATs carry the same privileges as your user account, so be sure to keep it secret.

   To generate or manage your personal access tokens, visit your account page.

2. OAuth2: OAuth2 allows your application to generate tokens on behalf of a Supabase user, providing secure and limited access to their account without requiring their credentials. Use this if you're building a third-party app that needs to create or manage Supabase projects on behalf of your users. Tokens generated via OAuth2 are short-lived and tied to specific scopes to ensure your app can only perform actions that are explicitly approved by the user.

   See Build a Supabase Integration to set up OAuth2 for your application.

1
curl https://api.supabase.com/v1/projects \
2
  -H "Authorization: Bearer sbp_bdd0••••••••••••••••••••••••••••••••4f23"

All API requests must be authenticated and made over HTTPS.

速率限制 #

🌐 Rate limits

为了防止滥用并确保管理 API 的公平使用，会使用速率限制。速率限制是基于每个用户、每个范围的模式，也就是说每个用户在每个他们参与的项目和组织中都会有独立的速率限制。

🌐 Rate limits are applied to prevent abuse and ensure fair usage of the Management API. Rate limits are based on a per-user, per-scope model, meaning each user gets independent rate limits for each project and organization they interact with.

标准速率限制 #

🌐 Standard rate limit

当你超过这个速率限制时，接下来的一分钟内所有的 API 调用都会返回 429 Too Many Requests 响应。一旦时间窗口结束，你的请求配额会重置，你就可以再次发起请求。

🌐 When you exceed this rate limit, all subsequent API calls will return a 429 Too Many Requests response for the remainder of the minute. Once the time window expires, your request quota resets and you can make requests again.

速率限制范围 #

🌐 Rate limit scope

速率限制是按每个用户 + 每个范围隔离应用的：

🌐 Rate limits are applied with per-user + per-scope isolation:

• 项目范围：每个项目的速率限制是独立的。对一个项目的请求不会算作另一个项目的限制。
• 组织范围：速率限制对每个组织独立适用。对一个组织的请求不会计入另一个组织的限制。

这意味着你可以在同一分钟内对项目A发起120次请求，对项目B发起120次请求，而不会触发速率限制，因为它们是单独计算的。

🌐 This means you can make 120 requests to Project A and 120 requests to Project B within the same minute without hitting rate limits, as they are tracked separately.

速率限制响应头 #

🌐 Rate limit response headers

每个 API 响应都会包含遵循官方 HTTP 规范头 的速率限制信息：

🌐 Every API response includes rate limit information following official HTTP specification headers:

• X-RateLimit-Limit - 当前时间窗口允许的最大请求数
• X-RateLimit-Remaining - 在达到速率限制之前剩余的请求次数
• X-RateLimit-Reset - 距离你的速率限制重置还剩多少秒

你可以使用这些头信息来监控你的使用情况，并在收到 429 响应之前主动处理速率限制。

🌐 You can use these headers to monitor your usage and implement proactive rate limit handling before receiving a 429 response.

速率限制是如何被追踪的 #

🌐 How rate limits are tracked

你的请求会使用以下几种标识符之一进行识别和跟踪，优先顺序如下：

🌐 Your requests are identified and tracked using one of the following identifiers, in this order of priority:

1. OAuth 应用 ID - 如果你的请求是通过 OAuth 应用认证的
2. 用户 ID - 如果你的请求通过个人访问令牌进行身份验证
3. IP 地址 - 如果你的请求未经过身份验证（从请求头中提取）

每个标识符都会与作用域（项目或组织）结合，创建一个唯一的跟踪键。这可以确保速率限制在每个用户和每个作用域之间独立，防止一个项目或组织影响到另一个。

🌐 Each identifier is combined with the scope (project or organization) to create a unique tracking key. This ensures that rate limits are isolated per user and per scope, preventing one project or organization from affecting another.

端点异常 #

🌐 Endpoint exceptions

有些端点的速率限制比每分钟标准的 120 次请求更严格，以防止滥用资源密集型操作：

🌐 Some endpoints have stricter rate limits than the standard 120 requests per minute to prevent abuse of resource-intensive operations:

注意: GET /v1/projects/:ref/database/context 接口有双重速率限制。你每分钟最多可以发起10次请求，但每秒最多只能发起1次请求，以防流量突增。

有些端点每分钟有标准的 120 次请求，但超时时间不一样：

🌐 Some endpoints have the standard 120 requests per minute but with different timeout durations:

最佳实践 #

🌐 Best practices

• 监控速率限制头 - 查看 X-RateLimit-Remaining 头，了解你还剩下多少请求。当接近 0 时，放慢请求速度以避免触发限制。
• 实现指数退避 - 当你收到 429 响应时，先等一会再重试。你可以使用 X-RateLimit-Reset 头（秒）来确定究竟要等多久。
• 批量操作 - 尽量把多个操作合并成更少的 API 调用，以减少请求次数。
• 注意昂贵的端点 - 分析、数据库上下文和域端点的限制更严格，所以要谨慎使用它们。

The Management API is subject to our fair-use policy. All resources created via the API are subject to the pricing detailed on our Pricing pages.