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
2
curl https://api.supabase.com/v1/projects \  -H "Authorization: Bearer sbp_bdd0••••••••••••••••••••••••••••••••4f23"

All API requests must be authenticated and made over HTTPS foo.

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 in the following 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 milliseconds 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 (milliseconds) 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

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

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

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

Path parameters

ref
Required
string
Project ref

Query parameters

lint_type
Optional
enum

Response codes

Response (200)

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

Gets a project's function combined statistics

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

Path parameters

ref
Required
string
Project ref

Query parameters

interval
Required
enum
function_id
Required
string

Response codes

Response (200)

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

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

Path parameters

ref
Required
string
Project ref

Query parameters

sql
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)

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

Gets project's usage api counts

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

Path parameters

ref
Required
string
Project ref

Query parameters

interval
Optional
enum

Response codes

Response (200)

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

Gets project's usage api requests count

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

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

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

Creates a new SSO provider

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

OAuth scopes

auth:write

Path parameters

ref
Required
string
Project ref

Body

type
Required
enum
metadata_xml
Optional
string
metadata_url
Optional
string
domains
Optional
Array<string>
attribute_mapping
Optional
object
name_id_format
Optional
enum

Response codes

Response (201)

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

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

Path parameters

ref
Required
string
Project ref

Response codes

Response (201)

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

Create a new signing key for the project in standby status

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

OAuth scopes

secrets:write

Path parameters

ref
Required
string
Project ref

Body

algorithm
Required
enum
status
Optional
enum
private_jwk
Optional
one of the following options

Response codes

Response (201)

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

Creates a new third-party auth integration

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

OAuth scopes

auth:write

Path parameters

ref
Required
string
Project ref

Body

oidc_issuer_url
Optional
string
jwks_url
Optional
string
custom_jwks
Optional
unknown

Response codes

Response (201)

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

Removes a SSO provider by its UUID

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

OAuth scopes

auth:write

Path parameters

ref
Required
string
Project ref
provider_id
Required
string

Response codes

Response (200)

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

Removes a third-party auth integration

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

OAuth scopes

auth:write

Path parameters

ref
Required
string
Project ref
tpa_id
Required
string

Response codes

Response (200)

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

Gets a SSO provider by its UUID

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

OAuth scopes

auth:read

Path parameters

ref
Required
string
Project ref
provider_id
Required
string

Response codes

Response (200)

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

Gets project's auth config

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

OAuth scopes

auth:read

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

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

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

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

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

Get information about a signing key

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

Path parameters

id
Required
string
ref
Required
string
Project ref

Response codes

Response (200)

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

List all signing keys for the project

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

OAuth scopes

secrets:read

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

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

Get a third-party integration

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

OAuth scopes

auth:read

Path parameters

ref
Required
string
Project ref
tpa_id
Required
string

Response codes

Response (200)

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

Lists all SSO providers

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

OAuth scopes

auth:read

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

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

Lists all third-party auth integrations

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

OAuth scopes

auth:read

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

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

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

Path parameters

id
Required
string
ref
Required
string
Project ref

Response codes

Response (200)

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

Updates a SSO provider by its UUID

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

OAuth scopes

auth:write

Path parameters

ref
Required
string
Project ref
provider_id
Required
string

Body

metadata_xml
Optional
string
metadata_url
Optional
string
domains
Optional
Array<string>
attribute_mapping
Optional
object
name_id_format
Optional
enum

Response codes

Response (200)

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

Updates a project's auth config

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

OAuth scopes

auth:write

Path parameters

ref
Required
string
Project ref

Body

site_url
Optional
string
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
security_captcha_enabled
Optional
boolean
security_captcha_provider
Optional
enum
security_captcha_secret
Optional
string
sessions_timebox
Optional
integer
sessions_inactivity_timeout
Optional
integer
sessions_single_per_user
Optional
boolean
sessions_tags
Optional
string
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
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
sms_messagebird_access_key
Optional
string
sms_messagebird_originator
Optional
string
sms_test_otp
Optional
string
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_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
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
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

Response codes

Response (200)

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

Update a signing key, mainly its status

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

OAuth scopes

secrets:write

Path parameters

id
Required
string
ref
Required
string
Project ref

Body

status
Required
enum

Response codes

Response (200)

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

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.

Path parameters

ref
Required
string
Project ref

Body

addon_variant
Required
one of the following options
addon_type
Required
enum

Response codes

Response (200)

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.

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

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

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.

Path parameters

ref
Required
string
Project ref
addon_variant
Required
one of the following options

Response codes

Response (200)

1
{}

[Beta] Apply a database migration

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

Only available to selected partner OAuth apps

OAuth scopes

database:write

Path parameters

ref
Required
string
Project ref

Body

query
Required
string
name
Optional
string
rollback
Optional
string

Response codes

Response (200)

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

Path parameters

ref
Required
string
Project ref

Body

role
Required
string
rhost
Required
string

Response codes

Response (200)

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

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

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

OAuth scopes

database:write

Path parameters

ref
Required
string
Project ref

Body

read_only
Required
boolean

Response codes

Response (201)

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

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

Path parameters

ref
Required
string
Project ref
user_id
Required
string

Response codes

Response (200)

1
{}

[Beta] Delete existing login roles used by CLI

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

OAuth scopes

database:write

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

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

Disables project's readonly mode for the next 15 minutes

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

OAuth scopes

database:write

Path parameters

ref
Required
string
Project ref

Response codes

Response (201)

1
{}

[Beta] Enables Database Webhooks on the project

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

OAuth scopes

database:write

Path parameters

ref
Required
string
Project ref

Response codes

Response (201)

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

Path parameters

ref
Required
string
Project ref

Query parameters

included_schemas
Optional
string

Response codes

Response (200)

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

[Beta] 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

Path parameters

ref
Required
string
Project ref
version
Required
string

Response codes

Response (200)

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

Gets a specific SQL snippet

get/v1/snippets/{id}

OAuth scopes

database:read

Path parameters

id
Required
string

Response codes

Response (200)

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

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

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

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

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

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

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

Gets project's supavisor config

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

OAuth scopes

database:read

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

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

Gets project's Postgres config

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

OAuth scopes

database:read

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

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

Get project's pgbouncer config

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

OAuth scopes

database:read

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

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

Returns project's readonly mode status

get/v1/projects/{ref}/readonly

OAuth scopes

database:read

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

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

[Beta] Get project's SSL enforcement configuration.

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

OAuth scopes

