Management API Reference

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:

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.

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 #

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 #

Limit	Duration	Scope
120 requests	1 minute	Per user, per project/organization

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:

Project scope: Rate limits apply independently to each project. Requests to one project do not count toward the limit of another project.
Organization scope: Rate limits apply independently to each organization. Requests to one organization do not count toward the limit of another organization.

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 #

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

X-RateLimit-Limit - The maximum number of requests allowed in the current time window
X-RateLimit-Remaining - The number of requests remaining before you hit the rate limit
X-RateLimit-Reset - The number of seconds remaining until your rate limit resets

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:

OAuth App ID - If your request is authenticated via an OAuth application
User ID - If your request is authenticated with a personal access token
IP Address - If your request is unauthenticated (extracted from request headers)

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 #

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

Endpoint	Limit	Duration	Reason
`GET /v1/projects/:ref/endpoints/logs.all`	30 requests	1 minute	Analytics log queries are computationally expensive
`GET /v1/projects/:ref/endpoints/usage.api-counts`	30 requests	1 minute	Analytics aggregation is computationally expensive
`GET /v1/projects/:ref/endpoints/usage.api-requests-count`	30 requests	1 minute	Analytics aggregation is computationally expensive
`GET /v1/projects/:ref/database/context`	10 requests	1 minute	Database context operations are resource-intensive
`GET /v1/projects/:ref/database/context`	1 request	1 second	Burst limit to prevent rapid successive requests
`POST /v1/projects/:ref/config/custom-hostname/initialize`	10 requests	1 minute	These operations are expensive
`POST /v1/projects/:ref/config/custom-hostname/reverify`	10 requests	1 minute	These operations are expensive
`DELETE /v1/projects/:ref/config/custom-hostname`	10 requests	1 minute	These operations are expensive
`GET /v1/projects/:ref/config/vanity-subdomain`	10 requests	1 minute	These operations are expensive

Note: The GET /v1/projects/:ref/database/context endpoint has dual rate limiting. You can make up to 10 requests per minute, but also no more than 1 request per second to prevent burst traffic.

Best practices #

Monitor rate limit headers - Check the X-RateLimit-Remaining header to see how many requests you have left. When it approaches 0, slow down your requests to avoid hitting the limit.
Implement exponential backoff - When you receive a 429 response, wait before retrying. You can use the X-RateLimit-Reset header (seconds) to determine exactly how long to wait.
Batch operations - Where possible, combine multiple operations into fewer API calls to reduce your request count.
Be mindful of expensive endpoints - Analytics, database context, and domain endpoints have stricter limits, so use them judiciously.

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.

Additional links

Gets project performance advisors. deprecated

get/v1/projects/{ref}/advisors/performance

This is an experimental endpoint. It is subject to change or removal in future versions. Use it with caution, as it may not remain supported or stable.

OAuth scopes

database:read

The fine-grained token must include the following permissions to access this endpoint:

advisors_read

Path parameters

Required

string

Project ref

Details

Response codes

Response (200)

exampleschema

1
{
2
  "lints": [\
3\
    {\
4\
      "name": "unindexed_foreign_keys",\
5\
      "title": "lorem",\
6\
      "level": "ERROR",\
7\
      "facing": "EXTERNAL",\
8\
      "categories": [\
9\
        "PERFORMANCE"\
10\
      ],\
11\
      "description": "lorem",\
12\
      "detail": "lorem",\
13\
      "remediation": "lorem",\
14\
      "metadata": {\
15\
        "schema": "lorem",\
16\
        "name": "lorem",\
17\
        "entity": "lorem",\
18\
        "type": "table",\
19\
        "fkey_name": "lorem",\
20\
        "fkey_columns": [\
21\
          42\
22\
        ]\
23\
      },\
24\
      "cache_key": "lorem"\
25\
    }\
26\
  ]
27
}

Gets project security advisors. deprecated

get/v1/projects/{ref}/advisors/security

This is an experimental endpoint. It is subject to change or removal in future versions. Use it with caution, as it may not remain supported or stable.

OAuth scopes

database:read

The fine-grained token must include the following permissions to access this endpoint:

advisors_read

Path parameters

Required

string

Project ref

Details

Query parameters

lint_type

Optional

enum

Accepted values

Response codes

Response (200)

exampleschema

Gets a project's function combined statistics

get/v1/projects/{ref}/analytics/endpoints/functions.combined-stats

The fine-grained token must include the following permissions to access this endpoint:

analytics_usage_read

Path parameters

Required

string

Project ref

Details

Query parameters

interval

Required

enum

Accepted values

function_id

Required

string

Response codes

Response (200)

exampleschema

1
{
2
  "result": [\
3\
    null\
4\
  ],
5
  "error": "lorem"
6
}

Gets project's logs

get/v1/projects/{ref}/analytics/endpoints/logs.all

Executes a SQL query on the project's logs.

Either the iso_timestamp_start and iso_timestamp_end parameters must be provided. If both are not provided, only the last 1 minute of logs will be queried. The timestamp range must be no more than 24 hours and is rounded to the nearest minute. If the range is more than 24 hours, a validation error will be thrown.

Note: Unless the sql parameter is provided, only edge_logs will be queried. See the log query docs for all available sources.

OAuth scopes

analytics:read

The fine-grained token must include the following permissions to access this endpoint:

analytics_logs_read

Path parameters

Required

string

Project ref

Details

Query parameters

Optional

string

Custom SQL query to execute on the logs. See querying logs for more details.

iso_timestamp_start

Optional

string

iso_timestamp_end

Optional

string

Response codes

Response (200)

exampleschema

1
{
2
  "result": [\
3\
    null\
4\
  ],
5
  "error": "lorem"
6
}

Gets project's usage api counts

get/v1/projects/{ref}/analytics/endpoints/usage.api-counts

The fine-grained token must include the following permissions to access this endpoint:

analytics_usage_read

Path parameters

Required

string

Project ref

Details

Query parameters

interval

Optional

enum

Accepted values

Response codes

Response (200)

exampleschema

1
{
2
  "result": [\
3\
    {\
4\
      "timestamp": "2021-12-31T23:34:00Z",\
5\
      "total_auth_requests": 42,\
6\
      "total_realtime_requests": 42,\
7\
      "total_rest_requests": 42,\
8\
      "total_storage_requests": 42\
9\
    }\
10\
  ],
11
  "error": "lorem"
12
}

Gets project's usage api requests count

get/v1/projects/{ref}/analytics/endpoints/usage.api-requests-count

The fine-grained token must include the following permissions to access this endpoint:

analytics_usage_read

Path parameters

Required

string

Project ref

Details

Response codes

Response (200)

exampleschema

1
{
2
  "result": [\
3\
    {\
4\
      "count": 42\
5\
    }\
6\
  ],
7
  "error": "lorem"
8
}

Creates a new SSO provider

post/v1/projects/{ref}/config/auth/sso/providers

OAuth scopes

auth:write

The fine-grained token must include the following permissions to access this endpoint:

auth_config_write

Path parameters

Required

string

Project ref

Details

Body

application/json

type

Required

enum

Accepted values

metadata_xml

Optional

string

metadata_url

Optional

string

domains

Optional

Array

attribute_mapping

Optional

object

Object schema

name_id_format

Optional

enum

Accepted values

Response codes

Response (201)

exampleschema

