Authenticate with the Python SDK

Every request the Python client sends carries one credential. The credential decides who TaruviBase treats as the caller, and so which roles and access policies apply. This guide helps you pick one and pass it.

Choose a credential

• API key, api_key= — For backends, jobs, and scripts that don't act for a signed-in user. Sent as Authorization: Api-Key …, and acts as the user who created the key.
• Session token, session_token= — For a backend that acts for a user of your web app. Sent as X-Session-Token: …, and acts as that signed-in user.
• JWT, jwt= — For tokens from signInWithPassword() or your own sign-in flow. Sent as Authorization: Bearer …, and acts as the user the token was issued to.
• Function client — For code running inside a TaruviBase function. TaruviBase sets the credential; it acts as the calling user, or as the function's creator when there is none.

The client sends exactly one credential. If more than one is set, it sends the API key, else the JWT, else the session token. A credential you pass to Client() replaces any credential in the environment.

An API key is a personal access token that acts as the member of your organization who created it. That member has organization access, so requests made with the key skip app roles and Database row policies. Use keys only for trusted server jobs; to act for a user, pass their session token instead.

Pass a credential to the client

taruvi_client.py

import os

from taruvi import Client

client = Client(
    api_url=os.environ["TARUVI_SITE_URL"],
    app_slug=os.environ["TARUVI_APP_SLUG"],
    api_key=os.environ["TARUVI_API_KEY"],
    mode="sync",
)

Replace api_key= with session_token= or jwt= for the other credentials. Generate API keys with an expiry on Settings → Connect or under Settings → API Tokens; see Issue API tokens.

Credentials can come from the environment

When you pass no credential, the client reads TARUVI_API_KEY, TARUVI_JWT, or TARUVI_SESSION_TOKEN from the environment or a .env file in the working directory. Unset them in processes that must not act as that user.

Act for a signed-in user

When your web app calls your Python backend, forward the user's TaruviBase session token, which the JavaScript SDK returns from auth.getSessionToken(), and create a client for that request:

views.py

import os

from taruvi import Client


def list_tasks_for(session_token: str) -> list[dict]:
    with Client(
        api_url=os.environ["TARUVI_SITE_URL"],
        app_slug=os.environ["TARUVI_APP_SLUG"],
        session_token=session_token,
        mode="sync",
    ) as client:
        return client.database.from_("tasks").page_size(20).execute()["data"]

TaruviBase then applies that user's permissions, even when TARUVI_API_KEY is set in the same process. Don't reuse one client across users, and don't log the token.

Sign in from an existing client

client.auth returns a new client with the credential applied. The original client doesn't change, so close both when you're done.

Synchronous

import os

from taruvi import Client

with Client(os.environ["TARUVI_SITE_URL"], os.environ["TARUVI_APP_SLUG"], mode="sync") as client:
    user_client = client.auth.signInWithPassword(
        email=os.environ["TARUVI_USER_EMAIL"],
        password=os.environ["TARUVI_USER_PASSWORD"],
    )
    print(user_client.auth.get_current_user())
    user_client.close()

Asynchronous

import os

from taruvi import Client


async def sign_in():
    client = Client(os.environ["TARUVI_SITE_URL"], os.environ["TARUVI_APP_SLUG"], mode="async")

    user_client = await client.auth.signInWithPassword(
        email=os.environ["TARUVI_USER_EMAIL"],
        password=os.environ["TARUVI_USER_PASSWORD"],
    )
    print(await user_client.auth.get_current_user())

    await user_client.close()
    await client.close()

The sign-in methods return a new client and leave the original unchanged:

• signInWithPassword(email, password) — Signs in through POST /_allauth/app/v1/auth/login and uses the returned access token as a JWT. It's a coroutine in the async client.
• signInWithToken(token, token_type="jwt") — Uses an existing token. token_type is "jwt", "api_key", or "session_token".
• signOut() — A copy with no credential. It doesn't end the session on TaruviBase.

To check who the client acts as:

• get_current_user() — The response from GET /api/users/me/, with the user under ["data"].
• client.is_authenticated — Whether the client holds a credential. It doesn't check that the credential is valid.

The SDK doesn't refresh JWTs. When a request raises AuthenticationError, sign in again.

Don't ship passwords in code

signInWithPassword() suits tests and one-off scripts run by a person. For unattended jobs, use an API key with an expiry, stored in a secret manager.

Inside a TaruviBase function

Function code doesn't create a client. TaruviBase passes a synchronous, authenticated client as the third argument:

main.py

def main(params, user_data, sdk_client):
    open_tasks = (
        sdk_client.database.from_("tasks")
        .filter("done", "eq", False)
        .count()
    )
    return {"open_tasks": open_tasks}

sdk_client acts as the user who called the function. For runs with no signed-in caller, such as schedules and calls to public functions, it acts as the function's creator. Its token lasts one hour at most and is revoked when the run ends.

TaruviBase checks function code when you save it: the entry point must be written exactly as def main(params, user_data, sdk_client):, without type hints, and imports are limited to an allowed list. params also carries platform keys such as request and __function__. See Write a function.

Troubleshooting

NotAuthenticatedError on the first request. The client has no credential. Pass one, or check the environment variables above.

AuthenticationError (401). The credential is invalid, expired, revoked, or belongs to another site. Generate a new API key or sign in again.

AuthorizationError (403). The caller is known but not allowed. Check the caller's roles and your access policies.