database:read

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

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

Lists all backups

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

OAuth scopes

database:read

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

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

Lists SQL snippets for the logged in user

get/v1/snippets

OAuth scopes

database:read

Query parameters

project_ref
Optional
string
Project ref
cursor
Optional
string
limit
Optional
string
sort_by
Optional
enum
sort_order
Optional
enum

Response codes

Response (200)

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

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

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

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

[Beta] List applied migration versions

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

Only available to selected partner OAuth apps

OAuth scopes

database:read

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

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

[Beta] 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

Path parameters

ref
Required
string
Project ref
version
Required
string

Body

name
Optional
string
rollback
Optional
string

Response codes

Response (200)

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

Path parameters

ref
Required
string
Project ref

Body

query
Required
string
parameters
Optional
Array<unknown>

Response codes

Response (201)

1
{}

[Beta] Remove a read replica

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

Path parameters

ref
Required
string
Project ref

Body

database_identifier
Required
string

Response codes

Response (201)

1
{}

Restores a PITR backup for a database

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

OAuth scopes

database:write

Path parameters

ref
Required
string
Project ref

Body

recovery_time_target_unix
Required
integer

Response codes

Response (201)

1
{}

[Beta] 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

Path parameters

ref
Required
string
Project ref

Query parameters

gte
Required
string
Rollback migrations greater or equal to this version

Response codes

Response (200)

1
{}

[Beta] Run sql query

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

OAuth scopes

database:write

Path parameters

ref
Required
string
Project ref

Body

query
Required
string
parameters
Optional
Array<unknown>
read_only
Optional
boolean

Response codes

Response (201)

1
{}

[Beta] Set up a read replica

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

Path parameters

ref
Required
string
Project ref

Body

read_replica_region
Required
enum

Response codes

Response (201)

1
{}

Updates the database password

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

OAuth scopes

database:write

Path parameters

ref
Required
string
Project ref

Body

password
Required
string

Response codes

Response (200)

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

Updates a user mapping for JIT access

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

Modifies the roles that can be assumed and for how long

Path parameters

ref
Required
string
Project ref

Body

user_id
Required
string
roles
Required
Array<object>

Response codes

Response (200)

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

Updates project's supavisor config

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

OAuth scopes

database:write

Path parameters

ref
Required
string
Project ref

Body

default_pool_size
Optional
integer
pool_mode
Optional
enum

Response codes

Response (200)

1
2
3
4
{  "default_pool_size": 42,  "pool_mode": "lorem"}

Updates project's Postgres config

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

OAuth scopes

database:write

Path parameters

ref
Required
string
Project ref

Body

effective_cache_size
Optional
string
logical_decoding_work_mem
Optional
string
maintenance_work_mem
Optional
string
track_activity_query_size
Optional
string
max_connections
Optional
integer
max_locks_per_transaction
Optional
integer
max_parallel_maintenance_workers
Optional
integer
max_parallel_workers
Optional
integer
max_parallel_workers_per_gather
Optional
integer
max_replication_slots
Optional
integer
max_slot_wal_keep_size
Optional
string
max_standby_archive_delay
Optional
string
max_standby_streaming_delay
Optional
string
max_wal_size
Optional
string
max_wal_senders
Optional
integer
max_worker_processes
Optional
integer
session_replication_role
Optional
enum
shared_buffers
Optional
string
statement_timeout
Optional
string
track_commit_timestamp
Optional
boolean
wal_keep_size
Optional
string
wal_sender_timeout
Optional
string
work_mem
Optional
string
checkpoint_timeout
Optional
string
hot_standby_feedback
Optional
boolean
restart_database
Optional
boolean

Response codes

Response (200)

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

[Beta] Update project's SSL enforcement configuration.

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

OAuth scopes

database:write

Path parameters

ref
Required
string
Project ref

Body

requestedConfig
Required
object

Response codes

Response (200)

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

[Beta] Upsert a database migration without applying

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

Only available to selected partner OAuth apps

OAuth scopes

database:write

Path parameters

ref
Required
string
Project ref

Body

query
Required
string
name
Optional
string
rollback
Optional
string

Response codes

Response (200)

1
{}

[Beta] Activates a custom hostname for a project.

post/v1/projects/{ref}/custom-hostname/activate

OAuth scopes

domains:write

Path parameters

ref
Required
string
Project ref

Response codes

Response (201)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
{  "status": "1_not_started",  "custom_hostname": "lorem",  "data": {    "success": true,    "errors": [      null    ],    "messages": [      null    ],    "result": {      "id": "lorem",      "hostname": "lorem",      "ssl": {        "status": "lorem",        "validation_records": [          {            "txt_name": "lorem",            "txt_value": "lorem"          }        ],        "validation_errors": [          {            "message": "lorem"          }        ]      },      "ownership_verification": {        "type": "lorem",        "name": "lorem",        "value": "lorem"      },      "custom_origin_server": "lorem",      "verification_errors": [        "lorem"      ],      "status": "lorem"    }  }}

[Beta] Activates a vanity subdomain for a project.

post/v1/projects/{ref}/vanity-subdomain/activate

OAuth scopes

domains:write

Path parameters

ref
Required
string
Project ref

Body

vanity_subdomain
Required
string

Response codes

Response (201)

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

[Beta] Checks vanity subdomain availability

post/v1/projects/{ref}/vanity-subdomain/check-availability

OAuth scopes

domains:write

Path parameters

ref
Required
string
Project ref

Body

vanity_subdomain
Required
string

Response codes

Response (201)

1
2
3
{  "available": true}

[Beta] Deletes a project's vanity subdomain configuration

delete/v1/projects/{ref}/vanity-subdomain

OAuth scopes

domains:write

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

1
{}

[Beta] Gets project's custom hostname config

get/v1/projects/{ref}/custom-hostname

OAuth scopes

domains:read

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
{  "status": "1_not_started",  "custom_hostname": "lorem",  "data": {    "success": true,    "errors": [      null    ],    "messages": [      null    ],    "result": {      "id": "lorem",      "hostname": "lorem",      "ssl": {        "status": "lorem",        "validation_records": [          {            "txt_name": "lorem",            "txt_value": "lorem"          }        ],        "validation_errors": [          {            "message": "lorem"          }        ]      },      "ownership_verification": {        "type": "lorem",        "name": "lorem",        "value": "lorem"      },      "custom_origin_server": "lorem",      "verification_errors": [        "lorem"      ],      "status": "lorem"    }  }}