1
{
2
  "id": "lorem",
3
  "saml": {
4
    "id": "lorem",
5
    "entity_id": "lorem",
6
    "metadata_url": "lorem",
7
    "metadata_xml": "lorem",
8
    "attribute_mapping": {
9
      "keys": {
10
        "property1": {
11
          "name": "lorem",
12
          "names": [\
13\
            "lorem"\
14\
          ],
15
          "default": {},
16
          "array": true
17
        },
18
        "property2": {
19
          "name": "lorem",
20
          "names": [\
21\
            "lorem"\
22\
          ],
23
          "default": {},
24
          "array": true
25
        }
26
      }
27
    },
28
    "name_id_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
29
  },
30
  "domains": [\
31\
    {\
32\
      "id": "lorem",\
33\
      "domain": "lorem",\
34\
      "created_at": "lorem",\
35\
      "updated_at": "lorem"\
36\
    }\
37\
  ],
38
  "created_at": "lorem",
39
  "updated_at": "lorem"
40
}

Set up the project's existing JWT secret as an in_use JWT signing key. This endpoint will be removed in the future always check for HTTP 404 Not Found.

post/v1/projects/{ref}/config/auth/signing-keys/legacy

OAuth scopes

secrets:write

The fine-grained token must include the following permissions to access this endpoint:

auth_signing_keys_write

Path parameters

Required

string

Project ref

Details

Response codes

Response (201)

exampleschema

1
{
2
  "id": "fbdf5a53-161e-4460-98ad-0e39408d8689",
3
  "algorithm": "EdDSA",
4
  "status": "in_use",
5
  "public_jwk": null,
6
  "created_at": "2021-12-31T23:34:00Z",
7
  "updated_at": "2021-12-31T23:34:00Z"
8
}

Create a new signing key for the project in standby status

post/v1/projects/{ref}/config/auth/signing-keys

OAuth scopes

secrets:write

The fine-grained token must include the following permissions to access this endpoint:

auth_signing_keys_write

Path parameters

Required

string

Project ref

Details

Body

application/json

algorithm

Required

enum

Accepted values

status

Optional

enum

Accepted values

private_jwk

Optional

one of the following options

Options

Response codes

Response (201)

exampleschema

Creates a new third-party auth integration

post/v1/projects/{ref}/config/auth/third-party-auth

OAuth scopes

auth:write

The fine-grained token must include the following permissions to access this endpoint:

auth_config_write

Path parameters

Required

string

Project ref

Details

Body

application/json

oidc_issuer_url

Optional

string

jwks_url

Optional

string

custom_jwks

Optional

unknown

Details

Response codes

Response (201)

exampleschema

1
{
2
  "id": "fbdf5a53-161e-4460-98ad-0e39408d8689",
3
  "type": "lorem",
4
  "oidc_issuer_url": "lorem",
5
  "jwks_url": "lorem",
6
  "custom_jwks": null,
7
  "resolved_jwks": null,
8
  "inserted_at": "lorem",
9
  "updated_at": "lorem",
10
  "resolved_at": "lorem"
11
}

Removes a SSO provider by its UUID

delete/v1/projects/{ref}/config/auth/sso/providers/{provider_id}

OAuth scopes

auth:write

The fine-grained token must include the following permissions to access this endpoint:

auth_config_write

Path parameters

Required

string

Project ref

Details

provider_id

Required

string

Response codes

Response (200)

exampleschema

Removes a third-party auth integration

delete/v1/projects/{ref}/config/auth/third-party-auth/{tpa_id}

OAuth scopes

auth:write

The fine-grained token must include the following permissions to access this endpoint:

auth_config_write

Path parameters

Required

string

Project ref

Details

tpa_id

Required

string

Response codes

Response (200)

exampleschema

Gets a SSO provider by its UUID

get/v1/projects/{ref}/config/auth/sso/providers/{provider_id}

OAuth scopes

auth:read

The fine-grained token must include the following permissions to access this endpoint:

auth_config_read

Path parameters

Required

string

Project ref

Details

provider_id

Required

string

Response codes

Response (200)

exampleschema

Gets project's auth config

get/v1/projects/{ref}/config/auth

OAuth scopes

auth:read

The fine-grained token must include the following permissions to access this endpoint:

auth_config_read

Path parameters

Required

string

Project ref

Details

Response codes

Response (200)

exampleschema

