dima/supabase
1
0 Fork 0
mirror of https://github.com/supabase/supabase.git synced 2026-10-13 05:09:12 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs: update apps/docs/spec/supabase_py_v2.yml based on supabase/supabase-py#1222

Browse Source
This commit is contained in:
Guilherme Souza committed 2025-09-30 14:56:09 -03:00
1 parent d13a47b8e9
commit 9d6cc130ce
1 file changed
+759 -2
Download Patch File Download Diff File Expand all files Collapse all files
apps/docs/spec/supabase_py_v2.yml
+759 -2
View File
@@ -1,4 +1,3 @@
```markdown
openref: 0.1
info:
@@ -767,4 +766,762 @@ functions:
isOptional: true
type: string
description: |
If the ID token contains an `at_hash
If the ID token contains an `at_hash` claim, then the hash of this value is compared to the value in the ID token.
notes: |
Allows signing in with an OIDC ID token. The authentication provider used should be enabled and configured.
examples:
- id: sign-in-with-id-token
name: 'Sign In using ID Token'
code: |
```python
response = supabase.auth.sign_in_with_id_token(
{
"provider": "google",
"token": "your-id-token",
}
)
```
response: |
```json
{
"session": {
"access_token": "<ACCESS_TOKEN>",
"expires_at": 1721236789,
"expires_in": 60,
"provider_refresh_token": null,
"provider_token": null,
"refresh_token": "<REFRESH_TOKEN>",
"token_type": "bearer",
"user": {
"action_link": null,
"app_metadata": {
...
},
"aud": "authenticated",
"confirmation_sent_at": null,
"confirmed_at": "Wed, 17 Jul 2024 16:34:24 GMT",
"created_at": "Wed, 17 Jul 2024 16:34:24 GMT",
"email": "email@example.com",
"email_change_sent_at": null,
"email_confirmed_at": "Wed, 17 Jul 2024 16:34:24 GMT",
"factors": null,
"id": "11111111-1111-1111-1111-111111111111",
"identities": [
{
"identity_id": "22222222-2222-2222-2222-222222222222",
"provider": "google",
"user_id": "11111111-1111-1111-1111-111111111111"
}
],
"invited_at": null,
"last_sign_in_at": "Wed, 17 Jul 2024 17:18:49 GMT",
"new_email": null,
"phone": "",
"phone_confirmed_at": null,
"recovery_sent_at": null,
"role": "authenticated",
"updated_at": "Wed, 17 Jul 2024 17:18:49 GMT",
"user_metadata": {
...
}
}
},
"user": {
"action_link": null,
"app_metadata": {
...
},
"aud": "authenticated",
"confirmation_sent_at": null,
"confirmed_at": "Wed, 17 Jul 2024 16:34:24 GMT",
"created_at": "Wed, 17 Jul 2024 16:34:24 GMT",
"email": "email@example.com",
"email_change_sent_at": null,
"email_confirmed_at": "Wed, 17 Jul 2024 16:34:24 GMT",
"factors": null,
"id": "11111111-1111-1111-1111-111111111111",
"identities": [
{
"identity_id": "22222222-2222-2222-2222-222222222222",
"provider": "google",
"user_id": "11111111-1111-1111-1111-111111111111"
}
],
"invited_at": null,
"last_sign_in_at": "Wed, 17 Jul 2024 17:18:49 GMT",
"new_email": null,
"phone": "",
"phone_confirmed_at": null,
"recovery_sent_at": null,
"role": "authenticated",
"updated_at": "Wed, 17 Jul 2024 17:18:49 GMT",
"user_metadata": {
...
}
}
}
```
- id: sign-in-with-sso
title: 'sign_in_with_sso()'
overwriteParams:
- name: params
type: SignInWithSSOCredentials
subContent:
- name: provider_id
isOptional: true
type: string
description: >
UUID of the SSO provider.
One of `provider_id` or `domain` is required.
- name: domain
isOptional: true
type: string
description: >
Domain name of the organization to use SSO with.
One of `provider_id` or `domain` is required.
- name: options
isOptional: true
type: object
subContent:
- name: redirect_to
type: string
description: >
The URL to redirect the user to after they have signed in.
Must be a configured redirect URL for your Supabase instance.
- name: captcha_token
type: string
notes: |
- Before you can call this method you need to [establish a connection](/docs/guides/auth/sso/auth-sso-saml#managing-saml-20-connections) to an identity provider. Use the [CLI commands](/docs/reference/cli/supabase-sso) to do this.
- If you've associated an email domain to the identity provider, you can use the `domain` property to start a sign-in flow.
- In case you need to use a different way to start the authentication flow with an identity provider, you can use the `provider_id` property. For example:
- Mapping specific user email addresses with an identity provider.
- Using different hints to identity the identity provider to be used by the user, like a company-specific page, IP address or other tracking information.
examples:
- id: sign-in-with-domain
name: Sign in with email domain
isSpotlight: true
description: |
You can extract the user's email domain and use it to trigger the authentication flow with the correct identity provider.
code: |
```python
response = supabase.auth.sign_in_with_sso(
{"domain": "company.com"}
)
```
response: |
```json
{
"url": ""
}
```
- id: sign-in-with-provider-uuid
name: Sign in with provider UUID
isSpotlight: true
description: |
Useful when you need to map a user's sign in request according to different rules that can't use email domains.
code: |
```python
response = supabase.auth.sign_in_with_sso(
{"provider_id": "21648a9d-8d5a-4555-a9d1-d6375dc14e92"}
)
```
- id: get-claims
title: 'get_claims'
params:
- name: jwt
isOptional: true
type: string
description: An optional specific JWT you wish to verify, not the one you can obtain from [`get_session`](/docs/reference/python/auth-getsession).
- name: jwks
isOptional: true
type: JWKSet
description: If set, this JSON Web Key Set is going to have precedence over the cached value available on the server.
subContent:
- name: keys
isOptional: false
type: list<JWK>
subContent:
- name: key_opt
isOptional: false
type: list[string]
- name: kty
isOptional: false
type: RSA | EC | oct
- name: alg
isOptional: false
type: string
- name: kid
isOptional: false
type: string
notes: |
Extracts the JWT claims present in the access token by first verifying the JWT against the server's JSON Web Key Set endpoint /.well-known/jwks.json which is often cached, resulting in significantly faster responses. Prefer this method over [`get_user`](/docs/reference/python/auth-getuser) which always sends a request to the Auth server for each JWT.
examples:
- id: get-user-object
name: Get user object
isSpotlight: true
code: |
```
response = supabase.auth.get_claims()
```
response: |
```json
{
"claims": {
"aal": "aal1",
"amr": [{
"method": "email",
"timestamp": 1715766000
}],
"app_metadata": {},
"aud": "authenticated",
"email": "example@email.com",
"exp": 1715769600,
"iat": 1715766000,
"is_anonymous": false,
"iss": "https://api.supabase.com/auth/v1",
"phone": "+13334445555",
"role": "authenticated",
"session_id": "11111111-1111-1111-1111-111111111111",
"sub": "11111111-1111-1111-1111-111111111111",
"user_metadata": {}
},
"header": {
"alg": "RS256",
"typ": "JWT",
"kid": "abcdefgh"
},
"signature": [/** Uint8Array */],
}
```
- id: sign-out
title: 'sign_out()'
params:
- name: options
isOptional: true
type: SignOutOptions
subContent:
- name: scope
isOptional: true
type: '"global" | "local" | "others"'
description: |
Determines which sessions should be logged out. Global means all sessions by this account. Local means only this session. Others means all other sessions except the current one. When using others, there is no sign-out event fired on the current session!
notes: |
- In order to use the `sign_out()` method, the user needs to be signed in first.
- By default, `sign_out()` uses the global scope, which signs out all other sessions that the user is logged into as well.
- Since Supabase Auth uses JWTs for authentication, the access token JWT will be valid until it's expired. When the user signs out, Supabase revokes the refresh token and deletes the JWT from the client-side. This does not revoke the JWT and it will still be valid until it expires.
examples:
- id: sign-out
name: Sign out
code: |
```python
response = supabase.auth.sign_out()
```
- id: verify-otp
title: 'verify_otp'
params:
- name: params
type: VerifyOtpParams
subContent:
- name: phone
isOptional: true
type: string
description: One of `phone`, `email`, or `token_hash` must be provided.
- name: email
isOptional: true
type: string
description: One of `phone`, `email`, or `token_hash` must be provided.
- name: token_hash
isOptional: true
type: string
description: >
The token hash from the user's email link.
One of `phone`, `email`, or `token_hash` must be provided.
- name: type
type: sms | phone_change | signup | invite | magiclink | recovery | email_change | email
- name: token
isOptional: true
type: string
description: The OTP sent to the user. Required if using `phone` or `email`.
- name: options
isOptional: true
type: object
subContent:
- name: redirect_to
isOptional: true
type: string
description: >
A URL to redirect the user to after they are confirmed.
Must be in your configured redirect URLs.
- name: captcha_token
isOptional: true
type: string
description: Deprecated.
notes: |
- The `verify_otp` method takes in different verification types. If a phone number is used, the type can either be `sms` or `phone_change`. If an email address is used, the type can be one of the following: `email`, `recovery`, `invite` or `email_change` (`signup` and `magiclink` types are deprecated).
- The verification type used should be determined based on the corresponding auth method called before `verify_otp` to sign up / sign-in a user.
- The `TokenHash` is contained in the [email templates](/docs/guides/auth/auth-email-templates) and can be used to sign in. You may wish to use the hash with Magic Links for the PKCE flow for Server Side Auth. See [this guide](/docs/guides/auth/server-side/email-based-auth-with-pkce-flow-for-ssr) for more details.
examples:
- id: verify-signup-one-time-password(otp)
name: Verify Signup One-Time Password (OTP)
isSpotlight: false
code: |
```python
response = supabase.auth.verify_otp(
{
"email": "email@example.com",
"token": "123456",
"type": "email",
}
)
```
response: |
```json
{
"user": {
"id": "11111111-1111-1111-1111-111111111111",
"app_metadata": {
"provider": "email",
"providers": []
},
"user_metadata": {},
"aud": "authenticated",
"confirmation_sent_at": "2023-02-19T00:01:51.147035Z",
"recovery_sent_at": "2024-07-21T22:20:00.366959Z",
"email_change_sent_at": null,
"new_email": null,
"invited_at": null,
"action_link": null,
"email": "email@example.com",
"phone": "",
"created_at": "2023-02-19T00:01:51.142802Z",
"confirmed_at": "2023-02-19T00:01:51.351735Z",
"email_confirmed_at": "2023-02-19T00:01:51.351735Z",
"phone_confirmed_at": null,
"last_sign_in_at": "2024-07-21T22:21:35.199451Z",
"role": "authenticated",
"updated_at": "2024-07-21T22:21:35.206985Z",
"identities": [],
"factors": null,
"is_anonymous": false
},
"session": {
"provider_token": null,
"provider_refresh_token": null,
"access_token": "<ACCESS_TOKEN>",
"refresh_token": "<REFRESH_TOKEN>",
"expires_in": 3600,
"expires_at": 1700000000,
"token_type": "bearer",
"user": {
"id": "11111111-1111-1111-1111-111111111111",
"app_metadata": {
"provider": "email",
"providers": []
},
"user_metadata": {},
"aud": "authenticated",
"confirmation_sent_at": "2023-02-19T00:01:51.147035Z",
"recovery_sent_at": "2024-07-21T22:20:00.366959Z",
"email_change_sent_at": null,
"new_email": null,
"invited_at": null,
"action_link": null,
"email": "email@example.com",
"phone": "",
"created_at": "2023-02-19T00:01:51.142802Z",
"confirmed_at": "2023-02-19T00:01:51.351735Z",
"email_confirmed_at": "2023-02-19T00:01:51.351735Z",
"phone_confirmed_at": null,
"last_sign_in_at": "2024-07-21T22:21:35.199451Z",
"role": "authenticated",
"updated_at": "2024-07-21T22:21:35.206985Z",
"identities": [],
"factors": null,
"is_anonymous": false
}
}
}
```
- id: verify-sms-one-time-password
name: Verify SMS One-Time Password (OTP)
isSpotlight: true
code: |
```python
response = supabase.auth.verify_otp(
{
"phone": "+13334445555",
"token": "123456",
"type": "sms",
}
)
```
- id: verify-email-auth(tokenhash)
name: Verify Email Auth (Token Hash)
isSpotlight: false
code: |
```python
response = supabase.auth.verify_otp(
{
"email": "email@example.com",
"token_hash": "<token-hash>",
"type": "email",
}
)
```
- id: get-session
title: 'get_session'
notes: |
- This method retrieves the current local session (i.e in memory).
- The session contains a signed JWT and unencoded session data.
- Since the unencoded session data is retrieved from the local storage medium, **do not** rely on it as a source of trusted data on the server. It could be tampered with by the sender. If you need verified, trustworthy user data, call [`get_user`](/docs/reference/python/auth-getuser) instead.
- If the session has an expired access token, this method will use the refresh token to get a new session.
examples:
- id: get-the-session-data
name: Get the session data
isSpotlight: true
code: |
```python
response = supabase.auth.get_session()
```
response: |
```json
{
"provider_token": null,
"provider_refresh_token": null,
"access_token": "<ACCESS_TOKEN>",
"refresh_token": "<REFRESH_TOKEN>",
"expires_in": 3600,
"expires_at": 1700000000,
"token_type": "bearer",
"user": {
"id": "11111111-1111-1111-1111-111111111111",
"app_metadata": {
"provider": "email",
"providers": []
},
"user_metadata": {},
"aud": "authenticated",
"confirmation_sent_at": "2023-02-19T00:01:51.147035Z",
"recovery_sent_at": "2024-07-21T22:20:00.366959Z",
"email_change_sent_at": null,
"new_email": null,
"invited_at": null,
"action_link": null,
"email": "email@example.com",
"phone": "",
"created_at": "2023-02-19T00:01:51.142802Z",
"confirmed_at": "2023-02-19T00:01:51.351735Z",
"email_confirmed_at": "2023-02-19T00:01:51.351735Z",
"phone_confirmed_at": null,
"last_sign_in_at": "2024-07-21T22:36:45.194120Z",
"role": "authenticated",
"updated_at": "2024-07-21T22:36:45.196044Z",
"identities": [],
"factors": null,
"is_anonymous": false
}
}
```
- id: get-user
title: 'get_user'
params:
- name: jwt
isOptional: true
type: string
description: Takes in an optional access token JWT. If no JWT is provided, the JWT from the current session is used.
notes: |
- This method fetches the user object from the database instead of local session.
- This method is useful for checking if the user is authorized because it validates the user's access token JWT on the server.
examples:
- id: get-the-logged-in-user-with-the-current-existing-session
name: Get the logged in user with the current existing session
isSpotlight: true
code: |
```
response = supabase.auth.get_user()
```
response: |
```json
{
"user": {
"id": "11111111-1111-1111-1111-111111111111",
"app_metadata": {
"provider": "email",
"providers": []
},
"user_metadata": {},
"aud": "authenticated",
"confirmation_sent_at": "2023-02-19T00:01:51.147035Z",
"recovery_sent_at": "2024-07-21T22:20:00.366959Z",
"email_change_sent_at": null,
"new_email": null,
"new_phone": null,
"invited_at": null,
"action_link": null,
"email": "email@example.com",
"phone": "",
"created_at": "2023-02-19T00:01:51.142802Z",
"confirmed_at": "2023-02-19T00:01:51.351735Z",
"email_confirmed_at": "2023-02-19T00:01:51.351735Z",
"phone_confirmed_at": null,
"last_sign_in_at": "2024-07-24T22:24:57.642878Z",
"role": "authenticated",
"updated_at": "2024-07-24T22:24:57.650021Z",
"identities": [],
"is_anonymous": false,
"factors": null
}
}
```
- id: get-the-logged-in-user-with-a-custom-access-token-jwt
name: Get the logged in user with a custom access token jwt
isSpotlight: false
code: |
```
response = supabase.auth.get_user(jwt)
```
- id: update-user
title: 'update_user()'
notes: |
- In order to use the `update_user()` method, the user needs to be signed in first.
- By default, email updates sends a confirmation link to both the user's current and new email.
To only send a confirmation link to the user's new email, disable **Secure email change** in your project's [email auth provider settings](/dashboard/project/_/settings/auth).
params:
- name: attributes
isOptional: false
type: UserAttributes
subContent:
- name: data
isOptional: true
type: object
description: A custom data object to store the user's metadata. This maps to the `auth.users.raw_user_meta_data` column.
- name: email
isOptional: true
type: string
description: The user's email.
- name: nonce
isOptional: true
type: string
description: The nonce sent for reauthentication if the user's password is to be updated.
- name: password
isOptional: true
type: string
description: The user's password.
- name: phone
isOptional: true
type: string
description: The user's phone.
- name: options
isOptional: true
type: object
subContent:
- name: email_redirect_to
isOptional: true
type: string
examples:
- id: update-the-email-for-an-authenticated-user
name: Update the email for an authenticated user
description: Sends a "Confirm Email Change" email to the new email address.
isSpotlight: false
code: |
```python
response = supabase.auth.update_user(
{"email": "new@email.com"}
)
```
response: |
```json
{
"user": {
"id": "11111111-1111-1111-1111-111111111111",
"aud": "authenticated",
"role": "authenticated",
"email": "example@email.com",
"email_confirmed_at": "2024-01-01T00:00:00Z",
"phone": "",
"confirmed_at": "2024-01-01T00:00:00Z",
"new_email": "new@email.com",
"email_change_sent_at": "2024-01-01T00:00:00Z",
"last_sign_in_at": "2024-01-01T00:00:00Z",
"app_metadata": {
"provider": "email",
"providers": [
"email"
]
},
"user_metadata": {
"email": "example@email.com",
"email_verified": false,
"phone_verified": false,
"sub": "11111111-1111-1111-1111-111111111111"
},
"identities": [
{
"identity_id": "22222222-2222-2222-2222-222222222222",
"id": "11111111-1111-1111-1111-111111111111",
"user_id": "11111111-1111-1111-1111-111111111111",
"identity_data": {
"email": "example@email.com",
"email_verified": false,
"phone_verified": false,
"sub": "11111111-1111-1111-1111-111111111111"
},
"provider": "email",
"last_sign_in_at": "2024-01-01T00:00:00Z",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"email": "example@email.com"
}
],
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"is_anonymous": false
}
}
```
- id: update-the-phone-for-an-authenticated-user
name: Update the phone number for an authenticated user
description: Sends a one-time password (OTP) to the new phone number.
isSpotlight: false
code: |
```python
response = supabase.auth.update_user(
{"phone": "123456789"}
)
```
- id: update-the-password-for-an-authenticated-user
name: Update the password for an authenticated user
isSpotlight: false
code: |
```python
response = supabase.auth.update_user(
{"password": "new password"}
)
```
- id: update-the-users-metadata
name: Update the user's metadata
isSpotlight: true
code: |
```python
response = supabase.auth.update_user(
{
"data": {"hello": "world"},
}
)
```
- id: update-password-with-reauthentication
name: Update the user's password with a nonce
description: |
If **Secure password change** is enabled in your [project's email provider settings](/dashboard/project/_/auth/providers), updating the user's password would require a nonce if the user **hasn't recently signed in**. The nonce is sent to the user's email or phone number. A user is deemed recently signed in if the session was created in the last 24 hours.
isSpotlight: true
code: |
```python
response = supabase.auth.update_user(
{
"password": "new password",
"nonce": "123456",
}
)
```
- id: get-user-identities
title: 'get_user_identities()'
notes: |
Gets all the identities linked to a user.
- The user needs to be signed in to call `get_user_identities()`.
examples:
- id: get-user-identities
name: Returns a list of identities linked to the user
isSpotlight: true
code: |
```python
response = supabase.auth.get_user_identities()
```
response: |
```json
{
"identities": [
{
"identity_id": "22222222-2222-2222-2222-222222222222",
"id": "2024-01-01T00:00:00Z",
"user_id": "2024-01-01T00:00:00Z",
"identity_data": {
"email": "example@email.com",
"email_verified": false,
"phone_verified": false,
"sub": "11111111-1111-1111-1111-111111111111"
},
"provider": "email",
"last_sign_in_at": "2024-01-01T00:00:00Z",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"email": "example@email.com"
}
]
}
```
- id: link-identity
title: 'link_identity()'
params:
- name: credentials
isOptional: false
type: SignInWithOAuthCredentials
subContent:
- name: provider
isOptional: false
type: boolean
description: One of the providers supported by GoTrue.
- name: options
isOptional: true
type: object
subContent:
- name: scopes
isOptional: true
type: string
description: A space-separated list of scopes granted to the OAuth application.
- name: redirect_to
isOptional: true
type: string
description: A URL to send the user to after they are confirmed.
- name: query_params
isOptional: true
type: string
description: An object of query params
notes: |
- The **Enable Manual Linking** option must be enabled from your [project's authentication settings](/dashboard/project/_/settings/auth).
- The user needs to be signed in to call `link_identity()`.
- If the candidate identity is already linked to the existing user or another user, `link_identity()` will fail.
- If `link_identity` is run on the server, you should handle the redirect.
examples:
- id: link-identity
name: Link an identity to a user
isSpotlight: true
code: |
```python
response = supabase.auth.link_identity(
{provider: "github"}
)
```
response: |
```json
{
"provider": "github",
"url": "<PROVIDER_URL_TO_REDIRECT_TO>"
}
```
- id: unlink-identity
title: 'unlink_identity()'
params:
- name: identity
isOptional: false
type: UserIdentity
subContent:
- name: id
isOptional: false
type: string
- name: identity_id
isOptional: false
type: string
- name: provider
isOptional: false
type: string
- name: user_id