A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Supabase API is how an app or AI agent manages a Supabase account from the outside: listing and creating projects, running SQL against a project's database, deploying Edge Functions, reading and writing secrets, and changing auth settings. Access is granted through an access token, where a personal access token carries the full reach of the user who made it, while an OAuth app is limited to the permissions granted when it was authorized. It manages the projects rather than the data inside them, and it has no event stream to subscribe to.
How an app or AI agent connects to Supabase determines what it can reach. There are several routes, each governed by the access token behind it and, for an OAuth app, the permissions that token carries.
The Management API answers at https://api.supabase.com under the /v1 path prefix. It is a REST API for managing projects, the database, functions, secrets, and config, and every call carries an access token as a bearer token.
Supabase publishes a first-party MCP server at https://mcp.supabase.com/mcp, which lets an AI assistant manage projects, run SQL, deploy functions, and read logs. It authenticates by OAuth through dynamic client registration by default, and also accepts a personal access token. It supports a read-only mode and a single-project scope, and Supabase recommends pointing it at a development project. The source is at github.com/supabase-community/supabase-mcp.
An OAuth app is authorized through a browser flow and exchanges an auth code for an access and refresh token at https://api.supabase.com/v1/oauth/token. It acts on behalf of a Supabase user and is limited to the fine-grained permissions granted at authorization.
A personal access token is generated by hand in the dashboard and sent as a bearer token. It carries the full reach of the account that created it, across every project and organization, with no way to narrow it to one project or one permission.
An OAuth app token is issued through an authorization flow and is limited to the fine-grained permissions granted when the app was authorized, such as database_read or edge_functions_write. It is the least-privilege choice and the one meant for software acting on behalf of other users.
The Management API is split into areas an agent can act on, such as projects, the database, Edge Functions, secrets, and auth configuration. Each area has its own methods and its own permission, and some grant access to far more than others.
List, read, create, and delete projects, and pause or restore a project.
List the organizations the account belongs to and create a new one.
Run SQL against a project's Postgres database, run read-only SQL, list and apply migrations, and enable Database Webhooks.
List, read, create, update, deploy, and delete a project's Edge Functions, and read a function's body.
List a project's secrets, bulk-create secrets, and bulk-delete them by name.
Read and update a project's auth configuration, such as sign-up rules and SMTP settings.
Read and update a project's Postgres configuration and storage configuration.
List a project's storage buckets.
List and create a project's data-API keys.
List, read, create, update, and delete a project's database branches.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
ProjectsList, read, create, and delete projects, and pause or restore a project.6 | ||||||
| GET | /v1/projects | List all projects the account has created. | read | projects_read | Current | |
OAuth-app permission. A personal access token ignores permissions and lists every project the account can reach. Acts onproject Permission (capability) projects_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/projects | Create a new project in an organization. | write | organization_projects_create | Current | |
OAuth-app permission. Creating a project incurs billing on a paid organization. Acts onproject Permission (capability) organization_projects_createVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/projects/{ref} | Get a single project's details. | read | project_admin_read | Current | |
OAuth-app permission. ref is the project's reference id. Acts onproject Permission (capability) project_admin_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/projects/{ref} | Delete a project. | write | project_admin_write | Current | |
OAuth-app permission. This destroys the project and its database. Acts onproject Permission (capability) project_admin_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/projects/{ref}/pause | Pause a project. | write | project_admin_write | Current | |
OAuth-app permission. A paused project stops serving requests until it is restored. Acts onproject Permission (capability) project_admin_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/projects/{ref}/restore | Restore a paused project. | write | project_admin_write | Current | |
OAuth-app permission. Acts onproject Permission (capability) project_admin_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
OrganizationsList the organizations the account belongs to and create a new one.2 | ||||||
| GET | /v1/organizations | List the organizations the account belongs to. | read | organizations_read | Current | |
OAuth-app permission. Acts onorganization Permission (capability) organizations_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/organizations | Create an organization. | write | organizations_create | Current | |
OAuth-app permission. Acts onorganization Permission (capability) organizations_createVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DatabaseRun SQL against a project's Postgres database, run read-only SQL, list and apply migrations, and enable Database Webhooks.5 | ||||||
| POST | /v1/projects/{ref}/database/query | Run an arbitrary SQL query against the project's Postgres database. Marked Beta. | write | database_write | Current | |
OAuth-app permissions: database_write and database_read. The statement can read or write anything in the database, so this is the widest-reaching call in the API. Acts onquery Permission (capability) database_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/projects/{ref}/database/query/read-only | Run a SQL query as the restricted supabase_read_only_user, which cannot write. Marked Beta. | read | database_read | Current | |
OAuth-app permission. Runs as a read-only Postgres role, so it is the safer choice when an agent only needs to read. Acts onquery Permission (capability) database_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/projects/{ref}/database/migrations | List the applied migration versions. | read | database_migrations_read | Current | |
OAuth-app permission. Acts onmigration Permission (capability) database_migrations_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/projects/{ref}/database/migrations | Apply a database migration and record it in the migration history. | write | database_migrations_write | Current | |
OAuth-app permission. Runs schema changes against the database and keeps a recorded history. Acts onmigration Permission (capability) database_migrations_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/projects/{ref}/database/webhooks/enable | Enable the Database Webhooks feature on the project. Marked Beta. | write | database_webhooks_config_write | Current | |
OAuth-app permission. This turns on a per-project feature that sends row changes to a URL; it is not an event stream from the Management API. Acts ondatabase webhook Permission (capability) database_webhooks_config_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Edge FunctionsList, read, create, update, deploy, and delete a project's Edge Functions, and read a function's body.5 | ||||||
| GET | /v1/projects/{ref}/functions | List all Edge Functions in a project. | read | edge_functions_read | Current | |
OAuth-app permission. Acts onfunction Permission (capability) edge_functions_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/projects/{ref}/functions/{function_slug} | Retrieve a single Edge Function. | read | edge_functions_read | Current | |
OAuth-app permission. A separate body endpoint returns the function's source. Acts onfunction Permission (capability) edge_functions_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/projects/{ref}/functions/deploy | Deploy an Edge Function. | write | edge_functions_write | Current | |
OAuth-app permission. This changes the code that runs on the project. Acts onfunction Permission (capability) edge_functions_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v1/projects/{ref}/functions/{function_slug} | Update an Edge Function's settings or code. | write | edge_functions_write | Current | |
OAuth-app permission. Acts onfunction Permission (capability) edge_functions_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/projects/{ref}/functions/{function_slug} | Delete an Edge Function. | write | edge_functions_write | Current | |
OAuth-app permission. Acts onfunction Permission (capability) edge_functions_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SecretsList a project's secrets, bulk-create secrets, and bulk-delete them by name.3 | ||||||
| GET | /v1/projects/{ref}/secrets | List the secrets added to a project. | read | edge_functions_secrets_read | Current | |
OAuth-app permission. Secrets are the credentials an Edge Function runs with. Acts onsecret Permission (capability) edge_functions_secrets_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/projects/{ref}/secrets | Bulk-create secrets on a project. | write | edge_functions_secrets_write | Current | |
OAuth-app permission. Accepts several secrets in one call. Acts onsecret Permission (capability) edge_functions_secrets_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/projects/{ref}/secrets | Bulk-delete secrets from a project by name. | write | edge_functions_secrets_write | Current | |
OAuth-app permission. Acts onsecret Permission (capability) edge_functions_secrets_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Auth configRead and update a project's auth configuration, such as sign-up rules and SMTP settings.2 | ||||||
| GET | /v1/projects/{ref}/config/auth | Get a project's auth configuration. | read | auth_config_read | Current | |
OAuth-app permission. Acts onauth config Permission (capability) auth_config_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v1/projects/{ref}/config/auth | Update a project's auth configuration, such as sign-up rules and SMTP settings. | write | auth_config_write | Current | |
OAuth-app permissions: auth_config_write and project_admin_write. Changes how users sign in to the project. Acts onauth config Permission (capability) auth_config_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Project configRead and update a project's Postgres configuration and storage configuration.2 | ||||||
| GET | /v1/projects/{ref}/config/database/postgres | Get a project's Postgres configuration. | read | database_config_read | Current | |
OAuth-app permission. Acts ondatabase config Permission (capability) database_config_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v1/projects/{ref}/config/database/postgres | Update a project's Postgres configuration. | write | database_config_write | Current | |
OAuth-app permission. Changes live database engine settings. Acts ondatabase config Permission (capability) database_config_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
StorageList a project's storage buckets.1 | ||||||
| GET | /v1/projects/{ref}/storage/buckets | List a project's storage buckets. | read | storage_read | Current | |
OAuth-app permission. The Management API lists buckets; objects inside them are handled by the project's own Storage API. Acts onbucket Permission (capability) storage_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
API keysList and create a project's data-API keys.2 | ||||||
| GET | /v1/projects/{ref}/api-keys | Get a project's data-API keys. | read | api_gateway_keys_read | Current | |
OAuth-app permission. These are the keys that grant access to the project's own data API, distinct from the Management API token. Acts onapi key Permission (capability) api_gateway_keys_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/projects/{ref}/api-keys | Create a new data-API key for the project. | write | api_gateway_keys_write | Current | |
OAuth-app permission. Acts onapi key Permission (capability) api_gateway_keys_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
BranchesList, read, create, update, and delete a project's database branches.3 | ||||||
| GET | /v1/projects/{ref}/branches | List a project's database branches. | read | branching_development_read | Current | |
OAuth-app permissions: branching_production_read and branching_development_read. Branching is a paid, experimental feature. Acts onbranch Permission (capability) branching_development_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/projects/{ref}/branches | Create a database branch from the project. | write | branching_development_create | Current | |
OAuth-app permissions: branching_production_create and branching_development_create. Creates a separate preview database environment. Acts onbranch Permission (capability) branching_development_createVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/branches/{branch_id_or_ref} | Delete a database branch. | write | branching_development_delete | Current | |
OAuth-app permissions: branching_production_delete and branching_development_delete. Acts onbranch Permission (capability) branching_development_deleteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
The Management API does not push events. It can switch on a project's own Database Webhooks feature, which then sends row changes from that project's tables to a URL, but the Management API itself has no event stream an agent can subscribe to.
| Event | What it signals | Triggered by |
|---|
Supabase limits how fast an app or AI agent can call the Management API, through a per-minute request quota that is tracked separately for each user and each project or organization, with stricter caps on a few heavy endpoints.
Supabase caps Management API calls per minute, tracked on a per-user, per-scope model, so each user gets an independent quota for each project and each organization, and traffic to one project does not eat into another's. The standard ceiling is 120 requests per minute. A few heavy endpoints are stricter, for example the database metadata endpoint is held to about 10 requests per minute and no more than 1 per second. Going over returns 429 Too Many Requests for the rest of that minute, and the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset response headers report the current state. The guidance is to back off using X-RateLimit-Reset and to batch operations where an endpoint supports it, such as bulk secret creation.
Most Management API list endpoints return the full set in one response rather than paging, since the lists, such as a user's projects or a project's functions, are small. The action-runs list endpoint is the exception and is paginated, with a companion HEAD request that returns the total count.
Requests and responses are JSON over HTTPS. The SQL query endpoint accepts a statement in the request body and returns its result rows as JSON. Individual endpoints set their own field limits rather than the API enforcing one global payload size.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | Unauthorized | The access token is missing, invalid, or expired. | Send a valid token in the Authorization header as 'Bearer |
| 403 | Forbidden | The token is valid but lacks the permission for this method, which applies to an OAuth app that was not granted the matching fine-grained permission. | Re-authorize the OAuth app with the permission the method needs, or use a token with the required reach. |
| 404 | Not Found | The project reference id or other resource in the path does not exist, or the token cannot see it. | Confirm the project ref and the path, and that the token has access to the resource. |
| 429 | Too Many Requests | The per-minute rate limit for this user and scope was exceeded. All further calls return 429 for the rest of the minute. | Back off until the X-RateLimit-Reset time, then retry, and batch calls where an endpoint allows it. |
| 500 | Internal Server Error | Supabase hit an unexpected error handling the request. | Retry with backoff, and check the Supabase status page if it persists. |
The Management API is served under a single stable major version, v1. Changes ship continuously through the changelog rather than through dated version strings, and an earlier experimental v0 still exists for a few endpoints.
The Management API is served under a single stable major version, v1, reached under the /v1 path prefix at https://api.supabase.com. It is not versioned by date and has no version header to pin. New endpoints and fields are added over time through the changelog, and some v1 endpoints are individually marked Beta or Alpha in the reference. An earlier experimental v0 still backs a few endpoints.
Supabase announced the Management API in beta alongside CLI v1, opening programmatic management of organizations and projects to all users. It was released in 2022.
An integration calls the stable v1 paths; new endpoints are added over time rather than minted as a new version.
Supabase changelog ↗Bollard AI sits between a team's AI agents and the Supabase Management API. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.