1
{
2
  "api_max_request_duration": 42,
3
  "db_max_pool_size": 42,
4
  "db_max_pool_size_unit": "connections",
5
  "disable_signup": true,
6
  "external_anonymous_users_enabled": true,
7
  "external_apple_additional_client_ids": "lorem",
8
  "external_apple_client_id": "lorem",
9
  "external_apple_email_optional": true,
10
  "external_apple_enabled": true,
11
  "external_apple_secret": "lorem",
12
  "external_azure_client_id": "lorem",
13
  "external_azure_email_optional": true,
14
  "external_azure_enabled": true,
15
  "external_azure_secret": "lorem",
16
  "external_azure_url": "lorem",
17
  "external_bitbucket_client_id": "lorem",
18
  "external_bitbucket_email_optional": true,
19
  "external_bitbucket_enabled": true,
20
  "external_bitbucket_secret": "lorem",
21
  "external_discord_client_id": "lorem",
22
  "external_discord_email_optional": true,
23
  "external_discord_enabled": true,
24
  "external_discord_secret": "lorem",
25
  "external_email_enabled": true,
26
  "external_facebook_client_id": "lorem",
27
  "external_facebook_email_optional": true,
28
  "external_facebook_enabled": true,
29
  "external_facebook_secret": "lorem",
30
  "external_figma_client_id": "lorem",
31
  "external_figma_email_optional": true,
32
  "external_figma_enabled": true,
33
  "external_figma_secret": "lorem",
34
  "external_github_client_id": "lorem",
35
  "external_github_email_optional": true,
36
  "external_github_enabled": true,
37
  "external_github_secret": "lorem",
38
  "external_gitlab_client_id": "lorem",
39
  "external_gitlab_email_optional": true,
40
  "external_gitlab_enabled": true,
41
  "external_gitlab_secret": "lorem",
42
  "external_gitlab_url": "lorem",
43
  "external_google_additional_client_ids": "lorem",
44
  "external_google_client_id": "lorem",
45
  "external_google_email_optional": true,
46
  "external_google_enabled": true,
47
  "external_google_secret": "lorem",
48
  "external_google_skip_nonce_check": true,
49
  "external_kakao_client_id": "lorem",
50
  "external_kakao_email_optional": true,
51
  "external_kakao_enabled": true,
52
  "external_kakao_secret": "lorem",
53
  "external_keycloak_client_id": "lorem",
54
  "external_keycloak_email_optional": true,
55
  "external_keycloak_enabled": true,
56
  "external_keycloak_secret": "lorem",
57
  "external_keycloak_url": "lorem",
58
  "external_linkedin_oidc_client_id": "lorem",
59
  "external_linkedin_oidc_email_optional": true,
60
  "external_linkedin_oidc_enabled": true,
61
  "external_linkedin_oidc_secret": "lorem",
62
  "external_slack_oidc_client_id": "lorem",
63
  "external_slack_oidc_email_optional": true,
64
  "external_slack_oidc_enabled": true,
65
  "external_slack_oidc_secret": "lorem",
66
  "external_notion_client_id": "lorem",
67
  "external_notion_email_optional": true,
68
  "external_notion_enabled": true,
69
  "external_notion_secret": "lorem",
70
  "external_phone_enabled": true,
71
  "external_slack_client_id": "lorem",
72
  "external_slack_email_optional": true,
73
  "external_slack_enabled": true,
74
  "external_slack_secret": "lorem",
75
  "external_spotify_client_id": "lorem",
76
  "external_spotify_email_optional": true,
77
  "external_spotify_enabled": true,
78
  "external_spotify_secret": "lorem",
79
  "external_twitch_client_id": "lorem",
80
  "external_twitch_email_optional": true,
81
  "external_twitch_enabled": true,
82
  "external_twitch_secret": "lorem",
83
  "external_twitter_client_id": "lorem",
84
  "external_twitter_email_optional": true,
85
  "external_twitter_enabled": true,
86
  "external_twitter_secret": "lorem",
87
  "external_x_client_id": "lorem",
88
  "external_x_email_optional": true,
89
  "external_x_enabled": true,
90
  "external_x_secret": "lorem",
91
  "external_workos_client_id": "lorem",
92
  "external_workos_enabled": true,
93
  "external_workos_secret": "lorem",
94
  "external_workos_url": "lorem",
95
  "external_web3_solana_enabled": true,
96
  "external_web3_ethereum_enabled": true,
97
  "external_zoom_client_id": "lorem",
98
  "external_zoom_email_optional": true,
99
  "external_zoom_enabled": true,
100
  "external_zoom_secret": "lorem",
101
  "hook_custom_access_token_enabled": true,
102
  "hook_custom_access_token_uri": "lorem",
103
  "hook_custom_access_token_secrets": "lorem",
104
  "hook_mfa_verification_attempt_enabled": true,
105
  "hook_mfa_verification_attempt_uri": "lorem",
106
  "hook_mfa_verification_attempt_secrets": "lorem",
107
  "hook_password_verification_attempt_enabled": true,
108
  "hook_password_verification_attempt_uri": "lorem",
109
  "hook_password_verification_attempt_secrets": "lorem",
110
  "hook_send_sms_enabled": true,
111
  "hook_send_sms_uri": "lorem",
112
  "hook_send_sms_secrets": "lorem",
113
  "hook_send_email_enabled": true,
114
  "hook_send_email_uri": "lorem",
115
  "hook_send_email_secrets": "lorem",
116
  "hook_before_user_created_enabled": true,
117
  "hook_before_user_created_uri": "lorem",
118
  "hook_before_user_created_secrets": "lorem",
119
  "hook_after_user_created_enabled": true,
120
  "hook_after_user_created_uri": "lorem",
121
  "hook_after_user_created_secrets": "lorem",
122
  "jwt_exp": 42,
123
  "mailer_allow_unverified_email_sign_ins": true,
124
  "mailer_autoconfirm": true,
125
  "mailer_otp_exp": 42,
126
  "mailer_otp_length": 42,
127
  "mailer_secure_email_change_enabled": true,
128
  "mailer_subjects_confirmation": "lorem",
129
  "mailer_subjects_email_change": "lorem",
130
  "mailer_subjects_invite": "lorem",
131
  "mailer_subjects_magic_link": "lorem",
132
  "mailer_subjects_reauthentication": "lorem",
133
  "mailer_subjects_recovery": "lorem",
134
  "mailer_subjects_password_changed_notification": "lorem",
135
  "mailer_subjects_email_changed_notification": "lorem",
136
  "mailer_subjects_phone_changed_notification": "lorem",
137
  "mailer_subjects_mfa_factor_enrolled_notification": "lorem",
138
  "mailer_subjects_mfa_factor_unenrolled_notification": "lorem",
139
  "mailer_subjects_identity_linked_notification": "lorem",
140
  "mailer_subjects_identity_unlinked_notification": "lorem",
141
  "mailer_templates_confirmation_content": "lorem",
142
  "mailer_templates_email_change_content": "lorem",
143
  "mailer_templates_invite_content": "lorem",
144
  "mailer_templates_magic_link_content": "lorem",
145
  "mailer_templates_reauthentication_content": "lorem",
146
  "mailer_templates_recovery_content": "lorem",
147
  "mailer_templates_password_changed_notification_content": "lorem",
148
  "mailer_templates_email_changed_notification_content": "lorem",
149
  "mailer_templates_phone_changed_notification_content": "lorem",
150
  "mailer_templates_mfa_factor_enrolled_notification_content": "lorem",
151
  "mailer_templates_mfa_factor_unenrolled_notification_content": "lorem",
152
  "mailer_templates_identity_linked_notification_content": "lorem",
153
  "mailer_templates_identity_unlinked_notification_content": "lorem",
154
  "mailer_notifications_password_changed_enabled": true,
155
  "mailer_notifications_email_changed_enabled": true,
156
  "mailer_notifications_phone_changed_enabled": true,
157
  "mailer_notifications_mfa_factor_enrolled_enabled": true,
158
  "mailer_notifications_mfa_factor_unenrolled_enabled": true,
159
  "mailer_notifications_identity_linked_enabled": true,
160
  "mailer_notifications_identity_unlinked_enabled": true,
161
  "mfa_max_enrolled_factors": 42,
162
  "mfa_totp_enroll_enabled": true,
163
  "mfa_totp_verify_enabled": true,
164
  "mfa_phone_enroll_enabled": true,
165
  "mfa_phone_verify_enabled": true,
166
  "mfa_web_authn_enroll_enabled": true,
167
  "mfa_web_authn_verify_enabled": true,
168
  "passkey_enabled": true,
169
  "webauthn_rp_display_name": "lorem",
170
  "webauthn_rp_id": "lorem",
171
  "webauthn_rp_origins": "lorem",
172
  "mfa_phone_otp_length": 42,
173
  "mfa_phone_template": "lorem",
174
  "mfa_phone_max_frequency": 42,
175
  "nimbus_oauth_client_id": "lorem",
176
  "nimbus_oauth_email_optional": true,
177
  "nimbus_oauth_client_secret": "lorem",
178
  "password_hibp_enabled": true,
179
  "password_min_length": 42,
180
  "password_required_characters": "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ:0123456789",
181
  "rate_limit_anonymous_users": 42,
182
  "rate_limit_email_sent": 42,
183
  "rate_limit_sms_sent": 42,
184
  "rate_limit_token_refresh": 42,
185
  "rate_limit_verify": 42,
186
  "rate_limit_otp": 42,
187
  "rate_limit_web3": 42,
188
  "refresh_token_rotation_enabled": true,
189
  "saml_enabled": true,
190
  "saml_external_url": "lorem",
191
  "saml_allow_encrypted_assertions": true,
192
  "security_sb_forwarded_for_enabled": true,
193
  "security_captcha_enabled": true,
194
  "security_captcha_provider": "turnstile",
195
  "security_captcha_secret": "lorem",
196
  "security_manual_linking_enabled": true,
197
  "security_refresh_token_reuse_interval": 42,
198
  "security_update_password_require_reauthentication": true,
199
  "sessions_inactivity_timeout": 42,
200
  "sessions_single_per_user": true,
201
  "sessions_tags": "lorem",
202
  "sessions_timebox": 42,
203
  "site_url": "lorem",
204
  "sms_autoconfirm": true,
205
  "sms_max_frequency": 42,
206
  "sms_messagebird_access_key": "lorem",
207
  "sms_messagebird_originator": "lorem",
208
  "sms_otp_exp": 42,
209
  "sms_otp_length": 42,
210
  "sms_provider": "messagebird",
211
  "sms_template": "lorem",
212
  "sms_test_otp": "lorem",
213
  "sms_test_otp_valid_until": "2021-12-31T23:34:00Z",
214
  "sms_textlocal_api_key": "lorem",
215
  "sms_textlocal_sender": "lorem",
216
  "sms_twilio_account_sid": "lorem",
217
  "sms_twilio_auth_token": "lorem",
218
  "sms_twilio_content_sid": "lorem",
219
  "sms_twilio_message_service_sid": "lorem",
220
  "sms_twilio_verify_account_sid": "lorem",
221
  "sms_twilio_verify_auth_token": "lorem",
222
  "sms_twilio_verify_message_service_sid": "lorem",
223
  "sms_vonage_api_key": "lorem",
224
  "sms_vonage_api_secret": "lorem",
225
  "sms_vonage_from": "lorem",
226
  "smtp_admin_email": "jon.snow@targaryen.com",
227
  "smtp_host": "lorem",
228
  "smtp_max_frequency": 42,
229
  "smtp_pass": "lorem",
230
  "smtp_port": "lorem",
231
  "smtp_sender_name": "lorem",
232
  "smtp_user": "lorem",
233
  "uri_allow_list": "lorem",
234
  "oauth_server_enabled": true,
235
  "oauth_server_allow_dynamic_registration": true,
236
  "oauth_server_authorization_path": "lorem",
237
  "custom_oauth_enabled": true,
238
  "custom_oauth_max_providers": 42
239
}

