Before you start
- Node.js
- Go
- .NET
- Python
- Java
- CLI
- curl
- Deploy an instance of the OpenFGA server, and have ready the values for your setup: FGA_STORE_ID, FGA_API_URL and, if needed, FGA_API_TOKEN.
- You have installed the SDK.
- You have configured the authorization model and updated the relationship tuples.
- You have loaded
FGA_STORE_IDandFGA_API_URLas environment variables.
Step by step
Assume that you want to check whether useranne has relationship reader with object document:Z
01. Configure the OpenFGA API client
Before calling the check API, you will need to configure the API client.- Node.js
- Go
- .NET
- Python
- Java
- CLI
- curl
02. Calling Check API
To check whether useruser:anne has relationship reader with object document:Z
The result’s allowed field will be:
trueif the relationship exists.falseif the relation is defined in your model but no matching tuple exists.
400 Bad Request instead of false.
03. Calling Batch Check API
If you want to check multiple user-object-relationship combinations in a single request, you can use the Batch Check API endpoint. Batching authorization checks together in a single request significantly reduces overall network latency. The BatchCheck endpoint requires acorrelation_id parameter for each check. The correlation_id is used to “correlate” the check responses with the checks sent in the request, since tuple_keys and contextual_tuples are not returned in the response on purpose to reduce data transfer to improve network latency. A correlation_id can be composed of any string of alphanumeric characters or dashes between 1-36 characters in length. This means you can use:
- simple iterating integers
1,2,3,etc - UUID
e5fe049b-f252-40b3-b795-fe485d588279 - ULID
01JBMD9YG0XH3B4GVA8A9D2PSN - or some other unique string
correlation_id within a request must be unique.
If you are using one of our SDKs:
- the
correlation_idis inserted for you by default and automatically correlates theallowedresponse with the propertuple_key - if you pass in more checks than the server supports in a single call (default
50, configurable on the server), the SDK will automatically split and batch theBatchCheckrequests for you, how it does this can be configured using themaxBatchSizeandmaxParallelRequestsoptions in the SDK.
user:anne has multiple relationships writer and reader with object document:Z
The result will include an allowed field for each authorization check that will return true if the relationship exists and false if the relationship does not exist.
Configuring Batch Check
BatchCheck has two available configuration options:-
Limit the number of checks allowed in a single BatchCheck request.
- Environment variable:
OPENFGA_MAX_CHECKS_PER_BATCH_CHECK - Command line flag:
--max-checks-per-batch-check - If more items are received in a single request than allowed by this limit, the API will return an error.
- Environment variable:
-
Limit the number of Checks which can be resolved concurrently
- Environment variable:
OPENFGA_MAX_CONCURRENT_CHECKS_PER_BATCH_CHECK - Command line flag:
--max-concurrent-checks-per-batch-check
- Environment variable:
Related Sections
Take a look at the following section for more on how to perform authorization checks in your systemOpenFGA Check API
Read the Check API documentation and see how it works.
OpenFGA Batch Check API
Read the Batch Check API documentation and see how it works.