[Beta] Gets current vanity subdomain config

get/v1/projects/{ref}/vanity-subdomain

OAuth scopes

domains:read

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

1
2
3
4
{  "status": "not-used",  "custom_domain": "lorem"}

[Beta] Updates project's custom hostname configuration

post/v1/projects/{ref}/custom-hostname/initialize

OAuth scopes

domains:write

Path parameters

ref
Required
string
Project ref

Body

custom_hostname
Required
string

Response codes

Response (201)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
{  "status": "1_not_started",  "custom_hostname": "lorem",  "data": {    "success": true,    "errors": [      null    ],    "messages": [      null    ],    "result": {      "id": "lorem",      "hostname": "lorem",      "ssl": {        "status": "lorem",        "validation_records": [          {            "txt_name": "lorem",            "txt_value": "lorem"          }        ],        "validation_errors": [          {            "message": "lorem"          }        ]      },      "ownership_verification": {        "type": "lorem",        "name": "lorem",        "value": "lorem"      },      "custom_origin_server": "lorem",      "verification_errors": [        "lorem"      ],      "status": "lorem"    }  }}

[Beta] Attempts to verify the DNS configuration for project's custom hostname configuration

post/v1/projects/{ref}/custom-hostname/reverify

OAuth scopes

domains:write

Path parameters

ref
Required
string
Project ref

Response codes

Response (201)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
{  "status": "1_not_started",  "custom_hostname": "lorem",  "data": {    "success": true,    "errors": [      null    ],    "messages": [      null    ],    "result": {      "id": "lorem",      "hostname": "lorem",      "ssl": {        "status": "lorem",        "validation_records": [          {            "txt_name": "lorem",            "txt_value": "lorem"          }        ],        "validation_errors": [          {            "message": "lorem"          }        ]      },      "ownership_verification": {        "type": "lorem",        "name": "lorem",        "value": "lorem"      },      "custom_origin_server": "lorem",      "verification_errors": [        "lorem"      ],      "status": "lorem"    }  }}

Bulk update functions

put/v1/projects/{ref}/functions

Bulk update functions. It will create a new function or replace existing. The operation is idempotent. NOTE: You will need to manually bump the version.

OAuth scopes

edge_functions:write

Path parameters

ref
Required
string
Project ref

Body

Array of object

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{  "functions": [    {      "id": "lorem",      "slug": "lorem",      "name": "lorem",      "status": "ACTIVE",      "version": 42,      "created_at": 42,      "updated_at": 42,      "verify_jwt": true,      "import_map": true,      "entrypoint_path": "lorem",      "import_map_path": "lorem",      "ezbr_sha256": "lorem"    }  ]}

Create a function
deprecated

post/v1/projects/{ref}/functions

This endpoint is deprecated - use the deploy endpoint. Creates a function and adds it to the specified project.

OAuth scopes

edge_functions:write

Path parameters

ref
Required
string
Project ref

Query parameters

slug
Optional
string
name
Optional
string
verify_jwt
Optional
boolean
Boolean string, true or false
import_map
Optional
boolean
Boolean string, true or false
entrypoint_path
Optional
string
import_map_path
Optional
string
ezbr_sha256
Optional
string

Body

string

Response codes

Response (201)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{  "id": "lorem",  "slug": "lorem",  "name": "lorem",  "status": "ACTIVE",  "version": 42,  "created_at": 42,  "updated_at": 42,  "verify_jwt": true,  "import_map": true,  "entrypoint_path": "lorem",  "import_map_path": "lorem",  "ezbr_sha256": "lorem"}

Delete a function

delete/v1/projects/{ref}/functions/{function_slug}

Deletes a function with the specified slug from the specified project.

OAuth scopes

edge_functions:write

Path parameters

ref
Required
string
Project ref
function_slug
Required
string
Function slug

Response codes

Response (200)

1
{}

Deploy a function

post/v1/projects/{ref}/functions/deploy

A new endpoint to deploy functions. It will create if function does not exist.

OAuth scopes

edge_functions:write

Path parameters

ref
Required
string
Project ref

Query parameters

slug
Optional
string
bundleOnly
Optional
boolean
Boolean string, true or false

Body

file
Optional
Array<string>
metadata
Required
object

Response codes

Response (201)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{  "id": "lorem",  "slug": "lorem",  "name": "lorem",  "status": "ACTIVE",  "version": 42,  "created_at": 42,  "updated_at": 42,  "verify_jwt": true,  "import_map": true,  "entrypoint_path": "lorem",  "import_map_path": "lorem",  "ezbr_sha256": "lorem"}

Retrieve a function

get/v1/projects/{ref}/functions/{function_slug}

Retrieves a function with the specified slug and project.

OAuth scopes

edge_functions:read

Path parameters

ref
Required
string
Project ref
function_slug
Required
string
Function slug

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{  "id": "lorem",  "slug": "lorem",  "name": "lorem",  "status": "ACTIVE",  "version": 42,  "created_at": 42,  "updated_at": 42,  "verify_jwt": true,  "import_map": true,  "entrypoint_path": "lorem",  "import_map_path": "lorem",  "ezbr_sha256": "lorem"}

Retrieve a function body

get/v1/projects/{ref}/functions/{function_slug}/body

Retrieves a function body for the specified slug and project.

OAuth scopes

edge_functions:read

Path parameters

ref
Required
string
Project ref
function_slug
Required
string
Function slug

Response codes

Response (200)

1
{}

List all functions

get/v1/projects/{ref}/functions

Returns all functions you've previously added to the specified project.

OAuth scopes

edge_functions:read

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
[  {    "id": "lorem",    "slug": "lorem",    "name": "lorem",    "status": "ACTIVE",    "version": 42,    "created_at": 42,    "updated_at": 42,    "verify_jwt": true,    "import_map": true,    "entrypoint_path": "lorem",    "import_map_path": "lorem",    "ezbr_sha256": "lorem"  }]

Update a function

patch/v1/projects/{ref}/functions/{function_slug}

Updates a function with the specified slug and project.

OAuth scopes

edge_functions:write

Path parameters

ref
Required
string
Project ref
function_slug
Required
string
Function slug

Query parameters

slug
Optional
string
name
Optional
string
verify_jwt
Optional
boolean
Boolean string, true or false
import_map
Optional
boolean
Boolean string, true or false
entrypoint_path
Optional
string
import_map_path
Optional
string
ezbr_sha256
Optional
string

Body

string

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{  "id": "lorem",  "slug": "lorem",  "name": "lorem",  "status": "ACTIVE",  "version": 42,  "created_at": 42,  "updated_at": 42,  "verify_jwt": true,  "import_map": true,  "entrypoint_path": "lorem",  "import_map_path": "lorem",  "ezbr_sha256": "lorem"}

Count the number of action runs

head/v1/projects/{ref}/actions

Returns the total number of action runs of the specified project.

OAuth scopes

environment:read

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

1
{}

Create a database branch

post/v1/projects/{ref}/branches

Creates a database branch from the specified project.

OAuth scopes

environment:write

Path parameters

ref
Required
string
Project ref

Body

branch_name
Required
string
git_branch
Optional
string
is_default
Optional
boolean
persistent
Optional
boolean
region
Optional
string
desired_instance_size
Optional
enum
release_channel
Optional
enum
postgres_engine
Optional
enum
secrets
Optional
object
with_data
Optional
boolean
notify_url
Optional
string

Response codes

Response (201)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{  "id": "fbdf5a53-161e-4460-98ad-0e39408d8689",  "name": "lorem",  "project_ref": "lorem",  "parent_project_ref": "lorem",  "is_default": true,  "git_branch": "lorem",  "pr_number": 42,  "latest_check_run_id": 42,  "persistent": true,  "status": "CREATING_PROJECT",  "created_at": "2021-12-31T23:34:00Z",  "updated_at": "2021-12-31T23:34:00Z",  "review_requested_at": "2021-12-31T23:34:00Z",  "with_data": true,  "notify_url": "https://github.com/NeuraLegion/brokencrystals",  "deletion_scheduled_at": "2021-12-31T23:34:00Z",  "preview_project_status": "INACTIVE"}

Delete a database branch

delete/v1/branches/{branch_id_or_ref}

Deletes the specified database branch. By default, deletes immediately. Use force=false to schedule deletion with 1-hour grace period (only when soft deletion is enabled).

OAuth scopes

environment:write

Path parameters

branch_id_or_ref
Required
one of the following options
Branch ID

Query parameters

force
Optional
boolean
If set to false, schedule deletion with 1-hour grace period (only when soft deletion is enabled).

Response codes

Response (200)

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

[Beta] Diffs a database branch

get/v1/branches/{branch_id_or_ref}/diff

Diffs the specified database branch

OAuth scopes

environment:write

Path parameters

branch_id_or_ref
Required
one of the following options
Branch ID

Query parameters

included_schemas
Optional
string

Response codes

Response (200)

1
{}

Disables preview branching

delete/v1/projects/{ref}/branches

Disables preview branching for the specified project

OAuth scopes

environment:write

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

1
{}

Get a database branch

get/v1/projects/{ref}/branches/{name}

Fetches the specified database branch by its name.

OAuth scopes

environment:read

Path parameters

ref
Required
string
Project ref
name
Required
string

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{  "id": "fbdf5a53-161e-4460-98ad-0e39408d8689",  "name": "lorem",  "project_ref": "lorem",  "parent_project_ref": "lorem",  "is_default": true,  "git_branch": "lorem",  "pr_number": 42,  "latest_check_run_id": 42,  "persistent": true,  "status": "CREATING_PROJECT",  "created_at": "2021-12-31T23:34:00Z",  "updated_at": "2021-12-31T23:34:00Z",  "review_requested_at": "2021-12-31T23:34:00Z",  "with_data": true,  "notify_url": "https://github.com/NeuraLegion/brokencrystals",  "deletion_scheduled_at": "2021-12-31T23:34:00Z",  "preview_project_status": "INACTIVE"}

Get database branch config

get/v1/branches/{branch_id_or_ref}

Fetches configurations of the specified database branch

OAuth scopes

environment:read

Path parameters

branch_id_or_ref
Required
one of the following options
Branch ID

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
10
11
12
{  "ref": "lorem",  "postgres_version": "lorem",  "postgres_engine": "lorem",  "release_channel": "lorem",  "status": "INACTIVE",  "db_host": "lorem",  "db_port": 1,  "db_user": "lorem",  "db_pass": "lorem",  "jwt_secret": "lorem"}

Get the status of an action run

get/v1/projects/{ref}/actions/{run_id}

Returns the current status of the specified action run.

OAuth scopes

environment:read

Path parameters

ref
Required
string
Project ref
run_id
Required
string
Action Run ID

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{  "id": "lorem",  "branch_id": "lorem",  "run_steps": [    {      "name": "clone",      "status": "CREATED",      "created_at": "lorem",      "updated_at": "lorem"    }  ],  "git_config": null,  "workdir": "lorem",  "check_run_id": 42,  "created_at": "lorem",  "updated_at": "lorem"}

Get the logs of an action run

get/v1/projects/{ref}/actions/{run_id}/logs

Returns the logs from the specified action run.

OAuth scopes

environment:read

Path parameters

ref
Required
string
Project ref
run_id
Required
string
Action Run ID

Response codes

Response (200)

1
{}

List all action runs

get/v1/projects/{ref}/actions

Returns a paginated list of action runs of the specified project.

OAuth scopes

environment:read

Path parameters

ref
Required
string
Project ref

Query parameters

offset
Optional
number
limit
Optional
number

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
[  {    "id": "lorem",    "branch_id": "lorem",    "run_steps": [      {        "name": "clone",        "status": "CREATED",        "created_at": "lorem",        "updated_at": "lorem"      }    ],    "git_config": null,    "workdir": "lorem",    "check_run_id": 42,    "created_at": "lorem",    "updated_at": "lorem"  }]

List all database branches

get/v1/projects/{ref}/branches

Returns all database branches of the specified project.

OAuth scopes

environment:read

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
[  {    "id": "fbdf5a53-161e-4460-98ad-0e39408d8689",    "name": "lorem",    "project_ref": "lorem",    "parent_project_ref": "lorem",    "is_default": true,    "git_branch": "lorem",    "pr_number": 42,    "latest_check_run_id": 42,    "persistent": true,    "status": "CREATING_PROJECT",    "created_at": "2021-12-31T23:34:00Z",    "updated_at": "2021-12-31T23:34:00Z",    "review_requested_at": "2021-12-31T23:34:00Z",    "with_data": true,    "notify_url": "https://github.com/NeuraLegion/brokencrystals",    "deletion_scheduled_at": "2021-12-31T23:34:00Z",    "preview_project_status": "INACTIVE"  }]

Merges a database branch

