Supertokens-python

- Adds caching per API based on user context.

Breaking change:
- Changes general error in querier to normal python error.

Breaking change

- Removed ThirdPartyEmailPassword and ThirdPartyPasswordless recipes. Instead, you should use ThirdParty + EmailPassword or ThirdParty + Passwordless recipes separately in your recipe list.
- Removed `rid` query param from:
- email verification links
- passwordless magic links
- password reset links

Changes

- If `rid` header is present in an API call, the routing no only only depends on that. If the SDK cannot resolve a request handler based on the `rid`, request path and method, it will try to resolve a request handler only based on the request path and method (therefore ignoring the `rid` header).
- New API handlers are:
- `GET /emailpassword/email/exists` => email password, does email exist API (used to be `GET /signup/email/exists` with `rid` of `emailpassword` or `thirdpartyemailpassword` which is now deprecated)
- `GET /passwordless/email/exists` => email password, does email exist API (used to be `GET /signup/email/exists` with `rid` of `passwordless` or `thirdpartypasswordless` which is now deprecated)
- `GET /passwordless/phonenumber/exists` => email password, does email exist API (used to be `GET /signup/phonenumber/exists` which is now deprecated)
- Support for FDI 2.0

Migration guide

- If you were using `ThirdPartyEmailPassword`, you should now init `ThirdParty` and `EmailPassword` recipes separately. The config for the individual recipes are mostly the same, except the syntax may be different. Check our recipe guides for [ThirdParty](https://supertokens.com/docs/thirdparty/introduction) and [EmailPassword](https://supertokens.com/docs/emailpassword/introduction) for more information.

- If you were using `ThirdPartyPasswordless`, you should now init `ThirdParty` and `Passwordless` recipes separately. The config for the individual recipes are mostly the same, except the syntax may be different. Check our recipe guides for [ThirdParty](https://supertokens.com/docs/thirdparty/introduction) and [Passwordless](https://supertokens.com/docs/passwordless/introduction) for more information.

- The way to get user information has changed:
- If you are using `get_users_by_email` from `thirdpartyemailpassword` recipe:

Before:
python
from supertokens_python.recipe.thirdpartyemailpassword.syncio import get_users_by_email

user_info = get_users_by_email("public", "testexample.com")


After:
python
from supertokens_python.recipe.thirdparty.syncio import get_users_by_email as get_users_by_email_third_party
from supertokens_python.recipe.emailpassword.syncio import get_user_by_email as get_user_by_email_emailpassword

third_party_user_info = get_users_by_email_third_party("public", "testexample.com")

email_password_user_info = get_user_by_email_emailpassword("public", "testexample.com")

if email_password_user_info is not None:
print(email_password_user_info)

if len(third_party_user_info) > 0:
print(third_party_user_info)


- If you are using `get_user_id` from `thirdpartyemailpassword` recipe:

Before:
python
from supertokens_python.recipe.thirdpartyemailpassword.syncio import get_user_by_id

_ = get_user_by_id(user_id)


After:
python
from supertokens_python.recipe.thirdparty.syncio import (
get_user_by_id as get_user_by_id_thirdparty,
)
from supertokens_python.recipe.emailpassword.syncio import (
get_user_by_id as get_user_by_id_emailpassword,
)

thirdparty_user = get_user_by_id_thirdparty(user_id)
if thirdparty_user is None:
email_password_user = get_user_by_id_emailpassword(user_id)
if email_password_user is not None:
print(email_password_user)
else:
print(thirdparty_user)


- If you are using `get_users_by_email` from `thirdpartypasswordless` recipe:

Before:
python
from supertokens_python.recipe.thirdpartypasswordless.syncio import get_users_by_email

user_info = get_users_by_email("public", "testexample.com")


After:
python
from supertokens_python.recipe.thirdparty.syncio import get_users_by_email as get_users_by_email_third_party
from supertokens_python.recipe.passwordless.syncio import get_user_by_email as get_user_by_email_passwordless

third_party_user_info = get_users_by_email_third_party("public", "testexample.com")

passwordless_user_info = get_user_by_email_passwordless("public", "testexample.com")

if passwordless_user_info is not None:
print(passwordless_user_info)

if len(third_party_user_info) > 0:
print(third_party_user_info)


- If you are using `get_user_id` from `thirdpartypasswordless` recipe:

Before:
python
from supertokens_python.recipe.thirdpartypasswordless.syncio import get_user_by_id

_ = get_user_by_id(user_id)


After:
python
from supertokens_python.recipe.thirdparty.syncio import (
get_user_by_id as get_user_by_id_thirdparty,
)
from supertokens_python.recipe.passwordless.syncio import (
get_user_by_id as get_user_by_id_passwordless,
)

thirdparty_user = get_user_by_id_thirdparty(user_id)
if thirdparty_user is None:
passwordless_user = get_user_by_id_passwordless(user_id)
if passwordless_user is not None:
print(passwordless_user)
else:
print(thirdparty_user)

- Improves FastAPI middleware performance using recommended ASGI middleware implementation.

- Fixes parameter mismatch in generating fake email

- Added `older_cookie_domain` config option in the session recipe. This will allow users to clear cookies from the older domain when the `cookie_domain` is changed.
- If `verify_session` detects multiple access tokens in the request, it will return a 401 error, prompting a refresh, even if one of the tokens is valid.
- `refresh_post` (`/auth/session/refresh` by default) API changes:
- now returns 500 error if multiple access tokens are present in the request and `config.older_cookie_domain` is not set.
- now clears the access token cookie if it was called without a refresh token (if an access token cookie exists and if using cookie-based sessions).
- now clears cookies from the old domain if `older_cookie_domain` is specified and multiple refresh/access token cookies exist, without updating the front-token or any of the tokens.
- now a 200 response may not include new session tokens.
- Fixed a bug in the `normalise_session_scope` util function that caused it to remove leading dots from the scope string.

Migration

With this update, the second argument in the `session.init` function changes from `cookie_secure` to `older_cookie_domain`. If you're using positional arguments, you need to insert `None` for `older_cookie_domain` as the second argument to maintain the correct order of parameters.

Before:
python
from supertokens_python import init, SupertokensConfig, InputAppInfo
from supertokens_python.recipe import session

init(
supertokens_config=SupertokensConfig("..."),
app_info=InputAppInfo("..."),
framework="...",
recipe_list=[
session.init(
"example.com" cookie_domain
True, cookie_secure
"strict" cookie_same_site
),
],
)


After the update:

python
from supertokens_python import init, SupertokensConfig, InputAppInfo
from supertokens_python.recipe import session

init(
supertokens_config=SupertokensConfig("..."),
app_info=InputAppInfo("..."),
framework="...",
recipe_list=[
session.init(
"example.com" cookie_domain
None, older_cookie_domain
True, cookie_secure
"strict" cookie_same_site
),
],
)


Rationale

This update addresses an edge case where changing the `cookie_domain` config on the server can lead to session integrity issues. For instance, if the API server URL is 'api.example.com' with a cookie domain of '.example.com', and the server updates the cookie domain to 'api.example.com', the client may retain cookies with both '.example.com' and 'api.example.com' domains, resulting in multiple sets of session token cookies existing.

Previously, verify_session would select one of the access tokens from the incoming request. If it chose the older cookie, it would return a 401 status code, prompting a refresh request. However, the `refresh_post` API would then set new session token cookies with the updated `cookie_domain`, but older cookies will persist, leading to repeated 401 errors and refresh loops.

With this update, verify_session will return a 401 error if it detects multiple access tokens in the request, prompting a refresh request. The `refresh_post` API will clear cookies from the old domain if `older_cookie_domain` is specified in the configuration, then return a 200 status. If `older_cookie_domain` is not configured, the `refresh_post` API will return a 500 error with a message instructing to set `older_cookie_domain`.

**Example:**

- `apiDomain`: 'api.example.com'
- `cookie_domain`: 'api.example.com'

**Flow:**

1. After authentication, the frontend has cookies set with `domain=api.example.com`, but the access token has expired.
2. The server updates `cookie_domain` to `.example.com`.
3. An API call requiring session with an expired access token (cookie with `domain=api.example.com`) results in a 401 response.
4. The frontend attempts to refresh the session, generating a new access token saved with `domain=.example.com`.
5. The original API call is retried, but because it sends both the old and new cookies, it again results in a 401 response.
6. The frontend tries to refresh the session with multiple access tokens:
- If `older_cookie_domain` is not set, the refresh fails with a 500 error.
- The user remains stuck until they clear cookies manually or `older_cookie_domain` is set.
- If `older_cookie_domain` is set, the refresh clears the older cookie, returning a 200 response.
- The frontend retries the original API call, sending only the new cookie (`domain=.example.com`), resulting in a successful request.

- `create_new_session` now defaults to the value of the `st-auth-mode` header (if available) if the configured `get_token_transfer_method` returns `any`.
- Enable smooth switching between `use_dynamic_access_token_signing_key` settings by allowing refresh calls to change the signing key type of a session.

Breaking change:
- A session is not required when calling the sign out API. Otherwise the API will return a 401 error.