Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/exegia/corpora-py/llms.txt

Use this file to discover all available pages before exploring further.

The exegia.auth.signin module provides three functions covering the two main sign-in paths: email OTP (two-step) and OIDC ID token (one-step). After the provider authenticates the user, both paths run a public.users lookup and return a SignInResult — either a full authenticated payload or a needs_signup signal if no application profile exists yet.

​
Email OTP Flow

The email OTP flow is two steps: first dispatch the code, then verify it. No session is created until the second step.
1

Send the one-time code

Call request_email_otp with the user’s email address. This triggers a magic-link email via Supabase Auth. No session or profile check happens at this stage.
from exegia.auth.signin import request_email_otp

response = request_email_otp(
    email="user@example.com",
    email_redirect_to="https://myapp.com/auth/callback",  # optional
    should_create_user=False,  # optional
)
2

Verify the code

Pass the 6-digit code the user received to verify_email_otp. On success, the function looks up public.users and returns a SignInResult.
from exegia.auth.signin import verify_email_otp

result = verify_email_otp(email="user@example.com", token="123456")

if result.ok:
    print(result.current_user.id)    # auth user UUID
    print(result.current_user.email) # user email
elif result.needs_signup:
    # User authenticated but has no public.users record
    print(result.message)  # "No account is linked..."
    # result.session is still set — pass it to sign_up() to complete registration

​
OIDC ID Token Flow

The Apple and Google flows are single-step. The client obtains an ID token directly from the provider and exchanges it for a Supabase session in one call. 
from exegia.auth.signin import sign_in_with_id_token

result = sign_in_with_id_token(
    provider="google",  # or "apple"
    token="<oidc_id_token_from_provider>",
    access_token="<provider_access_token>",  # optional
    nonce="<nonce>",  # required for Apple
)

if result.ok:
    user = result.current_user
    session = result.session

​
SignInResult Fields

​
ok
bool
True when the user is authenticated and has a public.users record. This is the only fully successful state.
​
current_user
CurrentUser | None
The combined auth identity and application profile. Set only when ok is True. Contains id, email, is_anonymous, is_permanent, has_profile, and providers.
​
session
Session | None
The Supabase session (access and refresh tokens). Present both on success and on the needs_signup path, so the caller can pass session.access_token to sign_up() without re-authenticating.
​
message
str | None
A user-facing message. Set on all non-ok paths, including needs_signup.
​
needs_signup
bool
True when the provider authenticated the user but no public.users record was found. Defaults to False. Offer registration rather than a sign-in error.

​
Function Reference

​
request_email_otp

​
email
str
required
Destination email address to send the OTP or magic link to.
​
email_redirect_to
str
URL to redirect the user to after they click the magic link. Optional.
​
should_create_user
bool
Whether to create a new auth.users record when the email is not yet registered. Defaults to the project setting when omitted. Optional.
​
captcha_token
str
CAPTCHA verification token. Required when CAPTCHA protection is enabled on the Supabase project. Optional.

​
verify_email_otp

​
email
str
required
The email address the OTP was sent to. Must match the address used in request_email_otp.
​
token
str
required
The 6-digit one-time code the user received by email.
​
captcha_token
str
CAPTCHA verification token. Optional.

​
sign_in_with_id_token

​
provider
IdTokenProvider
required
The OIDC provider that issued the token. IdTokenProvider is a Literal["apple", "google"] type from exegia.supabase.authentication. GitHub is not supported via this flow — use the OAuth identity-linking flow for GitHub instead.
​
token
str
required
The OIDC ID token (JWT) returned by the provider’s native sign-in SDK.
​
access_token
str
Optional provider access token. Some providers require this to fetch additional profile details. Optional.
​
nonce
str
The raw nonce used when requesting the ID token from the provider. Apple sign-in typically requires this to be supplied. Optional.
​
captcha_token
str
CAPTCHA verification token. Optional.

​
Error Handling

Both verify_email_otp and sign_in_with_id_token raise AuthApiError (from supabase_auth) when the provider rejects the request — for example, when a code has expired or a token is malformed. Catch this at the call site to surface a clean error to the user. 
from supabase_auth import AuthApiError

try:
    result = verify_email_otp(email="user@example.com", token="123456")
except AuthApiError as e:
    # Token is invalid or has expired
    print(e)
If result.needs_signup is True, the user authenticated successfully but has no public.users record. The session is still available on result.session. Pass result.session.access_token to sign_up() to complete registration without requiring the user to sign in again.

Build docs developers (and LLMs) love

Get started for freeTalk to us