post/v1/branches/{branch_id_or_ref}/merge

Merges the specified database branch

OAuth scopes

environment:write

Path parameters

branch_id_or_ref
Required
one of the following options
Branch ID

Body

migration_version
Optional
string

Response codes

Response (201)

1
2
3
4
{  "workflow_run_id": "lorem",  "message": "ok"}

Pushes a database branch

post/v1/branches/{branch_id_or_ref}/push

Pushes the specified database branch

OAuth scopes

environment:write

Path parameters

branch_id_or_ref
Required
one of the following options
Branch ID

Body

migration_version
Optional
string

Response codes

Response (201)

1
2
3
4
{  "workflow_run_id": "lorem",  "message": "ok"}

Resets a database branch

post/v1/branches/{branch_id_or_ref}/reset

Resets the specified database branch

OAuth scopes

environment:write

Path parameters

branch_id_or_ref
Required
one of the following options
Branch ID

Body

migration_version
Optional
string

Response codes

Response (201)

1
2
3
4
{  "workflow_run_id": "lorem",  "message": "ok"}

Restore a scheduled branch deletion

post/v1/branches/{branch_id_or_ref}/restore

Cancels scheduled deletion and restores the branch to active state

OAuth scopes

environment:write

Path parameters

branch_id_or_ref
Required
one of the following options
Branch ID

Response codes

Response (200)

1
2
3
{  "message": "Branch restoration initiated"}

Update database branch config

patch/v1/branches/{branch_id_or_ref}

Updates the configuration of the specified database branch

OAuth scopes

environment:write

Path parameters

branch_id_or_ref
Required
one of the following options
Branch ID

Body

branch_name
Optional
string
git_branch
Optional
string
reset_on_push
Optional
Deprecatedboolean
persistent
Optional
boolean
status
Optional
enum
request_review
Optional
boolean
notify_url
Optional
string

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{  "id": "fbdf5a53-161e-4460-98ad-0e39408d8689",  "name": "lorem",  "project_ref": "lorem",  "parent_project_ref": "lorem",  "is_default": true,  "git_branch": "lorem",  "pr_number": 42,  "latest_check_run_id": 42,  "persistent": true,  "status": "CREATING_PROJECT",  "created_at": "2021-12-31T23:34:00Z",  "updated_at": "2021-12-31T23:34:00Z",  "review_requested_at": "2021-12-31T23:34:00Z",  "with_data": true,  "notify_url": "https://github.com/NeuraLegion/brokencrystals",  "deletion_scheduled_at": "2021-12-31T23:34:00Z",  "preview_project_status": "INACTIVE"}

Update the status of an action run

patch/v1/projects/{ref}/actions/{run_id}/status

Updates the status of an ongoing action run.

OAuth scopes

environment:write

Path parameters

ref
Required
string
Project ref
run_id
Required
string
Action Run ID

Body

clone
Optional
enum
pull
Optional
enum
health
Optional
enum
configure
Optional
enum
migrate
Optional
enum
seed
Optional
enum
deploy
Optional
enum

Response codes

Response (200)

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

[Beta] Authorize user through oauth

get/v1/oauth/authorize

Query parameters

client_id
Required
string
response_type
Required
enum
redirect_uri
Required
string
scope
Optional
string
state
Optional
string
response_mode
Optional
string
code_challenge
Optional
string
code_challenge_method
Optional
enum
organization_slug
Optional
string
Organization slug
resource
Optional
string
Resource indicator for MCP (Model Context Protocol) clients

Response codes

Response (204)

1
{}

[Beta] Exchange auth code for user's access and refresh token

post/v1/oauth/token

Body

grant_type
Optional
enum
client_id
Optional
string
client_secret
Optional
string
code
Optional
string
code_verifier
Optional
string
redirect_uri
Optional
string
refresh_token
Optional
string
resource
Optional
string
scope
Optional
string

Response codes

Response (201)

1
2
3
4
5
6
{  "access_token": "lorem",  "refresh_token": "lorem",  "expires_in": 42,  "token_type": "Bearer"}

Authorize user through oauth and claim a project

get/v1/oauth/authorize/project-claim

Initiates the OAuth authorization flow for the specified provider. After successful authentication, the user can claim ownership of the specified project.

Query parameters

project_ref
Required
string
Project ref
client_id
Required
string
response_type
Required
enum
redirect_uri
Required
string
state
Optional
string
response_mode
Optional
string
code_challenge
Optional
string
code_challenge_method
Optional
enum

Response codes

Response (204)

1
{}

[Beta] Revoke oauth app authorization and it's corresponding tokens

post/v1/oauth/revoke

Body

client_id
Required
string
client_secret
Required
string
refresh_token
Required
string

Response codes

Response (204)

1
{}

Create an organization

post/v1/organizations

Body

name
Required
string

Response codes

Response (201)

1
2
3
4
5
{  "id": "lorem",  "slug": "EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE",  "name": "lorem"}

Gets information about the organization

get/v1/organizations/{slug}

OAuth scopes

organizations:read

Path parameters

slug
Required
string
Organization slug

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
10
11
{  "id": "lorem",  "name": "lorem",  "plan": "free",  "opt_in_tags": [    "AI_SQL_GENERATOR_OPT_IN"  ],  "allowed_release_channels": [    "internal"  ]}

List all organizations

get/v1/organizations

Returns a list of organizations that you currently belong to.

OAuth scopes

organizations:read

Response codes

Response (200)

1
2
3
4
5
6
7
[  {    "id": "lorem",    "slug": "EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE",    "name": "lorem"  }]

List members of an organization

get/v1/organizations/{slug}/members

OAuth scopes

organizations:read

Path parameters

slug
Required
string
Organization slug

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
[  {    "user_id": "lorem",    "user_name": "lorem",    "email": "lorem",    "role_name": "lorem",    "mfa_enabled": true  }]

Cancels the given project restoration

post/v1/projects/{ref}/restore/cancel

OAuth scopes

projects:write

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

1
{}

Create a project

post/v1/projects

OAuth scopes

projects:write

Body

db_pass
Required
string
name
Required
string
organization_id
Optional
Deprecatedstring
organization_slug
Required
string
plan
Optional
Deprecatedenum
region
Optional
Deprecatedenum
region_selection
Optional
one of the following options
kps_enabled
Optional
Deprecatedboolean
desired_instance_size
Optional
enum
template_url
Optional
string
release_channel
Optional
Deprecatedenum
postgres_engine
Optional
Deprecatedenum

Response codes