Get the signing key information for the JWT secret imported as signing key for this project. This endpoint will be removed in the future, check for HTTP 404 Not Found.

get/v1/projects/{ref}/config/auth/signing-keys/legacy

OAuth scopes

secrets:read

The fine-grained token must include the following permissions to access this endpoint:

auth_signing_keys_read

Path parameters

Required

string

Project ref

Details

Response codes

Response (200)

exampleschema

Get information about a signing key

get/v1/projects/{ref}/config/auth/signing-keys/{id}

The fine-grained token must include the following permissions to access this endpoint:

auth_signing_keys_read

Path parameters

Required

string

Required

string

Project ref

Details

Response codes

Response (200)

exampleschema

List all signing keys for the project

get/v1/projects/{ref}/config/auth/signing-keys

OAuth scopes

secrets:read

The fine-grained token must include the following permissions to access this endpoint:

auth_signing_keys_read

Path parameters

Required

string

Project ref

Details

Response codes

Response (200)

exampleschema

1
{
2
  "keys": [\
3\
    {\
4\
      "id": "fbdf5a53-161e-4460-98ad-0e39408d8689",\
5\
      "algorithm": "EdDSA",\
6\
      "status": "in_use",\
7\
      "public_jwk": null,\
8\
      "created_at": "2021-12-31T23:34:00Z",\
9\
      "updated_at": "2021-12-31T23:34:00Z"\
10\
    }\
11\
  ]
12
}

Get a third-party integration

get/v1/projects/{ref}/config/auth/third-party-auth/{tpa_id}

OAuth scopes

auth:read

The fine-grained token must include the following permissions to access this endpoint:

auth_config_read

Path parameters

Required

string

Project ref

Details

tpa_id

Required

string

Response codes

Response (200)

exampleschema

Lists all SSO providers

get/v1/projects/{ref}/config/auth/sso/providers

OAuth scopes

auth:read

The fine-grained token must include the following permissions to access this endpoint:

auth_config_read

Path parameters

Required

string

Project ref

Details

Response codes

Response (200)

exampleschema

1
{
2
  "items": [\
3\
    {\
4\
      "id": "lorem",\
5\
      "saml": {\
6\
        "id": "lorem",\
7\
        "entity_id": "lorem",\
8\
        "metadata_url": "lorem",\
9\
        "metadata_xml": "lorem",\
10\
        "attribute_mapping": {\
11\
          "keys": {\
12\
            "property1": {\
13\
              "name": "lorem",\
14\
              "names": [\
15\
                "lorem"\
16\
              ],\
17\
              "default": {},\
18\
              "array": true\
19\
            },\
20\
            "property2": {\
21\
              "name": "lorem",\
22\
              "names": [\
23\
                "lorem"\
24\
              ],\
25\
              "default": {},\
26\
              "array": true\
27\
            }\
28\
          }\
29\
        },\
30\
        "name_id_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"\
31\
      },\
32\
      "domains": [\
33\
        {\
34\
          "id": "lorem",\
35\
          "domain": "lorem",\
36\
          "created_at": "lorem",\
37\
          "updated_at": "lorem"\
38\
        }\
39\
      ],\
40\
      "created_at": "lorem",\
41\
      "updated_at": "lorem"\
42\
    }\
43\
  ]
44
}

Lists all third-party auth integrations

get/v1/projects/{ref}/config/auth/third-party-auth

OAuth scopes

auth:read

The fine-grained token must include the following permissions to access this endpoint:

auth_config_read

Path parameters

Required

string

Project ref

Details

Response codes

Response (200)

exampleschema

1
[\
2\
  {\
3\
    "id": "fbdf5a53-161e-4460-98ad-0e39408d8689",\
4\
    "type": "lorem",\
5\
    "oidc_issuer_url": "lorem",\
6\
    "jwks_url": "lorem",\
7\
    "custom_jwks": null,\
8\
    "resolved_jwks": null,\
9\
    "inserted_at": "lorem",\
10\
    "updated_at": "lorem",\
11\
    "resolved_at": "lorem"\
12\
  }\
13\
]

Remove a signing key from a project. Only possible if the key has been in revoked status for a while.

delete/v1/projects/{ref}/config/auth/signing-keys/{id}

OAuth scopes

secrets:write

The fine-grained token must include the following permissions to access this endpoint:

auth_signing_keys_write

Path parameters

Required

string

Required

string

Project ref

Details

Response codes

Response (200)

exampleschema

Updates a SSO provider by its UUID

put/v1/projects/{ref}/config/auth/sso/providers/{provider_id}

OAuth scopes

auth:write

The fine-grained token must include the following permissions to access this endpoint:

auth_config_write

Path parameters

Required

string

Project ref

Details

provider_id

Required

string

Body

application/json

metadata_xml

Optional

string

metadata_url

Optional

string

domains

Optional

Array

attribute_mapping

Optional

object

Object schema

name_id_format

Optional

enum

Accepted values

Response codes

Response (200)

exampleschema

Updates a project's auth config

patch/v1/projects/{ref}/config/auth

OAuth scopes

auth:write

The fine-grained token must include the following permissions to access this endpoint:

auth_config_write
project_admin_write

Path parameters

Required

string

Project ref

Details

Body

application/json

site_url

Optional

string

Details

disable_signup

Optional

boolean

jwt_exp

Optional

integer

smtp_admin_email

Optional

string

smtp_host

Optional

string

smtp_port

Optional

string

smtp_user

Optional

string

smtp_pass

Optional

string

smtp_max_frequency

Optional

integer

smtp_sender_name

Optional

string

mailer_allow_unverified_email_sign_ins

Optional

boolean

mailer_autoconfirm

Optional

boolean

mailer_subjects_invite

Optional

string

mailer_subjects_confirmation

Optional

string

mailer_subjects_recovery

Optional

string

mailer_subjects_email_change

Optional

string

mailer_subjects_magic_link

Optional

string

mailer_subjects_reauthentication

Optional

string

mailer_subjects_password_changed_notification

Optional

string

mailer_subjects_email_changed_notification

Optional

string

mailer_subjects_phone_changed_notification

Optional

string

mailer_subjects_mfa_factor_enrolled_notification

Optional

string

mailer_subjects_mfa_factor_unenrolled_notification

Optional

string

mailer_subjects_identity_linked_notification

Optional

string

mailer_subjects_identity_unlinked_notification

Optional

string

mailer_templates_invite_content

