This is an autogenerated python SDK for OpenFGA. It provides a wrapper around the OpenFGA API definition.
- About OpenFGA
- Resources
- Installation
- Getting Started
- Contributing
- License
OpenFGA is an open source Fine-Grained Authorization solution inspired by Google's Zanzibar paper. It was created by the FGA team at Auth0 based on Auth0 Fine-Grained Authorization (FGA), available under a permissive license (Apache-2) and welcomes community contributions.
OpenFGA is designed to make it easy for application builders to model their permission layer, and to add and integrate fine-grained authorization into their applications. OpenFGA’s design is optimized for reliability and low latency at a high scale.
- OpenFGA Documentation
- OpenFGA API Documentation
- OpenFGA Discord Community
- Zanzibar Academy
- Google's Zanzibar Paper (2019)
The openfga_sdk is available to be downloaded via PyPI, you can install directly using:
pip3 install openfga_sdk(you may need to run pip with root permission: sudo pip3 install openfga_sdk)
Then import the package:
import openfga_sdkThe openfga_sdk is also hosted in GitHub, you can install directly using:
pip3 install https://github.com/openfga/python-sdk.git(you may need to run pip with root permission: sudo pip3 install https://github.com/openfga/python-sdk.git)
Then import the package:
import openfga_sdkInstall via Setuptools.
python setup.py install --user(or sudo python setup.py install to install the package for all users)
Then import the package:
import openfga_sdkLearn how to initialize your SDK
To configure the SDK API client without store ID, we can initialize the api client by specifying the scheme and host.
import openfga_sdk from openfga_sdk.api import open_fga_api configuration = openfga_sdk.Configuration( api_scheme = 'https', api_host = 'api.fga.example' ) async def api_setup(): # Enter a context with an instance of the API client async with openfga_sdk.ApiClient(configuration) as api_client: # Create an instance of the API class api_instance = open_fga_api.OpenFgaApi(api_client)To configure the SDK API client store ID, we can initialize the api client by specifying the scheme, host and store_id.
import openfga_sdk from openfga_sdk.api import open_fga_api configuration = openfga_sdk.Configuration( api_scheme = 'https', api_host = 'api.fga.example', store_id = 'YOUR_STORE_ID' ) async def api_setup(): # Enter a context with an instance of the API client async with openfga_sdk.ApiClient(configuration) as api_client: # Create an instance of the API class api_instance = open_fga_api.OpenFgaApi(api_client)Another possibility is to use the existing configuration and add store id in its configuration
import openfga_sdk from openfga_sdk.api import open_fga_api configuration = openfga_sdk.Configuration( api_scheme = 'https', api_host = 'api.fga.example' ) async def api_setup(): configuration.store_id = 'YOUR_STORE_ID' # Enter a context with an instance of the API client async with openfga_sdk.ApiClient(configuration) as api_client: # Create an instance of the API class api_instance = open_fga_api.OpenFgaApi(api_client)To configure the SDK API client with authentication via API TOKEN, we can initialize the api client by specifying the scheme, host and credentials.
import openfga_sdk from openfga_sdk.api import open_fga_api from openfga_sdk.credentials import Credentials, CredentialConfiguration credentials = Credentials(method='api_token', configuration=CredentialConfiguration(api_token='TOKEN1')) configuration = openfga_sdk.Configuration( api_scheme = 'https', api_host = 'api.fga.example', credentials = credentials ) async def api_setup(): # Enter a context with an instance of the API client async with openfga_sdk.ApiClient(configuration) as api_client: # Create an instance of the API class api_instance = open_fga_api.OpenFgaApi(api_client)You need your store id to call the OpenFGA API (unless it is to call the CreateStore or ListStores methods).
If your server is configured with authentication enabled, you also need to have your credentials ready.
configuration = openfga_sdk.Configuration( api_scheme = os.environ.get(OPENFGA_API_SCHEME), api_host = os.environ.get(OPENFGA_API_HOST), ) # Get all stores async def list_stores(): # Create an instance of the API class api_client = openfga_sdk.ApiClient(configuration) api_instance = open_fga_api.OpenFgaApi(api_client) response = await api_instance.list_stores() # response = ListStoreResponse(...) # response.stores = [Store({"id": "01FQH7V8BEG3GPQW93KTRFR8JB", "name": "FGA Demo Store", "created_at": "2022-01-01T00:00:00.000Z", "updated_at": "2022-01-01T00:00:00.000Z"})] await api_client.close()configuration = openfga_sdk.Configuration( api_scheme = os.environ.get(OPENFGA_API_SCHEME), api_host = os.environ.get(OPENFGA_API_HOST), ) # Create a store async def create_store(): # Create an instance of the API class api_client = openfga_sdk.ApiClient(configuration) api_instance = open_fga_api.OpenFgaApi(api_client) body = CreateStoreRequest( name = "FGA Demo Store", ) response = await api_instance.create_store(body) # response.id = "01FQH7V8BEG3GPQW93KTRFR8JB" await api_client.close()Requires a client initialized with a storeId
configuration = openfga_sdk.Configuration( api_scheme = os.environ.get(OPENFGA_API_SCHEME), api_host = os.environ.get(OPENFGA_API_HOST), store_id = os.environ.get(OPENFGA_STORE_ID), ) # Get a store async def get_store(): # Create an instance of the API class api_client = openfga_sdk.ApiClient(configuration) api_instance = open_fga_api.OpenFgaApi(api_client) response = await api_instance.get_store() # response = Store({"id": "01FQH7V8BEG3GPQW93KTRFR8JB", "name": "FGA Demo Store", "created_at": "2022-01-01T00:00:00.000Z", "updated_at": "2022-01-01T00:00:00.000Z"}) await api_client.close()Requires a client initialized with a storeId
configuration = openfga_sdk.Configuration( api_scheme = os.environ.get(OPENFGA_API_SCHEME), api_host = os.environ.get(OPENFGA_API_HOST), store_id = os.environ.get(OPENFGA_STORE_ID), ) # Delete a store async def delete_store(): # Create an instance of the API class api_client = openfga_sdk.ApiClient(configuration) api_instance = open_fga_api.OpenFgaApi(api_client) await api_instance.delete_store() await api_client.close()Requires a client initialized with a storeId
Note: To learn how to build your authorization model, check the Docs at https://openfga.dev/docs.
Learn more about the OpenFGA configuration language.
configuration = openfga_sdk.Configuration( api_scheme = os.environ.get(OPENFGA_API_SCHEME), api_host = os.environ.get(OPENFGA_API_HOST), store_id = os.environ.get(OPENFGA_STORE_ID), ) # Create a new authorization model async def write_authorization_model(): # Create an instance of the API class api_client = openfga_sdk.ApiClient(configuration) api_instance = open_fga_api.OpenFgaApi(api_client) body = WriteAuthorizationModelRequest( schema_version = "1.1", type_definitions=[ TypeDefinition( type="user", ), TypeDefinition( type="document", relations=dict( writer=Userset( this=dict(), ), viewer=Userset( union=Usersets( child=[ Userset(this=dict()), Userset(computed_userset=ObjectRelation( object="", relation="writer", )), ], ), ), ) ), ], ) response = await api_instance.write_authorization_model(body) # response.authorization_model_id = "01GXSA8YR785C4FYS3C0RTG7B1" await api_client.close()configuration = openfga_sdk.Configuration( api_scheme = os.environ.get(OPENFGA_API_SCHEME), api_host = os.environ.get(OPENFGA_API_HOST), store_id = os.environ.get(OPENFGA_STORE_ID), ) # Return a particular version of an authorization model async def read_authorization_id(): # Create an instance of the API class api_client = openfga_sdk.ApiClient(configuration) api_instance = open_fga_api.OpenFgaApi(api_client) id = "01GXSA8YR785C4FYS3C0RTG7B1" # Assuming `01GXSA8YR785C4FYS3C0RTG7B1` is an id of an existing model response = await api_instance.read_authorization_model(id) # response.authorization_model = AuthorizationModel(id='01GXSA8YR785C4FYS3C0RTG7B1', schema_version = '1.1', type_definitions=type_definitions[...]) await api_client.close()configuration = openfga_sdk.Configuration( api_scheme = os.environ.get(OPENFGA_API_SCHEME), api_host = os.environ.get(OPENFGA_API_HOST), store_id = os.environ.get(OPENFGA_STORE_ID), ) # Return all the authorization models for a particular store async def read_authorization_models(): # Create an instance of the API class api_client = openfga_sdk.ApiClient(configuration) api_instance = open_fga_api.OpenFgaApi(api_client) response = await api_instance.read_authorization_models() # response.authorization_models = [AuthorizationModel(id='01GXSA8YR785C4FYS3C0RTG7B1', schema_version = '1.1', type_definitions=type_definitions[...], AuthorizationModel(id='01GXSBM5PVYHCJNRNKXMB4QZTW', schema_version = '1.1', type_definitions=type_definitions[...])] await api_client.close()configuration = openfga_sdk.Configuration( api_scheme = os.environ.get(OPENFGA_API_SCHEME), api_host = os.environ.get(OPENFGA_API_HOST), store_id = os.environ.get(OPENFGA_STORE_ID), ) # Check whether a user is authorized to access an object async def check(): # Create an instance of the API class api_client = openfga_sdk.ApiClient(configuration) api_instance = open_fga_api.OpenFgaApi(api_client) body = CheckRequest( tuple_key=TupleKey( user="user:81684243-9356-4421-8fbf-a4f8d36aa31b", relation="viewer", object="document:roadmap", ), authorization_model_id="01GXSA8YR785C4FYS3C0RTG7B1", ) response = await api_instance.check(body) # response.allowed = True await api_client.close()configuration = openfga_sdk.Configuration( api_scheme = os.environ.get(OPENFGA_API_SCHEME), api_host = os.environ.get(OPENFGA_API_HOST), store_id = os.environ.get(OPENFGA_STORE_ID), ) # Add tuples from the store async def write(): # Create an instance of the API class api_client = openfga_sdk.ApiClient(configuration) api_instance = open_fga_api.OpenFgaApi(api_client) body = WriteRequest( writes=TupleKeys( tuple_keys=[ TupleKey( user="user:81684243-9356-4421-8fbf-a4f8d36aa31b", relation="viewer", object="document:roadmap", ), ], ), authorization_model_id="01GXSA8YR785C4FYS3C0RTG7B1", ) response = await api_instance.write(body) await api_client.close()configuration = openfga_sdk.Configuration( api_scheme = os.environ.get(OPENFGA_API_SCHEME), api_host = os.environ.get(OPENFGA_API_HOST), store_id = os.environ.get(OPENFGA_STORE_ID), ) # Delete tuples from the store async def delete(): # Create an instance of the API class api_client = openfga_sdk.ApiClient(configuration) api_instance = open_fga_api.OpenFgaApi(api_client) body = WriteRequest( deletes=TupleKeys( tuple_keys=[ TupleKey( user="user:81684243-9356-4421-8fbf-a4f8d36aa31b", relation="viewer", object="document:roadmap", ), ], ), authorization_model_id="01GXSA8YR785C4FYS3C0RTG7B1", ) response = await api_instance.write(body) await api_client.close()configuration = openfga_sdk.Configuration( api_scheme = os.environ.get(OPENFGA_API_SCHEME), api_host = os.environ.get(OPENFGA_API_HOST), store_id = os.environ.get(OPENFGA_STORE_ID), ) # Expand all relationships in userset tree format, and following userset rewrite rules. Useful to reason about and debug a certain relationship async def expand(): # Create an instance of the API class api_client = openfga_sdk.ApiClient(configuration) api_instance = open_fga_api.OpenFgaApi(api_client) body = ExpandRequest( tuple_key=TupleKey( relation="viewer", object="document:roadmap", ), authorization_model_id="01GXSA8YR785C4FYS3C0RTG7B1", ) response = await api_instance.expand(body) # response = ExpandResponse({"tree": UsersetTree({"root": Node({"name": "document:roadmap#viewer", "leaf": Leaf({"users": Users({"users": ["user:81684243-9356-4421-8fbf-a4f8d36aa31b", "user:f52a4f7a-054d-47ff-bb6e-3ac81269988f"]})})})})}) await api_client.close()configuration = openfga_sdk.Configuration( api_scheme = os.environ.get(OPENFGA_API_SCHEME), api_host = os.environ.get(OPENFGA_API_HOST), store_id = os.environ.get(OPENFGA_STORE_ID), ) async def read(): # Create an instance of the API class api_client = openfga_sdk.ApiClient(configuration) api_instance = open_fga_api.OpenFgaApi(api_client) # Find if a relationship tuple stating that a certain user is a viewer of certain document body = ReadRequest( tuple_key=TupleKey( user="user:81684243-9356-4421-8fbf-a4f8d36aa31b", relation="viewer", object="document:roadmap", ), ) # Find all relationship tuples where a certain user has a relationship as any relation to a certain document body = ReadRequest( tuple_key=TupleKey( user="user:81684243-9356-4421-8fbf-a4f8d36aa31b", object="document:roadmap", ), ) # Find all relationship tuples where a certain user is a viewer of any document body = ReadRequest( tuple_key=TupleKey( user="user:81684243-9356-4421-8fbf-a4f8d36aa31b", relation="viewer", object="document:", ), ) # Find all relationship tuples where any user has a relationship as any relation with a particular document body = ReadRequest( tuple_key=TupleKey( object="document:roadmap", ), ) // Read all stored relationship tuples body := ReadRequest() response = await api_instance.read(body) # response = ReadResponse({"tuples": [Tuple({"key": TupleKey({"user":"...","relation":"...","object":"..."}), "timestamp": datetime.fromisoformat("...") })]}) await api_client.close()configuration = openfga_sdk.Configuration( api_scheme = os.environ.get(OPENFGA_API_SCHEME), api_host = os.environ.get(OPENFGA_API_HOST), store_id = os.environ.get(OPENFGA_STORE_ID), ) # Return a list of all the tuple changes async def read_changes(): # Create an instance of the API class api_client = openfga_sdk.ApiClient(configuration) api_instance = open_fga_api.OpenFgaApi(api_client) type = "document" page_size = 25 continuation_token = "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==" response = await api_instance.read_changes(type=type, page_size=page_size, continuation_token=continuation_token) # response.continuation_token = ... # response.changes = [TupleChange(tuple_key=TupleKey(object="...",relation="...",user="..."),operation=TupleOperation("TUPLE_OPERATION_WRITE"),timestamp=datetime.fromisoformat("..."))] await api_client.close()configuration = openfga_sdk.Configuration( api_scheme = os.environ.get(OPENFGA_API_SCHEME), api_host = os.environ.get(OPENFGA_API_HOST), store_id = os.environ.get(OPENFGA_STORE_ID), ) # ListObjects lists all of the object ids for objects of the provided type that the given user has a specific relation with. async def list_objects(): # Create an instance of the API class api_client = openfga_sdk.ApiClient(configuration) api_instance = open_fga_api.OpenFgaApi(api_client) body = ListObjectsRequest( authorization_model_id="01GXSA8YR785C4FYS3C0RTG7B1", user="user:81684243-9356-4421-8fbf-a4f8d36aa31b", relation="viewer", type="document", contextual_tuples=ContextualTupleKeys( # optional tuple_keys=[ TupleKey( user="user:81684243-9356-4421-8fbf-a4f8d36aa31b", relation="writer", object="document:budget", ), ], ), ) response = await api_instance.list_objects(body) # response.objects = ["document:roadmap"] await api_client.close()| Class | Method | HTTP request | Description |
|---|---|---|---|
| OpenFgaApi | check | POST /stores/{store_id}/check | Check whether a user is authorized to access an object |
| OpenFgaApi | create_store | POST /stores | Create a store |
| OpenFgaApi | delete_store | DELETE /stores/{store_id} | Delete a store |
| OpenFgaApi | expand | POST /stores/{store_id}/expand | Expand all relationships in userset tree format, and following userset rewrite rules. Useful to reason about and debug a certain relationship |
| OpenFgaApi | get_store | GET /stores/{store_id} | Get a store |
| OpenFgaApi | list_objects | POST /stores/{store_id}/list-objects | Get all objects of the given type that the user has a relation with |
| OpenFgaApi | list_stores | GET /stores | List all stores |
| OpenFgaApi | read | POST /stores/{store_id}/read | Get tuples from the store that matches a query, without following userset rewrite rules |
| OpenFgaApi | read_assertions | GET /stores/{store_id}/assertions/{authorization_model_id} | Read assertions for an authorization model ID |
| OpenFgaApi | read_authorization_model | GET /stores/{store_id}/authorization-models/{id} | Return a particular version of an authorization model |
| OpenFgaApi | read_authorization_models | GET /stores/{store_id}/authorization-models | Return all the authorization models for a particular store |
| OpenFgaApi | read_changes | GET /stores/{store_id}/changes | Return a list of all the tuple changes |
| OpenFgaApi | write | POST /stores/{store_id}/write | Add or delete tuples from the store |
| OpenFgaApi | write_assertions | PUT /stores/{store_id}/assertions/{authorization_model_id} | Upsert assertions for an authorization model ID |
| OpenFgaApi | write_authorization_model | POST /stores/{store_id}/authorization-models | Create a new authorization model |
- Any
- Assertion
- AuthorizationModel
- CheckRequest
- CheckResponse
- Computed
- ContextualTupleKeys
- CreateStoreRequest
- CreateStoreResponse
- Difference
- ErrorCode
- ExpandRequest
- ExpandResponse
- GetStoreResponse
- InternalErrorCode
- InternalErrorMessageResponse
- Leaf
- ListObjectsRequest
- ListObjectsResponse
- ListStoresResponse
- Metadata
- Node
- Nodes
- NotFoundErrorCode
- ObjectRelation
- PathUnknownErrorMessageResponse
- ReadAssertionsResponse
- ReadAuthorizationModelResponse
- ReadAuthorizationModelsResponse
- ReadChangesResponse
- ReadRequest
- ReadResponse
- RelationMetadata
- RelationReference
- Status
- Store
- Tuple
- TupleChange
- TupleKey
- TupleKeys
- TupleOperation
- TupleToUserset
- TypeDefinition
- Users
- Userset
- UsersetTree
- UsersetTreeDifference
- UsersetTreeTupleToUserset
- Usersets
- ValidationErrorMessageResponse
- WriteAssertionsRequest
- WriteAuthorizationModelRequest
- WriteAuthorizationModelResponse
- WriteRequest
If you have found a bug or if you have a feature request, please report them on the sdk-generator repo issues section. Please do not report security vulnerabilities on the public GitHub issue tracker.
All changes made to this repo will be overwritten on the next generation, so we kindly ask that you send all pull requests related to the SDKs to the sdk-generator repo instead.
This project is licensed under the Apache-2.0 license. See the LICENSE file for more info.
The code in this repo was auto generated by OpenAPI Generator from a template based on the python legacy template, licensed under the Apache License 2.0.