Response (201)

1
2
3
4
5
6
7
8
9
10
{  "id": "lorem",  "ref": "mmmmmmmmmmmmmmmmmmmm",  "organization_id": "lorem",  "organization_slug": "EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE",  "name": "lorem",  "region": "us-east-1",  "created_at": "2023-03-29T16:32:59Z",  "status": "INACTIVE"}

Deletes the given project

delete/v1/projects/{ref}

OAuth scopes

projects:write

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

1
2
3
4
5
{  "id": 42,  "ref": "lorem",  "name": "lorem"}

[Beta] Remove network bans.

delete/v1/projects/{ref}/network-bans

OAuth scopes

projects:write

Path parameters

ref
Required
string
Project ref

Body

ipv4_addresses
Required
Array<string>
requester_ip
Optional
boolean
identifier
Optional
string

Response codes

Response (200)

1
{}

Gets all projects for the given organization

get/v1/organizations/{slug}/projects

Returns a paginated list of projects for the specified organization.

This endpoint uses offset-based pagination. Use the `offset` parameter to skip a number of projects and the `limit` parameter to control the number of projects returned per page.

Path parameters

slug
Required
string
Organization slug

Query parameters

offset
Optional
integer
Number of projects to skip
limit
Optional
integer
Number of projects to return per page
search
Optional
string
Search projects by name
sort
Optional
enum
Sort order for projects
statuses
Optional
string
A comma-separated list of project statuses to filter by.

The following values are supported: ACTIVE_HEALTHY, INACTIVE.

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{  "projects": [    {      "ref": "lorem",      "name": "lorem",      "cloud_provider": "lorem",      "region": "lorem",      "is_branch": true,      "status": "INACTIVE",      "inserted_at": "lorem",      "databases": [        {          "infra_compute_size": "pico",          "region": "lorem",          "status": "ACTIVE_HEALTHY",          "cloud_provider": "lorem",          "identifier": "lorem",          "type": "PRIMARY",          "disk_volume_size_gb": 42,          "disk_type": "gp3",          "disk_throughput_mbps": 42,          "disk_last_modified_at": "lorem"        }      ]    }  ],  "pagination": {    "count": 42,    "limit": 42,    "offset": 42  }}

[Beta] Gets the list of available regions that can be used for a new project

get/v1/projects/available-regions

Query parameters

organization_slug
Required
string
Slug of your organization
continent
Optional
enum
Continent code to determine regional recommendations: NA (North America), SA (South America), EU (Europe), AF (Africa), AS (Asia), OC (Oceania), AN (Antarctica)
desired_instance_size
Optional
enum
Desired instance size

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{  "recommendations": {    "smartGroup": {      "name": "lorem",      "code": "americas",      "type": "smartGroup"    },    "specific": [      {        "name": "lorem",        "code": "lorem",        "type": "specific",        "provider": "AWS",        "status": "capacity"      }    ]  },  "all": {    "smartGroup": [      {        "name": "lorem",        "code": "americas",        "type": "smartGroup"      }    ],    "specific": [      {        "name": "lorem",        "code": "lorem",        "type": "specific",        "provider": "AWS",        "status": "capacity"      }    ]  }}

[Beta] Gets project's network restrictions

get/v1/projects/{ref}/network-restrictions

OAuth scopes

projects:read

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{  "entitlement": "disallowed",  "config": {    "dbAllowedCidrs": [      "lorem"    ],    "dbAllowedCidrsV6": [      "lorem"    ]  },  "old_config": {    "dbAllowedCidrs": [      "lorem"    ],    "dbAllowedCidrsV6": [      "lorem"    ]  },  "status": "stored",  "updated_at": "2021-12-31T23:34:00Z",  "applied_at": "2021-12-31T23:34:00Z"}

[Beta] Returns the project's eligibility for upgrades

get/v1/projects/{ref}/upgrade/eligibility

OAuth scopes

projects:read

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{  "eligible": true,  "current_app_version": "lorem",  "current_app_version_release_channel": "internal",  "latest_app_version": "lorem",  "target_upgrade_versions": [    {      "postgres_version": "13",      "release_channel": "internal",      "app_version": "lorem"    }  ],  "duration_estimate_hours": 42,  "legacy_auth_custom_roles": [    "lorem"  ],  "objects_to_be_dropped": [    "lorem"  ],  "unsupported_extensions": [    "lorem"  ],  "user_defined_objects_in_internal_schemas": [    "lorem"  ]}

[Beta] Gets the latest status of the project's upgrade

get/v1/projects/{ref}/upgrade/status

OAuth scopes

projects:read

Path parameters

ref
Required
string
Project ref

Query parameters

tracking_id
Optional
string

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
10
{  "databaseUpgradeStatus": {    "initiated_at": "lorem",    "latest_status_at": "lorem",    "target_version": 42,    "error": "1_upgraded_instance_launch_failed",    "progress": "0_requested",    "status": 42  }}

Gets a specific project that belongs to the authenticated user

get/v1/projects/{ref}

OAuth scopes

projects:read

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{  "id": "lorem",  "ref": "mmmmmmmmmmmmmmmmmmmm",  "organization_id": "lorem",  "organization_slug": "EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE",  "name": "lorem",  "region": "us-east-1",  "created_at": "2023-03-29T16:32:59Z",  "status": "INACTIVE",  "database": {    "host": "lorem",    "version": "lorem",    "postgres_engine": "lorem",    "release_channel": "lorem"  }}

Gets project's service health status

get/v1/projects/{ref}/health

OAuth scopes

projects:read

Path parameters

ref
Required
string
Project ref

Query parameters

services
Required
Array<enum>
timeout_ms
Optional
integer

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
10
11
12
13
[  {    "name": "auth",    "healthy": true,    "status": "COMING_UP",    "info": {      "name": "GoTrue",      "version": "lorem",      "description": "lorem"    },    "error": "lorem"  }]

[Beta] Gets project's network bans

post/v1/projects/{ref}/network-bans/retrieve

OAuth scopes

projects:read

Path parameters

ref
Required
string
Project ref

Response codes

Response (201)

1
2
3
4
5
{  "banned_ipv4_addresses": [    "lorem"  ]}

[Beta] Gets project's network bans with additional information about which databases they affect

post/v1/projects/{ref}/network-bans/retrieve/enriched

OAuth scopes

projects:read

Path parameters

ref
Required
string
Project ref

Response codes

Response (201)

