plystra 1.0.0rc6

Official Python SDK for Plystra.

plystra

Official Python SDK for Plystra Core v1.0.

PyPI package name: plystra Repository name: plystra/python-sdk

Requires Python 3.10 or newer.

Install

pip install plystra

Synchronous Usage

For production backend code, prefer passing a server-side access token or API key that was issued outside the request path. Keep password login available for admin tools and bootstrap flows, not for routine service-to-service checks.

Using an API key:

from plystra import Plystra

with Plystra("https://plystra.internal", api_key="ply_ak_...") as plystra:
    decision = plystra.authz.check(
        actor={
            "user_id": "user_alice",
            "space_id": "space_acme",
            "member_id": "member_finance_reviewer",
            "user_member_id": "um_alice_finance_reviewer",
        },
        resource_type="invoice",
        resource_id="invoice_001",
        action="approve",
    )

Using an access token received from your frontend or gateway session:

from plystra import Plystra

with Plystra("https://plystra.internal", access_token=session["plystra_access_token"]) as plystra:
    print(plystra.authz.check(action="approve", resource_type="invoice", resource_id="invoice_001"))

Access-token calls may omit actor; Core uses the token's active actor. API key calls must pass the nested actor explicitly.

Attach an application request id to a group of calls with with_request_id:

from plystra import Plystra

with Plystra("https://plystra.internal", access_token=session["plystra_access_token"]) as plystra:
    scoped = plystra.with_request_id("req_01HY...")
    decision = scoped.authz.check(
        resource_type="invoice",
        resource_id="invoice_001",
        action="approve",
    )

Password login is still supported:

from plystra import Plystra

with Plystra("http://localhost:8080") as plystra:
    plystra.auth.login("[e-mail]", "plystra-demo")

    # Core rotates refresh tokens. Omitting the argument uses the stored one.
    plystra.auth.refresh()

    decision = plystra.authz.check(
        actor={
            "user_id": "user_alice",
            "space_id": "space_acme",
            "member_id": "member_finance_reviewer",
            "user_member_id": "um_alice_finance_reviewer",
        },
        resource_type="invoice",
        resource_id="invoice_001",
        action="approve",
    )

    print(decision["decision"])

Registration is disabled by default in Core. When an operator enables it and gives you a registration token:

with Plystra("https://plystra.internal") as plystra:
    plystra.auth.register(
        email="[e-mail]",
        password="long-enough-password",
        space_name="Founder Space",
        registration_token=registration_token,
    )

Asynchronous Usage

import asyncio
from plystra import AsyncPlystra


async def main() -> None:
    async with AsyncPlystra("https://plystra.internal", api_key="ply_ak_...") as plystra:
        decision = await plystra.authz.check(
            actor={
                "user_id": "user_alice",
                "space_id": "space_acme",
                "member_id": "member_finance_reviewer",
                "user_member_id": "um_alice_finance_reviewer",
            },
            resource_type="invoice",
            resource_id="invoice_001",
            action="approve",
        )
        print(decision["decision"])


asyncio.run(main())

Modules

The SDK exposes v1.0 Core modules as attributes:

• system
• auth
• actor
• admin
• api_keys
• users
• spaces
• groups
• members
• user_members
• roles
• member_roles
• permissions
• role_permissions
• resource_types
• resources
• authz
• audit
• data
• plugins
• templates

Non-public endpoints require either a Bearer session whose user has an active admin grant or a scoped API key with matching permission keys.

Keep SDK tokens in a server-side encrypted session store. login() and refresh() update access_token and refresh_token on the client; call plystra.tokens() when you need to persist the rotated token pair.