OpenFga::OpenFgaApi

February 16, 2026 · View on GitHub

All URIs are relative to http://localhost

Method	HTTP request	Description
batch_check	POST /stores/{store_id}/batch-check	Send a list of `check` operations in a single request
check	POST /stores/{store_id}/check	Check whether a user is authorized to access an object
create_store	POST /stores	Create a store
delete_store	DELETE /stores/{store_id}	Delete a store
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
get_store	GET /stores/{store_id}	Get a store
list_objects	POST /stores/{store_id}/list-objects	List all objects of the given type that the user has a relation with
list_stores	GET /stores	List all stores
list_users	POST /stores/{store_id}/list-users	List the users matching the provided filter who have a certain relation to a particular type.
read	POST /stores/{store_id}/read	Get tuples from the store that matches a query, without following userset rewrite rules
read_assertions	GET /stores/{store_id}/assertions/{authorization_model_id}	Read assertions for an authorization model ID
read_authorization_model	GET /stores/{store_id}/authorization-models/{id}	Return a particular version of an authorization model
read_authorization_models	GET /stores/{store_id}/authorization-models	Return all the authorization models for a particular store
read_changes	GET /stores/{store_id}/changes	Return a list of all the tuple changes
write	POST /stores/{store_id}/write	Add or delete tuples from the store
write_assertions	PUT /stores/{store_id}/assertions/{authorization_model_id}	Upsert assertions for an authorization model ID
write_authorization_model	POST /stores/{store_id}/authorization-models	Create a new authorization model

batch_check

batch_check(store_id, body)

Send a list of check operations in a single request

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 associated correlation_id is required for each check in the batch. This ID is used to correlate a check to the appropriate response. It is a string consisting of only alphanumeric characters or hyphens with a maximum length of 36 characters. This correlation_id is used to map the result of each check to the item which was checked, so it must be unique for each item in the batch. We recommend using a UUID or ULID as the correlation_id, but you can use whatever unique identifier you need as long as it matches this regex pattern: ^[\\w\\d-]{1,36}$ NOTE: The maximum number of checks that can be passed in the BatchCheck API is configurable via the OPENFGA_MAX_CHECKS_PER_BATCH_CHECK environment variable. If BatchCheck is called using the SDK, the SDK can split the batch check requests for you. For more details on how Check functions, see the docs for /check. ### Examples #### A BatchCheckRequest json { \"checks\": [ { \"tuple_key\": { \"object\": \"document:2021-budget\" \"relation\": \"reader\", \"user\": \"user:anne\", }, \"contextual_tuples\": {...} \"context\": {} \"correlation_id\": \"01JA8PM3QM7VBPGB8KMPK8SBD5\" }, { \"tuple_key\": { \"object\": \"document:2021-budget\" \"relation\": \"reader\", \"user\": \"user:bob\", }, \"contextual_tuples\": {...} \"context\": {} \"correlation_id\": \"01JA8PMM6A90NV5ET0F28CYSZQ\" } ] } Below is a possible response to the above request. Note that the result map's keys are the correlation_id values from the checked items in the request: json { \"result\": { \"01JA8PMM6A90NV5ET0F28CYSZQ\": { \"allowed\": false, \"error\": {\"message\": \"\"} }, \"01JA8PM3QM7VBPGB8KMPK8SBD5\": { \"allowed\": true, \"error\": {\"message\": \"\"} } }

Examples

require 'time'
require 'openfga'

api_instance = OpenFga::OpenFgaApi.new
store_id = 'store_id_example' # String | 
body = OpenFga::BatchCheckRequest.new({checks: [OpenFga::BatchCheckItem.new({tuple_key: OpenFga::CheckRequestTupleKey.new({user: 'user:anne', relation: 'reader', object: 'document:2021-budget'}), correlation_id: '1cd93d8c-8e45-43c6-9a15-cbb3c7f394bc'})]}) # BatchCheckRequest | 

begin
  # Send a list of `check` operations in a single request
  result = api_instance.batch_check(store_id, body)
  p result
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->batch_check: #{e}"
end

Using the batch_check_with_http_info variant

This returns an Array which contains the response data, status code and headers.

<Array(, Integer, Hash)> batch_check_with_http_info(store_id, body)

begin
  # Send a list of `check` operations in a single request
  data, status_code, headers = api_instance.batch_check_with_http_info(store_id, body)
  p status_code # => 2xx
  p headers # => { ... }
  p data # => <BatchCheckResponse>
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->batch_check_with_http_info: #{e}"
end

Parameters

Name	Type	Description	Notes
store_id	String
body	BatchCheckRequest

Return type

BatchCheckResponse

Authorization

No authorization required

HTTP request headers

Content-Type: application/json
Accept: application/json

check

check(store_id, body)

Check whether a user is authorized to access an object

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 public access user:*. 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 implicit tuples that exist by virtue of applying set theory (such as document:2021-budget#viewer@document:2021-budget#viewer; the set of users who are viewers of document:2021-budget are the set of users who are the viewers of document:2021-budget). A contextual_tuples object may also be included in the body of the request. This object contains one field tuple_keys, which is an array of tuple keys. Each of these tuples may have an associated condition. You may also provide an authorization_model_id in the body. This will be used to assert that the input tuple_key is valid for the model specified. If not specified, the assertion will be made against the latest authorization model ID. It is strongly recommended to specify authorization model id for better performance. You may also provide a context object that will be used to evaluate the conditioned tuples in the system. It is strongly recommended to provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly. By default, the Check API caches results for a short time to optimize performance. You may specify a value of HIGHER_CONSISTENCY for the optional consistency parameter in the body to inform the server that higher conisistency is preferred at the expense of increased latency. Consideration should be given to the increased latency if requesting higher consistency. The response will return whether the relationship exists in the field allowed. Some exceptions apply, but in general, if a Check API responds with {allowed: true}, then you can expect the equivalent ListObjects query to return the object, and viceversa. For example, if Check(user:anne, reader, document:2021-budget) responds with {allowed: true}, then ListObjects(user:anne, reader, document) may include document:2021-budget in the response. ## Examples ### Querying with contextual tuples In order to check if user user:anne of type user has a reader relationship with object document:2021-budget given the following contextual tuple json { \"user\": \"user:anne\", \"relation\": \"member\", \"object\": \"time_slot:office_hours\" } the Check API can be used with the following request body: json { \"tuple_key\": { \"user\": \"user:anne\", \"relation\": \"reader\", \"object\": \"document:2021-budget\" }, \"contextual_tuples\": { \"tuple_keys\": [ { \"user\": \"user:anne\", \"relation\": \"member\", \"object\": \"time_slot:office_hours\" } ] }, \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\" } ### Querying usersets Some Checks will always return true, even without any tuples. For example, for the following authorization model python model schema 1.1 type user type document relations define reader: [user] the following query json { \"tuple_key\": { \"user\": \"document:2021-budget#reader\", \"relation\": \"reader\", \"object\": \"document:2021-budget\" } } will always return { \"allowed\": true }. This is because usersets are self-defining: the userset document:2021-budget#reader will always have the reader relation with document:2021-budget. ### Querying usersets with difference in the model A Check for a userset can yield results that must be treated carefully if the model involves difference. For example, for the following authorization model python model schema 1.1 type user type group relations define member: [user] type document relations define blocked: [user] define reader: [group#member] but not blocked the following query json { \"tuple_key\": { \"user\": \"group:finance#member\", \"relation\": \"reader\", \"object\": \"document:2021-budget\" }, \"contextual_tuples\": { \"tuple_keys\": [ { \"user\": \"user:anne\", \"relation\": \"member\", \"object\": \"group:finance\" }, { \"user\": \"group:finance#member\", \"relation\": \"reader\", \"object\": \"document:2021-budget\" }, { \"user\": \"user:anne\", \"relation\": \"blocked\", \"object\": \"document:2021-budget\" } ] }, } will return { \"allowed\": true }, even though a specific user of the userset group:finance#member does not have the reader relationship with the given object. ### Requesting higher consistency By default, the Check API caches results for a short time to optimize performance. You may request higher consistency to inform the server that higher consistency should be preferred at the expense of increased latency. Care should be taken when requesting higher consistency due to the increased latency. json { \"tuple_key\": { \"user\": \"group:finance#member\", \"relation\": \"reader\", \"object\": \"document:2021-budget\" }, \"consistency\": \"HIGHER_CONSISTENCY\" }

Examples

require 'time'
require 'openfga'

api_instance = OpenFga::OpenFgaApi.new
store_id = 'store_id_example' # String | 
body = OpenFga::CheckRequest.new({tuple_key: OpenFga::CheckRequestTupleKey.new({user: 'user:anne', relation: 'reader', object: 'document:2021-budget'})}) # CheckRequest | 

begin
  # Check whether a user is authorized to access an object
  result = api_instance.check(store_id, body)
  p result
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->check: #{e}"
end

Using the check_with_http_info variant

This returns an Array which contains the response data, status code and headers.

<Array(, Integer, Hash)> check_with_http_info(store_id, body)

begin
  # Check whether a user is authorized to access an object
  data, status_code, headers = api_instance.check_with_http_info(store_id, body)
  p status_code # => 2xx
  p headers # => { ... }
  p data # => <CheckResponse>
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->check_with_http_info: #{e}"
end

Parameters

Name	Type	Description	Notes
store_id	String
body	CheckRequest

Return type

CheckResponse

Authorization

No authorization required

HTTP request headers

Content-Type: application/json
Accept: application/json

create_store

create_store(body)

Create a store

Create a unique OpenFGA store which will be used to store authorization models and relationship tuples.

Examples

require 'time'
require 'openfga'

api_instance = OpenFga::OpenFgaApi.new
body = OpenFga::CreateStoreRequest.new({name: 'my-store-name'}) # CreateStoreRequest | 

begin
  # Create a store
  result = api_instance.create_store(body)
  p result
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->create_store: #{e}"
end

Using the create_store_with_http_info variant

This returns an Array which contains the response data, status code and headers.

<Array(, Integer, Hash)> create_store_with_http_info(body)

begin
  # Create a store
  data, status_code, headers = api_instance.create_store_with_http_info(body)
  p status_code # => 2xx
  p headers # => { ... }
  p data # => <CreateStoreResponse>
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->create_store_with_http_info: #{e}"
end

Parameters

Name	Type	Description	Notes
body	CreateStoreRequest

Return type

CreateStoreResponse

Authorization

No authorization required

HTTP request headers

Content-Type: application/json
Accept: application/json

delete_store

delete_store(store_id)

Delete a store

Delete an OpenFGA store. This does not delete the data associated with the store, like tuples or authorization models.

Examples

require 'time'
require 'openfga'

api_instance = OpenFga::OpenFgaApi.new
store_id = 'store_id_example' # String | 

begin
  # Delete a store
  api_instance.delete_store(store_id)
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->delete_store: #{e}"
end

Using the delete_store_with_http_info variant

This returns an Array which contains the response data (nil in this case), status code and headers.

<Array(nil, Integer, Hash)> delete_store_with_http_info(store_id)

begin
  # Delete a store
  data, status_code, headers = api_instance.delete_store_with_http_info(store_id)
  p status_code # => 2xx
  p headers # => { ... }
  p data # => nil
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->delete_store_with_http_info: #{e}"
end

Parameters

Name	Type	Description	Notes
store_id	String

Return type

nil (empty response body)

Authorization

No authorization required

HTTP request headers

Content-Type: Not defined
Accept: application/json

expand

expand(store_id, body)

Expand all relationships in userset tree format, and following userset rewrite rules. Useful to reason about and debug a certain relationship

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.object and tuple_key.relation are all required. A contextual_tuples object may also be included in the body of the request. This object contains one field tuple_keys, which is an array of tuple keys. Each of these tuples may have an associated condition. The response will return a tree whose leaves are the specific users and usersets. Union, intersection and difference operator are located in the intermediate nodes. ## Example To expand all users that have the reader relationship with object document:2021-budget, use the Expand API with the following request body json { \"tuple_key\": { \"object\": \"document:2021-budget\", \"relation\": \"reader\" }, \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\" } OpenFGA's response will be a userset tree of the users and usersets that have read access to the document. json { \"tree\":{ \"root\":{ \"type\":\"document:2021-budget#reader\", \"union\":{ \"nodes\":[ { \"type\":\"document:2021-budget#reader\", \"leaf\":{ \"users\":{ \"users\":[ \"user:bob\" ] } } }, { \"type\":\"document:2021-budget#reader\", \"leaf\":{ \"computed\":{ \"userset\":\"document:2021-budget#writer\" } } } ] } } } } The caller can then call expand API for the writer relationship for the document:2021-budget. ### Expand Request with Contextual Tuples Given the model python model schema 1.1 type user type folder relations define owner: [user] type document relations define parent: [folder] define viewer: [user] or writer define writer: [user] or owner from parent and the initial tuples json [{ \"user\": \"user:bob\", \"relation\": \"owner\", \"object\": \"folder:1\" }] To expand all writers of document:1 when document:1 is put in folder:1, the first call could be json { \"tuple_key\": { \"object\": \"document:1\", \"relation\": \"writer\" }, \"contextual_tuples\": { \"tuple_keys\": [ { \"user\": \"folder:1\", \"relation\": \"parent\", \"object\": \"document:1\" } ] } } this returns: json { \"tree\": { \"root\": { \"name\": \"document:1#writer\", \"union\": { \"nodes\": [ { \"name\": \"document:1#writer\", \"leaf\": { \"users\": { \"users\": [] } } }, { \"name\": \"document:1#writer\", \"leaf\": { \"tupleToUserset\": { \"tupleset\": \"document:1#parent\", \"computed\": [ { \"userset\": \"folder:1#owner\" } ] } } } ] } } } } This tells us that the owner of folder:1 may also be a writer. So our next call could be to find the owners of folder:1 json { \"tuple_key\": { \"object\": \"folder:1\", \"relation\": \"owner\" } } which gives json { \"tree\": { \"root\": { \"name\": \"folder:1#owner\", \"leaf\": { \"users\": { \"users\": [ \"user:bob\" ] } } } } }

Examples

require 'time'
require 'openfga'

api_instance = OpenFga::OpenFgaApi.new
store_id = 'store_id_example' # String | 
body = OpenFga::ExpandRequest.new({tuple_key: OpenFga::ExpandRequestTupleKey.new({relation: 'reader', object: 'document:2021-budget'})}) # ExpandRequest | 

begin
  # Expand all relationships in userset tree format, and following userset rewrite rules.  Useful to reason about and debug a certain relationship
  result = api_instance.expand(store_id, body)
  p result
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->expand: #{e}"
end

Using the expand_with_http_info variant

This returns an Array which contains the response data, status code and headers.

<Array(, Integer, Hash)> expand_with_http_info(store_id, body)

begin
  # Expand all relationships in userset tree format, and following userset rewrite rules.  Useful to reason about and debug a certain relationship
  data, status_code, headers = api_instance.expand_with_http_info(store_id, body)
  p status_code # => 2xx
  p headers # => { ... }
  p data # => <ExpandResponse>
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->expand_with_http_info: #{e}"
end

Parameters

Name	Type	Description	Notes
store_id	String
body	ExpandRequest

Return type

ExpandResponse

Authorization

No authorization required

HTTP request headers

Content-Type: application/json
Accept: application/json

get_store

get_store(store_id)

Get a store

Returns an OpenFGA store by its identifier

Examples

require 'time'
require 'openfga'

api_instance = OpenFga::OpenFgaApi.new
store_id = 'store_id_example' # String | 

begin
  # Get a store
  result = api_instance.get_store(store_id)
  p result
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->get_store: #{e}"
end

Using the get_store_with_http_info variant

This returns an Array which contains the response data, status code and headers.

<Array(, Integer, Hash)> get_store_with_http_info(store_id)

begin
  # Get a store
  data, status_code, headers = api_instance.get_store_with_http_info(store_id)
  p status_code # => 2xx
  p headers # => { ... }
  p data # => <GetStoreResponse>
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->get_store_with_http_info: #{e}"
end

Parameters

Name	Type	Description	Notes
store_id	String

Return type

GetStoreResponse

Authorization

No authorization required

HTTP request headers

Content-Type: Not defined
Accept: application/json

list_objects

list_objects(store_id, body)

List all objects of the given type that the user has a relation with

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 implicit tuples that exist by virtue of applying set theory (such as document:2021-budget#viewer@document:2021-budget#viewer; the set of users who are viewers of document:2021-budget are the set of users who are the viewers of document:2021-budget). An authorization_model_id may be specified in the body. If it is not specified, the latest authorization model ID will be used. It is strongly recommended to specify authorization model id for better performance. You may also specify contextual_tuples that will be treated as regular tuples. Each of these tuples may have an associated condition. You may also provide a context object that will be used to evaluate the conditioned tuples in the system. It is strongly recommended to provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly. By default, the Check API caches results for a short time to optimize performance. You may specify a value of HIGHER_CONSISTENCY for the optional consistency parameter in the body to inform the server that higher conisistency is preferred at the expense of increased latency. Consideration should be given to the increased latency if requesting higher consistency. The response will contain the related objects in an array in the "objects" field of the response and they will be strings in the object format <type>:<id> (e.g. "document:roadmap"). The number of objects in the response array will be limited by the execution timeout specified in the flag OPENFGA_LIST_OBJECTS_DEADLINE and by the upper bound specified in the flag OPENFGA_LIST_OBJECTS_MAX_RESULTS, whichever is hit first. The objects given will not be sorted, and therefore two identical calls can give a given different set of objects.

Examples

require 'time'
require 'openfga'

api_instance = OpenFga::OpenFgaApi.new
store_id = 'store_id_example' # String | 
body = OpenFga::ListObjectsRequest.new({type: 'document', relation: 'reader', user: 'user:anne'}) # ListObjectsRequest | 

begin
  # List all objects of the given type that the user has a relation with
  result = api_instance.list_objects(store_id, body)
  p result
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->list_objects: #{e}"
end

Using the list_objects_with_http_info variant

This returns an Array which contains the response data, status code and headers.

<Array(, Integer, Hash)> list_objects_with_http_info(store_id, body)

begin
  # List all objects of the given type that the user has a relation with
  data, status_code, headers = api_instance.list_objects_with_http_info(store_id, body)
  p status_code # => 2xx
  p headers # => { ... }
  p data # => <ListObjectsResponse>
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->list_objects_with_http_info: #{e}"
end

Parameters

Name	Type	Description	Notes
store_id	String
body	ListObjectsRequest

Return type

ListObjectsResponse

Authorization

No authorization required

HTTP request headers

Content-Type: application/json
Accept: application/json

list_stores

list_stores(opts)

List all stores

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.

Examples

require 'time'
require 'openfga'

api_instance = OpenFga::OpenFgaApi.new
opts = {
  page_size: 56, # Integer | 
  continuation_token: 'continuation_token_example', # String | 
  name: 'name_example' # String | The name parameter instructs the API to only include results that match that name.Multiple results may be returned. Only exact matches will be returned; substring matches and regexes will not be evaluated
}

begin
  # List all stores
  result = api_instance.list_stores(opts)
  p result
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->list_stores: #{e}"
end

Using the list_stores_with_http_info variant

This returns an Array which contains the response data, status code and headers.

<Array(, Integer, Hash)> list_stores_with_http_info(opts)

begin
  # List all stores
  data, status_code, headers = api_instance.list_stores_with_http_info(opts)
  p status_code # => 2xx
  p headers # => { ... }
  p data # => <ListStoresResponse>
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->list_stores_with_http_info: #{e}"
end

Parameters

Name	Type	Description	Notes
page_size	Integer		[optional]
continuation_token	String		[optional]
name	String	The name parameter instructs the API to only include results that match that name.Multiple results may be returned. Only exact matches will be returned; substring matches and regexes will not be evaluated	[optional]

Return type

ListStoresResponse

Authorization

No authorization required

HTTP request headers

Content-Type: Not defined
Accept: application/json

list_users

list_users(store_id, body)

List the users matching the provided filter who have a certain relation to a particular type.

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, and implicit tuples that exist by virtue of applying set theory (such as document:2021-budget#viewer@document:2021-budget#viewer; the set of users who are viewers of document:2021-budget are the set of users who are the viewers of document:2021-budget). An authorization_model_id may be specified in the body. If it is not specified, the latest authorization model ID will be used. It is strongly recommended to specify authorization model id for better performance. You may also specify contextual_tuples that will be treated as regular tuples. Each of these tuples may have an associated condition. You may also provide a context object that will be used to evaluate the conditioned tuples in the system. It is strongly recommended to provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly. The response will contain the related users in an array in the "users" field of the response. These results may include specific objects, usersets or type-bound public access. Each of these types of results is encoded in its own type and not represented as a string.In cases where a type-bound public access result is returned (e.g. user:*), it cannot be inferred that all subjects of that type have a relation to the object; it is possible that negations exist and checks should still be queried on individual subjects to ensure access to that document.The number of users in the response array will be limited by the execution timeout specified in the flag OPENFGA_LIST_USERS_DEADLINE and by the upper bound specified in the flag OPENFGA_LIST_USERS_MAX_RESULTS, whichever is hit first. The returned users will not be sorted, and therefore two identical calls may yield different sets of users.

Examples

require 'time'
require 'openfga'

api_instance = OpenFga::OpenFgaApi.new
store_id = 'store_id_example' # String | 
body = OpenFga::ListUsersRequest.new({object: OpenFga::FgaObject.new({type: 'document', id: '0bcdf6fa-a6aa-4730-a8eb-9cf172ff16d9'}), relation: 'reader', user_filters: [{type=user},  {type=group,  relation=member}]}) # ListUsersRequest | 

begin
  # List the users matching the provided filter who have a certain relation to a particular type.
  result = api_instance.list_users(store_id, body)
  p result
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->list_users: #{e}"
end

Using the list_users_with_http_info variant

This returns an Array which contains the response data, status code and headers.

<Array(, Integer, Hash)> list_users_with_http_info(store_id, body)

begin
  # List the users matching the provided filter who have a certain relation to a particular type.
  data, status_code, headers = api_instance.list_users_with_http_info(store_id, body)
  p status_code # => 2xx
  p headers # => { ... }
  p data # => <ListUsersResponse>
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->list_users_with_http_info: #{e}"
end

Parameters

Name	Type	Description	Notes
store_id	String
body	ListUsersRequest

Return type

ListUsersResponse

Authorization

No authorization required

HTTP request headers

Content-Type: application/json
Accept: application/json

read

read(store_id, body)

Get tuples from the store that matches a query, without following userset rewrite rules

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 tuples that are stored in the system and satisfy the query. In the body: 1. tuple_key is optional. If not specified, it will return all tuples in the store. 2. tuple_key.object is mandatory if tuple_key is specified. It can be a full object (e.g., type:object_id) or type only (e.g., type:). 3. tuple_key.user is mandatory if tuple_key is specified in the case the tuple_key.object is a type only. If tuple_key.user is specified, it needs to be a full object (e.g., type:user_id). ## Examples ### Query for all objects in a type definition To query for all objects that user:bob has reader relationship in the document type definition, call read API with body of json { \"tuple_key\": { \"user\": \"user:bob\", \"relation\": \"reader\", \"object\": \"document:\" } } The API will return tuples and a continuation token, something like json { \"tuples\": [ { \"key\": { \"user\": \"user:bob\", \"relation\": \"reader\", \"object\": \"document:2021-budget\" }, \"timestamp\": \"2021-10-06T15:32:11.128Z\" } ], \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\" } This means that user:bob has a reader relationship with 1 document document:2021-budget. Note that this API, unlike the List Objects API, does not evaluate the tuples in the store. The continuation token will be empty if there are no more tuples to query. ### Query for all stored relationship tuples that have a particular relation and object To query for all users that have reader relationship with document:2021-budget, call read API with body of json { \"tuple_key\": { \"object\": \"document:2021-budget\", \"relation\": \"reader\" } } The API will return something like json { \"tuples\": [ { \"key\": { \"user\": \"user:bob\", \"relation\": \"reader\", \"object\": \"document:2021-budget\" }, \"timestamp\": \"2021-10-06T15:32:11.128Z\" } ], \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\" } This means that document:2021-budget has 1 reader (user:bob). Note that, even if the model said that all writers are also readers, the API will not return writers such as user:anne because it only returns tuples and does not evaluate them. ### Query for all users with all relationships for a particular document To query for all users that have any relationship with document:2021-budget, call read API with body of json { \"tuple_key\": { \"object\": \"document:2021-budget\" } } The API will return something like json { \"tuples\": [ { \"key\": { \"user\": \"user:anne\", \"relation\": \"writer\", \"object\": \"document:2021-budget\" }, \"timestamp\": \"2021-10-05T13:42:12.356Z\" }, { \"key\": { \"user\": \"user:bob\", \"relation\": \"reader\", \"object\": \"document:2021-budget\" }, \"timestamp\": \"2021-10-06T15:32:11.128Z\" } ], \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\" } This means that document:2021-budget has 1 reader (user:bob) and 1 writer (user:anne).

Examples

require 'time'
require 'openfga'

api_instance = OpenFga::OpenFgaApi.new
store_id = 'store_id_example' # String | 
body = OpenFga::ReadRequest.new # ReadRequest | 

begin
  # Get tuples from the store that matches a query, without following userset rewrite rules
  result = api_instance.read(store_id, body)
  p result
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->read: #{e}"
end

Using the read_with_http_info variant

This returns an Array which contains the response data, status code and headers.

<Array(, Integer, Hash)> read_with_http_info(store_id, body)

begin
  # Get tuples from the store that matches a query, without following userset rewrite rules
  data, status_code, headers = api_instance.read_with_http_info(store_id, body)
  p status_code # => 2xx
  p headers # => { ... }
  p data # => <ReadResponse>
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->read_with_http_info: #{e}"
end

Parameters

Name	Type	Description	Notes
store_id	String
body	ReadRequest

Return type

ReadResponse

Authorization

No authorization required

HTTP request headers

Content-Type: application/json
Accept: application/json

read_assertions

read_assertions(store_id, authorization_model_id)

Read assertions for an authorization model ID

The ReadAssertions API will return, for a given authorization model id, all the assertions stored for it.

Examples

require 'time'
require 'openfga'

api_instance = OpenFga::OpenFgaApi.new
store_id = 'store_id_example' # String | 
authorization_model_id = 'authorization_model_id_example' # String | 

begin
  # Read assertions for an authorization model ID
  result = api_instance.read_assertions(store_id, authorization_model_id)
  p result
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->read_assertions: #{e}"
end

Using the read_assertions_with_http_info variant

This returns an Array which contains the response data, status code and headers.

<Array(, Integer, Hash)> read_assertions_with_http_info(store_id, authorization_model_id)

begin
  # Read assertions for an authorization model ID
  data, status_code, headers = api_instance.read_assertions_with_http_info(store_id, authorization_model_id)
  p status_code # => 2xx
  p headers # => { ... }
  p data # => <ReadAssertionsResponse>
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->read_assertions_with_http_info: #{e}"
end

Parameters

Name	Type	Description	Notes
store_id	String
authorization_model_id	String

Return type

ReadAssertionsResponse

Authorization

No authorization required

HTTP request headers

Content-Type: Not defined
Accept: application/json

read_authorization_model

read_authorization_model(store_id, id)

Return a particular version of an authorization model

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, call the GET authorization-models by ID API with 01G5JAVJ41T49E9TT3SKVS7X1J as the id path parameter. The API will return: json { \"authorization_model\":{ \"id\":\"01G5JAVJ41T49E9TT3SKVS7X1J\", \"type_definitions\":[ { \"type\":\"user\" }, { \"type\":\"document\", \"relations\":{ \"reader\":{ \"union\":{ \"child\":[ { \"this\":{} }, { \"computedUserset\":{ \"object\":\"\", \"relation\":\"writer\" } } ] } }, \"writer\":{ \"this\":{} } } } ] } } In the above example, there are 2 types (user and document). The document type has 2 relations (writer and reader).

Examples

require 'time'
require 'openfga'

api_instance = OpenFga::OpenFgaApi.new
store_id = 'store_id_example' # String | 
id = 'id_example' # String | 

begin
  # Return a particular version of an authorization model
  result = api_instance.read_authorization_model(store_id, id)
  p result
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->read_authorization_model: #{e}"
end

Using the read_authorization_model_with_http_info variant

This returns an Array which contains the response data, status code and headers.

<Array(, Integer, Hash)> read_authorization_model_with_http_info(store_id, id)

begin
  # Return a particular version of an authorization model
  data, status_code, headers = api_instance.read_authorization_model_with_http_info(store_id, id)
  p status_code # => 2xx
  p headers # => { ... }
  p data # => <ReadAuthorizationModelResponse>
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->read_authorization_model_with_http_info: #{e}"
end

Parameters

Name	Type	Description	Notes
store_id	String
id	String

Return type

ReadAuthorizationModelResponse

Authorization

No authorization required

HTTP request headers

Content-Type: Not defined
Accept: application/json

read_authorization_models

read_authorization_models(store_id, opts)

Return all the authorization models for a particular store

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 been configured twice. To get all the authorization models that have been created in this store, call GET authorization-models. The API will return a response that looks like: json { \"authorization_models\": [ { \"id\": \"01G50QVV17PECNVAHX1GG4Y5NC\", \"type_definitions\": [...] }, { \"id\": \"01G4ZW8F4A07AKQ8RHSVG9RW04\", \"type_definitions\": [...] }, ], \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\" } If there are no more authorization models available, the continuation_token field will be empty json { \"authorization_models\": [ { \"id\": \"01G50QVV17PECNVAHX1GG4Y5NC\", \"type_definitions\": [...] }, { \"id\": \"01G4ZW8F4A07AKQ8RHSVG9RW04\", \"type_definitions\": [...] }, ], \"continuation_token\": \"\" }

Examples

require 'time'
require 'openfga'

api_instance = OpenFga::OpenFgaApi.new
store_id = 'store_id_example' # String | 
opts = {
  page_size: 56, # Integer | 
  continuation_token: 'continuation_token_example' # String | 
}

begin
  # Return all the authorization models for a particular store
  result = api_instance.read_authorization_models(store_id, opts)
  p result
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->read_authorization_models: #{e}"
end

Using the read_authorization_models_with_http_info variant

This returns an Array which contains the response data, status code and headers.

<Array(, Integer, Hash)> read_authorization_models_with_http_info(store_id, opts)

begin
  # Return all the authorization models for a particular store
  data, status_code, headers = api_instance.read_authorization_models_with_http_info(store_id, opts)
  p status_code # => 2xx
  p headers # => { ... }
  p data # => <ReadAuthorizationModelsResponse>
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->read_authorization_models_with_http_info: #{e}"
end

Parameters

Name	Type	Notes
store_id	String
page_size	Integer	[optional]
continuation_token	String	[optional]

Return type

ReadAuthorizationModelsResponse

Authorization

No authorization required

HTTP request headers

Content-Type: Not defined
Accept: application/json

read_changes

read_changes(store_id, opts)

Return a list of all the tuple changes

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 changes after the provided continuation token, the same token will be returned in order for it to be used when new changes are recorded. If the store never had any tuples added or removed, this token will be empty. You can use the type parameter to only get the list of tuple changes that affect objects of that type. When reading a write tuple change, if it was conditioned, the condition will be returned. When reading a delete tuple change, the condition will NOT be returned regardless of whether it was originally conditioned or not.

Examples

require 'time'
require 'openfga'

api_instance = OpenFga::OpenFgaApi.new
store_id = 'store_id_example' # String | 
opts = {
  type: 'type_example', # String | 
  page_size: 56, # Integer | 
  continuation_token: 'continuation_token_example', # String | 
  start_time: Time.parse('2013-10-20T19:20:30+01:00') # Time | Start date and time of changes to read. Format: ISO 8601 timestamp (e.g., 2022-01-01T00:00:00Z) If a continuation_token is provided along side start_time, the continuation_token will take precedence over start_time.
}

begin
  # Return a list of all the tuple changes
  result = api_instance.read_changes(store_id, opts)
  p result
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->read_changes: #{e}"
end

Using the read_changes_with_http_info variant

This returns an Array which contains the response data, status code and headers.

<Array(, Integer, Hash)> read_changes_with_http_info(store_id, opts)

begin
  # Return a list of all the tuple changes
  data, status_code, headers = api_instance.read_changes_with_http_info(store_id, opts)
  p status_code # => 2xx
  p headers # => { ... }
  p data # => <ReadChangesResponse>
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->read_changes_with_http_info: #{e}"
end

Parameters

Name	Type	Description	Notes
store_id	String
type	String		[optional]
page_size	Integer		[optional]
continuation_token	String		[optional]
start_time	Time	Start date and time of changes to read. Format: ISO 8601 timestamp (e.g., 2022-01-01T00:00:00Z) If a continuation_token is provided along side start_time, the continuation_token will take precedence over start_time.	[optional]

Return type

ReadChangesResponse

Authorization

No authorization required

HTTP request headers

Content-Type: Not defined
Accept: application/json

write

Object write(store_id, body)

Add or delete tuples from the store

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 tuples. When deleting a tuple, any condition specified with it is ignored. The API is not idempotent by default: if, later on, you try to add the same tuple key (even if the condition is different), or if you try to delete a non-existing tuple, it will throw an error. To allow writes when an identical tuple already exists in the database, set \"on_duplicate\": \"ignore\" on the writes object. To allow deletes when a tuple was already removed from the database, set \"on_missing\": \"ignore\" on the deletes object. If a Write request contains both idempotent (ignore) and non-idempotent (error) operations, the most restrictive action (error) will take precedence. If a condition fails for a sub-request with an error flag, the entire transaction will be rolled back. This gives developers explicit control over the atomicity of the requests. The API will not allow you to write tuples such as document:2021-budget#viewer@document:2021-budget#viewer, because they are implicit. An authorization_model_id may be specified in the body. If it is, it will be used to assert that each written tuple (not deleted) is valid for the model specified. If it is not specified, the latest authorization model ID will be used. ## Example ### Adding relationships To add user:anne as a writer for document:2021-budget, call write API with the following json { \"writes\": { \"tuple_keys\": [ { \"user\": \"user:anne\", \"relation\": \"writer\", \"object\": \"document:2021-budget\" } ], \"on_duplicate\": \"ignore\" }, \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\" } ### Removing relationships To remove user:bob as a reader for document:2021-budget, call write API with the following json { \"deletes\": { \"tuple_keys\": [ { \"user\": \"user:bob\", \"relation\": \"reader\", \"object\": \"document:2021-budget\" } ], \"on_missing\": \"ignore\" } }

Examples

require 'time'
require 'openfga'

api_instance = OpenFga::OpenFgaApi.new
store_id = 'store_id_example' # String | 
body = OpenFga::WriteRequest.new # WriteRequest | 

begin
  # Add or delete tuples from the store
  result = api_instance.write(store_id, body)
  p result
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->write: #{e}"
end

Using the write_with_http_info variant

This returns an Array which contains the response data, status code and headers.

<Array(Object, Integer, Hash)> write_with_http_info(store_id, body)

begin
  # Add or delete tuples from the store
  data, status_code, headers = api_instance.write_with_http_info(store_id, body)
  p status_code # => 2xx
  p headers # => { ... }
  p data # => Object
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->write_with_http_info: #{e}"
end

Parameters

Name	Type	Description	Notes
store_id	String
body	WriteRequest

Return type

Object

Authorization

No authorization required

HTTP request headers

Content-Type: application/json
Accept: application/json

write_assertions

write_assertions(store_id, authorization_model_id, body)

Upsert assertions for an authorization model ID

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 false, and optionally a list of contextual tuples.

Examples

require 'time'
require 'openfga'

api_instance = OpenFga::OpenFgaApi.new
store_id = 'store_id_example' # String | 
authorization_model_id = 'authorization_model_id_example' # String | 
body = OpenFga::WriteAssertionsRequest.new({assertions: [OpenFga::Assertion.new({tuple_key: OpenFga::AssertionTupleKey.new({object: 'document:2021-budget', relation: 'reader', user: 'user:anne'}), expectation: false})]}) # WriteAssertionsRequest | 

begin
  # Upsert assertions for an authorization model ID
  api_instance.write_assertions(store_id, authorization_model_id, body)
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->write_assertions: #{e}"
end

Using the write_assertions_with_http_info variant

This returns an Array which contains the response data (nil in this case), status code and headers.

<Array(nil, Integer, Hash)> write_assertions_with_http_info(store_id, authorization_model_id, body)

begin
  # Upsert assertions for an authorization model ID
  data, status_code, headers = api_instance.write_assertions_with_http_info(store_id, authorization_model_id, body)
  p status_code # => 2xx
  p headers # => { ... }
  p data # => nil
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->write_assertions_with_http_info: #{e}"
end

Parameters

Name	Type	Description	Notes
store_id	String
authorization_model_id	String
body	WriteAssertionsRequest

Return type

nil (empty response body)

Authorization

No authorization required

HTTP request headers

Content-Type: application/json
Accept: application/json

write_authorization_model

write_authorization_model(store_id, body)

Create a new authorization model

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. ## Example To add an authorization model with user and document type definitions, call POST authorization-models API with the body: json { \"type_definitions\":[ { \"type\":\"user\" }, { \"type\":\"document\", \"relations\":{ \"reader\":{ \"union\":{ \"child\":[ { \"this\":{} }, { \"computedUserset\":{ \"object\":\"\", \"relation\":\"writer\" } } ] } }, \"writer\":{ \"this\":{} } } } ] } OpenFGA's response will include the version id for this authorization model, which will look like {\"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"}

Examples

require 'time'
require 'openfga'

api_instance = OpenFga::OpenFgaApi.new
store_id = 'store_id_example' # String | 
body = OpenFga::WriteAuthorizationModelRequest.new({type_definitions: [OpenFga::TypeDefinition.new({type: 'document'})], schema_version: 'schema_version_example'}) # WriteAuthorizationModelRequest | 

begin
  # Create a new authorization model
  result = api_instance.write_authorization_model(store_id, body)
  p result
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->write_authorization_model: #{e}"
end

Using the write_authorization_model_with_http_info variant

This returns an Array which contains the response data, status code and headers.

<Array(, Integer, Hash)> write_authorization_model_with_http_info(store_id, body)

begin
  # Create a new authorization model
  data, status_code, headers = api_instance.write_authorization_model_with_http_info(store_id, body)
  p status_code # => 2xx
  p headers # => { ... }
  p data # => <WriteAuthorizationModelResponse>
rescue OpenFga::ApiError => e
  puts "Error when calling OpenFgaApi->write_authorization_model_with_http_info: #{e}"
end

Parameters

Name	Type	Description	Notes
store_id	String
body	WriteAuthorizationModelRequest

Content-Type: application/json
Accept: application/json