Optional

string

mailer_templates_confirmation_content

Optional

string

mailer_templates_recovery_content

Optional

string

mailer_templates_email_change_content

Optional

string

mailer_templates_magic_link_content

Optional

string

mailer_templates_reauthentication_content

Optional

string

mailer_templates_password_changed_notification_content

Optional

string

mailer_templates_email_changed_notification_content

Optional

string

mailer_templates_phone_changed_notification_content

Optional

string

mailer_templates_mfa_factor_enrolled_notification_content

Optional

string

mailer_templates_mfa_factor_unenrolled_notification_content

Optional

string

mailer_templates_identity_linked_notification_content

Optional

string

mailer_templates_identity_unlinked_notification_content

Optional

string

mailer_notifications_password_changed_enabled

Optional

boolean

mailer_notifications_email_changed_enabled

Optional

boolean

mailer_notifications_phone_changed_enabled

Optional

boolean

mailer_notifications_mfa_factor_enrolled_enabled

Optional

boolean

mailer_notifications_mfa_factor_unenrolled_enabled

Optional

boolean

mailer_notifications_identity_linked_enabled

Optional

boolean

mailer_notifications_identity_unlinked_enabled

Optional

boolean

mfa_max_enrolled_factors

Optional

integer

uri_allow_list

Optional

string

external_anonymous_users_enabled

Optional

boolean

external_email_enabled

Optional

boolean

external_phone_enabled

Optional

boolean

saml_enabled

Optional

boolean

saml_external_url

Optional

string

Details

security_sb_forwarded_for_enabled

Optional

boolean

security_captcha_enabled

Optional

boolean

security_captcha_provider

Optional

enum

Accepted values

security_captcha_secret

Optional

string

sessions_timebox

Optional

number

sessions_inactivity_timeout

Optional

number

sessions_single_per_user

Optional

boolean

sessions_tags

Optional

string

Details

rate_limit_anonymous_users

Optional

integer

rate_limit_email_sent

Optional

integer

rate_limit_sms_sent

Optional

integer

rate_limit_verify

Optional

integer

rate_limit_token_refresh

Optional

integer

rate_limit_otp

Optional

integer

rate_limit_web3

Optional

integer

mailer_secure_email_change_enabled

Optional

boolean

refresh_token_rotation_enabled

Optional

boolean

password_hibp_enabled

Optional

boolean

password_min_length

Optional

integer

password_required_characters

Optional

enum

Accepted values

security_manual_linking_enabled

Optional

boolean

security_update_password_require_reauthentication

Optional

boolean

security_refresh_token_reuse_interval

Optional

integer

mailer_otp_exp

Optional

integer

mailer_otp_length

Optional

integer

sms_autoconfirm

Optional

boolean

sms_max_frequency

Optional

integer

sms_otp_exp

Optional

integer

sms_otp_length

Optional

integer

sms_provider

Optional

enum

Accepted values

sms_messagebird_access_key

Optional

string

sms_messagebird_originator

Optional

string

sms_test_otp

Optional

string

Details

sms_test_otp_valid_until

Optional

string

sms_textlocal_api_key

Optional

string

sms_textlocal_sender

Optional

string

sms_twilio_account_sid

Optional

string

sms_twilio_auth_token

Optional

string

sms_twilio_content_sid

Optional

string

sms_twilio_message_service_sid

Optional

string

sms_twilio_verify_account_sid

Optional

string

sms_twilio_verify_auth_token

Optional

string

sms_twilio_verify_message_service_sid

Optional

string

sms_vonage_api_key

Optional

string

sms_vonage_api_secret

Optional

string

sms_vonage_from

Optional

string

sms_template

Optional

string

hook_mfa_verification_attempt_enabled

Optional

boolean

hook_mfa_verification_attempt_uri

Optional

string

hook_mfa_verification_attempt_secrets

Optional

string

hook_password_verification_attempt_enabled

Optional

boolean

hook_password_verification_attempt_uri

Optional

string

hook_password_verification_attempt_secrets

Optional

string

hook_custom_access_token_enabled

Optional

boolean

hook_custom_access_token_uri

Optional

string

hook_custom_access_token_secrets

Optional

string

hook_send_sms_enabled

Optional

boolean

hook_send_sms_uri

Optional

string

hook_send_sms_secrets

Optional

string

hook_send_email_enabled

Optional

boolean

hook_send_email_uri

Optional

string

hook_send_email_secrets

Optional

string

hook_before_user_created_enabled

Optional

boolean

hook_before_user_created_uri

Optional

string

hook_before_user_created_secrets

Optional

string

hook_after_user_created_enabled

Optional

boolean

hook_after_user_created_uri

Optional

string

hook_after_user_created_secrets

Optional

string

external_apple_enabled

Optional

boolean

external_apple_client_id

Optional

string

external_apple_email_optional

Optional

boolean

external_apple_secret

Optional

string

external_apple_additional_client_ids

Optional

string

external_azure_enabled

Optional

boolean

external_azure_client_id

Optional

string

external_azure_email_optional

Optional

boolean

external_azure_secret

Optional

string

external_azure_url

Optional

string

external_bitbucket_enabled

Optional

boolean

external_bitbucket_client_id

Optional

string

external_bitbucket_email_optional

Optional

boolean

external_bitbucket_secret

Optional

string

external_discord_enabled

Optional

boolean

external_discord_client_id

Optional

string

external_discord_email_optional

Optional

boolean

external_discord_secret

Optional

string

external_facebook_enabled

Optional

boolean

external_facebook_client_id

Optional

string

external_facebook_email_optional

Optional

boolean

external_facebook_secret

Optional

string

external_figma_enabled

Optional

boolean

external_figma_client_id

Optional

string

external_figma_email_optional

Optional

boolean

external_figma_secret

Optional

string

external_github_enabled

Optional

boolean

external_github_client_id

Optional

string

external_github_email_optional

Optional

boolean

external_github_secret

Optional

string

external_gitlab_enabled

Optional

boolean

external_gitlab_client_id

Optional

string

external_gitlab_email_optional

Optional

boolean

external_gitlab_secret

Optional

string

external_gitlab_url

Optional

string

external_google_enabled

Optional

boolean

external_google_client_id

Optional

string

external_google_email_optional

Optional

boolean

external_google_secret

Optional

string

external_google_additional_client_ids

Optional

string

external_google_skip_nonce_check

Optional

boolean

external_kakao_enabled

Optional

boolean

external_kakao_client_id

Optional

string

external_kakao_email_optional

Optional

boolean

external_kakao_secret

Optional

string

external_keycloak_enabled

Optional

boolean

external_keycloak_client_id

Optional

string

external_keycloak_email_optional

Optional

boolean

external_keycloak_secret

Optional

string

external_keycloak_url

Optional

string

external_linkedin_oidc_enabled

Optional

boolean

external_linkedin_oidc_client_id

Optional

string

external_linkedin_oidc_email_optional

Optional

boolean

external_linkedin_oidc_secret

Optional

string

external_slack_oidc_enabled

Optional

boolean

external_slack_oidc_client_id

Optional

string

external_slack_oidc_email_optional

Optional

boolean

external_slack_oidc_secret

Optional

string

external_notion_enabled

Optional

boolean

external_notion_client_id

Optional

string

external_notion_email_optional

Optional

boolean

external_notion_secret

Optional

string

external_slack_enabled

Optional

boolean

external_slack_client_id

Optional

string

external_slack_email_optional

Optional

boolean

external_slack_secret

Optional

string

external_spotify_enabled

Optional

