Authzed Python Client

1.24.4 · active · verified Sun Apr 12

The `authzed` library is the official Python client for Authzed's SpiceDB, a permissions database and service. It enables developers to define authorization schemas, manage relationships between objects, and perform efficient permission checks within their applications. The library supports both the v1 Core SpiceDB API and the materialize/v0 API for building materialized permission views. It maintains an active development status with regular updates.

Warnings

gotcha When developing locally or with self-signed certificates, standard `bearer_token_credentials` might fail due to TLS verification issues. Use `insecure_bearer_token_credentials()` for non-TLS connections or explicitly provide `certChain` for custom certificates.
Fix: For local insecure connections: `from grpcutil import insecure_bearer_token_credentials; client = Client('localhost:50051', insecure_bearer_token_credentials('your_token'))`. For self-signed certs: pass the root certificate as `certChain` to `bearer_token_credentials`.
gotcha The 'Dual-Write Problem' is a common architectural challenge when integrating Authzed/SpiceDB with an application database. Ensuring consistency between both systems (e.g., when creating a file and its permissions) requires careful handling.
Fix: Implement patterns like the transactional outbox to ensure eventual consistency between your application database and SpiceDB. Avoid treating API calls as RPCs that immediately reflect system state.
gotcha The `InsecureClient` provided by `authzed-py` uses `grpc.insecure_channel`, which is not inherently compatible with `asyncio`. Attempting to use it with asynchronous operations, especially methods like `LookupResources` that return `UnaryStreamCall`, may lead to authentication errors or unexpected behavior.
Fix: For asynchronous use, consider implementing an async-compatible client or using documented workarounds/patterns for async gRPC interactions. Consult the Authzed community for the latest best practices on async usage.
gotcha Periodically, specific minor releases may encounter packaging issues that prevent correct installation or module imports, as was observed with `authzed-py v1.22.0`.
Fix: If encountering unexpected import errors or installation failures after an update, check the project's GitHub issues for known packaging problems. Pinning to a previous stable version may be necessary until a fix is released (e.g., `pip install authzed==1.21.0`).
gotcha Avoid creating cycles in your SpiceDB schema definitions. While recursive schemas can be powerful, incorrect usage or accidental cycles can lead to significant performance issues and unexpected behavior in permission evaluations.
Fix: Design schemas carefully to ensure acyclic relationships where possible. If recursion is necessary (e.g., groups having subgroups), ensure the structure directly refers back to itself in a controlled manner, avoiding indirect cycles through other definitions.
gotcha When making permission checks, prefer checking permissions directly rather than relations. If the logic for a check needs to change, modifying a permission definition is significantly easier and safer than changing a relation definition, which often requires a data migration.
Fix: Structure your schema so that a permission points to a relation, and then check the permission. Example: `permission read = reader`, then check `document:id#read@user:id` instead of `document:id#reader@user:id` directly.

Install

pip install authzed Install latest version

Imports

Client
```
from authzed.api.v1 import Client
```
bearer_token_credentials
```
from grpcutil import bearer_token_credentials
```
`grpcutil` is typically imported directly, not as a submodule of `authzed`.
insecure_bearer_token_credentials
```
from grpcutil import insecure_bearer_token_credentials
```
Used for local development without TLS/self-signed certificates.

Quickstart

This quickstart demonstrates how to initialize the Authzed client using an API token and perform a basic permission check. Ensure `SPICEDB_ENDPOINT` and `SPICEDB_API_TOKEN` environment variables are set or replaced with your actual SpiceDB connection details.

import os
from authzed.api.v1 import Client, CheckPermissionRequest, ObjectReference, SubjectReference
from grpcutil import bearer_token_credentials

# Replace with your SpiceDB endpoint and API token from environment variables
SPICEDB_ENDPOINT = os.environ.get('SPICEDB_ENDPOINT', 'grpc.authzed.com:443')
SPICEDB_API_TOKEN = os.environ.get('SPICEDB_API_TOKEN', 't_your_token_here_1234567deadbeef')

if not SPICEDB_API_TOKEN:
    raise ValueError("SPICEDB_API_TOKEN environment variable not set or is empty.")

# Initialize the client with bearer token credentials
client = Client(
    SPICEDB_ENDPOINT,
    bearer_token_credentials(SPICEDB_API_TOKEN),
)

try:
    # Example: Check if a user 'emilia' can 'view' a document 'first_doc'
    request = CheckPermissionRequest(
        resource=ObjectReference(object_type="document", object_id="first_doc"),
        permission="view",
        subject=SubjectReference(object=ObjectReference(object_type="user", object_id="emilia"))
    )
    
    response = client.CheckPermission(request)
    print(f"Permission check result: {response.permissionship}")

except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →