data
OpenFGA Lua API for KosmoKrator Agents
Agent-facing Lua documentation and function reference for the OpenFGA KosmoKrator integration.Lua Namespace
Agents call this integration through app.integrations.openfga.*.
Use lua_read_doc("integrations.openfga") inside KosmoKrator to discover the same reference at runtime.
Call Lua from the Headless CLI
Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic
OpenFGA workflow without starting an interactive agent session.
kosmo integrations:lua --eval 'dump(app.integrations.openfga.get_configuration({}))' --json kosmo integrations:lua --eval 'print(docs.read("openfga"))' --json
kosmo integrations:lua --eval 'print(docs.read("openfga.get_configuration"))' --json Workflow file
Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.
local openfga = app.integrations.openfga
local result = openfga.get_configuration({})
dump(result) kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json integrations:lua exposes app.integrations.openfga, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.openfga.default.* or app.integrations.openfga.work.* when you configured named credential accounts.
MCP-only Lua
If the script only needs configured MCP servers and does not need OpenFGA, use the narrower mcp:lua command.
# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json Agent-Facing Lua Docs
This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.
OpenFGA Lua Tools
Namespace: openfga
Generated from the official OpenFGA Swagger document in openfga/api. Configure url with the OpenFGA server base URL and optionally api_token for bearer-token protected deployments.
Coverage
- Paths: 20
- Tools: 24
- Read tools: 7
- Write tools: 17
Usage Notes
- Path and query parameters use snake_case tool keys and are sent with official API names.
- JSON request payloads go in
body. - Empty optional query parameters are omitted.
Example Lua
local stores = openfga.openfga_list_stores({ page_size = 25 })
local allowed = openfga.openfga_check({ store_id = "01HV...", body = { tuple_key = { user = "user:anne", relation = "viewer", object = "document:roadmap" } } })Raw agent markdown
# OpenFGA Lua Tools
Namespace: `openfga`
Generated from the official OpenFGA Swagger document in `openfga/api`. Configure `url` with the OpenFGA server base URL and optionally `api_token` for bearer-token protected deployments.
## Coverage
- Paths: 20
- Tools: 24
- Read tools: 7
- Write tools: 17
## Usage Notes
- Path and query parameters use snake_case tool keys and are sent with official API names.
- JSON request payloads go in `body`.
- Empty optional query parameters are omitted.
## Example Lua
```lua
local stores = openfga.openfga_list_stores({ page_size = 25 })
local allowed = openfga.openfga_check({ store_id = "01HV...", body = { tuple_key = { user = "user:anne", relation = "viewer", object = "document:roadmap" } } })
``` local result = app.integrations.openfga.get_configuration({})
print(result) Functions
get_configuration Read
[Experimental] The GetConfiguration API returns metadata about the Policy Decision Point (PDP) including its name, version, supported endpoints, and capabilities. This endpoint follows the AuthZEN specification for PDP discovery. Following the AuthZEN spec's m
- Lua path
app.integrations.openfga.get_configuration- Full name
openfga.openfga_get_configuration
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
list_stores Read
Returns a paginated list of OpenFGA stores and a continuation token to get additional stores. The continuation token will be empty if there are no more stores. Official OpenFGA endpoint: GET /stores.
- Lua path
app.integrations.openfga.list_stores- Full name
openfga.openfga_list_stores
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
create_store Write
Create a unique OpenFGA store which will be used to store authorization models and relationship tuples. Official OpenFGA endpoint: POST /stores.
- Lua path
app.integrations.openfga.create_store- Full name
openfga.openfga_create_store
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
get_store Read
Returns an OpenFGA store by its identifier Official OpenFGA endpoint: GET /stores/{store_id}.
- Lua path
app.integrations.openfga.get_store- Full name
openfga.openfga_get_store
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
delete_store Write
Delete an OpenFGA store. This does not delete the data associated with the store, like tuples or authorization models. Official OpenFGA endpoint: DELETE /stores/{store_id}.
- Lua path
app.integrations.openfga.delete_store- Full name
openfga.openfga_delete_store
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
evaluation Write
[Experimental] The Evaluation API determines whether a subject is authorized to perform an action on a resource. This endpoint implements the AuthZEN Access Evaluation API specification. ## Request Structure The request requires three components: - **subject**
- Lua path
app.integrations.openfga.evaluation- Full name
openfga.openfga_evaluation
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
evaluations Write
[Experimental] The Evaluations API allows batch authorization checks in a single request. It supports request-level defaults for subject, action, resource, and context that can be overridden per evaluation item. ## Evaluation Semantics The `options.evaluations
- Lua path
app.integrations.openfga.evaluations- Full name
openfga.openfga_evaluations
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
action_search Write
[Experimental] The ActionSearch API returns all actions (relations) that a subject can perform on a specific resource. This is useful for answering questions like "What can Anne do with this document?" or building dynamic UIs that show only the actions a user
- Lua path
app.integrations.openfga.action_search- Full name
openfga.openfga_action_search
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
resource_search Write
[Experimental] The ResourceSearch API returns all resources of a given type that a subject has a specific action (relation) on. This is useful for answering questions like "What documents can Anne read?" or "What folders can Bob administer?" The resource type
- Lua path
app.integrations.openfga.resource_search- Full name
openfga.openfga_resource_search
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
subject_search Write
[Experimental] The SubjectSearch API returns all subjects that have a specific action (relation) on a given resource. This is useful for answering questions like "Who can read this document?" or "Who can administer this folder?" Results can be filtered by subj
- Lua path
app.integrations.openfga.subject_search- Full name
openfga.openfga_subject_search
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
read_assertions Read
The ReadAssertions API will return, for a given authorization model id, all the assertions stored for it. Official OpenFGA endpoint: GET /stores/{store_id}/assertions/{authorization_model_id}.
- Lua path
app.integrations.openfga.read_assertions- Full name
openfga.openfga_read_assertions
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
write_assertions Write
The WriteAssertions API will upsert new assertions for an authorization model id, or overwrite the existing ones. An assertion is an object that contains a tuple key, the expectation of whether a call to the Check API of that tuple key will return true or fals
- Lua path
app.integrations.openfga.write_assertions- Full name
openfga.openfga_write_assertions
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
read_authorization_models Read
The ReadAuthorizationModels API will return all the authorization models for a certain store. OpenFGA's response will contain an array of all authorization models, sorted in descending order of creation. ## Example Assume that a store's authorization model has
- Lua path
app.integrations.openfga.read_authorization_models- Full name
openfga.openfga_read_authorization_models
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
write_authorization_model Write
The WriteAuthorizationModel API will add a new authorization model to a store. Each item in the `type_definitions` array is a type definition as specified in the field `type_definition`. The response will return the authorization model's ID in the `id` field.
- Lua path
app.integrations.openfga.write_authorization_model- Full name
openfga.openfga_write_authorization_model
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
read_authorization_model Read
The ReadAuthorizationModel API returns an authorization model by its identifier. The response will return the authorization model for the particular version. ## Example To retrieve the authorization model with ID `01G5JAVJ41T49E9TT3SKVS7X1J` for the store, cal
- Lua path
app.integrations.openfga.read_authorization_model- Full name
openfga.openfga_read_authorization_model
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
batch_check Write
The `BatchCheck` API functions nearly identically to `Check`, but instead of checking a single user-object relationship BatchCheck accepts a list of relationships to check and returns a map containing `BatchCheckItem` response for each check it received. An as
- Lua path
app.integrations.openfga.batch_check- Full name
openfga.openfga_batch_check
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
read_changes Read
The ReadChanges API will return a paginated list of tuple changes (additions and deletions) that occurred in a given store, sorted by ascending time. The response will include a continuation token that is used to get the next set of changes. If there are no ch
- Lua path
app.integrations.openfga.read_changes- Full name
openfga.openfga_read_changes
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
check Write
The Check API returns whether a given user has a relationship with a given object in a given store. The `user` field of the request can be a specific target, such as `user:anne`, or a userset (set of users) such as `group:marketing#member` or a type-bound publ
- Lua path
app.integrations.openfga.check- Full name
openfga.openfga_check
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
expand Write
The Expand API will return all users and usersets that have certain relationship with an object in a certain store. This is different from the `/stores/{store_id}/read` API in that both users and computed usersets are returned. Body parameters `tuple_key.objec
- Lua path
app.integrations.openfga.expand- Full name
openfga.openfga_expand
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
list_objects Write
The ListObjects API returns a list of all the objects of the given type that the user has a relation with. To arrive at a result, the API uses: an authorization model, explicit tuples written through the Write API, contextual tuples present in the request, and
- Lua path
app.integrations.openfga.list_objects- Full name
openfga.openfga_list_objects
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
list_users Write
The ListUsers API returns a list of all the users of a specific type that have a relation to a given object. To arrive at a result, the API uses: an authorization model, explicit tuples written through the Write API, contextual tuples present in the request, a
- Lua path
app.integrations.openfga.list_users- Full name
openfga.openfga_list_users
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
read Write
The Read API will return the tuples for a certain store that match a query filter specified in the body of the request. The API doesn't guarantee order by any field. It is different from the `/stores/{store_id}/expand` API in that it only returns relationship
- Lua path
app.integrations.openfga.read- Full name
openfga.openfga_read
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
streamed_list_objects Write
The Streamed ListObjects API is very similar to the the ListObjects API, with two differences: 1. Instead of collecting all objects before returning a response, it streams them to the client as they are collected. 2. The number of results returned is only limi
- Lua path
app.integrations.openfga.streamed_list_objects- Full name
openfga.openfga_streamed_list_objects
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||
write Write
The Write API will transactionally update the tuples for a certain store. Tuples and type definitions allow OpenFGA to determine whether a relationship exists between an object and an user. In the body, `writes` adds new tuples and `deletes` removes existing t
- Lua path
app.integrations.openfga.write- Full name
openfga.openfga_write
| Parameter | Type | Required | Description |
|---|---|---|---|
| No parameters. | |||