boolean

external_spotify_client_id

Optional

string

external_spotify_email_optional

Optional

boolean

external_spotify_secret

Optional

string

external_twitch_enabled

Optional

boolean

external_twitch_client_id

Optional

string

external_twitch_email_optional

Optional

boolean

external_twitch_secret

Optional

string

external_twitter_enabled

Optional

boolean

external_twitter_client_id

Optional

string

external_twitter_email_optional

Optional

boolean

external_twitter_secret

Optional

string

external_x_enabled

Optional

boolean

external_x_client_id

Optional

string

external_x_email_optional

Optional

boolean

external_x_secret

Optional

string

external_workos_enabled

Optional

boolean

external_workos_client_id

Optional

string

external_workos_secret

Optional

string

external_workos_url

Optional

string

external_web3_solana_enabled

Optional

boolean

external_web3_ethereum_enabled

Optional

boolean

external_zoom_enabled

Optional

boolean

external_zoom_client_id

Optional

string

external_zoom_email_optional

Optional

boolean

external_zoom_secret

Optional

string

db_max_pool_size

Optional

integer

db_max_pool_size_unit

Optional

enum

Accepted values

api_max_request_duration

Optional

integer

mfa_totp_enroll_enabled

Optional

boolean

mfa_totp_verify_enabled

Optional

boolean

mfa_web_authn_enroll_enabled

Optional

boolean

mfa_web_authn_verify_enabled

Optional

boolean

passkey_enabled

Optional

boolean

webauthn_rp_display_name

Optional

string

webauthn_rp_id

Optional

string

webauthn_rp_origins

Optional

string

mfa_phone_enroll_enabled

Optional

boolean

mfa_phone_verify_enabled

Optional

boolean

mfa_phone_max_frequency

Optional

integer

mfa_phone_otp_length

Optional

integer

mfa_phone_template

Optional

string

nimbus_oauth_client_id

Optional

string

nimbus_oauth_client_secret

Optional

string

oauth_server_enabled

Optional

boolean

oauth_server_allow_dynamic_registration

Optional

boolean

oauth_server_authorization_path

Optional

string

custom_oauth_enabled

Optional

boolean

Response codes

Response (200)

exampleschema

Update a signing key, mainly its status

patch/v1/projects/{ref}/config/auth/signing-keys/{id}

OAuth scopes

secrets:write

The fine-grained token must include the following permissions to access this endpoint:

auth_signing_keys_write

Path parameters

Required

string

Required

string

Project ref

Details

Body

application/json

status

Required

enum

Accepted values

Response codes

Response (200)

exampleschema

Apply or update billing addons, including compute instance size

patch/v1/projects/{ref}/billing/addons

Selects an addon variant, for example scaling the project’s compute instance up or down, and applies it to the project.

The fine-grained token must include the following permissions to access this endpoint:

infra_add_ons_write

Path parameters

Required

string

Project ref

Details

Body

application/json

addon_variant

Required

one of the following options

Options

addon_type

Required

enum

Accepted values

Response codes

Response (200)

schema

1
{}

List billing addons and compute instance selections

get/v1/projects/{ref}/billing/addons

Returns the billing addons that are currently applied, including the active compute instance size, and lists every addon option that can be provisioned with pricing metadata.

The fine-grained token must include the following permissions to access this endpoint:

infra_add_ons_read

Path parameters

Required

string

Project ref

Details

Response codes

Response (200)

exampleschema

1
{
2
  "selected_addons": [\
3\
    {\
4\
      "type": "custom_domain",\
5\
      "variant": {\
6\
        "id": "ci_micro",\
7\
        "name": "lorem",\
8\
        "price": {\
9\
          "description": "lorem",\
10\
          "type": "fixed",\
11\
          "interval": "monthly",\
12\
          "amount": 42\
13\
        },\
14\
        "meta": null\
15\
      }\
16\
    }\
17\
  ],
18
  "available_addons": [\
19\
    {\
20\
      "type": "custom_domain",\
21\
      "name": "lorem",\
22\
      "variants": [\
23\
        {\
24\
          "id": "ci_micro",\
25\
          "name": "lorem",\
26\
          "price": {\
27\
            "description": "lorem",\
28\
            "type": "fixed",\
29\
            "interval": "monthly",\
30\
            "amount": 42\
31\
          },\
32\
          "meta": null\
33\
        }\
34\
      ]\
35\
    }\
36\
  ]
37
}

Remove billing addons or revert compute instance sizing

delete/v1/projects/{ref}/billing/addons/{addon_variant}

Disables the selected addon variant, including rolling the compute instance back to its previous size.

The fine-grained token must include the following permissions to access this endpoint:

infra_add_ons_write

Path parameters

Required

string

Project ref

Details

addon_variant

Required

one of the following options

Options

Response codes

Response (200)

schema

1
{}

Apply a database migration

post/v1/projects/{ref}/database/migrations

Only available to selected partner OAuth apps

OAuth scopes

database:write

The fine-grained token must include the following permissions to access this endpoint:

database_migrations_write

Path parameters

Required

string

Project ref

Details

Body

application/json

query

Required

string

Details

name

Optional

string

rollback

Optional

string

Response codes

Response (200)

schema

1
{}

Authorize user-id to role mappings for JIT access

post/v1/projects/{ref}/database/jit

Authorizes the request to assume a role in the project database

OAuth scopes

database:read

The fine-grained token must include the following permissions to access this endpoint:

database_jit_read

Path parameters

Required

string

Project ref

Details

Body

application/json

role

Required

string

Details

rhost

Required

string

Details

Response codes

Response (200)

exampleschema

1
{
2
  "user_id": "fbdf5a53-161e-4460-98ad-0e39408d8689",
3
  "user_role": {
4
    "role": "lorem",
5
    "expires_at": 42,
6
    "allowed_networks": {
7
      "allowed_cidrs": [\
8\
        {\
9\
          "cidr": "lorem"\
10\
        }\
11\
      ],
12
      "allowed_cidrs_v6": [\
13\
        {\
14\
          "cidr": "lorem"\
15\
        }\
16\
      ]
17
    }
18
  }
19
}

[Beta] Create a login role for CLI with temporary password

post/v1/projects/{ref}/cli/login-role

OAuth scopes

database:write

The fine-grained token must include the following permissions to access this endpoint:

database_write

Path parameters

Required

string

Project ref

Details

Body

application/json

read_only

Required

boolean

Response codes

Response (201)

exampleschema

1
{
2
  "role": "lorem",
3
  "password": "lorem",
4
  "ttl_seconds": 1
5
}

Delete JIT access by user-id

delete/v1/projects/{ref}/database/jit/{user_id}

Remove JIT mappings of a user, revoking all JIT database access

The fine-grained token must include the following permissions to access this endpoint:

database_jit_write

Path parameters

Required

string

Project ref

Details

user_id

Required

string

Response codes

Response (200)

schema

1
{}

[Beta] Delete existing login roles used by CLI

delete/v1/projects/{ref}/cli/login-role

OAuth scopes

database:write

The fine-grained token must include the following permissions to access this endpoint:

database_write

Path parameters

Required

string

Project ref

Details

Response codes

Response (200)

exampleschema

1
{
2
  "message": "ok"
3
}

Disables project's readonly mode for the next 15 minutes

post/v1/projects/{ref}/readonly/temporary-disable

OAuth scopes

database:write

The fine-grained token must include the following permissions to access this endpoint:

database_readonly_config_write

Path parameters

Required

string

Project ref

Details

Response codes

Response (201)

schema

1
{}