1
2
3
4
5
6
7
8
9
{  "banned_ipv4_addresses": [    {      "banned_address": "lorem",      "identifier": "lorem",      "type": "lorem"    }  ]}

List all projects

get/v1/projects

Returns a list of all projects you've previously created.

OAuth scopes

projects:read

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
[  {    "id": "lorem",    "ref": "mmmmmmmmmmmmmmmmmmmm",    "organization_id": "lorem",    "organization_slug": "EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE",    "name": "lorem",    "region": "us-east-1",    "created_at": "2023-03-29T16:32:59Z",    "status": "INACTIVE",    "database": {      "host": "lorem",      "version": "lorem",      "postgres_engine": "lorem",      "release_channel": "lorem"    }  }]

Lists available restore versions for the given project

get/v1/projects/{ref}/restore

OAuth scopes

projects:read

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
{  "available_versions": [    {      "version": "lorem",      "release_channel": "internal",      "postgres_engine": "13"    }  ]}

[Alpha] Updates project's network restrictions by adding or removing CIDRs

patch/v1/projects/{ref}/network-restrictions

OAuth scopes

projects:write

Path parameters

ref
Required
string
Project ref

Body

add
Optional
object
remove
Optional
object

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{  "entitlement": "disallowed",  "config": {    "dbAllowedCidrs": [      {        "address": "lorem",        "type": "v4"      }    ]  },  "old_config": {    "dbAllowedCidrs": [      {        "address": "lorem",        "type": "v4"      }    ]  },  "updated_at": "2021-12-31T23:34:00Z",  "applied_at": "2021-12-31T23:34:00Z",  "status": "stored"}

Pauses the given project

post/v1/projects/{ref}/pause

OAuth scopes

projects:write

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

1
{}

Restores the given project

post/v1/projects/{ref}/restore

OAuth scopes

projects:write

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

1
{}

Updates the given project

patch/v1/projects/{ref}

OAuth scopes

projects:write

Path parameters

ref
Required
string
Project ref

Body

name
Required
string

Response codes

Response (200)

1
2
3
4
5
{  "id": 42,  "ref": "lorem",  "name": "lorem"}

[Beta] Updates project's network restrictions

post/v1/projects/{ref}/network-restrictions/apply

OAuth scopes

projects:write

Path parameters

ref
Required
string
Project ref

Body

dbAllowedCidrs
Optional
Array<string>
dbAllowedCidrsV6
Optional
Array<string>

Response codes

Response (201)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{  "entitlement": "disallowed",  "config": {    "dbAllowedCidrs": [      "lorem"    ],    "dbAllowedCidrsV6": [      "lorem"    ]  },  "old_config": {    "dbAllowedCidrs": [      "lorem"    ],    "dbAllowedCidrsV6": [      "lorem"    ]  },  "status": "stored",  "updated_at": "2021-12-31T23:34:00Z",  "applied_at": "2021-12-31T23:34:00Z"}

[Beta] Upgrades the project's Postgres version

post/v1/projects/{ref}/upgrade

OAuth scopes

projects:write

Path parameters

ref
Required
string
Project ref

Body

target_version
Required
string
release_channel
Optional
enum

Response codes

Response (201)

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

Gets realtime configuration

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

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
10
11
12
{  "private_only": true,  "connection_pool": 1,  "max_concurrent_users": 1,  "max_events_per_second": 1,  "max_bytes_per_second": 1,  "max_channels_per_client": 1,  "max_joins_per_second": 1,  "max_presence_events_per_second": 1,  "max_payload_size_in_kb": 1,  "suspend": true}

Updates realtime configuration

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

Path parameters

ref
Required
string
Project ref

Body

private_only
Optional
boolean
connection_pool
Optional
integer
max_concurrent_users
Optional
integer
max_events_per_second
Optional
integer
max_bytes_per_second
Optional
integer
max_channels_per_client
Optional
integer
max_joins_per_second
Optional
integer
max_presence_events_per_second
Optional
integer
max_payload_size_in_kb
Optional
integer
suspend
Optional
boolean

Response codes

Response (204)

1
{}

Gets project's postgrest config

get/v1/projects/{ref}/postgrest

OAuth scopes

rest:read

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

1
2
3
4
5
6
7
{  "db_schema": "lorem",  "max_rows": 42,  "db_extra_search_path": "lorem",  "db_pool": 42,  "jwt_secret": "lorem"}

Updates project's postgrest config

patch/v1/projects/{ref}/postgrest

OAuth scopes

rest:write

Path parameters

ref
Required
string
Project ref

Body

db_extra_search_path
Optional
string
db_schema
Optional
string
max_rows
Optional
integer
db_pool
Optional
integer

Response codes

Response (200)

1
2
3
4
5
6
{  "db_schema": "lorem",  "max_rows": 42,  "db_extra_search_path": "lorem",  "db_pool": 42}

Bulk create secrets

post/v1/projects/{ref}/secrets

Creates multiple secrets and adds them to the specified project.

OAuth scopes

secrets:write

Path parameters

ref
Required
string
Project ref

Body

Array of object

Response codes

Response (201)

1
{}

Bulk delete secrets

delete/v1/projects/{ref}/secrets

Deletes all secrets with the given names from the specified project

OAuth scopes

secrets:write

Path parameters

ref
Required
string
Project ref

Body

Array of string

Response codes

Response (200)

1
{}

Creates a new API key for the project

post/v1/projects/{ref}/api-keys

OAuth scopes

secrets:write

Path parameters

ref
Required
string
Project ref

Query parameters

reveal
Optional
boolean
Boolean string, true or false

Body

type
Required
enum
name
Required
string
description
Optional
string
secret_jwt_template
Optional
object

Response codes

Response (201)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{  "api_key": "lorem",  "id": "lorem",  "type": "legacy",  "prefix": "lorem",  "name": "lorem",  "description": "lorem",  "hash": "lorem",  "secret_jwt_template": {    "property1": null,    "property2": null  },  "inserted_at": "2021-12-31T23:34:00Z",  "updated_at": "2021-12-31T23:34:00Z"}

Deletes an API key for the project

delete/v1/projects/{ref}/api-keys/{id}

OAuth scopes

secrets:write

Path parameters

ref
Required
string
Project ref
id
Required
string

Query parameters