[Beta] Enables Database Webhooks on the project

post/v1/projects/{ref}/database/webhooks/enable

OAuth scopes

database:write

The fine-grained token must include the following permissions to access this endpoint:

database_webhooks_config_write

Path parameters

Required

string

Project ref

Details

Response codes

Response (201)

schema

1
{}

Generate TypeScript types

get/v1/projects/{ref}/types/typescript

Returns the TypeScript types of your schema for use with supabase-js.

OAuth scopes

database:read

The fine-grained token must include the following permissions to access this endpoint:

database_read

Path parameters

Required

string

Project ref

Details

Query parameters

included_schemas

Optional

string

Response codes

Response (200)

exampleschema

1
{
2
  "types": "lorem"
3
}

Fetch an existing entry from migration history

get/v1/projects/{ref}/database/migrations/{version}

Only available to selected partner OAuth apps

OAuth scopes

database:read

The fine-grained token must include the following permissions to access this endpoint:

database_migrations_read

Path parameters

Required

string

Project ref

Details

version

Required

string

Details

Response codes

Response (200)

exampleschema

1
{
2
  "version": "lorem",
3
  "name": "lorem",
4
  "statements": [\
5\
    "lorem"\
6\
  ],
7
  "rollback": [\
8\
    "lorem"\
9\
  ],
10
  "created_by": "lorem",
11
  "idempotency_key": "lorem"
12
}

Gets a specific SQL snippet

get/v1/snippets/{id}

OAuth scopes

database:read

The fine-grained token must include the following permissions to access this endpoint:

snippets_read

Path parameters

Required

string

Response codes

Response (200)

exampleschema

1
{
2
  "id": "lorem",
3
  "inserted_at": "lorem",
4
  "updated_at": "lorem",
5
  "type": "sql",
6
  "visibility": "user",
7
  "name": "lorem",
8
  "description": "lorem",
9
  "project": {
10
    "id": 42,
11
    "name": "lorem"
12
  },
13
  "owner": {
14
    "id": 42,
15
    "username": "lorem"
16
  },
17
  "updated_by": {
18
    "id": 42,
19
    "username": "lorem"
20
  },
21
  "favorite": true,
22
  "content": {
23
    "favorite": true,
24
    "schema_version": "lorem",
25
    "sql": "lorem"
26
  }
27
}

Gets database metadata for the given project. deprecated

get/v1/projects/{ref}/database/context

This is an experimental endpoint. It is subject to change or removal in future versions. Use it with caution, as it may not remain supported or stable.

OAuth scopes

projects:read

The fine-grained token must include the following permissions to access this endpoint:

database_read

Path parameters

Required

string

Project ref

Details

Response codes

Response (200)

exampleschema

1
{
2
  "databases": [\
3\
    {\
4\
      "name": "lorem",\
5\
      "schemas": [\
6\
        {\
7\
          "name": "lorem"\
8\
        }\
9\
      ]\
10\
    }\
11\
  ]
12
}

Get PostgREST OpenAPI spec

get/v1/projects/{ref}/database/openapi

Returns the PostgREST OpenAPI specification for the project. This is the replacement for querying /rest/v1/ directly with the anon key.

OAuth scopes

database:read

The fine-grained token must include the following permissions to access this endpoint:

database_read

Path parameters

Required

string

Project ref

Details

Query parameters

schema

Optional

string

The database schema to generate the OpenAPI spec for

Response codes

Response (200)

exampleschema

1
{}

Get user-id to role mappings for JIT access

get/v1/projects/{ref}/database/jit

Mappings of roles a user can assume in the project database

OAuth scopes

database:read

The fine-grained token must include the following permissions to access this endpoint:

database_jit_read

Path parameters

Required

string

Project ref

Details

Response codes

Response (200)

exampleschema

1
{
2
  "user_id": "fbdf5a53-161e-4460-98ad-0e39408d8689",
3
  "user_roles": [\
4\
    {\
5\
      "role": "lorem",\
6\
      "expires_at": 42,\
7\
      "allowed_networks": {\
8\
        "allowed_cidrs": [\
9\
          {\
10\
            "cidr": "lorem"\
11\
          }\
12\
        ],\
13\
        "allowed_cidrs_v6": [\
14\
          {\
15\
            "cidr": "lorem"\
16\
          }\
17\
        ]\
18\
      }\
19\
    }\
20\
  ]
21
}

[Beta] Get project's temporary access configuration.

get/v1/projects/{ref}/jit-access

OAuth scopes

database:read

The fine-grained token must include the following permissions to access this endpoint:

project_admin_read

Path parameters

Required

string

Project ref

Details

Response codes

Response (200)

exampleschema

Gets project's supavisor config

get/v1/projects/{ref}/config/database/pooler

OAuth scopes

database:read

The fine-grained token must include the following permissions to access this endpoint:

database_pooling_config_read

Path parameters

Required

string

Project ref

Details

Response codes

Response (200)

exampleschema

1
[\
2\
  {\
3\
    "identifier": "lorem",\
4\
    "database_type": "PRIMARY",\
5\
    "is_using_scram_auth": true,\
6\
    "db_user": "lorem",\
7\
    "db_host": "lorem",\
8\
    "db_port": 42,\
9\
    "db_name": "lorem",\
10\
    "connection_string": "lorem",\
11\
    "connectionString": "lorem",\
12\
    "default_pool_size": 42,\
13\
    "max_client_conn": 42,\
14\
    "pool_mode": "transaction"\
15\
  }\
16\
]

Gets project's Postgres config

get/v1/projects/{ref}/config/database/postgres

OAuth scopes

database:read

The fine-grained token must include the following permissions to access this endpoint:

database_config_read

Path parameters

Required

string

Project ref

Details

Response codes

Response (200)

exampleschema

1
{
2
  "effective_cache_size": "lorem",
3
  "logical_decoding_work_mem": "lorem",
4
  "maintenance_work_mem": "lorem",
5
  "track_activity_query_size": "lorem",
6
  "max_connections": 1,
7
  "max_locks_per_transaction": 10,
8
  "max_parallel_maintenance_workers": 0,
9
  "max_parallel_workers": 0,
10
  "max_parallel_workers_per_gather": 0,
11
  "max_replication_slots": 42,
12
  "max_slot_wal_keep_size": "lorem",
13
  "max_standby_archive_delay": "lorem",
14
  "max_standby_streaming_delay": "lorem",
15
  "max_wal_size": "lorem",
16
  "max_wal_senders": 42,
17
  "max_worker_processes": 0,
18
  "session_replication_role": "origin",
19
  "shared_buffers": "lorem",
20
  "statement_timeout": "444444444444444444444444444444444444444444444444444",
21
  "track_commit_timestamp": true,
22
  "wal_keep_size": "lorem",
23
  "wal_sender_timeout": "444444444444444444444444444444444444444444444444444",
24
  "work_mem": "lorem",
25
  "checkpoint_timeout": "444444444444444444444444444444444444444444444444444",
26
  "hot_standby_feedback": true
27
}

Get project's pgbouncer config

get/v1/projects/{ref}/config/database/pgbouncer

OAuth scopes

database:read

The fine-grained token must include the following permissions to access this endpoint:

database_read

Path parameters

Required

string

Project ref

Details

Response codes

Response (200)

exampleschema

1
{
2
  "default_pool_size": 42,
3
  "ignore_startup_parameters": "lorem",
4
  "max_client_conn": 42,
5
  "pool_mode": "transaction",
6
  "connection_string": "lorem",
7
  "server_idle_timeout": 42,
8
  "server_lifetime": 42,
9
  "query_wait_timeout": 42,
10
  "reserve_pool_size": 42
11
}

Returns project's readonly mode status

get/v1/projects/{ref}/readonly

OAuth scopes

database:read

The fine-grained token must include the following permissions to access this endpoint:

database_readonly_config_read

Path parameters

Required

string

Project ref

Details

Response codes

Response (200)

exampleschema

1
{
2
  "enabled": true,
3
  "override_enabled": true,
4
  "override_active_until": "lorem"
5
}

[Beta] Get project's SSL enforcement configuration.

get/v1/projects/{ref}/ssl-enforcement

OAuth scopes

database:read

The fine-grained token must include the following permissions to access this endpoint:

database_ssl_config_read

Path parameters

Required

string

Project ref

Details

Response codes

Response (200)

exampleschema

1
{
2
  "currentConfig": {
3
    "database": true
4
  },
5
  "appliedSuccessfully": true
6
}

Lists all backups

get/v1/projects/{ref}/database/backups

OAuth scopes

database:read

The fine-grained token must include the following permissions to access this endpoint:

backups_read

Path parameters

Required

string

Project ref

Details

Response codes

Response (200)

exampleschema

1
{
2
  "region": "lorem",
3
  "walg_enabled": true,
4
  "pitr_enabled": true,
5
  "backups": [\
6\
    {\
7\
      "is_physical_backup": true,\
8\
      "status": "COMPLETED",\
9\
      "inserted_at": "lorem"\
10\
    }\
11\
  ],
12
  "physical_backup_data": {
13
    "earliest_physical_backup_date_unix": 42,
14
    "latest_physical_backup_date_unix": 42
15
  }
16
}

Lists SQL snippets for the logged in user

get/v1/snippets

OAuth scopes

database:read

The fine-grained token must include the following permissions to access this endpoint:

snippets_read

Query parameters

project_ref

Optional

string

Project ref

Details

cursor

Optional

string

limit

Optional

string

sort_by

Optional

enum

Accepted values

sort_order

Optional

enum

Accepted values

Response codes

Response (200)

exampleschema

1
{
2
  "data": [\
3\
    {\
4\
      "id": "lorem",\
5\
      "inserted_at": "lorem",\
6\
      "updated_at": "lorem",\
7\
      "type": "sql",\
8\
      "visibility": "user",\
9\
      "name": "lorem",\
10\
      "description": "lorem",\
11\
      "project": {\
12\
        "id": 42,\
13\
        "name": "lorem"\
14\
      },\
15\
      "owner": {\
16\
        "id": 42,\
17\
        "username": "lorem"\
18\
      },\
19\
      "updated_by": {\
20\
        "id": 42,\
21\
        "username": "lorem"\
22\
      },\
23\
      "favorite": true\
24\
    }\
25\
  ],
26
  "cursor": "lorem"
27
}

List all user-id to role mappings for JIT access

get/v1/projects/{ref}/database/jit/list

Mappings of roles a user can assume in the project database

The fine-grained token must include the following permissions to access this endpoint:

database_jit_read

Path parameters

Required

string

Project ref

Details

Response codes

Response (200)

exampleschema

1
{
2
  "items": [\
3\
    {\
4\
      "user_id": "fbdf5a53-161e-4460-98ad-0e39408d8689",\
5\
      "user_roles": [\
6\
        {\
7\
          "role": "lorem",\
8\
          "expires_at": 42,\
9\
          "allowed_networks": {\
10\
            "allowed_cidrs": [\
11\
              {\
12\
                "cidr": "lorem"\
13\
              }\
14\
            ],\
15\
            "allowed_cidrs_v6": [\
16\
              {\
17\
                "cidr": "lorem"\
18\
              }\
19\
            ]\
20\
          }\
21\
        }\
22\
      ]\
23\
    }\
24\
  ]
25
}

List applied migration versions

get/v1/projects/{ref}/database/migrations

Only available to selected partner OAuth apps

OAuth scopes

database:read

The fine-grained token must include the following permissions to access this endpoint:

database_migrations_read

Path parameters

Required

string

Project ref

Details

Response codes

Response (200)

exampleschema

1
[\
2\
  {\
3\
    "version": "lorem",\
4\
    "name": "lorem"\
5\
  }\
6\
]

Patch an existing entry in migration history

patch/v1/projects/{ref}/database/migrations/{version}

Only available to selected partner OAuth apps

OAuth scopes

database:write

The fine-grained token must include the following permissions to access this endpoint:

database_migrations_write

Path parameters

Required

string

Project ref

Details

version

Required

string

Details

Body

application/json

name

Optional

string

rollback

Optional

string

Response codes

Response (200)

schema

1
{}

[Beta] Run a sql query as supabase_read_only_user

post/v1/projects/{ref}/database/query/read-only

All entity references must be schema qualified.

OAuth scopes

database:read

The fine-grained token must include the following permissions to access this endpoint:

database_read

Path parameters

Required

string

Project ref

Details

Body

application/json

query

Required

string

Details

parameters

Optional

Array

Items

Response codes

Response (201)

schema

1
{}

[Beta] Remove a read replica

post/v1/projects/{ref}/read-replicas/remove

The fine-grained token must include the following permissions to access this endpoint:

infra_read_replicas_write

Path parameters

Required

string

Project ref

Details

Body

application/json

database_identifier

Required

string

Response codes

Response (201)

schema

1
{}

Restores a PITR backup for a database

post/v1/projects/{ref}/database/backups/restore-pitr

OAuth scopes

database:write

The fine-grained token must include the following permissions to access this endpoint:

backups_write

Path parameters

Required

string

Project ref

Details

Body

application/json

recovery_time_target_unix

Required

integer

Response codes

Response (201)

schema

1
{}

Rollback database migrations and remove them from history table

delete/v1/projects/{ref}/database/migrations

Only available to selected partner OAuth apps

OAuth scopes

database:write

The fine-grained token must include the following permissions to access this endpoint:

database_migrations_write

Path parameters

Required

string

Project ref

Details

Query parameters

Required

string

Rollback migrations greater or equal to this version

Details

Response codes

Response (200)

schema

1
{}

[Beta] Run sql query

post/v1/projects/{ref}/database/query

OAuth scopes

database:write

The fine-grained token must include the following permissions to access this endpoint:

database_write
or
database_read

Path parameters

Required

string

Project ref

Details

Body

application/json

query

Required

string

Details

parameters

Optional

Array

Items

read_only

Optional

boolean

Response codes

Response (201)

schema

1
{}

[Beta] Set up a read replica

post/v1/projects/{ref}/read-replicas/setup

The fine-grained token must include the following permissions to access this endpoint:

infra_read_replicas_write

Path parameters

Required

string

Project ref

Details

Body

application/json

read_replica_region

Required

enum

Accepted values

Response codes

Response (201)

schema

1
{}

Updates the database password

patch/v1/projects/{ref}/database/password

OAuth scopes

database:write

The fine-grained token must include the following permissions to access this endpoint:

database_config_write

Path parameters

Required

string

Project ref

Details

Body

application/json

password

Required

string

Details

Response codes

Response (200)

exampleschema

1
{
2
  "message": "lorem"
3
}

Updates a user mapping for JIT access

put/v1/projects/{ref}/database/jit

Modifies the roles that can be assumed and for how long

The fine-grained token must include the following permissions to access this endpoint:

database_jit_write

Path parameters

Required

string

Project ref

Details

Body

application/json

user_id

Required

string

Details

roles

Required

Array