reveal
Optional
boolean
Boolean string, true or false
was_compromised
Optional
boolean
Boolean string, true or false
reason
Optional
string

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{  "api_key": "lorem",  "id": "lorem",  "type": "legacy",  "prefix": "lorem",  "name": "lorem",  "description": "lorem",  "hash": "lorem",  "secret_jwt_template": {    "property1": null,    "property2": null  },  "inserted_at": "2021-12-31T23:34:00Z",  "updated_at": "2021-12-31T23:34:00Z"}

[Beta] Gets project's pgsodium config

get/v1/projects/{ref}/pgsodium

OAuth scopes

secrets:read

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

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

Get API key

get/v1/projects/{ref}/api-keys/{id}

OAuth scopes

secrets:read

Path parameters

ref
Required
string
Project ref
id
Required
string

Query parameters

reveal
Optional
boolean
Boolean string, true or false

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{  "api_key": "lorem",  "id": "lorem",  "type": "legacy",  "prefix": "lorem",  "name": "lorem",  "description": "lorem",  "hash": "lorem",  "secret_jwt_template": {    "property1": null,    "property2": null  },  "inserted_at": "2021-12-31T23:34:00Z",  "updated_at": "2021-12-31T23:34:00Z"}

Get project api keys

get/v1/projects/{ref}/api-keys

OAuth scopes

secrets:read

Path parameters

ref
Required
string
Project ref

Query parameters

reveal
Optional
boolean
Boolean string, true or false

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
[  {    "api_key": "lorem",    "id": "lorem",    "type": "legacy",    "prefix": "lorem",    "name": "lorem",    "description": "lorem",    "hash": "lorem",    "secret_jwt_template": {      "property1": null,      "property2": null    },    "inserted_at": "2021-12-31T23:34:00Z",    "updated_at": "2021-12-31T23:34:00Z"  }]

Check whether JWT based legacy (anon, service_role) API keys are enabled. This API endpoint will be removed in the future, check for HTTP 404 Not Found.

get/v1/projects/{ref}/api-keys/legacy

OAuth scopes

secrets:read

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

1
2
3
{  "enabled": true}

List all secrets

get/v1/projects/{ref}/secrets

Returns all secrets you've previously added to the specified project.

OAuth scopes

secrets:read

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

1
2
3
4
5
6
7
[  {    "name": "lorem",    "value": "lorem",    "updated_at": "lorem"  }]

[Beta] Updates project's pgsodium config. Updating the root_key can cause all data encrypted with the older key to become inaccessible.

put/v1/projects/{ref}/pgsodium

OAuth scopes

secrets:write

Path parameters

ref
Required
string
Project ref

Body

root_key
Required
string

Response codes

Response (200)

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

Updates an API key for the project

patch/v1/projects/{ref}/api-keys/{id}

OAuth scopes

secrets:write

Path parameters

ref
Required
string
Project ref
id
Required
string

Query parameters

reveal
Optional
boolean
Boolean string, true or false

Body

name
Optional
string
description
Optional
string
secret_jwt_template
Optional
object

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{  "api_key": "lorem",  "id": "lorem",  "type": "legacy",  "prefix": "lorem",  "name": "lorem",  "description": "lorem",  "hash": "lorem",  "secret_jwt_template": {    "property1": null,    "property2": null  },  "inserted_at": "2021-12-31T23:34:00Z",  "updated_at": "2021-12-31T23:34:00Z"}

Disable or re-enable JWT based legacy (anon, service_role) API keys. This API endpoint will be removed in the future, check for HTTP 404 Not Found.

put/v1/projects/{ref}/api-keys/legacy

OAuth scopes

secrets:write

Path parameters

ref
Required
string
Project ref

Query parameters

enabled
Required
boolean
Boolean string, true or false

Response codes

Response (200)

1
2
3
{  "enabled": true}

Gets project's storage config

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

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{  "fileSizeLimit": 42,  "features": {    "imageTransformation": {      "enabled": true    },    "s3Protocol": {      "enabled": true    },    "icebergCatalog": {      "enabled": true,      "maxNamespaces": 0,      "maxTables": 0,      "maxCatalogs": 0    },    "vectorBuckets": {      "enabled": true,      "maxBuckets": 0,      "maxIndexes": 0    }  },  "capabilities": {    "list_v2": true,    "iceberg_catalog": true  },  "external": {    "upstreamTarget": "main"  },  "migrationVersion": "lorem",  "databasePoolMode": "lorem"}

Lists all buckets

get/v1/projects/{ref}/storage/buckets

OAuth scopes

storage:read

Path parameters

ref
Required
string
Project ref

Response codes

Response (200)

1
2
3
4
5
6
7
8
9
10
[  {    "id": "lorem",    "name": "lorem",    "owner": "lorem",    "created_at": "lorem",    "updated_at": "lorem",    "public": true  }]

Updates project's storage config

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

Path parameters

ref
Required
string
Project ref

Body

fileSizeLimit
Optional
integer
features
Optional
object
external
Optional
object

Response codes

Response (200)

1
{}

Management API

Authentication#

Rate limits#

Standard rate limit#

Rate limit scope#

Rate limit response headers#

How rate limits are tracked#

Endpoint exceptions#

Best practices#

Gets project performance advisors.deprecated

OAuth scopes

Path parameters

Response codes

Response (200)

Gets project security advisors.deprecated

OAuth scopes

Path parameters

Query parameters

Response codes

Response (200)

Gets a project's function combined statistics

Path parameters

Query parameters

Response codes

Response (200)

Gets project's logs

OAuth scopes

Path parameters

Query parameters

Response codes

Response (200)

Gets project's usage api counts

Path parameters

Query parameters

Response codes

Response (200)

Gets project's usage api requests count

Path parameters

Response codes

Response (200)

Creates a new SSO provider

OAuth scopes

Path parameters

Body

Response codes

Response (201)

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.

OAuth scopes

Path parameters

Response codes

Response (201)

Create a new signing key for the project in standby status

OAuth scopes

Path parameters

Body

Response codes

Response (201)

Creates a new third-party auth integration

OAuth scopes

Path parameters

Body

Response codes

Response (201)

Removes a SSO provider by its UUID

OAuth scopes

Path parameters

Response codes

Response (200)

Removes a third-party auth integration

OAuth scopes

Path parameters

Response codes

Response (200)

Gets a SSO provider by its UUID

OAuth scopes

Path parameters

Response codes

Response (200)

Gets project's auth config

OAuth scopes

Authentication

Rate limits

Standard rate limit

Rate limit scope

Rate limit response headers

How rate limits are tracked

Endpoint exceptions

Best practices

Gets project performance advisors.
deprecated

Gets project security advisors.
deprecated