From edaa9e3df214dccbbedf0b885316e5ef8b1cc96f Mon Sep 17 00:00:00 2001 From: amanda-vanscoy Date: Thu, 24 Sep 2026 11:19:48 -0400 Subject: [PATCH 1/4] Update API endpoint summaries and descriptions --- docs/openapiv2/apidocs.swagger.json | 54 +++---- docs/openapiv3/apidocs.openapi.json | 54 +++---- openfga/v1/openfga_service.proto | 135 +++++++++-------- proto/openfga/v1/openfga_service.pb.go | 195 ++++++++++++++++--------- 4 files changed, 259 insertions(+), 179 deletions(-) diff --git a/docs/openapiv2/apidocs.swagger.json b/docs/openapiv2/apidocs.swagger.json index 5f3237a7..99cfc49c 100644 --- a/docs/openapiv2/apidocs.swagger.json +++ b/docs/openapiv2/apidocs.swagger.json @@ -764,8 +764,8 @@ }, "/stores/{store_id}/assertions/{authorization_model_id}": { "get": { - "summary": "Read assertions for an authorization model ID", - "description": "The ReadAssertions API will return, for a given authorization model id, all the assertions stored for it. ", + "summary": "Get authorization model ID assertions", + "description": "The ReadAssertions API returns all the assertions stored for a given authorization model id.", "operationId": "ReadAssertions", "responses": { "200": { @@ -836,7 +836,7 @@ ] }, "put": { - "summary": "Upsert assertions for an authorization model ID", + "summary": "Upsert authorization model ID assertions", "description": "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.", "operationId": "WriteAssertions", "responses": { @@ -915,8 +915,8 @@ }, "/stores/{store_id}/authorization-models": { "get": { - "summary": "Return all the authorization models for a particular store", - "description": "The ReadAuthorizationModels API will return all the authorization models for a certain store.\nOpenFGA's response will contain an array of all authorization models, sorted in descending order of creation.\n\n## Example\nAssume 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:\n```json\n{\n \"authorization_models\": [\n {\n \"id\": \"01G50QVV17PECNVAHX1GG4Y5NC\",\n \"type_definitions\": [...]\n },\n {\n \"id\": \"01G4ZW8F4A07AKQ8RHSVG9RW04\",\n \"type_definitions\": [...]\n },\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nIf there are no more authorization models available, the `continuation_token` field will be empty\n```json\n{\n \"authorization_models\": [\n {\n \"id\": \"01G50QVV17PECNVAHX1GG4Y5NC\",\n \"type_definitions\": [...]\n },\n {\n \"id\": \"01G4ZW8F4A07AKQ8RHSVG9RW04\",\n \"type_definitions\": [...]\n },\n ],\n \"continuation_token\": \"\"\n}\n```\n", + "summary": "Get all authorization models", + "description": "The ReadAuthorizationModels API returns all the authorization models for a certain store.\nOpenFGA's response contains an array of all authorization models, sorted in descending order of creation.\n\n## Example\nAssume 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:\n```json\n{\n \"authorization_models\": [\n {\n \"id\": \"01G50QVV17PECNVAHX1GG4Y5NC\",\n \"type_definitions\": [...]\n },\n {\n \"id\": \"01G4ZW8F4A07AKQ8RHSVG9RW04\",\n \"type_definitions\": [...]\n },\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nIf there are no more authorization models available, the `continuation_token` field will be empty\n```json\n{\n \"authorization_models\": [\n {\n \"id\": \"01G50QVV17PECNVAHX1GG4Y5NC\",\n \"type_definitions\": [...]\n },\n {\n \"id\": \"01G4ZW8F4A07AKQ8RHSVG9RW04\",\n \"type_definitions\": [...]\n },\n ],\n \"continuation_token\": \"\"\n}\n```\n", "operationId": "ReadAuthorizationModels", "responses": { "200": { @@ -995,7 +995,7 @@ }, "post": { "summary": "Create a new authorization model", - "description": "The WriteAuthorizationModel API will add a new authorization model to a store.\nEach item in the `type_definitions` array is a type definition as specified in the field `type_definition`.\nThe response will return the authorization model's ID in the `id` field.\n\n## Example\nTo add an authorization model with `user` and `document` type definitions, call POST authorization-models API with the body: \n```json\n{\n \"type_definitions\":[\n {\n \"type\":\"user\"\n },\n {\n \"type\":\"document\",\n \"relations\":{\n \"reader\":{\n \"union\":{\n \"child\":[\n {\n \"this\":{}\n },\n {\n \"computedUserset\":{\n \"object\":\"\",\n \"relation\":\"writer\"\n }\n }\n ]\n }\n },\n \"writer\":{\n \"this\":{}\n }\n }\n }\n ]\n}\n```\nOpenFGA's response will include the version id for this authorization model, which will look like \n```\n{\"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"}\n```\n", + "description": "The WriteAuthorizationModel API will add a new authorization model to a store.\nEach item in the `type_definitions` array is a type definition as specified in the field `type_definition`.\nThe response will return the authorization model's ID in the `id` field.\n\n## Example\nTo add an authorization model with `user` and `document` type definitions, call `POST` `authorization-models` API with the body: \n```json\n{\n \"type_definitions\":[\n {\n \"type\":\"user\"\n },\n {\n \"type\":\"document\",\n \"relations\":{\n \"reader\":{\n \"union\":{\n \"child\":[\n {\n \"this\":{}\n },\n {\n \"computedUserset\":{\n \"object\":\"\",\n \"relation\":\"writer\"\n }\n }\n ]\n }\n },\n \"writer\":{\n \"this\":{}\n }\n }\n }\n ]\n}\n```\nOpenFGA's response will include the version id for this authorization model, which will look like \n```\n{\"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"}\n```\n", "operationId": "WriteAuthorizationModel", "responses": { "201": { @@ -1070,8 +1070,8 @@ }, "/stores/{store_id}/authorization-models/{id}": { "get": { - "summary": "Return a particular version of an authorization model", - "description": "The ReadAuthorizationModel API returns an authorization model by its identifier.\nThe response will return the authorization model for the particular version.\n\n## Example\nTo 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:\n```json\n{\n \"authorization_model\":{\n \"id\":\"01G5JAVJ41T49E9TT3SKVS7X1J\",\n \"type_definitions\":[\n {\n \"type\":\"user\"\n },\n {\n \"type\":\"document\",\n \"relations\":{\n \"reader\":{\n \"union\":{\n \"child\":[\n {\n \"this\":{}\n },\n {\n \"computedUserset\":{\n \"object\":\"\",\n \"relation\":\"writer\"\n }\n }\n ]\n }\n },\n \"writer\":{\n \"this\":{}\n }\n }\n }\n ]\n }\n}\n```\nIn the above example, there are 2 types (`user` and `document`). The `document` type has 2 relations (`writer` and `reader`).", + "summary": "Get an authorization model by version", + "description": "The ReadAuthorizationModel API returns an authorization model by its identifier.\nThe response will return the authorization model for the particular version.\n\n## Example\nTo 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:\n```json\n{\n \"authorization_model\":{\n \"id\":\"01G5JAVJ41T49E9TT3SKVS7X1J\",\n \"type_definitions\":[\n {\n \"type\":\"user\"\n },\n {\n \"type\":\"document\",\n \"relations\":{\n \"reader\":{\n \"union\":{\n \"child\":[\n {\n \"this\":{}\n },\n {\n \"computedUserset\":{\n \"object\":\"\",\n \"relation\":\"writer\"\n }\n }\n ]\n }\n },\n \"writer\":{\n \"this\":{}\n }\n }\n }\n ]\n }\n}\n```\nIn the above example, there are 2 types (`user` and `document`). The `document` type has 2 relations (`writer` and `reader`).", "operationId": "ReadAuthorizationModel", "responses": { "200": { @@ -1144,8 +1144,8 @@ }, "/stores/{store_id}/batch-check": { "post": { - "summary": "Send a list of `check` operations in a single request", - "description": "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.\n\nAn 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}$`\n\nNOTE: The maximum number of checks that can be passed in the `BatchCheck` API is configurable via the [OPENFGA_MAX_CHECKS_PER_BATCH_CHECK](https://openfga.dev/docs/getting-started/setup-openfga/configuration#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.\n\nFor more details on how `Check` functions, see the docs for `/check`.\n\n### Examples\n#### A BatchCheckRequest\n```json\n{\n \"checks\": [\n {\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n \"relation\": \"reader\",\n \"user\": \"user:anne\",\n },\n \"contextual_tuples\": {...}\n \"context\": {}\n \"correlation_id\": \"01JA8PM3QM7VBPGB8KMPK8SBD5\"\n },\n {\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n \"relation\": \"reader\",\n \"user\": \"user:bob\",\n },\n \"contextual_tuples\": {...}\n \"context\": {}\n \"correlation_id\": \"01JA8PMM6A90NV5ET0F28CYSZQ\"\n }\n ]\n}\n```\n\nBelow 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:\n```json\n{\n \"result\": {\n \"01JA8PMM6A90NV5ET0F28CYSZQ\": {\n \"allowed\": false, \n \"error\": {\"message\": \"\"} \n },\n \"01JA8PM3QM7VBPGB8KMPK8SBD5\": {\n \"allowed\": true, \n \"error\": {\"message\": \"\"} \n }\n}\n```\n", + "summary": "Send a list of related operations", + "description": "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.\n\nAn 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}$`\n\n> **Note:** The maximum number of checks that can be passed in the `BatchCheck` API is configurable via the [OPENFGA_MAX_CHECKS_PER_BATCH_CHECK](https://openfga.dev/docs/getting-started/setup-openfga/configuration#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.\n\nFor more details on how `Check` functions, review the docs for `/check`.\n\n### Examples\n#### A BatchCheckRequest\n```json\n{\n \"checks\": [\n {\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n \"relation\": \"reader\",\n \"user\": \"user:anne\",\n },\n \"contextual_tuples\": {...}\n \"context\": {}\n \"correlation_id\": \"01JA8PM3QM7VBPGB8KMPK8SBD5\"\n },\n {\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n \"relation\": \"reader\",\n \"user\": \"user:bob\",\n },\n \"contextual_tuples\": {...}\n \"context\": {}\n \"correlation_id\": \"01JA8PMM6A90NV5ET0F28CYSZQ\"\n }\n ]\n}\n```\n\nBelow 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:\n```json\n{\n \"result\": {\n \"01JA8PMM6A90NV5ET0F28CYSZQ\": {\n \"allowed\": false, \n \"error\": {\"message\": \"\"} \n },\n \"01JA8PM3QM7VBPGB8KMPK8SBD5\": {\n \"allowed\": true, \n \"error\": {\"message\": \"\"} \n }\n}\n```\n", "operationId": "BatchCheck", "responses": { "200": { @@ -1220,7 +1220,7 @@ }, "/stores/{store_id}/changes": { "get": { - "summary": "Return a list of all the tuple changes", + "summary": "Get all tuple changes", "description": "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.\nYou can use the `type` parameter to only get the list of tuple changes that affect objects of that type.\nWhen reading a write tuple change, if it was conditioned, the condition will be returned.\nWhen reading a delete tuple change, the condition will NOT be returned regardless of whether it was originally conditioned or not.\n", "operationId": "ReadChanges", "responses": { @@ -1315,8 +1315,8 @@ }, "/stores/{store_id}/check": { "post": { - "summary": "Check whether a user is authorized to access an object", - "description": "The Check API returns whether a given user has a relationship with a given object in a given store.\nThe `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:*`.\nTo 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`).\nA `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`.\nYou 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.\nYou 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.\nBy 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.\nThe response will return whether the relationship exists in the field `allowed`.\n\nSome 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. \nFor 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.\n## Examples\n### Querying with contextual tuples\nIn order to check if user `user:anne` of type `user` has a `reader` relationship with object `document:2021-budget` given the following contextual tuple\n```json\n{\n \"user\": \"user:anne\",\n \"relation\": \"member\",\n \"object\": \"time_slot:office_hours\"\n}\n```\nthe Check API can be used with the following request body:\n```json\n{\n \"tuple_key\": {\n \"user\": \"user:anne\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"contextual_tuples\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:anne\",\n \"relation\": \"member\",\n \"object\": \"time_slot:office_hours\"\n }\n ]\n },\n \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n}\n```\n### Querying usersets\nSome Checks will always return `true`, even without any tuples. For example, for the following authorization model\n```python\nmodel\n schema 1.1\ntype user\ntype document\n relations\n define reader: [user]\n```\nthe following query\n```json\n{\n \"tuple_key\": {\n \"user\": \"document:2021-budget#reader\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n }\n}\n```\nwill 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`.\n### Querying usersets with difference in the model\nA Check for a userset can yield results that must be treated carefully if the model involves difference. For example, for the following authorization model\n```python\nmodel\n schema 1.1\ntype user\ntype group\n relations\n define member: [user]\ntype document\n relations\n define blocked: [user]\n define reader: [group#member] but not blocked\n```\nthe following query\n```json\n{\n \"tuple_key\": {\n \"user\": \"group:finance#member\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"contextual_tuples\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:anne\",\n \"relation\": \"member\",\n \"object\": \"group:finance\"\n },\n {\n \"user\": \"group:finance#member\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n {\n \"user\": \"user:anne\",\n \"relation\": \"blocked\",\n \"object\": \"document:2021-budget\"\n }\n ]\n },\n}\n```\nwill return `{ \"allowed\": true }`, even though a specific user of the userset `group:finance#member` does not have the `reader` relationship with the given object.\n### Requesting higher consistency\nBy 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.\n```json\n{\n \"tuple_key\": {\n \"user\": \"group:finance#member\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"consistency\": \"HIGHER_CONSISTENCY\"\n}\n```\n", + "summary": "Check user authorization", + "description": "The Check API returns whether a given user has a relationship with a given object in a given store.\n\nThe `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:*`.\nTo arrive at a result, the API uses:\n\n- An authorization model\n\n- Explicit tuples written through the Write API\n\n- Contextual tuples present in the request\n\n- Implicit tuples that exist by virtue of applying set theory\n\nFor example: `document:2021-budget#viewer@document:2021-budget#viewer`. In this example, the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`).\n\nA `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`.\nYou 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.\n\n> **Note:** We recommend you specify authorization model id for better performance.\n\nYou may also provide a `context` object that will be used to evaluate the conditioned tuples in the system.\n\n> **Note:** We recommend you provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.\n\nBy 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.\nThe response will return whether the relationship exists in the field `allowed`.\n\nSome 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. \nFor 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.\n## Examples\n### Querying with contextual tuples\nIn order to check if user `user:anne` of type `user` has a `reader` relationship with object `document:2021-budget` given the following contextual tuple\n```json\n{\n \"user\": \"user:anne\",\n \"relation\": \"member\",\n \"object\": \"time_slot:office_hours\"\n}\n```\nthe Check API can be used with the following request body:\n```json\n{\n \"tuple_key\": {\n \"user\": \"user:anne\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"contextual_tuples\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:anne\",\n \"relation\": \"member\",\n \"object\": \"time_slot:office_hours\"\n }\n ]\n },\n \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n}\n```\n### Querying usersets\nSome Checks will always return `true`, even without any tuples. For example, for the following authorization model\n```python\nmodel\n schema 1.1\ntype user\ntype document\n relations\n define reader: [user]\n```\nthe following query\n```json\n{\n \"tuple_key\": {\n \"user\": \"document:2021-budget#reader\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n }\n}\n```\nwill 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`.\n### Querying usersets with difference in the model\nA Check for a userset can yield results that must be treated carefully if the model involves difference. For example, for the following authorization model\n```python\nmodel\n schema 1.1\ntype user\ntype group\n relations\n define member: [user]\ntype document\n relations\n define blocked: [user]\n define reader: [group#member] but not blocked\n```\nthe following query\n```json\n{\n \"tuple_key\": {\n \"user\": \"group:finance#member\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"contextual_tuples\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:anne\",\n \"relation\": \"member\",\n \"object\": \"group:finance\"\n },\n {\n \"user\": \"group:finance#member\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n {\n \"user\": \"user:anne\",\n \"relation\": \"blocked\",\n \"object\": \"document:2021-budget\"\n }\n ]\n },\n}\n```\nwill return `{ \"allowed\": true }`, even though a specific user of the userset `group:finance#member` does not have the `reader` relationship with the given object.\n### Requesting higher consistency\nBy 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.\n```json\n{\n \"tuple_key\": {\n \"user\": \"group:finance#member\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"consistency\": \"HIGHER_CONSISTENCY\"\n}\n```\n", "operationId": "Check", "responses": { "200": { @@ -1391,8 +1391,8 @@ }, "/stores/{store_id}/expand": { "post": { - "summary": "Expand all relationships in userset tree format, and following userset rewrite rules. Useful to reason about and debug a certain relationship", - "description": "The Expand API will return all users and usersets that have certain relationship with an object in a certain store.\nThis is different from the `/stores/{store_id}/read` API in that both users and computed usersets are returned.\nBody parameters `tuple_key.object` and `tuple_key.relation` are all required.\nA `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`.\nThe response will return a tree whose leaves are the specific users and usersets. Union, intersection and difference operator are located in the intermediate nodes.\n\n## Example\nTo expand all users that have the `reader` relationship with object `document:2021-budget`, use the Expand API with the following request body\n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\",\n \"relation\": \"reader\"\n },\n \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n}\n```\nOpenFGA's response will be a userset tree of the users and usersets that have read access to the document.\n```json\n{\n \"tree\":{\n \"root\":{\n \"type\":\"document:2021-budget#reader\",\n \"union\":{\n \"nodes\":[\n {\n \"type\":\"document:2021-budget#reader\",\n \"leaf\":{\n \"users\":{\n \"users\":[\n \"user:bob\"\n ]\n }\n }\n },\n {\n \"type\":\"document:2021-budget#reader\",\n \"leaf\":{\n \"computed\":{\n \"userset\":\"document:2021-budget#writer\"\n }\n }\n }\n ]\n }\n }\n }\n}\n```\nThe caller can then call expand API for the `writer` relationship for the `document:2021-budget`.\n### Expand Request with Contextual Tuples\n\nGiven the model\n```python\nmodel\n schema 1.1\n\ntype user\n\ntype folder\n relations\n define owner: [user]\n\ntype document\n relations\n define parent: [folder]\n define viewer: [user] or writer\n define writer: [user] or owner from parent\n```\nand the initial tuples\n```json\n[{\n \"user\": \"user:bob\",\n \"relation\": \"owner\",\n \"object\": \"folder:1\"\n}]\n```\n\nTo expand all `writers` of `document:1` when `document:1` is put in `folder:1`, the first call could be\n\n```json\n{\n \"tuple_key\": {\n \"object\": \"document:1\",\n \"relation\": \"writer\"\n },\n \"contextual_tuples\": {\n \"tuple_keys\": [\n {\n \"user\": \"folder:1\",\n \"relation\": \"parent\",\n \"object\": \"document:1\"\n }\n ]\n }\n}\n```\nthis returns:\n```json\n{\n \"tree\": {\n \"root\": {\n \"name\": \"document:1#writer\",\n \"union\": {\n \"nodes\": [\n {\n \"name\": \"document:1#writer\",\n \"leaf\": {\n \"users\": {\n \"users\": []\n }\n }\n },\n {\n \"name\": \"document:1#writer\",\n \"leaf\": {\n \"tupleToUserset\": {\n \"tupleset\": \"document:1#parent\",\n \"computed\": [\n {\n \"userset\": \"folder:1#owner\"\n }\n ]\n }\n }\n }\n ]\n }\n }\n }\n}\n```\nThis 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`\n```json\n{\n \"tuple_key\": {\n \"object\": \"folder:1\",\n \"relation\": \"owner\"\n }\n}\n```\nwhich gives\n```json\n{\n \"tree\": {\n \"root\": {\n \"name\": \"folder:1#owner\",\n \"leaf\": {\n \"users\": {\n \"users\": [\n \"user:bob\"\n ]\n }\n }\n }\n }\n}\n```\n", + "summary": "Expand relationships in userset tree format", + "description": "The Expand API will return all users and usersets that have certain relationship with an object in a certain store.\nThis is different from the `/stores/{store_id}/read` API in that both users and computed usersets are returned.\n\nBody parameters `tuple_key.object` and `tuple_key.relation` are all required.\nA `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`.\nThe response will return a tree whose leaves are the specific users and usersets. Union, intersection and difference operator are located in the intermediate nodes.\n\n## Example\nTo expand all users that have the `reader` relationship with object `document:2021-budget`, use the Expand API with the following request body\n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\",\n \"relation\": \"reader\"\n },\n \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n}\n```\nOpenFGA's response will be a userset tree of the users and usersets that have read access to the document.\n```json\n{\n \"tree\":{\n \"root\":{\n \"type\":\"document:2021-budget#reader\",\n \"union\":{\n \"nodes\":[\n {\n \"type\":\"document:2021-budget#reader\",\n \"leaf\":{\n \"users\":{\n \"users\":[\n \"user:bob\"\n ]\n }\n }\n },\n {\n \"type\":\"document:2021-budget#reader\",\n \"leaf\":{\n \"computed\":{\n \"userset\":\"document:2021-budget#writer\"\n }\n }\n }\n ]\n }\n }\n }\n}\n```\nThe caller can then call expand API for the `writer` relationship for the `document:2021-budget`.\n### Expand Request with Contextual Tuples\n\nGiven the model\n```python\nmodel\n schema 1.1\n\ntype user\n\ntype folder\n relations\n define owner: [user]\n\ntype document\n relations\n define parent: [folder]\n define viewer: [user] or writer\n define writer: [user] or owner from parent\n```\nand the initial tuples\n```json\n[{\n \"user\": \"user:bob\",\n \"relation\": \"owner\",\n \"object\": \"folder:1\"\n}]\n```\n\nTo expand all `writers` of `document:1` when `document:1` is put in `folder:1`, the first call could be\n\n```json\n{\n \"tuple_key\": {\n \"object\": \"document:1\",\n \"relation\": \"writer\"\n },\n \"contextual_tuples\": {\n \"tuple_keys\": [\n {\n \"user\": \"folder:1\",\n \"relation\": \"parent\",\n \"object\": \"document:1\"\n }\n ]\n }\n}\n```\nthis returns:\n```json\n{\n \"tree\": {\n \"root\": {\n \"name\": \"document:1#writer\",\n \"union\": {\n \"nodes\": [\n {\n \"name\": \"document:1#writer\",\n \"leaf\": {\n \"users\": {\n \"users\": []\n }\n }\n },\n {\n \"name\": \"document:1#writer\",\n \"leaf\": {\n \"tupleToUserset\": {\n \"tupleset\": \"document:1#parent\",\n \"computed\": [\n {\n \"userset\": \"folder:1#owner\"\n }\n ]\n }\n }\n }\n ]\n }\n }\n }\n}\n```\nThis 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`\n```json\n{\n \"tuple_key\": {\n \"object\": \"folder:1\",\n \"relation\": \"owner\"\n }\n}\n```\nwhich gives\n```json\n{\n \"tree\": {\n \"root\": {\n \"name\": \"folder:1#owner\",\n \"leaf\": {\n \"users\": {\n \"users\": [\n \"user:bob\"\n ]\n }\n }\n }\n }\n}\n```\n", "operationId": "Expand", "responses": { "200": { @@ -1467,8 +1467,8 @@ }, "/stores/{store_id}/list-objects": { "post": { - "summary": "List all objects of the given type that the user has a relation with", - "description": "The ListObjects API returns a list of all the objects of the given type that the user has a relation with.\n 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`).\nAn `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.\nYou may also specify `contextual_tuples` that will be treated as regular tuples. Each of these tuples may have an associated `condition`.\nYou 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.\nBy 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.\nThe 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 `:` (e.g. \"document:roadmap\").\nThe 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.\nThe objects given will not be sorted, and therefore two identical calls can give a given different set of objects.", + "summary": "List all objects with user-centric relationship", + "description": "The ListObjects API returns a list of all the objects of the given type that the user has a relation with.\n To arrive at a result, the API uses:\n\n- An authorization model\n- Explicit tuples written through the Write API\n- Contextual tuples present in the request\n- Implicit tuples that exist by virtue of applying set theory. For example:\n\n`document:2021-budget#viewer@document:2021-budget#viewer`\n\nIn the example the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n\nAn `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID will be used.\n\n> **Note:** We recommend you specify authorization model ID for better performance.\n\nYou may also specify `contextual_tuples` that is treated as regular tuples. Each of these tuples may have an associated `condition`.\nYou may also provide a `context` object that is used to evaluate the conditioned tuples in the system.\n\n> **Note:** We recommend you provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.\n\nBy 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.\nThe response contains the related objects in an array in the \"objects\" field of the response and they will be strings in the object format `:` (e.g. \"document:roadmap\").\n\nThe 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.\nThe objects given will not be sorted, and therefore two identical calls can give a given different set of objects.", "operationId": "ListObjects", "responses": { "200": { @@ -1543,8 +1543,8 @@ }, "/stores/{store_id}/list-users": { "post": { - "summary": "List the users matching the provided filter who have a certain relation to a particular type.", - "description": "The ListUsers API returns a list of all the users of a specific type that have a relation to a given object.\n 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`).\nAn `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.\nYou may also specify `contextual_tuples` that will be treated as regular tuples. Each of these tuples may have an associated `condition`.\nYou 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.\nThe response will contain the related users in an array in the \"users\" field of the response. These results may include specific objects, usersets \nor 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\nof that type have a relation to the object; it is possible that negations exist and checks should still be queried\non 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.\nThe returned users will not be sorted, and therefore two identical calls may yield different sets of users.", + "summary": "List all users with a relationship to an object", + "description": "The ListUsers API returns a list of all the users of a specific type that have a relation to a given object.\n\n To arrive at a result, the API uses:\n\n- An authorization model\n\n- Explicit tuples written through the Write API\n\n- Contextual tuples present in the request\n\n- Implicit tuples that exist by virtue of applying set theory\n\nFor example: `document:2021-budget#viewer@document:2021-budget#viewer`. In this example, the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n\nAn `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID will be used.\n\n> **Note:** We recommend you specify authorization model ID for better performance.\n\nYou may also specify `contextual_tuples` that will be treated as regular tuples. Each of these tuples may have an associated `condition`.\nYou may also provide a `context` object that will be used to evaluate the conditioned tuples in the system.\n\n> **Note:** We recommend you provide a value for all the input parameters of all the conditions. This ensures that all tuples be evaluated correctly.\n\nThe response will contain the related users in an array in the \"users\" field of the response. These results may include specific objects, usersets \nor 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\nof that type have a relation to the object; it is possible that negations exist and checks should still be queried\non 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.\nThe returned users will not be sorted, and therefore two identical calls may yield different sets of users.", "operationId": "ListUsers", "responses": { "200": { @@ -1619,8 +1619,8 @@ }, "/stores/{store_id}/read": { "post": { - "summary": "Get tuples from the store that matches a query, without following userset rewrite rules", - "description": "The Read API will return the tuples for a certain store that match a query filter specified in the body of the request. \nThe API doesn't guarantee order by any field. \nIt 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. \nIn the body:\n1. `tuple_key` is optional. If not specified, it will return all tuples in the store.\n2. `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:`).\n3. `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`).\n## Examples\n### Query for all objects in a type definition\nTo query for all objects that `user:bob` has `reader` relationship in the `document` type definition, call read API with body of\n```json\n{\n \"tuple_key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:\"\n }\n}\n```\nThe API will return tuples and a continuation token, something like\n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis 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.\nThe continuation token will be empty if there are no more tuples to query.\n### Query for all stored relationship tuples that have a particular relation and object\nTo query for all users that have `reader` relationship with `document:2021-budget`, call read API with body of \n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\",\n \"relation\": \"reader\"\n }\n}\n```\nThe API will return something like \n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis 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.\n### Query for all users with all relationships for a particular document\nTo query for all users that have any relationship with `document:2021-budget`, call read API with body of \n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n }\n}\n```\nThe API will return something like \n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:anne\",\n \"relation\": \"writer\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-05T13:42:12.356Z\"\n },\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis means that `document:2021-budget` has 1 `reader` (`user:bob`) and 1 `writer` (`user:anne`).\n", + "summary": "Get related tuples", + "description": "The Read API will return the tuples from a certain store that match a query filter specified in the body of the request. \nThe API doesn't guarantee order by any field. \nIt 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. \nIn the body:\n1. `tuple_key` is optional. If not specified, it will return all tuples in the store.\n2. `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:`).\n3. `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`).\n\n## Examples\n### Query for all objects in a type definition\nTo query for all objects that `user:bob` has `reader` relationship in the `document` type definition, call read API with body of\n```json\n{\n \"tuple_key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:\"\n }\n}\n```\nThe API will return tuples and a continuation token, something like\n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis 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.\nThe continuation token will be empty if there are no more tuples to query.\n\n### Query for all stored relationship tuples that have a particular relation and object\nTo query for all users that have `reader` relationship with `document:2021-budget`, call read API with body of \n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\",\n \"relation\": \"reader\"\n }\n}\n```\nThe API will return something like \n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis 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.\n\n### Query for all users with all relationships for a particular document\nTo query for all users that have any relationship with `document:2021-budget`, call read API with body of \n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n }\n}\n```\nThe API will return something like \n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:anne\",\n \"relation\": \"writer\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-05T13:42:12.356Z\"\n },\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis means that `document:2021-budget` has 1 `reader` (`user:bob`) and 1 `writer` (`user:anne`).\n", "operationId": "Read", "responses": { "200": { @@ -1695,8 +1695,8 @@ }, "/stores/{store_id}/streamed-list-objects": { "post": { - "summary": "Stream all objects of the given type that the user has a relation with", - "description": "The Streamed ListObjects API is very similar to the the ListObjects API, with two differences: \n1. Instead of collecting all objects before returning a response, it streams them to the client as they are collected. \n2. The number of results returned is only limited by the execution timeout specified in the flag OPENFGA_LIST_OBJECTS_DEADLINE. \n", + "summary": "Stream all objects with a user relationship", + "description": "The Streamed ListObjects API is very similar to the the ListObjects API, with two differences: \n1. Instead of collecting all objects before returning a response, it streams them to the client as they are collected. \n2. The number of results returned is only limited by the execution timeout specified in the flag `OPENFGA_LIST_OBJECTS_DEADLINE`. \n", "operationId": "StreamedListObjects", "responses": { "200": { @@ -1780,8 +1780,8 @@ }, "/stores/{store_id}/write": { "post": { - "summary": "Add or delete tuples from the store", - "description": "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.\nIn the body, `writes` adds new tuples and `deletes` removes existing tuples. When deleting a tuple, any `condition` specified with it is ignored.\nThe 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.\nTo allow writes when an identical tuple already exists in the database, set `\"on_duplicate\": \"ignore\"` on the `writes` object.\nTo allow deletes when a tuple was already removed from the database, set `\"on_missing\": \"ignore\"` on the `deletes` object.\nIf 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.\nThe API will not allow you to write tuples such as `document:2021-budget#viewer@document:2021-budget#viewer`, because they are implicit.\nAn `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.\n## Example\n### Adding relationships\nTo add `user:anne` as a `writer` for `document:2021-budget`, call write API with the following \n```json\n{\n \"writes\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:anne\",\n \"relation\": \"writer\",\n \"object\": \"document:2021-budget\"\n }\n ],\n \"on_duplicate\": \"ignore\"\n },\n \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n}\n```\n### Removing relationships\nTo remove `user:bob` as a `reader` for `document:2021-budget`, call write API with the following \n```json\n{\n \"deletes\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n }\n ],\n \"on_missing\": \"ignore\"\n }\n}\n```\n", + "summary": "Add or delete tuples", + "description": "The Write API transactionally updates the tuples for a certain store. Tuples and type definitions allow OpenFGA to determine whether a relationship exists between an object and an user.\n\nIn the body, `writes` adds new tuples and `deletes` removes existing tuples. When deleting a tuple, any `condition` specified with it is ignored.\n\nThe 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.\n\nTo allow writes when an identical tuple already exists in the database, set `\"on_duplicate\": \"ignore\"` on the `writes` object.\nTo allow deletes when a tuple was already removed from the database, set `\"on_missing\": \"ignore\"` on the `deletes` object.\nIf 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.\n\nThe API will not allow you to write tuples such as `document:2021-budget#viewer@document:2021-budget#viewer`, because they are implicit.\nAn `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.\n\n## Example\n### Adding relationships\nTo add `user:anne` as a `writer` for `document:2021-budget`, call write API with the following \n```json\n{\n \"writes\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:anne\",\n \"relation\": \"writer\",\n \"object\": \"document:2021-budget\"\n }\n ],\n \"on_duplicate\": \"ignore\"\n },\n \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n}\n```\n### Removing relationships\nTo remove `user:bob` as a `reader` for `document:2021-budget`, call write API with the following \n```json\n{\n \"deletes\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n }\n ],\n \"on_missing\": \"ignore\"\n }\n}\n```\n", "operationId": "Write", "responses": { "200": { @@ -2762,7 +2762,7 @@ }, "consistency": { "$ref": "#/definitions/ConsistencyPreference", - "description": "Controls the consistency preference for this request. Default value is UNSPECIFIED, which will have the same behavior as MINIMIZE_LATENCY." + "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which will have the same behavior as MINIMIZE_LATENCY." } }, "required": [ @@ -2953,7 +2953,7 @@ "NULL_VALUE" ], "default": "NULL_VALUE", - "description": "`NullValue` is a singleton enumeration to represent the null value for the\n`Value` type union.\n\nThe JSON representation for `NullValue` is JSON `null`.\n\n - NULL_VALUE: Null value." + "description": "Represents a JSON `null`.\n\n`NullValue` is a sentinel, using an enum with only one value to represent\nthe null value for the `Value` type union.\n\nA field of type `NullValue` with any value other than `0` is considered\ninvalid. Most ProtoJSON serializers will emit a Value with a `null_value` set\nas a JSON `null` regardless of the integer value, and so will round trip to\na `0` value.\n\n - NULL_VALUE: Null value." }, "Object": { "type": "object", diff --git a/docs/openapiv3/apidocs.openapi.json b/docs/openapiv3/apidocs.openapi.json index 7b837bab..079b1865 100644 --- a/docs/openapiv3/apidocs.openapi.json +++ b/docs/openapiv3/apidocs.openapi.json @@ -967,7 +967,7 @@ "$ref": "#/components/schemas/ConsistencyPreference" }, { - "description": "Controls the consistency preference for this request. Default value is UNSPECIFIED, which will have the same behavior as MINIMIZE_LATENCY." + "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which will have the same behavior as MINIMIZE_LATENCY." } ] }, @@ -1220,7 +1220,7 @@ }, "NullValue": { "default": "NULL_VALUE", - "description": "`NullValue` is a singleton enumeration to represent the null value for the\n`Value` type union.\n\nThe JSON representation for `NullValue` is JSON `null`.\n\n - NULL_VALUE: Null value.", + "description": "Represents a JSON `null`.\n\n`NullValue` is a sentinel, using an enum with only one value to represent\nthe null value for the `Value` type union.\n\nA field of type `NullValue` with any value other than `0` is considered\ninvalid. Most ProtoJSON serializers will emit a Value with a `null_value` set\nas a JSON `null` regardless of the integer value, and so will round trip to\na `0` value.\n\n - NULL_VALUE: Null value.", "enum": [ "NULL_VALUE" ], @@ -3534,7 +3534,7 @@ }, "/stores/{store_id}/assertions/{authorization_model_id}": { "get": { - "description": "The ReadAssertions API will return, for a given authorization model id, all the assertions stored for it. ", + "description": "The ReadAssertions API returns all the assertions stored for a given authorization model id.", "operationId": "ReadAssertions", "parameters": [ { @@ -3636,7 +3636,7 @@ "description": "Request failed due to internal server error." } }, - "summary": "Read assertions for an authorization model ID", + "summary": "Get authorization model ID assertions", "tags": [ "Assertions" ] @@ -3747,7 +3747,7 @@ "description": "Request failed due to internal server error." } }, - "summary": "Upsert assertions for an authorization model ID", + "summary": "Upsert authorization model ID assertions", "tags": [ "Assertions" ] @@ -3755,7 +3755,7 @@ }, "/stores/{store_id}/authorization-models": { "get": { - "description": "The ReadAuthorizationModels API will return all the authorization models for a certain store.\nOpenFGA's response will contain an array of all authorization models, sorted in descending order of creation.\n\n## Example\nAssume 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:\n```json\n{\n \"authorization_models\": [\n {\n \"id\": \"01G50QVV17PECNVAHX1GG4Y5NC\",\n \"type_definitions\": [...]\n },\n {\n \"id\": \"01G4ZW8F4A07AKQ8RHSVG9RW04\",\n \"type_definitions\": [...]\n },\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nIf there are no more authorization models available, the `continuation_token` field will be empty\n```json\n{\n \"authorization_models\": [\n {\n \"id\": \"01G50QVV17PECNVAHX1GG4Y5NC\",\n \"type_definitions\": [...]\n },\n {\n \"id\": \"01G4ZW8F4A07AKQ8RHSVG9RW04\",\n \"type_definitions\": [...]\n },\n ],\n \"continuation_token\": \"\"\n}\n```\n", + "description": "The ReadAuthorizationModels API returns all the authorization models for a certain store.\nOpenFGA's response contains an array of all authorization models, sorted in descending order of creation.\n\n## Example\nAssume 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:\n```json\n{\n \"authorization_models\": [\n {\n \"id\": \"01G50QVV17PECNVAHX1GG4Y5NC\",\n \"type_definitions\": [...]\n },\n {\n \"id\": \"01G4ZW8F4A07AKQ8RHSVG9RW04\",\n \"type_definitions\": [...]\n },\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nIf there are no more authorization models available, the `continuation_token` field will be empty\n```json\n{\n \"authorization_models\": [\n {\n \"id\": \"01G50QVV17PECNVAHX1GG4Y5NC\",\n \"type_definitions\": [...]\n },\n {\n \"id\": \"01G4ZW8F4A07AKQ8RHSVG9RW04\",\n \"type_definitions\": [...]\n },\n ],\n \"continuation_token\": \"\"\n}\n```\n", "operationId": "ReadAuthorizationModels", "parameters": [ { @@ -3866,13 +3866,13 @@ "description": "Request failed due to internal server error." } }, - "summary": "Return all the authorization models for a particular store", + "summary": "Get all authorization models", "tags": [ "Authorization Models" ] }, "post": { - "description": "The WriteAuthorizationModel API will add a new authorization model to a store.\nEach item in the `type_definitions` array is a type definition as specified in the field `type_definition`.\nThe response will return the authorization model's ID in the `id` field.\n\n## Example\nTo add an authorization model with `user` and `document` type definitions, call POST authorization-models API with the body: \n```json\n{\n \"type_definitions\":[\n {\n \"type\":\"user\"\n },\n {\n \"type\":\"document\",\n \"relations\":{\n \"reader\":{\n \"union\":{\n \"child\":[\n {\n \"this\":{}\n },\n {\n \"computedUserset\":{\n \"object\":\"\",\n \"relation\":\"writer\"\n }\n }\n ]\n }\n },\n \"writer\":{\n \"this\":{}\n }\n }\n }\n ]\n}\n```\nOpenFGA's response will include the version id for this authorization model, which will look like \n```\n{\"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"}\n```\n", + "description": "The WriteAuthorizationModel API will add a new authorization model to a store.\nEach item in the `type_definitions` array is a type definition as specified in the field `type_definition`.\nThe response will return the authorization model's ID in the `id` field.\n\n## Example\nTo add an authorization model with `user` and `document` type definitions, call `POST` `authorization-models` API with the body: \n```json\n{\n \"type_definitions\":[\n {\n \"type\":\"user\"\n },\n {\n \"type\":\"document\",\n \"relations\":{\n \"reader\":{\n \"union\":{\n \"child\":[\n {\n \"this\":{}\n },\n {\n \"computedUserset\":{\n \"object\":\"\",\n \"relation\":\"writer\"\n }\n }\n ]\n }\n },\n \"writer\":{\n \"this\":{}\n }\n }\n }\n ]\n}\n```\nOpenFGA's response will include the version id for this authorization model, which will look like \n```\n{\"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"}\n```\n", "operationId": "WriteAuthorizationModel", "parameters": [ { @@ -3984,7 +3984,7 @@ }, "/stores/{store_id}/authorization-models/{id}": { "get": { - "description": "The ReadAuthorizationModel API returns an authorization model by its identifier.\nThe response will return the authorization model for the particular version.\n\n## Example\nTo 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:\n```json\n{\n \"authorization_model\":{\n \"id\":\"01G5JAVJ41T49E9TT3SKVS7X1J\",\n \"type_definitions\":[\n {\n \"type\":\"user\"\n },\n {\n \"type\":\"document\",\n \"relations\":{\n \"reader\":{\n \"union\":{\n \"child\":[\n {\n \"this\":{}\n },\n {\n \"computedUserset\":{\n \"object\":\"\",\n \"relation\":\"writer\"\n }\n }\n ]\n }\n },\n \"writer\":{\n \"this\":{}\n }\n }\n }\n ]\n }\n}\n```\nIn the above example, there are 2 types (`user` and `document`). The `document` type has 2 relations (`writer` and `reader`).", + "description": "The ReadAuthorizationModel API returns an authorization model by its identifier.\nThe response will return the authorization model for the particular version.\n\n## Example\nTo 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:\n```json\n{\n \"authorization_model\":{\n \"id\":\"01G5JAVJ41T49E9TT3SKVS7X1J\",\n \"type_definitions\":[\n {\n \"type\":\"user\"\n },\n {\n \"type\":\"document\",\n \"relations\":{\n \"reader\":{\n \"union\":{\n \"child\":[\n {\n \"this\":{}\n },\n {\n \"computedUserset\":{\n \"object\":\"\",\n \"relation\":\"writer\"\n }\n }\n ]\n }\n },\n \"writer\":{\n \"this\":{}\n }\n }\n }\n ]\n }\n}\n```\nIn the above example, there are 2 types (`user` and `document`). The `document` type has 2 relations (`writer` and `reader`).", "operationId": "ReadAuthorizationModel", "parameters": [ { @@ -4086,7 +4086,7 @@ "description": "Request failed due to internal server error." } }, - "summary": "Return a particular version of an authorization model", + "summary": "Get an authorization model by version", "tags": [ "Authorization Models" ] @@ -4094,7 +4094,7 @@ }, "/stores/{store_id}/batch-check": { "post": { - "description": "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.\n\nAn 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}$`\n\nNOTE: The maximum number of checks that can be passed in the `BatchCheck` API is configurable via the [OPENFGA_MAX_CHECKS_PER_BATCH_CHECK](https://openfga.dev/docs/getting-started/setup-openfga/configuration#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.\n\nFor more details on how `Check` functions, see the docs for `/check`.\n\n### Examples\n#### A BatchCheckRequest\n```json\n{\n \"checks\": [\n {\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n \"relation\": \"reader\",\n \"user\": \"user:anne\",\n },\n \"contextual_tuples\": {...}\n \"context\": {}\n \"correlation_id\": \"01JA8PM3QM7VBPGB8KMPK8SBD5\"\n },\n {\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n \"relation\": \"reader\",\n \"user\": \"user:bob\",\n },\n \"contextual_tuples\": {...}\n \"context\": {}\n \"correlation_id\": \"01JA8PMM6A90NV5ET0F28CYSZQ\"\n }\n ]\n}\n```\n\nBelow 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:\n```json\n{\n \"result\": {\n \"01JA8PMM6A90NV5ET0F28CYSZQ\": {\n \"allowed\": false, \n \"error\": {\"message\": \"\"} \n },\n \"01JA8PM3QM7VBPGB8KMPK8SBD5\": {\n \"allowed\": true, \n \"error\": {\"message\": \"\"} \n }\n}\n```\n", + "description": "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.\n\nAn 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}$`\n\n> **Note:** The maximum number of checks that can be passed in the `BatchCheck` API is configurable via the [OPENFGA_MAX_CHECKS_PER_BATCH_CHECK](https://openfga.dev/docs/getting-started/setup-openfga/configuration#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.\n\nFor more details on how `Check` functions, review the docs for `/check`.\n\n### Examples\n#### A BatchCheckRequest\n```json\n{\n \"checks\": [\n {\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n \"relation\": \"reader\",\n \"user\": \"user:anne\",\n },\n \"contextual_tuples\": {...}\n \"context\": {}\n \"correlation_id\": \"01JA8PM3QM7VBPGB8KMPK8SBD5\"\n },\n {\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n \"relation\": \"reader\",\n \"user\": \"user:bob\",\n },\n \"contextual_tuples\": {...}\n \"context\": {}\n \"correlation_id\": \"01JA8PMM6A90NV5ET0F28CYSZQ\"\n }\n ]\n}\n```\n\nBelow 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:\n```json\n{\n \"result\": {\n \"01JA8PMM6A90NV5ET0F28CYSZQ\": {\n \"allowed\": false, \n \"error\": {\"message\": \"\"} \n },\n \"01JA8PM3QM7VBPGB8KMPK8SBD5\": {\n \"allowed\": true, \n \"error\": {\"message\": \"\"} \n }\n}\n```\n", "operationId": "BatchCheck", "parameters": [ { @@ -4198,7 +4198,7 @@ "description": "Request failed due to internal server error." } }, - "summary": "Send a list of `check` operations in a single request", + "summary": "Send a list of related operations", "tags": [ "Relationship Queries" ] @@ -4335,7 +4335,7 @@ "description": "Request failed due to internal server error." } }, - "summary": "Return a list of all the tuple changes", + "summary": "Get all tuple changes", "tags": [ "Relationship Tuples" ] @@ -4343,7 +4343,7 @@ }, "/stores/{store_id}/check": { "post": { - "description": "The Check API returns whether a given user has a relationship with a given object in a given store.\nThe `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:*`.\nTo 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`).\nA `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`.\nYou 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.\nYou 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.\nBy 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.\nThe response will return whether the relationship exists in the field `allowed`.\n\nSome 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. \nFor 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.\n## Examples\n### Querying with contextual tuples\nIn order to check if user `user:anne` of type `user` has a `reader` relationship with object `document:2021-budget` given the following contextual tuple\n```json\n{\n \"user\": \"user:anne\",\n \"relation\": \"member\",\n \"object\": \"time_slot:office_hours\"\n}\n```\nthe Check API can be used with the following request body:\n```json\n{\n \"tuple_key\": {\n \"user\": \"user:anne\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"contextual_tuples\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:anne\",\n \"relation\": \"member\",\n \"object\": \"time_slot:office_hours\"\n }\n ]\n },\n \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n}\n```\n### Querying usersets\nSome Checks will always return `true`, even without any tuples. For example, for the following authorization model\n```python\nmodel\n schema 1.1\ntype user\ntype document\n relations\n define reader: [user]\n```\nthe following query\n```json\n{\n \"tuple_key\": {\n \"user\": \"document:2021-budget#reader\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n }\n}\n```\nwill 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`.\n### Querying usersets with difference in the model\nA Check for a userset can yield results that must be treated carefully if the model involves difference. For example, for the following authorization model\n```python\nmodel\n schema 1.1\ntype user\ntype group\n relations\n define member: [user]\ntype document\n relations\n define blocked: [user]\n define reader: [group#member] but not blocked\n```\nthe following query\n```json\n{\n \"tuple_key\": {\n \"user\": \"group:finance#member\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"contextual_tuples\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:anne\",\n \"relation\": \"member\",\n \"object\": \"group:finance\"\n },\n {\n \"user\": \"group:finance#member\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n {\n \"user\": \"user:anne\",\n \"relation\": \"blocked\",\n \"object\": \"document:2021-budget\"\n }\n ]\n },\n}\n```\nwill return `{ \"allowed\": true }`, even though a specific user of the userset `group:finance#member` does not have the `reader` relationship with the given object.\n### Requesting higher consistency\nBy 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.\n```json\n{\n \"tuple_key\": {\n \"user\": \"group:finance#member\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"consistency\": \"HIGHER_CONSISTENCY\"\n}\n```\n", + "description": "The Check API returns whether a given user has a relationship with a given object in a given store.\n\nThe `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:*`.\nTo arrive at a result, the API uses:\n\n- An authorization model\n\n- Explicit tuples written through the Write API\n\n- Contextual tuples present in the request\n\n- Implicit tuples that exist by virtue of applying set theory\n\nFor example: `document:2021-budget#viewer@document:2021-budget#viewer`. In this example, the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`).\n\nA `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`.\nYou 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.\n\n> **Note:** We recommend you specify authorization model id for better performance.\n\nYou may also provide a `context` object that will be used to evaluate the conditioned tuples in the system.\n\n> **Note:** We recommend you provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.\n\nBy 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.\nThe response will return whether the relationship exists in the field `allowed`.\n\nSome 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. \nFor 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.\n## Examples\n### Querying with contextual tuples\nIn order to check if user `user:anne` of type `user` has a `reader` relationship with object `document:2021-budget` given the following contextual tuple\n```json\n{\n \"user\": \"user:anne\",\n \"relation\": \"member\",\n \"object\": \"time_slot:office_hours\"\n}\n```\nthe Check API can be used with the following request body:\n```json\n{\n \"tuple_key\": {\n \"user\": \"user:anne\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"contextual_tuples\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:anne\",\n \"relation\": \"member\",\n \"object\": \"time_slot:office_hours\"\n }\n ]\n },\n \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n}\n```\n### Querying usersets\nSome Checks will always return `true`, even without any tuples. For example, for the following authorization model\n```python\nmodel\n schema 1.1\ntype user\ntype document\n relations\n define reader: [user]\n```\nthe following query\n```json\n{\n \"tuple_key\": {\n \"user\": \"document:2021-budget#reader\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n }\n}\n```\nwill 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`.\n### Querying usersets with difference in the model\nA Check for a userset can yield results that must be treated carefully if the model involves difference. For example, for the following authorization model\n```python\nmodel\n schema 1.1\ntype user\ntype group\n relations\n define member: [user]\ntype document\n relations\n define blocked: [user]\n define reader: [group#member] but not blocked\n```\nthe following query\n```json\n{\n \"tuple_key\": {\n \"user\": \"group:finance#member\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"contextual_tuples\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:anne\",\n \"relation\": \"member\",\n \"object\": \"group:finance\"\n },\n {\n \"user\": \"group:finance#member\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n {\n \"user\": \"user:anne\",\n \"relation\": \"blocked\",\n \"object\": \"document:2021-budget\"\n }\n ]\n },\n}\n```\nwill return `{ \"allowed\": true }`, even though a specific user of the userset `group:finance#member` does not have the `reader` relationship with the given object.\n### Requesting higher consistency\nBy 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.\n```json\n{\n \"tuple_key\": {\n \"user\": \"group:finance#member\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"consistency\": \"HIGHER_CONSISTENCY\"\n}\n```\n", "operationId": "Check", "parameters": [ { @@ -4447,7 +4447,7 @@ "description": "Request failed due to internal server error." } }, - "summary": "Check whether a user is authorized to access an object", + "summary": "Check user authorization", "tags": [ "Relationship Queries" ] @@ -4455,7 +4455,7 @@ }, "/stores/{store_id}/expand": { "post": { - "description": "The Expand API will return all users and usersets that have certain relationship with an object in a certain store.\nThis is different from the `/stores/{store_id}/read` API in that both users and computed usersets are returned.\nBody parameters `tuple_key.object` and `tuple_key.relation` are all required.\nA `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`.\nThe response will return a tree whose leaves are the specific users and usersets. Union, intersection and difference operator are located in the intermediate nodes.\n\n## Example\nTo expand all users that have the `reader` relationship with object `document:2021-budget`, use the Expand API with the following request body\n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\",\n \"relation\": \"reader\"\n },\n \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n}\n```\nOpenFGA's response will be a userset tree of the users and usersets that have read access to the document.\n```json\n{\n \"tree\":{\n \"root\":{\n \"type\":\"document:2021-budget#reader\",\n \"union\":{\n \"nodes\":[\n {\n \"type\":\"document:2021-budget#reader\",\n \"leaf\":{\n \"users\":{\n \"users\":[\n \"user:bob\"\n ]\n }\n }\n },\n {\n \"type\":\"document:2021-budget#reader\",\n \"leaf\":{\n \"computed\":{\n \"userset\":\"document:2021-budget#writer\"\n }\n }\n }\n ]\n }\n }\n }\n}\n```\nThe caller can then call expand API for the `writer` relationship for the `document:2021-budget`.\n### Expand Request with Contextual Tuples\n\nGiven the model\n```python\nmodel\n schema 1.1\n\ntype user\n\ntype folder\n relations\n define owner: [user]\n\ntype document\n relations\n define parent: [folder]\n define viewer: [user] or writer\n define writer: [user] or owner from parent\n```\nand the initial tuples\n```json\n[{\n \"user\": \"user:bob\",\n \"relation\": \"owner\",\n \"object\": \"folder:1\"\n}]\n```\n\nTo expand all `writers` of `document:1` when `document:1` is put in `folder:1`, the first call could be\n\n```json\n{\n \"tuple_key\": {\n \"object\": \"document:1\",\n \"relation\": \"writer\"\n },\n \"contextual_tuples\": {\n \"tuple_keys\": [\n {\n \"user\": \"folder:1\",\n \"relation\": \"parent\",\n \"object\": \"document:1\"\n }\n ]\n }\n}\n```\nthis returns:\n```json\n{\n \"tree\": {\n \"root\": {\n \"name\": \"document:1#writer\",\n \"union\": {\n \"nodes\": [\n {\n \"name\": \"document:1#writer\",\n \"leaf\": {\n \"users\": {\n \"users\": []\n }\n }\n },\n {\n \"name\": \"document:1#writer\",\n \"leaf\": {\n \"tupleToUserset\": {\n \"tupleset\": \"document:1#parent\",\n \"computed\": [\n {\n \"userset\": \"folder:1#owner\"\n }\n ]\n }\n }\n }\n ]\n }\n }\n }\n}\n```\nThis 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`\n```json\n{\n \"tuple_key\": {\n \"object\": \"folder:1\",\n \"relation\": \"owner\"\n }\n}\n```\nwhich gives\n```json\n{\n \"tree\": {\n \"root\": {\n \"name\": \"folder:1#owner\",\n \"leaf\": {\n \"users\": {\n \"users\": [\n \"user:bob\"\n ]\n }\n }\n }\n }\n}\n```\n", + "description": "The Expand API will return all users and usersets that have certain relationship with an object in a certain store.\nThis is different from the `/stores/{store_id}/read` API in that both users and computed usersets are returned.\n\nBody parameters `tuple_key.object` and `tuple_key.relation` are all required.\nA `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`.\nThe response will return a tree whose leaves are the specific users and usersets. Union, intersection and difference operator are located in the intermediate nodes.\n\n## Example\nTo expand all users that have the `reader` relationship with object `document:2021-budget`, use the Expand API with the following request body\n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\",\n \"relation\": \"reader\"\n },\n \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n}\n```\nOpenFGA's response will be a userset tree of the users and usersets that have read access to the document.\n```json\n{\n \"tree\":{\n \"root\":{\n \"type\":\"document:2021-budget#reader\",\n \"union\":{\n \"nodes\":[\n {\n \"type\":\"document:2021-budget#reader\",\n \"leaf\":{\n \"users\":{\n \"users\":[\n \"user:bob\"\n ]\n }\n }\n },\n {\n \"type\":\"document:2021-budget#reader\",\n \"leaf\":{\n \"computed\":{\n \"userset\":\"document:2021-budget#writer\"\n }\n }\n }\n ]\n }\n }\n }\n}\n```\nThe caller can then call expand API for the `writer` relationship for the `document:2021-budget`.\n### Expand Request with Contextual Tuples\n\nGiven the model\n```python\nmodel\n schema 1.1\n\ntype user\n\ntype folder\n relations\n define owner: [user]\n\ntype document\n relations\n define parent: [folder]\n define viewer: [user] or writer\n define writer: [user] or owner from parent\n```\nand the initial tuples\n```json\n[{\n \"user\": \"user:bob\",\n \"relation\": \"owner\",\n \"object\": \"folder:1\"\n}]\n```\n\nTo expand all `writers` of `document:1` when `document:1` is put in `folder:1`, the first call could be\n\n```json\n{\n \"tuple_key\": {\n \"object\": \"document:1\",\n \"relation\": \"writer\"\n },\n \"contextual_tuples\": {\n \"tuple_keys\": [\n {\n \"user\": \"folder:1\",\n \"relation\": \"parent\",\n \"object\": \"document:1\"\n }\n ]\n }\n}\n```\nthis returns:\n```json\n{\n \"tree\": {\n \"root\": {\n \"name\": \"document:1#writer\",\n \"union\": {\n \"nodes\": [\n {\n \"name\": \"document:1#writer\",\n \"leaf\": {\n \"users\": {\n \"users\": []\n }\n }\n },\n {\n \"name\": \"document:1#writer\",\n \"leaf\": {\n \"tupleToUserset\": {\n \"tupleset\": \"document:1#parent\",\n \"computed\": [\n {\n \"userset\": \"folder:1#owner\"\n }\n ]\n }\n }\n }\n ]\n }\n }\n }\n}\n```\nThis 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`\n```json\n{\n \"tuple_key\": {\n \"object\": \"folder:1\",\n \"relation\": \"owner\"\n }\n}\n```\nwhich gives\n```json\n{\n \"tree\": {\n \"root\": {\n \"name\": \"folder:1#owner\",\n \"leaf\": {\n \"users\": {\n \"users\": [\n \"user:bob\"\n ]\n }\n }\n }\n }\n}\n```\n", "operationId": "Expand", "parameters": [ { @@ -4559,7 +4559,7 @@ "description": "Request failed due to internal server error." } }, - "summary": "Expand all relationships in userset tree format, and following userset rewrite rules. Useful to reason about and debug a certain relationship", + "summary": "Expand relationships in userset tree format", "tags": [ "Relationship Queries" ] @@ -4567,7 +4567,7 @@ }, "/stores/{store_id}/list-objects": { "post": { - "description": "The ListObjects API returns a list of all the objects of the given type that the user has a relation with.\n 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`).\nAn `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.\nYou may also specify `contextual_tuples` that will be treated as regular tuples. Each of these tuples may have an associated `condition`.\nYou 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.\nBy 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.\nThe 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 `:` (e.g. \"document:roadmap\").\nThe 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.\nThe objects given will not be sorted, and therefore two identical calls can give a given different set of objects.", + "description": "The ListObjects API returns a list of all the objects of the given type that the user has a relation with.\n To arrive at a result, the API uses:\n\n- An authorization model\n- Explicit tuples written through the Write API\n- Contextual tuples present in the request\n- Implicit tuples that exist by virtue of applying set theory. For example:\n\n`document:2021-budget#viewer@document:2021-budget#viewer`\n\nIn the example the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n\nAn `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID will be used.\n\n> **Note:** We recommend you specify authorization model ID for better performance.\n\nYou may also specify `contextual_tuples` that is treated as regular tuples. Each of these tuples may have an associated `condition`.\nYou may also provide a `context` object that is used to evaluate the conditioned tuples in the system.\n\n> **Note:** We recommend you provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.\n\nBy 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.\nThe response contains the related objects in an array in the \"objects\" field of the response and they will be strings in the object format `:` (e.g. \"document:roadmap\").\n\nThe 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.\nThe objects given will not be sorted, and therefore two identical calls can give a given different set of objects.", "operationId": "ListObjects", "parameters": [ { @@ -4671,7 +4671,7 @@ "description": "Request failed due to internal server error." } }, - "summary": "List all objects of the given type that the user has a relation with", + "summary": "List all objects with user-centric relationship", "tags": [ "Relationship Queries" ] @@ -4679,7 +4679,7 @@ }, "/stores/{store_id}/list-users": { "post": { - "description": "The ListUsers API returns a list of all the users of a specific type that have a relation to a given object.\n 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`).\nAn `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.\nYou may also specify `contextual_tuples` that will be treated as regular tuples. Each of these tuples may have an associated `condition`.\nYou 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.\nThe response will contain the related users in an array in the \"users\" field of the response. These results may include specific objects, usersets \nor 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\nof that type have a relation to the object; it is possible that negations exist and checks should still be queried\non 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.\nThe returned users will not be sorted, and therefore two identical calls may yield different sets of users.", + "description": "The ListUsers API returns a list of all the users of a specific type that have a relation to a given object.\n\n To arrive at a result, the API uses:\n\n- An authorization model\n\n- Explicit tuples written through the Write API\n\n- Contextual tuples present in the request\n\n- Implicit tuples that exist by virtue of applying set theory\n\nFor example: `document:2021-budget#viewer@document:2021-budget#viewer`. In this example, the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n\nAn `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID will be used.\n\n> **Note:** We recommend you specify authorization model ID for better performance.\n\nYou may also specify `contextual_tuples` that will be treated as regular tuples. Each of these tuples may have an associated `condition`.\nYou may also provide a `context` object that will be used to evaluate the conditioned tuples in the system.\n\n> **Note:** We recommend you provide a value for all the input parameters of all the conditions. This ensures that all tuples be evaluated correctly.\n\nThe response will contain the related users in an array in the \"users\" field of the response. These results may include specific objects, usersets \nor 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\nof that type have a relation to the object; it is possible that negations exist and checks should still be queried\non 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.\nThe returned users will not be sorted, and therefore two identical calls may yield different sets of users.", "operationId": "ListUsers", "parameters": [ { @@ -4783,7 +4783,7 @@ "description": "Request failed due to internal server error." } }, - "summary": "List the users matching the provided filter who have a certain relation to a particular type.", + "summary": "List all users with a relationship to an object", "tags": [ "Relationship Queries" ] @@ -4791,7 +4791,7 @@ }, "/stores/{store_id}/read": { "post": { - "description": "The Read API will return the tuples for a certain store that match a query filter specified in the body of the request. \nThe API doesn't guarantee order by any field. \nIt 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. \nIn the body:\n1. `tuple_key` is optional. If not specified, it will return all tuples in the store.\n2. `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:`).\n3. `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`).\n## Examples\n### Query for all objects in a type definition\nTo query for all objects that `user:bob` has `reader` relationship in the `document` type definition, call read API with body of\n```json\n{\n \"tuple_key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:\"\n }\n}\n```\nThe API will return tuples and a continuation token, something like\n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis 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.\nThe continuation token will be empty if there are no more tuples to query.\n### Query for all stored relationship tuples that have a particular relation and object\nTo query for all users that have `reader` relationship with `document:2021-budget`, call read API with body of \n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\",\n \"relation\": \"reader\"\n }\n}\n```\nThe API will return something like \n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis 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.\n### Query for all users with all relationships for a particular document\nTo query for all users that have any relationship with `document:2021-budget`, call read API with body of \n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n }\n}\n```\nThe API will return something like \n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:anne\",\n \"relation\": \"writer\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-05T13:42:12.356Z\"\n },\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis means that `document:2021-budget` has 1 `reader` (`user:bob`) and 1 `writer` (`user:anne`).\n", + "description": "The Read API will return the tuples from a certain store that match a query filter specified in the body of the request. \nThe API doesn't guarantee order by any field. \nIt 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. \nIn the body:\n1. `tuple_key` is optional. If not specified, it will return all tuples in the store.\n2. `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:`).\n3. `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`).\n\n## Examples\n### Query for all objects in a type definition\nTo query for all objects that `user:bob` has `reader` relationship in the `document` type definition, call read API with body of\n```json\n{\n \"tuple_key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:\"\n }\n}\n```\nThe API will return tuples and a continuation token, something like\n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis 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.\nThe continuation token will be empty if there are no more tuples to query.\n\n### Query for all stored relationship tuples that have a particular relation and object\nTo query for all users that have `reader` relationship with `document:2021-budget`, call read API with body of \n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\",\n \"relation\": \"reader\"\n }\n}\n```\nThe API will return something like \n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis 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.\n\n### Query for all users with all relationships for a particular document\nTo query for all users that have any relationship with `document:2021-budget`, call read API with body of \n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n }\n}\n```\nThe API will return something like \n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:anne\",\n \"relation\": \"writer\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-05T13:42:12.356Z\"\n },\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis means that `document:2021-budget` has 1 `reader` (`user:bob`) and 1 `writer` (`user:anne`).\n", "operationId": "Read", "parameters": [ { @@ -4895,7 +4895,7 @@ "description": "Request failed due to internal server error." } }, - "summary": "Get tuples from the store that matches a query, without following userset rewrite rules", + "summary": "Get related tuples", "tags": [ "Relationship Tuples" ] @@ -4903,7 +4903,7 @@ }, "/stores/{store_id}/streamed-list-objects": { "post": { - "description": "The Streamed ListObjects API is very similar to the the ListObjects API, with two differences: \n1. Instead of collecting all objects before returning a response, it streams them to the client as they are collected. \n2. The number of results returned is only limited by the execution timeout specified in the flag OPENFGA_LIST_OBJECTS_DEADLINE. \n", + "description": "The Streamed ListObjects API is very similar to the the ListObjects API, with two differences: \n1. Instead of collecting all objects before returning a response, it streams them to the client as they are collected. \n2. The number of results returned is only limited by the execution timeout specified in the flag `OPENFGA_LIST_OBJECTS_DEADLINE`. \n", "operationId": "StreamedListObjects", "parameters": [ { @@ -5016,7 +5016,7 @@ "description": "Request failed due to internal server error." } }, - "summary": "Stream all objects of the given type that the user has a relation with", + "summary": "Stream all objects with a user relationship", "tags": [ "Relationship Queries" ] @@ -5024,7 +5024,7 @@ }, "/stores/{store_id}/write": { "post": { - "description": "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.\nIn the body, `writes` adds new tuples and `deletes` removes existing tuples. When deleting a tuple, any `condition` specified with it is ignored.\nThe 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.\nTo allow writes when an identical tuple already exists in the database, set `\"on_duplicate\": \"ignore\"` on the `writes` object.\nTo allow deletes when a tuple was already removed from the database, set `\"on_missing\": \"ignore\"` on the `deletes` object.\nIf 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.\nThe API will not allow you to write tuples such as `document:2021-budget#viewer@document:2021-budget#viewer`, because they are implicit.\nAn `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.\n## Example\n### Adding relationships\nTo add `user:anne` as a `writer` for `document:2021-budget`, call write API with the following \n```json\n{\n \"writes\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:anne\",\n \"relation\": \"writer\",\n \"object\": \"document:2021-budget\"\n }\n ],\n \"on_duplicate\": \"ignore\"\n },\n \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n}\n```\n### Removing relationships\nTo remove `user:bob` as a `reader` for `document:2021-budget`, call write API with the following \n```json\n{\n \"deletes\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n }\n ],\n \"on_missing\": \"ignore\"\n }\n}\n```\n", + "description": "The Write API transactionally updates the tuples for a certain store. Tuples and type definitions allow OpenFGA to determine whether a relationship exists between an object and an user.\n\nIn the body, `writes` adds new tuples and `deletes` removes existing tuples. When deleting a tuple, any `condition` specified with it is ignored.\n\nThe 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.\n\nTo allow writes when an identical tuple already exists in the database, set `\"on_duplicate\": \"ignore\"` on the `writes` object.\nTo allow deletes when a tuple was already removed from the database, set `\"on_missing\": \"ignore\"` on the `deletes` object.\nIf 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.\n\nThe API will not allow you to write tuples such as `document:2021-budget#viewer@document:2021-budget#viewer`, because they are implicit.\nAn `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.\n\n## Example\n### Adding relationships\nTo add `user:anne` as a `writer` for `document:2021-budget`, call write API with the following \n```json\n{\n \"writes\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:anne\",\n \"relation\": \"writer\",\n \"object\": \"document:2021-budget\"\n }\n ],\n \"on_duplicate\": \"ignore\"\n },\n \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n}\n```\n### Removing relationships\nTo remove `user:bob` as a `reader` for `document:2021-budget`, call write API with the following \n```json\n{\n \"deletes\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n }\n ],\n \"on_missing\": \"ignore\"\n }\n}\n```\n", "operationId": "Write", "parameters": [ { @@ -5128,7 +5128,7 @@ "description": "Request failed due to internal server error." } }, - "summary": "Add or delete tuples from the store", + "summary": "Add or delete tuples", "tags": [ "Relationship Tuples" ] diff --git a/openfga/v1/openfga_service.proto b/openfga/v1/openfga_service.proto index 3b4e9ac1..f5da5a90 100644 --- a/openfga/v1/openfga_service.proto +++ b/openfga/v1/openfga_service.proto @@ -23,11 +23,11 @@ service OpenFGAService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - summary: "Get tuples from the store that matches a query, without following userset rewrite rules" + summary: "Get related tuples" tags: ["Relationship Tuples"] operation_id: "Read" description: - "The Read API will return the tuples for a certain store that match a " + "The Read API will return the tuples from a certain store that match a " "query filter specified in the body of the request. \n" "The API doesn't guarantee order by any field. \n" "It is different from the `/stores/{store_id}/expand` API in that it only " @@ -37,7 +37,7 @@ service OpenFGAService { "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:`).\n" "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`).\n" + "If tuple_key.user is specified, it needs to be a full object (e.g., `type:user_id`).\n\n" "## Examples\n" "### Query for all objects in a type definition\n" "To query for all objects that `user:bob` has `reader` relationship in " @@ -69,7 +69,7 @@ service OpenFGAService { "```\n" "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.\n" - "The continuation token will be empty if there are no more tuples to query.\n" + "The continuation token will be empty if there are no more tuples to query.\n\n" "### Query for all stored relationship tuples that have a particular relation and object\n" "To query for all users that have `reader` relationship with " "`document:2021-budget`, call read API with body of \n" @@ -99,7 +99,7 @@ service OpenFGAService { "```\n" "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.\n" + "`user:anne` because it only returns tuples and does not evaluate them.\n\n" "### Query for all users with all relationships for a particular document\n" "To query for all users that have any relationship with " "`document:2021-budget`, call read API with body of \n" @@ -146,21 +146,21 @@ service OpenFGAService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - summary: "Add or delete tuples from the store" + summary: "Add or delete tuples" tags: ["Relationship Tuples"] operation_id: "Write" description: - "The Write API will transactionally update the tuples for a certain store. Tuples and " + "The Write API transactionally updates the tuples for a certain store. Tuples and " "type definitions allow OpenFGA to determine whether a " - "relationship exists between an object and an user.\n" - "In the body, `writes` adds new tuples and `deletes` removes existing tuples. When deleting a tuple, any `condition` specified with it is ignored.\n" - "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.\n" + "relationship exists between an object and an user.\n\n" + "In the body, `writes` adds new tuples and `deletes` removes existing tuples. When deleting a tuple, any `condition` specified with it is ignored.\n\n" + "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.\n\n" "To allow writes when an identical tuple already exists in the database, set `\"on_duplicate\": \"ignore\"` on the `writes` object.\n" "To allow deletes when a tuple was already removed from the database, set `\"on_missing\": \"ignore\"` on the `deletes` object.\n" - "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.\n" + "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.\n\n" "The API will not allow you to write tuples such as `document:2021-budget#viewer@document:2021-budget#viewer`, because they are implicit.\n" "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.\n" + "is valid for the model specified. If it is not specified, the latest authorization model ID will be used.\n\n" "## Example\n" "### Adding relationships\n" "To add `user:anne` as a `writer` for `document:2021-budget`, call " @@ -207,18 +207,24 @@ service OpenFGAService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - summary: "Check whether a user is authorized to access an object" + summary: "Check user authorization" tags: ["Relationship Queries"] operation_id: "Check" description: - "The Check API returns whether a given user has a relationship with a given object in a given store.\n" + "The Check API returns whether a given user has a relationship with a given object in a given store.\n\n" "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:*`.\n" - "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`).\n" + "To arrive at a result, the API uses:\n\n" + "- An authorization model\n\n" + "- Explicit tuples written through the Write API\n\n" + "- Contextual tuples present in the request\n\n" + "- Implicit tuples that exist by virtue of applying set theory\n\n" + "For example: `document:2021-budget#viewer@document:2021-budget#viewer`. In this example, the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`).\n\n" "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`.\n" "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.\n" - "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.\n" + "If not specified, the assertion will be made against the latest authorization model ID.\n\n" + "> **Note:** We recommend you specify authorization model id for better performance.\n\n" + "You may also provide a `context` object that will be used to evaluate the conditioned tuples in the system.\n\n" + "> **Note:** We recommend you provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.\n\n" "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.\n" "The response will return whether the relationship exists in the field `allowed`.\n\n" "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. \n" @@ -340,7 +346,7 @@ service OpenFGAService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - summary: "Send a list of `check` operations in a single request" + summary: "Send a list of related operations" tags: ["Relationship Queries"] operation_id: "BatchCheck" description: @@ -352,8 +358,8 @@ service OpenFGAService { "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}$`\n\n" - "NOTE: The maximum number of checks that can be passed in the `BatchCheck` API is configurable via the [OPENFGA_MAX_CHECKS_PER_BATCH_CHECK](https://openfga.dev/docs/getting-started/setup-openfga/configuration#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.\n\n" - "For more details on how `Check` functions, see the docs for `/check`.\n\n" + "> **Note:** The maximum number of checks that can be passed in the `BatchCheck` API is configurable via the [OPENFGA_MAX_CHECKS_PER_BATCH_CHECK](https://openfga.dev/docs/getting-started/setup-openfga/configuration#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.\n\n" + "For more details on how `Check` functions, review the docs for `/check`.\n\n" "### Examples\n" "#### A BatchCheckRequest\n" "```json\n" @@ -406,14 +412,14 @@ service OpenFGAService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - summary: "Expand all relationships in userset tree format, and following userset rewrite rules. Useful to reason about and debug a certain relationship" + summary: "Expand relationships in userset tree format" tags: ["Relationship Queries"] operation_id: "Expand" description: "The Expand API will return all users and usersets " "that have certain relationship with an object in a certain store.\n" "This is different from the `/stores/{store_id}/read` API in that both users and " - "computed usersets are returned.\n" + "computed usersets are returned.\n\n" "Body parameters `tuple_key.object` and `tuple_key.relation` are all required.\n" "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`.\n" "The response will return a tree whose leaves are the specific users and usersets. " @@ -579,14 +585,14 @@ service OpenFGAService { option (google.api.http) = {get: "/stores/{store_id}/authorization-models"}; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - summary: "Return all the authorization models for a particular store" + summary: "Get all authorization models" tags: ["Authorization Models"] operation_id: "ReadAuthorizationModels" description: - "The ReadAuthorizationModels API will return all the authorization models for a certain store.\n" - "OpenFGA's response will contain an array of all authorization models, sorted in descending order of creation.\n\n" + "The ReadAuthorizationModels API returns all the authorization models for a certain store.\n" + "OpenFGA's response contains an array of all authorization models, sorted in descending order of creation.\n\n" "## Example\n" - "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:\n" + "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:\n" "```json\n" "{\n" " \"authorization_models\": [\n" @@ -626,7 +632,7 @@ service OpenFGAService { option (google.api.http) = {get: "/stores/{store_id}/authorization-models/{id}"}; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - summary: "Return a particular version of an authorization model" + summary: "Get an authorization model by version" tags: ["Authorization Models"] operation_id: "ReadAuthorizationModel" description: @@ -634,7 +640,7 @@ service OpenFGAService { "The response will return the authorization model for the particular version.\n\n" "## Example\n" "To retrieve the authorization model with ID `01G5JAVJ41T49E9TT3SKVS7X1J` for the store, " - "call the GET authorization-models by ID API with `01G5JAVJ41T49E9TT3SKVS7X1J` as the " + "call the `GET` authorization-models by ID API with `01G5JAVJ41T49E9TT3SKVS7X1J` as the " "`id` path parameter. The API will return:\n" "```json\n" "{\n" @@ -693,8 +699,8 @@ service OpenFGAService { "definition as specified in the field `type_definition`.\n" "The response will return the authorization model's ID in the `id` field.\n\n" "## Example\n" - "To add an authorization model with `user` and `document` type definitions, call POST " - "authorization-models API with the body: \n" + "To add an authorization model with `user` and `document` type definitions, call `POST` " + "`authorization-models` API with the body: \n" "```json\n" "{\n" " \"type_definitions\":[\n" @@ -751,7 +757,7 @@ service OpenFGAService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - summary: "Upsert assertions for an authorization model ID" + summary: "Upsert authorization model ID assertions" tags: ["Assertions"] operation_id: "WriteAssertions" description: @@ -775,12 +781,10 @@ service OpenFGAService { option (google.api.http) = {get: "/stores/{store_id}/assertions/{authorization_model_id}"}; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - summary: "Read assertions for an authorization model ID" + summary: "Get authorization model ID assertions" tags: ["Assertions"] operation_id: "ReadAssertions" - description: - "The ReadAssertions API will return, for a given authorization model id, " - "all the assertions stored for it. " + description: "The ReadAssertions API returns all the assertions stored for a given authorization model id." }; } @@ -788,7 +792,7 @@ service OpenFGAService { option (google.api.http) = {get: "/stores/{store_id}/changes"}; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - summary: "Return a list of all the tuple changes" + summary: "Get all tuple changes" tags: ["Relationship Tuples"] operation_id: "ReadChanges" description: @@ -902,13 +906,13 @@ service OpenFGAService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - summary: "Stream all objects of the given type that the user has a relation with" + summary: "Stream all objects with a user relationship" tags: ["Relationship Queries"] operation_id: "StreamedListObjects" description: "The Streamed ListObjects API is very similar to the the ListObjects API, with two differences: \n" "1. Instead of collecting all objects before returning a response, it streams them to the client as they are collected. \n" - "2. The number of results returned is only limited by the execution timeout specified in the flag OPENFGA_LIST_OBJECTS_DEADLINE. \n" + "2. The number of results returned is only limited by the execution timeout specified in the flag `OPENFGA_LIST_OBJECTS_DEADLINE`. \n" }; } @@ -919,22 +923,29 @@ service OpenFGAService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - summary: "List all objects of the given type that the user has a relation with" + summary: "List all objects with user-centric relationship" tags: ["Relationship Queries"] operation_id: "ListObjects" description: "The ListObjects API returns a list of all the objects of the given type that the user has a relation with.\n " - "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`).\n" + "To arrive at a result, the API uses:\n\n" + "- An authorization model\n" + "- Explicit tuples written through the Write API\n" + "- Contextual tuples present in the request\n" + "- Implicit tuples that exist by virtue of applying set theory. For example:\n\n" + "`document:2021-budget#viewer@document:2021-budget#viewer`\n\n" + "In the example the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n\n" "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.\n" - "You may also specify `contextual_tuples` that will be treated as regular tuples. Each of these tuples may have an associated `condition`.\n" - "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.\n" + "model ID will be used.\n\n" + "> **Note:** We recommend you specify authorization model ID for better performance.\n\n" + "You may also specify `contextual_tuples` that is treated as regular tuples. Each of these tuples may have an associated `condition`.\n" + "You may also provide a `context` object that is used to evaluate the conditioned tuples in the system.\n\n" + "> **Note:** We recommend you provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.\n\n" "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.\n" - "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 `:` (e.g. \"document:roadmap\").\n" - "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.\n" + "The response contains the related objects in an array in the \"objects\" field of the response and they will " + "be strings in the object format `:` (e.g. \"document:roadmap\").\n\n" + "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.\n" "The objects given will not be sorted, and therefore two identical calls can give a given different set of objects." }; } @@ -946,24 +957,30 @@ service OpenFGAService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - summary: "List the users matching the provided filter who have a certain relation to a particular type." + summary: "List all users with a relationship to an object" tags: ["Relationship Queries"] operation_id: "ListUsers" description: - "The ListUsers API returns a list of all the users of a specific type that have a relation to a given object.\n " - "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`).\n" + "The ListUsers API returns a list of all the users of a specific type that have a relation to a given object.\n\n " + "To arrive at a result, the API uses:\n\n" + "- An authorization model\n\n" + "- Explicit tuples written through the Write API\n\n" + "- Contextual tuples present in the request\n\n" + "- Implicit tuples that exist by virtue of applying set theory\n\n" + "For example: `document:2021-budget#viewer@document:2021-budget#viewer`. In this example, the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n\n" "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.\n" + "model ID will be used.\n\n" + "> **Note:** We recommend you specify authorization model ID for better performance.\n\n" "You may also specify `contextual_tuples` that will be treated as regular tuples. Each of these tuples may have an associated `condition`.\n" - "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.\n" + "You may also provide a `context` object that will be used to evaluate the conditioned tuples in the system.\n\n" + "> **Note:** We recommend you provide a value for all the input parameters of all the conditions. This ensures that all tuples be evaluated correctly.\n\n" "The response will contain the related users in an array in the \"users\" field of the response. These results may include specific objects, usersets \n" - "or type-bound public access. Each of these types of results is encoded in its own type and not represented as a string." + "or type-bound public access. Each of these types of results is encoded in its own type and not represented as a string.\n\n" "In cases where a type-bound public access result is returned (e.g. `user:*`), it cannot be inferred that all subjects\n" "of that type have a relation to the object; it is possible that negations exist and checks should still be queried\n" "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.\n" + "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.\n" "The returned users will not be sorted, and therefore two identical calls may yield different sets of users." }; } @@ -1017,7 +1034,7 @@ message ListObjectsRequest { // in the query evaluation. google.protobuf.Struct context = 7; - // Controls the consistency preference for this request. Default value is UNSPECIFIED, which will have the same behavior as MINIMIZE_LATENCY. + // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which will have the same behavior as MINIMIZE_LATENCY. ConsistencyPreference consistency = 8 [(validate.rules).enum.defined_only = true]; } diff --git a/proto/openfga/v1/openfga_service.pb.go b/proto/openfga/v1/openfga_service.pb.go index d91bd64c..2404e551 100644 --- a/proto/openfga/v1/openfga_service.pb.go +++ b/proto/openfga/v1/openfga_service.pb.go @@ -39,7 +39,7 @@ type ListObjectsRequest struct { // Additional request context that will be used to evaluate any ABAC conditions encountered // in the query evaluation. Context *structpb.Struct `protobuf:"bytes,7,opt,name=context,proto3" json:"context,omitempty"` - // Controls the consistency preference for this request. Default value is UNSPECIFIED, which will have the same behavior as MINIMIZE_LATENCY. + // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which will have the same behavior as MINIMIZE_LATENCY. Consistency ConsistencyPreference `protobuf:"varint,8,opt,name=consistency,proto3,enum=openfga.v1.ConsistencyPreference" json:"consistency,omitempty"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache @@ -3207,16 +3207,17 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + "Assertions\x12:\n" + "\n" + "assertions\x18\x01 \x03(\v2\x15.openfga.v1.AssertionB\x03\xe0A\x02R\n" + - "assertions2\xee\xf0\x01\n" + - "\x0eOpenFGAService\x12\xd0\x1d\n" + - "\x04Read\x12\x17.openfga.v1.ReadRequest\x1a\x18.openfga.v1.ReadResponse\"\x94\x1d\x92A\xee\x1c\n" + - "\x13Relationship Tuples\x12WGet tuples from the store that matches a query, without following userset rewrite rules\x1a\xf7\x1bThe Read API will return the tuples for a certain store that match a query filter specified in the body of the request. \n" + + "assertions2\xaf\xee\x01\n" + + "\x0eOpenFGAService\x12\x8f\x1d\n" + + "\x04Read\x12\x17.openfga.v1.ReadRequest\x1a\x18.openfga.v1.ReadResponse\"\xd3\x1c\x92A\xad\x1c\n" + + "\x13Relationship Tuples\x12\x12Get related tuples\x1a\xfb\x1bThe Read API will return the tuples from a certain store that match a query filter specified in the body of the request. \n" + "The API doesn't guarantee order by any field. \n" + "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. \n" + "In the body:\n" + "1. `tuple_key` is optional. If not specified, it will return all tuples in the store.\n" + "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:`).\n" + "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`).\n" + + "\n" + "## Examples\n" + "### Query for all objects in a type definition\n" + "To query for all objects that `user:bob` has `reader` relationship in the `document` type definition, call read API with body of\n" + @@ -3247,6 +3248,7 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + "```\n" + "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.\n" + "The continuation token will be empty if there are no more tuples to query.\n" + + "\n" + "### Query for all stored relationship tuples that have a particular relation and object\n" + "To query for all users that have `reader` relationship with `document:2021-budget`, call read API with body of \n" + "```json\n" + @@ -3274,6 +3276,7 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + "}\n" + "```\n" + "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.\n" + + "\n" + "### Query for all users with all relationships for a particular document\n" + "To query for all users that have any relationship with `document:2021-budget`, call read API with body of \n" + "```json\n" + @@ -3308,16 +3311,21 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + "}\n" + "```\n" + "This means that `document:2021-budget` has 1 `reader` (`user:bob`) and 1 `writer` (`user:anne`).\n" + - "*\x04Read\x82\xd3\xe4\x93\x02\x1c:\x01*\"\x17/stores/{store_id}/read\x12\xcc\x12\n" + - "\x05Write\x12\x18.openfga.v1.WriteRequest\x1a\x19.openfga.v1.WriteResponse\"\x8d\x12\x92A\xe6\x11\n" + - "\x13Relationship Tuples\x12#Add or delete tuples from the store\x1a\xa2\x11The 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.\n" + + "*\x04Read\x82\xd3\xe4\x93\x02\x1c:\x01*\"\x17/stores/{store_id}/read\x12\xbe\x12\n" + + "\x05Write\x12\x18.openfga.v1.WriteRequest\x1a\x19.openfga.v1.WriteResponse\"\xff\x11\x92A\xd8\x11\n" + + "\x13Relationship Tuples\x12\x14Add or delete tuples\x1a\xa3\x11The Write API transactionally updates the tuples for a certain store. Tuples and type definitions allow OpenFGA to determine whether a relationship exists between an object and an user.\n" + + "\n" + "In the body, `writes` adds new tuples and `deletes` removes existing tuples. When deleting a tuple, any `condition` specified with it is ignored.\n" + + "\n" + "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.\n" + + "\n" + "To allow writes when an identical tuple already exists in the database, set `\"on_duplicate\": \"ignore\"` on the `writes` object.\n" + "To allow deletes when a tuple was already removed from the database, set `\"on_missing\": \"ignore\"` on the `deletes` object.\n" + "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.\n" + + "\n" + "The API will not allow you to write tuples such as `document:2021-budget#viewer@document:2021-budget#viewer`, because they are implicit.\n" + "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.\n" + + "\n" + "## Example\n" + "### Adding relationships\n" + "To add `user:anne` as a `writer` for `document:2021-budget`, call write API with the following \n" + @@ -3352,14 +3360,32 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + " }\n" + "}\n" + "```\n" + - "*\x05Write\x82\xd3\xe4\x93\x02\x1d:\x01*\"\x18/stores/{store_id}/write\x12\xda*\n" + - "\x05Check\x12\x18.openfga.v1.CheckRequest\x1a\x19.openfga.v1.CheckResponse\"\x9b*\x92A\xf4)\n" + - "\x14Relationship Queries\x126Check whether a user is authorized to access an object\x1a\x9c)The Check API returns whether a given user has a relationship with a given object in a given store.\n" + + "*\x05Write\x82\xd3\xe4\x93\x02\x1d:\x01*\"\x18/stores/{store_id}/write\x12\xdb*\n" + + "\x05Check\x12\x18.openfga.v1.CheckRequest\x1a\x19.openfga.v1.CheckResponse\"\x9c*\x92A\xf5)\n" + + "\x14Relationship Queries\x12\x18Check user authorization\x1a\xbb)The Check API returns whether a given user has a relationship with a given object in a given store.\n" + + "\n" + "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:*`.\n" + - "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`).\n" + + "To arrive at a result, the API uses:\n" + + "\n" + + "- An authorization model\n" + + "\n" + + "- Explicit tuples written through the Write API\n" + + "\n" + + "- Contextual tuples present in the request\n" + + "\n" + + "- Implicit tuples that exist by virtue of applying set theory\n" + + "\n" + + "For example: `document:2021-budget#viewer@document:2021-budget#viewer`. In this example, the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`).\n" + + "\n" + "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`.\n" + - "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.\n" + - "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.\n" + + "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.\n" + + "\n" + + "> **Note:** We recommend you specify authorization model id for better performance.\n" + + "\n" + + "You may also provide a `context` object that will be used to evaluate the conditioned tuples in the system.\n" + + "\n" + + "> **Note:** We recommend you provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.\n" + + "\n" + "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.\n" + "The response will return whether the relationship exists in the field `allowed`.\n" + "\n" + @@ -3472,16 +3498,16 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + " \"consistency\": \"HIGHER_CONSISTENCY\"\n" + "}\n" + "```\n" + - "*\x05Check\x82\xd3\xe4\x93\x02\x1d:\x01*\"\x18/stores/{store_id}/check\x12\x8b\x13\n" + + "*\x05Check\x82\xd3\xe4\x93\x02\x1d:\x01*\"\x18/stores/{store_id}/check\x12\x80\x13\n" + "\n" + - "BatchCheck\x12\x1d.openfga.v1.BatchCheckRequest\x1a\x1e.openfga.v1.BatchCheckResponse\"\xbd\x12\x92A\x90\x12\n" + - "\x14Relationship Queries\x125Send a list of `check` operations in a single request\x1a\xb4\x11The `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.\n" + + "BatchCheck\x12\x1d.openfga.v1.BatchCheckRequest\x1a\x1e.openfga.v1.BatchCheckResponse\"\xb2\x12\x92A\x85\x12\n" + + "\x14Relationship Queries\x12!Send a list of related operations\x1a\xbd\x11The `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.\n" + "\n" + "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}$`\n" + "\n" + - "NOTE: The maximum number of checks that can be passed in the `BatchCheck` API is configurable via the [OPENFGA_MAX_CHECKS_PER_BATCH_CHECK](https://openfga.dev/docs/getting-started/setup-openfga/configuration#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.\n" + + "> **Note:** The maximum number of checks that can be passed in the `BatchCheck` API is configurable via the [OPENFGA_MAX_CHECKS_PER_BATCH_CHECK](https://openfga.dev/docs/getting-started/setup-openfga/configuration#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.\n" + "\n" + - "For more details on how `Check` functions, see the docs for `/check`.\n" + + "For more details on how `Check` functions, review the docs for `/check`.\n" + "\n" + "### Examples\n" + "#### A BatchCheckRequest\n" + @@ -3527,10 +3553,11 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + "}\n" + "```\n" + "*\n" + - "BatchCheck\x82\xd3\xe4\x93\x02#:\x01*\"\x1e/stores/{store_id}/batch-check\x12\xda\x1e\n" + - "\x06Expand\x12\x19.openfga.v1.ExpandRequest\x1a\x1a.openfga.v1.ExpandResponse\"\x98\x1e\x92A\xf0\x1d\n" + - "\x14Relationship Queries\x12\x8e\x01Expand all relationships in userset tree format, and following userset rewrite rules. Useful to reason about and debug a certain relationship\x1a\xbe\x1cThe Expand API will return all users and usersets that have certain relationship with an object in a certain store.\n" + + "BatchCheck\x82\xd3\xe4\x93\x02#:\x01*\"\x1e/stores/{store_id}/batch-check\x12\xf7\x1d\n" + + "\x06Expand\x12\x19.openfga.v1.ExpandRequest\x1a\x1a.openfga.v1.ExpandResponse\"\xb5\x1d\x92A\x8d\x1d\n" + + "\x14Relationship Queries\x12+Expand relationships in userset tree format\x1a\xbf\x1cThe Expand API will return all users and usersets that have certain relationship with an object in a certain store.\n" + "This is different from the `/stores/{store_id}/read` API in that both users and computed usersets are returned.\n" + + "\n" + "Body parameters `tuple_key.object` and `tuple_key.relation` are all required.\n" + "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`.\n" + "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.\n" + @@ -3687,14 +3714,14 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + " }\n" + "}\n" + "```\n" + - "*\x06Expand\x82\xd3\xe4\x93\x02\x1e:\x01*\"\x19/stores/{store_id}/expand\x12\x82\v\n" + - "\x17ReadAuthorizationModels\x12*.openfga.v1.ReadAuthorizationModelsRequest\x1a+.openfga.v1.ReadAuthorizationModelsResponse\"\x8d\n" + - "\x92A\xda\t\n" + - "\x14Authorization Models\x12:Return all the authorization models for a particular store\x1a\xec\bThe ReadAuthorizationModels API will return all the authorization models for a certain store.\n" + - "OpenFGA's response will contain an array of all authorization models, sorted in descending order of creation.\n" + + "*\x06Expand\x82\xd3\xe4\x93\x02\x1e:\x01*\"\x19/stores/{store_id}/expand\x12\xde\n" + + "\n" + + "\x17ReadAuthorizationModels\x12*.openfga.v1.ReadAuthorizationModelsRequest\x1a+.openfga.v1.ReadAuthorizationModelsResponse\"\xe9\t\x92A\xb6\t\n" + + "\x14Authorization Models\x12\x1cGet all authorization models\x1a\xe6\bThe ReadAuthorizationModels API returns all the authorization models for a certain store.\n" + + "OpenFGA's response contains an array of all authorization models, sorted in descending order of creation.\n" + "\n" + "## Example\n" + - "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:\n" + + "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:\n" + "```json\n" + "{\n" + " \"authorization_models\": [\n" + @@ -3726,14 +3753,15 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + " \"continuation_token\": \"\"\n" + "}\n" + "```\n" + - "*\x17ReadAuthorizationModels\x82\xd3\xe4\x93\x02)\x12'/stores/{store_id}/authorization-models\x12\x84\v\n" + - "\x16ReadAuthorizationModel\x12).openfga.v1.ReadAuthorizationModelRequest\x1a*.openfga.v1.ReadAuthorizationModelResponse\"\x92\n" + - "\x92A\xda\t\n" + - "\x14Authorization Models\x125Return a particular version of an authorization model\x1a\xf2\bThe ReadAuthorizationModel API returns an authorization model by its identifier.\n" + + "*\x17ReadAuthorizationModels\x82\xd3\xe4\x93\x02)\x12'/stores/{store_id}/authorization-models\x12\xf6\n" + + "\n" + + "\x16ReadAuthorizationModel\x12).openfga.v1.ReadAuthorizationModelRequest\x1a*.openfga.v1.ReadAuthorizationModelResponse\"\x84\n" + + "\x92A\xcc\t\n" + + "\x14Authorization Models\x12%Get an authorization model by version\x1a\xf4\bThe ReadAuthorizationModel API returns an authorization model by its identifier.\n" + "The response will return the authorization model for the particular version.\n" + "\n" + "## Example\n" + - "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:\n" + + "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:\n" + "```json\n" + "{\n" + " \"authorization_model\":{\n" + @@ -3769,16 +3797,16 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + " }\n" + "}\n" + "```\n" + - "In the above example, there are 2 types (`user` and `document`). The `document` type has 2 relations (`writer` and `reader`).*\x16ReadAuthorizationModel\x82\xd3\xe4\x93\x02.\x12,/stores/{store_id}/authorization-models/{id}\x12\xf9\n" + + "In the above example, there are 2 types (`user` and `document`). The `document` type has 2 relations (`writer` and `reader`).*\x16ReadAuthorizationModel\x82\xd3\xe4\x93\x02.\x12,/stores/{store_id}/authorization-models/{id}\x12\xfd\n" + "\n" + - "\x17WriteAuthorizationModel\x12*.openfga.v1.WriteAuthorizationModelRequest\x1a+.openfga.v1.WriteAuthorizationModelResponse\"\x84\n" + - "\x92A\xce\t\n" + - "\x14Authorization Models\x12 Create a new authorization model\x1a\xa8\bThe WriteAuthorizationModel API will add a new authorization model to a store.\n" + + "\x17WriteAuthorizationModel\x12*.openfga.v1.WriteAuthorizationModelRequest\x1a+.openfga.v1.WriteAuthorizationModelResponse\"\x88\n" + + "\x92A\xd2\t\n" + + "\x14Authorization Models\x12 Create a new authorization model\x1a\xac\bThe WriteAuthorizationModel API will add a new authorization model to a store.\n" + "Each item in the `type_definitions` array is a type definition as specified in the field `type_definition`.\n" + "The response will return the authorization model's ID in the `id` field.\n" + "\n" + "## Example\n" + - "To add an authorization model with `user` and `document` type definitions, call POST authorization-models API with the body: \n" + + "To add an authorization model with `user` and `document` type definitions, call `POST` `authorization-models` API with the body: \n" + "```json\n" + "{\n" + " \"type_definitions\":[\n" + @@ -3818,18 +3846,18 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + "*\x17WriteAuthorizationModelJP\n" + "\x03201\x12I\n" + "\x16A successful response.\x12/\n" + - "-\x1a+.openfga.v1.WriteAuthorizationModelResponse\x82\xd3\xe4\x93\x02,:\x01*\"'/stores/{store_id}/authorization-models\x12\xef\x04\n" + - "\x0fWriteAssertions\x12\".openfga.v1.WriteAssertionsRequest\x1a#.openfga.v1.WriteAssertionsResponse\"\x92\x04\x92A\xcd\x03\n" + + "-\x1a+.openfga.v1.WriteAuthorizationModelResponse\x82\xd3\xe4\x93\x02,:\x01*\"'/stores/{store_id}/authorization-models\x12\xe8\x04\n" + + "\x0fWriteAssertions\x12\".openfga.v1.WriteAssertionsRequest\x1a#.openfga.v1.WriteAssertionsResponse\"\x8b\x04\x92A\xc6\x03\n" + "\n" + - "Assertions\x12/Upsert assertions for an authorization model ID\x1a\xb2\x02The 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.*\x0fWriteAssertionsJH\n" + + "Assertions\x12(Upsert authorization model ID assertions\x1a\xb2\x02The 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.*\x0fWriteAssertionsJH\n" + "\x03204\x12A\n" + "\x16A successful response.\x12'\n" + - "%\x1a#.openfga.v1.WriteAssertionsResponse\x82\xd3\xe4\x93\x02;:\x01*\x1a6/stores/{store_id}/assertions/{authorization_model_id}\x12\xd3\x02\n" + - "\x0eReadAssertions\x12!.openfga.v1.ReadAssertionsRequest\x1a\".openfga.v1.ReadAssertionsResponse\"\xf9\x01\x92A\xb7\x01\n" + + "%\x1a#.openfga.v1.WriteAssertionsResponse\x82\xd3\xe4\x93\x02;:\x01*\x1a6/stores/{store_id}/assertions/{authorization_model_id}\x12\xbd\x02\n" + + "\x0eReadAssertions\x12!.openfga.v1.ReadAssertionsRequest\x1a\".openfga.v1.ReadAssertionsResponse\"\xe3\x01\x92A\xa1\x01\n" + "\n" + - "Assertions\x12-Read assertions for an authorization model ID\x1ajThe ReadAssertions API will return, for a given authorization model id, all the assertions stored for it. *\x0eReadAssertions\x82\xd3\xe4\x93\x028\x126/stores/{store_id}/assertions/{authorization_model_id}\x12\xe3\a\n" + - "\vReadChanges\x12\x1e.openfga.v1.ReadChangesRequest\x1a\x1f.openfga.v1.ReadChangesResponse\"\x92\a\x92A\xec\x06\n" + - "\x13Relationship Tuples\x12&Return a list of all the tuple changes\x1a\x9f\x06The 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.\n" + + "Assertions\x12%Get authorization model ID assertions\x1a\\The ReadAssertions API returns all the assertions stored for a given authorization model id.*\x0eReadAssertions\x82\xd3\xe4\x93\x028\x126/stores/{store_id}/assertions/{authorization_model_id}\x12\xd2\a\n" + + "\vReadChanges\x12\x1e.openfga.v1.ReadChangesRequest\x1a\x1f.openfga.v1.ReadChangesResponse\"\x81\a\x92A\xdb\x06\n" + + "\x13Relationship Tuples\x12\x15Get all tuple changes\x1a\x9f\x06The 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.\n" + "You can use the `type` parameter to only get the list of tuple changes that affect objects of that type.\n" + "When reading a write tuple change, if it was conditioned, the condition will be returned.\n" + "When reading a delete tuple change, the condition will NOT be returned regardless of whether it was originally conditioned or not.\n" + @@ -3856,32 +3884,67 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + "\x06Stores\x12\x0fList all stores\x1a\xa0\x01Returns a paginated list of OpenFGA stores and a continuation token to get additional stores.\n" + "The continuation token will be empty if there are no more stores.\n" + "*\n" + - "ListStores\x82\xd3\xe4\x93\x02\t\x12\a/stores\x12\xf1\x04\n" + - "\x13StreamedListObjects\x12&.openfga.v1.StreamedListObjectsRequest\x1a'.openfga.v1.StreamedListObjectsResponse\"\x86\x04\x92A\xcf\x03\n" + - "\x14Relationship Queries\x12FStream all objects of the given type that the user has a relation with\x1a\xd9\x02The Streamed ListObjects API is very similar to the the ListObjects API, with two differences: \n" + + "ListStores\x82\xd3\xe4\x93\x02\t\x12\a/stores\x12\xd8\x04\n" + + "\x13StreamedListObjects\x12&.openfga.v1.StreamedListObjectsRequest\x1a'.openfga.v1.StreamedListObjectsResponse\"\xed\x03\x92A\xb6\x03\n" + + "\x14Relationship Queries\x12+Stream all objects with a user relationship\x1a\xdb\x02The Streamed ListObjects API is very similar to the the ListObjects API, with two differences: \n" + "1. Instead of collecting all objects before returning a response, it streams them to the client as they are collected. \n" + - "2. The number of results returned is only limited by the execution timeout specified in the flag OPENFGA_LIST_OBJECTS_DEADLINE. \n" + - "*\x13StreamedListObjects\x82\xd3\xe4\x93\x02-:\x01*\"(/stores/{store_id}/streamed-list-objects0\x01\x12\xdd\x11\n" + - "\vListObjects\x12\x1e.openfga.v1.ListObjectsRequest\x1a\x1f.openfga.v1.ListObjectsResponse\"\x8c\x11\x92A\xde\x10\n" + - "\x14Relationship Queries\x12DList all objects of the given type that the user has a relation with\x1a\xf2\x0fThe ListObjects API returns a list of all the objects of the given type that the user has a relation with.\n" + - " 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`).\n" + - "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.\n" + - "You may also specify `contextual_tuples` that will be treated as regular tuples. Each of these tuples may have an associated `condition`.\n" + - "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.\n" + + "2. The number of results returned is only limited by the execution timeout specified in the flag `OPENFGA_LIST_OBJECTS_DEADLINE`. \n" + + "*\x13StreamedListObjects\x82\xd3\xe4\x93\x02-:\x01*\"(/stores/{store_id}/streamed-list-objects0\x01\x12\xd8\x11\n" + + "\vListObjects\x12\x1e.openfga.v1.ListObjectsRequest\x1a\x1f.openfga.v1.ListObjectsResponse\"\x87\x11\x92A\xd9\x10\n" + + "\x14Relationship Queries\x12/List all objects with user-centric relationship\x1a\x82\x10The ListObjects API returns a list of all the objects of the given type that the user has a relation with.\n" + + " To arrive at a result, the API uses:\n" + + "\n" + + "- An authorization model\n" + + "- Explicit tuples written through the Write API\n" + + "- Contextual tuples present in the request\n" + + "- Implicit tuples that exist by virtue of applying set theory. For example:\n" + + "\n" + + "`document:2021-budget#viewer@document:2021-budget#viewer`\n" + + "\n" + + "In the example the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n" + + "\n" + + "An `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID will be used.\n" + + "\n" + + "> **Note:** We recommend you specify authorization model ID for better performance.\n" + + "\n" + + "You may also specify `contextual_tuples` that is treated as regular tuples. Each of these tuples may have an associated `condition`.\n" + + "You may also provide a `context` object that is used to evaluate the conditioned tuples in the system.\n" + + "\n" + + "> **Note:** We recommend you provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.\n" + + "\n" + "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.\n" + - "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 `:` (e.g. \"document:roadmap\").\n" + - "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.\n" + - "The objects given will not be sorted, and therefore two identical calls can give a given different set of objects.*\vListObjects\x82\xd3\xe4\x93\x02$:\x01*\"\x1f/stores/{store_id}/list-objects\x12\xe5\x11\n" + - "\tListUsers\x12\x1c.openfga.v1.ListUsersRequest\x1a\x1d.openfga.v1.ListUsersResponse\"\x9a\x11\x92A\xee\x10\n" + - "\x14Relationship Queries\x12]List the users matching the provided filter who have a certain relation to a particular type.\x1a\xeb\x0fThe ListUsers API returns a list of all the users of a specific type that have a relation to a given object.\n" + - " 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`).\n" + - "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.\n" + + "The response contains the related objects in an array in the \"objects\" field of the response and they will be strings in the object format `:` (e.g. \"document:roadmap\").\n" + + "\n" + + "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.\n" + + "The objects given will not be sorted, and therefore two identical calls can give a given different set of objects.*\vListObjects\x82\xd3\xe4\x93\x02$:\x01*\"\x1f/stores/{store_id}/list-objects\x12\xdc\x11\n" + + "\tListUsers\x12\x1c.openfga.v1.ListUsersRequest\x1a\x1d.openfga.v1.ListUsersResponse\"\x91\x11\x92A\xe5\x10\n" + + "\x14Relationship Queries\x12/List all users with a relationship to an object\x1a\x90\x10The ListUsers API returns a list of all the users of a specific type that have a relation to a given object.\n" + + "\n" + + " To arrive at a result, the API uses:\n" + + "\n" + + "- An authorization model\n" + + "\n" + + "- Explicit tuples written through the Write API\n" + + "\n" + + "- Contextual tuples present in the request\n" + + "\n" + + "- Implicit tuples that exist by virtue of applying set theory\n" + + "\n" + + "For example: `document:2021-budget#viewer@document:2021-budget#viewer`. In this example, the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n" + + "\n" + + "An `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID will be used.\n" + + "\n" + + "> **Note:** We recommend you specify authorization model ID for better performance.\n" + + "\n" + "You may also specify `contextual_tuples` that will be treated as regular tuples. Each of these tuples may have an associated `condition`.\n" + - "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.\n" + + "You may also provide a `context` object that will be used to evaluate the conditioned tuples in the system.\n" + + "\n" + + "> **Note:** We recommend you provide a value for all the input parameters of all the conditions. This ensures that all tuples be evaluated correctly.\n" + + "\n" + "The response will contain the related users in an array in the \"users\" field of the response. These results may include specific objects, usersets \n" + "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\n" + "of that type have a relation to the object; it is possible that negations exist and checks should still be queried\n" + - "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.\n" + + "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.\n" + "The returned users will not be sorted, and therefore two identical calls may yield different sets of users.*\tListUsers\x82\xd3\xe4\x93\x02\":\x01*\"\x1d/stores/{store_id}/list-usersB\xa1\x01\n" + "\x0ecom.openfga.v1B\x13OpenfgaServiceProtoP\x01Z1github.com/openfga/api/proto/openfga/v1;openfgav1\xa2\x02\x03OXX\xaa\x02\n" + "Openfga.V1\xca\x02\n" + From ef3e4c972693f21319046c7dfe6c20e2d7d88ad6 Mon Sep 17 00:00:00 2001 From: amanda-vanscoy Date: Thu, 24 Sep 2026 12:55:05 -0400 Subject: [PATCH 2/4] Regenerate generated files with correct toolchain --- docs/openapiv2/apidocs.swagger.json | 2 +- docs/openapiv3/apidocs.openapi.json | 2 +- proto/openfga/v1/openfga_service.pb.go | 12 +++++++----- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/openapiv2/apidocs.swagger.json b/docs/openapiv2/apidocs.swagger.json index 99cfc49c..d85737cb 100644 --- a/docs/openapiv2/apidocs.swagger.json +++ b/docs/openapiv2/apidocs.swagger.json @@ -1544,7 +1544,7 @@ "/stores/{store_id}/list-users": { "post": { "summary": "List all users with a relationship to an object", - "description": "The ListUsers API returns a list of all the users of a specific type that have a relation to a given object.\n\n To arrive at a result, the API uses:\n\n- An authorization model\n\n- Explicit tuples written through the Write API\n\n- Contextual tuples present in the request\n\n- Implicit tuples that exist by virtue of applying set theory\n\nFor example: `document:2021-budget#viewer@document:2021-budget#viewer`. In this example, the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n\nAn `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID will be used.\n\n> **Note:** We recommend you specify authorization model ID for better performance.\n\nYou may also specify `contextual_tuples` that will be treated as regular tuples. Each of these tuples may have an associated `condition`.\nYou may also provide a `context` object that will be used to evaluate the conditioned tuples in the system.\n\n> **Note:** We recommend you provide a value for all the input parameters of all the conditions. This ensures that all tuples be evaluated correctly.\n\nThe response will contain the related users in an array in the \"users\" field of the response. These results may include specific objects, usersets \nor 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\nof that type have a relation to the object; it is possible that negations exist and checks should still be queried\non 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.\nThe returned users will not be sorted, and therefore two identical calls may yield different sets of users.", + "description": "The ListUsers API returns a list of all the users of a specific type that have a relation to a given object.\n\n To arrive at a result, the API uses:\n\n- An authorization model\n\n- Explicit tuples written through the Write API\n\n- Contextual tuples present in the request\n\n- Implicit tuples that exist by virtue of applying set theory\n\nFor example: `document:2021-budget#viewer@document:2021-budget#viewer`. In this example, the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n\nAn `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID will be used.\n\n> **Note:** We recommend you specify authorization model ID for better performance.\n\nYou may also specify `contextual_tuples` that will be treated as regular tuples. Each of these tuples may have an associated `condition`.\nYou may also provide a `context` object that will be used to evaluate the conditioned tuples in the system.\n\n> **Note:** We recommend you provide a value for all the input parameters of all the conditions. This ensures that all tuples be evaluated correctly.\n\nThe response will contain the related users in an array in the \"users\" field of the response. These results may include specific objects, usersets \nor type-bound public access. Each of these types of results is encoded in its own type and not represented as a string.\n\nIn cases where a type-bound public access result is returned (e.g. `user:*`), it cannot be inferred that all subjects\nof that type have a relation to the object; it is possible that negations exist and checks should still be queried\non 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.\nThe returned users will not be sorted, and therefore two identical calls may yield different sets of users.", "operationId": "ListUsers", "responses": { "200": { diff --git a/docs/openapiv3/apidocs.openapi.json b/docs/openapiv3/apidocs.openapi.json index 079b1865..f4828157 100644 --- a/docs/openapiv3/apidocs.openapi.json +++ b/docs/openapiv3/apidocs.openapi.json @@ -4679,7 +4679,7 @@ }, "/stores/{store_id}/list-users": { "post": { - "description": "The ListUsers API returns a list of all the users of a specific type that have a relation to a given object.\n\n To arrive at a result, the API uses:\n\n- An authorization model\n\n- Explicit tuples written through the Write API\n\n- Contextual tuples present in the request\n\n- Implicit tuples that exist by virtue of applying set theory\n\nFor example: `document:2021-budget#viewer@document:2021-budget#viewer`. In this example, the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n\nAn `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID will be used.\n\n> **Note:** We recommend you specify authorization model ID for better performance.\n\nYou may also specify `contextual_tuples` that will be treated as regular tuples. Each of these tuples may have an associated `condition`.\nYou may also provide a `context` object that will be used to evaluate the conditioned tuples in the system.\n\n> **Note:** We recommend you provide a value for all the input parameters of all the conditions. This ensures that all tuples be evaluated correctly.\n\nThe response will contain the related users in an array in the \"users\" field of the response. These results may include specific objects, usersets \nor 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\nof that type have a relation to the object; it is possible that negations exist and checks should still be queried\non 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.\nThe returned users will not be sorted, and therefore two identical calls may yield different sets of users.", + "description": "The ListUsers API returns a list of all the users of a specific type that have a relation to a given object.\n\n To arrive at a result, the API uses:\n\n- An authorization model\n\n- Explicit tuples written through the Write API\n\n- Contextual tuples present in the request\n\n- Implicit tuples that exist by virtue of applying set theory\n\nFor example: `document:2021-budget#viewer@document:2021-budget#viewer`. In this example, the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n\nAn `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID will be used.\n\n> **Note:** We recommend you specify authorization model ID for better performance.\n\nYou may also specify `contextual_tuples` that will be treated as regular tuples. Each of these tuples may have an associated `condition`.\nYou may also provide a `context` object that will be used to evaluate the conditioned tuples in the system.\n\n> **Note:** We recommend you provide a value for all the input parameters of all the conditions. This ensures that all tuples be evaluated correctly.\n\nThe response will contain the related users in an array in the \"users\" field of the response. These results may include specific objects, usersets \nor type-bound public access. Each of these types of results is encoded in its own type and not represented as a string.\n\nIn cases where a type-bound public access result is returned (e.g. `user:*`), it cannot be inferred that all subjects\nof that type have a relation to the object; it is possible that negations exist and checks should still be queried\non 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.\nThe returned users will not be sorted, and therefore two identical calls may yield different sets of users.", "operationId": "ListUsers", "parameters": [ { diff --git a/proto/openfga/v1/openfga_service.pb.go b/proto/openfga/v1/openfga_service.pb.go index 2404e551..294d4890 100644 --- a/proto/openfga/v1/openfga_service.pb.go +++ b/proto/openfga/v1/openfga_service.pb.go @@ -3207,7 +3207,7 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + "Assertions\x12:\n" + "\n" + "assertions\x18\x01 \x03(\v2\x15.openfga.v1.AssertionB\x03\xe0A\x02R\n" + - "assertions2\xaf\xee\x01\n" + + "assertions2\xb1\xee\x01\n" + "\x0eOpenFGAService\x12\x8f\x1d\n" + "\x04Read\x12\x17.openfga.v1.ReadRequest\x1a\x18.openfga.v1.ReadResponse\"\xd3\x1c\x92A\xad\x1c\n" + "\x13Relationship Tuples\x12\x12Get related tuples\x1a\xfb\x1bThe Read API will return the tuples from a certain store that match a query filter specified in the body of the request. \n" + @@ -3916,9 +3916,9 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + "The response contains the related objects in an array in the \"objects\" field of the response and they will be strings in the object format `:` (e.g. \"document:roadmap\").\n" + "\n" + "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.\n" + - "The objects given will not be sorted, and therefore two identical calls can give a given different set of objects.*\vListObjects\x82\xd3\xe4\x93\x02$:\x01*\"\x1f/stores/{store_id}/list-objects\x12\xdc\x11\n" + - "\tListUsers\x12\x1c.openfga.v1.ListUsersRequest\x1a\x1d.openfga.v1.ListUsersResponse\"\x91\x11\x92A\xe5\x10\n" + - "\x14Relationship Queries\x12/List all users with a relationship to an object\x1a\x90\x10The ListUsers API returns a list of all the users of a specific type that have a relation to a given object.\n" + + "The objects given will not be sorted, and therefore two identical calls can give a given different set of objects.*\vListObjects\x82\xd3\xe4\x93\x02$:\x01*\"\x1f/stores/{store_id}/list-objects\x12\xde\x11\n" + + "\tListUsers\x12\x1c.openfga.v1.ListUsersRequest\x1a\x1d.openfga.v1.ListUsersResponse\"\x93\x11\x92A\xe7\x10\n" + + "\x14Relationship Queries\x12/List all users with a relationship to an object\x1a\x92\x10The ListUsers API returns a list of all the users of a specific type that have a relation to a given object.\n" + "\n" + " To arrive at a result, the API uses:\n" + "\n" + @@ -3942,7 +3942,9 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + "> **Note:** We recommend you provide a value for all the input parameters of all the conditions. This ensures that all tuples be evaluated correctly.\n" + "\n" + "The response will contain the related users in an array in the \"users\" field of the response. These results may include specific objects, usersets \n" + - "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\n" + + "or type-bound public access. Each of these types of results is encoded in its own type and not represented as a string.\n" + + "\n" + + "In cases where a type-bound public access result is returned (e.g. `user:*`), it cannot be inferred that all subjects\n" + "of that type have a relation to the object; it is possible that negations exist and checks should still be queried\n" + "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.\n" + "The returned users will not be sorted, and therefore two identical calls may yield different sets of users.*\tListUsers\x82\xd3\xe4\x93\x02\":\x01*\"\x1d/stores/{store_id}/list-usersB\xa1\x01\n" + From b7d349314fa7ead2f0f77d27501f30dbd471544a Mon Sep 17 00:00:00 2001 From: amanda-vanscoy Date: Thu, 24 Sep 2026 15:52:17 -0400 Subject: [PATCH 3/4] Fix markdown formatting in API descriptions --- docs/openapiv2/apidocs.swagger.json | 66 +++--- docs/openapiv3/apidocs.openapi.json | 66 +++--- openfga/v1/openfga_service.proto | 206 +++++++++---------- proto/openfga/v1/openfga_service.pb.go | 273 +++++++++++++------------ 4 files changed, 316 insertions(+), 295 deletions(-) diff --git a/docs/openapiv2/apidocs.swagger.json b/docs/openapiv2/apidocs.swagger.json index d85737cb..5b5685c7 100644 --- a/docs/openapiv2/apidocs.swagger.json +++ b/docs/openapiv2/apidocs.swagger.json @@ -104,7 +104,7 @@ "/stores": { "get": { "summary": "List all stores", - "description": "Returns a paginated list of OpenFGA stores and a continuation token to get additional stores.\nThe continuation token will be empty if there are no more stores.\n", + "description": "Returns a paginated list of OpenFGA stores and a continuation token to get additional stores.\nThe continuation token is empty if there are no more stores.\n", "operationId": "ListStores", "responses": { "200": { @@ -172,7 +172,7 @@ }, { "name": "name", - "description": "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", + "description": "The name parameter instructs the API to only include results that match that name./nMultiple results may be returned. Only exact matches are returned; substring matches and regexes are not be evaluated.", "in": "query", "required": false, "type": "string" @@ -184,7 +184,7 @@ }, "post": { "summary": "Create a store", - "description": "Create a unique OpenFGA store which will be used to store authorization models and relationship tuples.", + "description": "Create a unique OpenFGA store which is used to store authorization models and relationship tuples.", "operationId": "CreateStore", "responses": { "201": { @@ -837,7 +837,7 @@ }, "put": { "summary": "Upsert authorization model ID assertions", - "description": "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.", + "description": "The WriteAssertions API upserts 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 returns true or false, and optionally a list of contextual tuples.", "operationId": "WriteAssertions", "responses": { "204": { @@ -916,7 +916,7 @@ "/stores/{store_id}/authorization-models": { "get": { "summary": "Get all authorization models", - "description": "The ReadAuthorizationModels API returns all the authorization models for a certain store.\nOpenFGA's response contains an array of all authorization models, sorted in descending order of creation.\n\n## Example\nAssume 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:\n```json\n{\n \"authorization_models\": [\n {\n \"id\": \"01G50QVV17PECNVAHX1GG4Y5NC\",\n \"type_definitions\": [...]\n },\n {\n \"id\": \"01G4ZW8F4A07AKQ8RHSVG9RW04\",\n \"type_definitions\": [...]\n },\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nIf there are no more authorization models available, the `continuation_token` field will be empty\n```json\n{\n \"authorization_models\": [\n {\n \"id\": \"01G50QVV17PECNVAHX1GG4Y5NC\",\n \"type_definitions\": [...]\n },\n {\n \"id\": \"01G4ZW8F4A07AKQ8RHSVG9RW04\",\n \"type_definitions\": [...]\n },\n ],\n \"continuation_token\": \"\"\n}\n```\n", + "description": "The ReadAuthorizationModels API returns all the authorization models for a certain store.\nOpenFGA's response contains an array of all authorization models, sorted in descending order of creation.\n\n## Example\n\nAssume 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 returns a response that looks like:\n\n```json\n{\n \"authorization_models\": [\n {\n \"id\": \"01G50QVV17PECNVAHX1GG4Y5NC\",\n \"type_definitions\": [...]\n },\n {\n \"id\": \"01G4ZW8F4A07AKQ8RHSVG9RW04\",\n \"type_definitions\": [...]\n },\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nIf there are no more authorization models available, then `continuation_token` field returns empty:\n\n```json\n{\n \"authorization_models\": [\n {\n \"id\": \"01G50QVV17PECNVAHX1GG4Y5NC\",\n \"type_definitions\": [...]\n },\n {\n \"id\": \"01G4ZW8F4A07AKQ8RHSVG9RW04\",\n \"type_definitions\": [...]\n },\n ],\n \"continuation_token\": \"\"\n}\n```\n", "operationId": "ReadAuthorizationModels", "responses": { "200": { @@ -995,7 +995,7 @@ }, "post": { "summary": "Create a new authorization model", - "description": "The WriteAuthorizationModel API will add a new authorization model to a store.\nEach item in the `type_definitions` array is a type definition as specified in the field `type_definition`.\nThe response will return the authorization model's ID in the `id` field.\n\n## Example\nTo add an authorization model with `user` and `document` type definitions, call `POST` `authorization-models` API with the body: \n```json\n{\n \"type_definitions\":[\n {\n \"type\":\"user\"\n },\n {\n \"type\":\"document\",\n \"relations\":{\n \"reader\":{\n \"union\":{\n \"child\":[\n {\n \"this\":{}\n },\n {\n \"computedUserset\":{\n \"object\":\"\",\n \"relation\":\"writer\"\n }\n }\n ]\n }\n },\n \"writer\":{\n \"this\":{}\n }\n }\n }\n ]\n}\n```\nOpenFGA's response will include the version id for this authorization model, which will look like \n```\n{\"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"}\n```\n", + "description": "The WriteAuthorizationModel API adds a new authorization model to a store.\nEach item in the `type_definitions` array is a type definition as specified in the field `type_definition`.\nThe response returns the authorization model's ID in the `id` field.\n\n## Example\n\nTo add an authorization model with `user` and `document` type definitions, call `POST` `authorization-models` API with the body: \n```json\n{\n \"type_definitions\":[\n {\n \"type\":\"user\"\n },\n {\n \"type\":\"document\",\n \"relations\":{\n \"reader\":{\n \"union\":{\n \"child\":[\n {\n \"this\":{}\n },\n {\n \"computedUserset\":{\n \"object\":\"\",\n \"relation\":\"writer\"\n }\n }\n ]\n }\n },\n \"writer\":{\n \"this\":{}\n }\n }\n }\n ]\n}\n```\nOpenFGA's response includes the version id for this authorization model, similar to:\n```\n{\"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"}\n```\n", "operationId": "WriteAuthorizationModel", "responses": { "201": { @@ -1071,7 +1071,7 @@ "/stores/{store_id}/authorization-models/{id}": { "get": { "summary": "Get an authorization model by version", - "description": "The ReadAuthorizationModel API returns an authorization model by its identifier.\nThe response will return the authorization model for the particular version.\n\n## Example\nTo 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:\n```json\n{\n \"authorization_model\":{\n \"id\":\"01G5JAVJ41T49E9TT3SKVS7X1J\",\n \"type_definitions\":[\n {\n \"type\":\"user\"\n },\n {\n \"type\":\"document\",\n \"relations\":{\n \"reader\":{\n \"union\":{\n \"child\":[\n {\n \"this\":{}\n },\n {\n \"computedUserset\":{\n \"object\":\"\",\n \"relation\":\"writer\"\n }\n }\n ]\n }\n },\n \"writer\":{\n \"this\":{}\n }\n }\n }\n ]\n }\n}\n```\nIn the above example, there are 2 types (`user` and `document`). The `document` type has 2 relations (`writer` and `reader`).", + "description": "The ReadAuthorizationModel API returns an authorization model by its identifier.\nThe response returns the authorization model for the particular version.\n\n## Example\n\nTo 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 returns:\n```json\n{\n \"authorization_model\":{\n \"id\":\"01G5JAVJ41T49E9TT3SKVS7X1J\",\n \"type_definitions\":[\n {\n \"type\":\"user\"\n },\n {\n \"type\":\"document\",\n \"relations\":{\n \"reader\":{\n \"union\":{\n \"child\":[\n {\n \"this\":{}\n },\n {\n \"computedUserset\":{\n \"object\":\"\",\n \"relation\":\"writer\"\n }\n }\n ]\n }\n },\n \"writer\":{\n \"this\":{}\n }\n }\n }\n ]\n }\n}\n```\nIn the above example, there are 2 types (`user` and `document`). The `document` type has 2 relations (`writer` and `reader`).", "operationId": "ReadAuthorizationModel", "responses": { "200": { @@ -1144,8 +1144,8 @@ }, "/stores/{store_id}/batch-check": { "post": { - "summary": "Send a list of related operations", - "description": "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.\n\nAn 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}$`\n\n> **Note:** The maximum number of checks that can be passed in the `BatchCheck` API is configurable via the [OPENFGA_MAX_CHECKS_PER_BATCH_CHECK](https://openfga.dev/docs/getting-started/setup-openfga/configuration#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.\n\nFor more details on how `Check` functions, review the docs for `/check`.\n\n### Examples\n#### A BatchCheckRequest\n```json\n{\n \"checks\": [\n {\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n \"relation\": \"reader\",\n \"user\": \"user:anne\",\n },\n \"contextual_tuples\": {...}\n \"context\": {}\n \"correlation_id\": \"01JA8PM3QM7VBPGB8KMPK8SBD5\"\n },\n {\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n \"relation\": \"reader\",\n \"user\": \"user:bob\",\n },\n \"contextual_tuples\": {...}\n \"context\": {}\n \"correlation_id\": \"01JA8PMM6A90NV5ET0F28CYSZQ\"\n }\n ]\n}\n```\n\nBelow 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:\n```json\n{\n \"result\": {\n \"01JA8PMM6A90NV5ET0F28CYSZQ\": {\n \"allowed\": false, \n \"error\": {\"message\": \"\"} \n },\n \"01JA8PM3QM7VBPGB8KMPK8SBD5\": {\n \"allowed\": true, \n \"error\": {\"message\": \"\"} \n }\n}\n```\n", + "summary": "Check multiple relationships in a single request", + "description": "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.\n\nAn 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}$`\n\n> **Note:** The maximum number of checks that can be passed in the `BatchCheck` API is configurable using the environment variable: `[OPENFGA_MAX_CHECKS_PER_BATCH_CHECK](https://openfga.dev/docs/getting-started/setup-openfga/configuration#OPENFGA_MAX_CHECKS_PER_BATCH_CHECK)`. If `BatchCheck` is called using the SDK, the SDK can split the batch check requests for you.\n\nFor more details on how `Check` functions, review the docs for `/check`.\n\n### Examples\n\n#### A BatchCheckRequest\n```json\n{\n \"checks\": [\n {\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n \"relation\": \"reader\",\n \"user\": \"user:anne\",\n },\n \"contextual_tuples\": {...}\n \"context\": {}\n \"correlation_id\": \"01JA8PM3QM7VBPGB8KMPK8SBD5\"\n },\n {\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n \"relation\": \"reader\",\n \"user\": \"user:bob\",\n },\n \"contextual_tuples\": {...}\n \"context\": {}\n \"correlation_id\": \"01JA8PMM6A90NV5ET0F28CYSZQ\"\n }\n ]\n}\n```\n\nBelow 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:\n```json\n{\n \"result\": {\n \"01JA8PMM6A90NV5ET0F28CYSZQ\": {\n \"allowed\": false, \n \"error\": {\"message\": \"\"} \n },\n \"01JA8PM3QM7VBPGB8KMPK8SBD5\": {\n \"allowed\": true, \n \"error\": {\"message\": \"\"} \n }\n}\n```\n", "operationId": "BatchCheck", "responses": { "200": { @@ -1221,7 +1221,7 @@ "/stores/{store_id}/changes": { "get": { "summary": "Get all tuple changes", - "description": "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.\nYou can use the `type` parameter to only get the list of tuple changes that affect objects of that type.\nWhen reading a write tuple change, if it was conditioned, the condition will be returned.\nWhen reading a delete tuple change, the condition will NOT be returned regardless of whether it was originally conditioned or not.\n", + "description": "The ReadChanges API returns a paginated list of tuple changes (additions and deletions) that occurred in a given store, sorted by ascending time. The response includes 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 is returned in order for it to be used when new changes are recorded.\n\nIf the store never had any tuples added or removed, then this token returns empty.\nYou can use the `type` parameter to only get the list of tuple changes that affect objects of that type.\nWhen reading a write tuple change, if it was conditioned, the condition is returned.\nWhen reading a delete tuple change, the condition is NOT returned regardless of whether it was originally conditioned or not.\n", "operationId": "ReadChanges", "responses": { "200": { @@ -1301,7 +1301,7 @@ }, { "name": "start_time", - "description": "Start date and time of changes to read.\nFormat: ISO 8601 timestamp (e.g., 2022-01-01T00:00:00Z)\nIf a continuation_token is provided along side start_time, the continuation_token will take precedence over start_time.", + "description": "Start date and time of changes to read.\nFormat: ISO 8601 timestamp (e.g., 2022-01-01T00:00:00Z)\nIf a `continuation_token` is provided along side `start_time`, the `continuation_token` takes precedence over `start_time`.", "in": "query", "required": false, "type": "string", @@ -1316,7 +1316,7 @@ "/stores/{store_id}/check": { "post": { "summary": "Check user authorization", - "description": "The Check API returns whether a given user has a relationship with a given object in a given store.\n\nThe `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:*`.\nTo arrive at a result, the API uses:\n\n- An authorization model\n\n- Explicit tuples written through the Write API\n\n- Contextual tuples present in the request\n\n- Implicit tuples that exist by virtue of applying set theory\n\nFor example: `document:2021-budget#viewer@document:2021-budget#viewer`. In this example, the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`).\n\nA `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`.\nYou 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.\n\n> **Note:** We recommend you specify authorization model id for better performance.\n\nYou may also provide a `context` object that will be used to evaluate the conditioned tuples in the system.\n\n> **Note:** We recommend you provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.\n\nBy 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.\nThe response will return whether the relationship exists in the field `allowed`.\n\nSome 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. \nFor 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.\n## Examples\n### Querying with contextual tuples\nIn order to check if user `user:anne` of type `user` has a `reader` relationship with object `document:2021-budget` given the following contextual tuple\n```json\n{\n \"user\": \"user:anne\",\n \"relation\": \"member\",\n \"object\": \"time_slot:office_hours\"\n}\n```\nthe Check API can be used with the following request body:\n```json\n{\n \"tuple_key\": {\n \"user\": \"user:anne\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"contextual_tuples\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:anne\",\n \"relation\": \"member\",\n \"object\": \"time_slot:office_hours\"\n }\n ]\n },\n \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n}\n```\n### Querying usersets\nSome Checks will always return `true`, even without any tuples. For example, for the following authorization model\n```python\nmodel\n schema 1.1\ntype user\ntype document\n relations\n define reader: [user]\n```\nthe following query\n```json\n{\n \"tuple_key\": {\n \"user\": \"document:2021-budget#reader\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n }\n}\n```\nwill 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`.\n### Querying usersets with difference in the model\nA Check for a userset can yield results that must be treated carefully if the model involves difference. For example, for the following authorization model\n```python\nmodel\n schema 1.1\ntype user\ntype group\n relations\n define member: [user]\ntype document\n relations\n define blocked: [user]\n define reader: [group#member] but not blocked\n```\nthe following query\n```json\n{\n \"tuple_key\": {\n \"user\": \"group:finance#member\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"contextual_tuples\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:anne\",\n \"relation\": \"member\",\n \"object\": \"group:finance\"\n },\n {\n \"user\": \"group:finance#member\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n {\n \"user\": \"user:anne\",\n \"relation\": \"blocked\",\n \"object\": \"document:2021-budget\"\n }\n ]\n },\n}\n```\nwill return `{ \"allowed\": true }`, even though a specific user of the userset `group:finance#member` does not have the `reader` relationship with the given object.\n### Requesting higher consistency\nBy 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.\n```json\n{\n \"tuple_key\": {\n \"user\": \"group:finance#member\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"consistency\": \"HIGHER_CONSISTENCY\"\n}\n```\n", + "description": "The Check API returns whether a given user has a relationship with a given object in a given store.\n\nThe `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:*`.\nTo arrive at a result, the API uses:\n\n- An [authorization model](/docs/getting-started/configure-model)\n\n- Explicit tuples written through the Write API\n\n- Contextual tuples present in the request\n\n- Implicit tuples that exist by virtue of applying set theory\n\nFor example: `document:2021-budget#viewer@document:2021-budget#viewer`. In this example, the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n\nA `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`.\nYou may also provide an `authorization_model_id` in the body. This is used to assert that the input `tuple_key` is valid for the model specified. If not specified, the assertion is made against the latest authorization model ID.\n\n> **Note:** We recommend you specify authorization model id for better performance.\n\nYou may also provide a `context` object that is used to evaluate the conditioned tuples in the system.\n\n> **Note:** We recommend you provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.\n\nBy 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.\nThe response returns whether the relationship exists in the field `allowed`.\n\nSome 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. \nFor 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.\n## Examples\n\n### Querying with contextual tuples\n\nIn order to check if user `user:anne` of type `user` has a `reader` relationship with object `document:2021-budget` given the following contextual tuple:\n```json\n{\n \"user\": \"user:anne\",\n \"relation\": \"member\",\n \"object\": \"time_slot:office_hours\"\n}\n```\nthe Check API can be used with the following request body:\n```json\n{\n \"tuple_key\": {\n \"user\": \"user:anne\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"contextual_tuples\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:anne\",\n \"relation\": \"member\",\n \"object\": \"time_slot:office_hours\"\n }\n ]\n },\n \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n}\n```\n### Querying usersets\n\nSome Checks always return `true`, even without any tuples. For example, for the following authorization model:\n```python\nmodel\n schema 1.1\ntype user\ntype document\n relations\n define reader: [user]\n```\nthe following query:\n```json\n{\n \"tuple_key\": {\n \"user\": \"document:2021-budget#reader\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n }\n}\n```\nalways returns `{ \"allowed\": true }`. This is because usersets are self-defining: the userset `document:2021-budget#reader` always has the `reader` relation with `document:2021-budget`.\n### Querying usersets with difference in the model\n\nA Check for a userset can yield results that must be treated carefully if the model involves difference. For example, for the following authorization model:\n```python\nmodel\n schema 1.1\ntype user\ntype group\n relations\n define member: [user]\ntype document\n relations\n define blocked: [user]\n define reader: [group#member] but not blocked\n```\nthe following query:\n```json\n{\n \"tuple_key\": {\n \"user\": \"group:finance#member\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"contextual_tuples\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:anne\",\n \"relation\": \"member\",\n \"object\": \"group:finance\"\n },\n {\n \"user\": \"group:finance#member\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n {\n \"user\": \"user:anne\",\n \"relation\": \"blocked\",\n \"object\": \"document:2021-budget\"\n }\n ]\n },\n}\n```\nreturns `{ \"allowed\": true }`, even though a specific user of the userset `group:finance#member` does not have the `reader` relationship with the given object.\n### Requesting higher consistency\n\nBy 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.\n```json\n{\n \"tuple_key\": {\n \"user\": \"group:finance#member\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"consistency\": \"HIGHER_CONSISTENCY\"\n}\n```\n", "operationId": "Check", "responses": { "200": { @@ -1392,7 +1392,7 @@ "/stores/{store_id}/expand": { "post": { "summary": "Expand relationships in userset tree format", - "description": "The Expand API will return all users and usersets that have certain relationship with an object in a certain store.\nThis is different from the `/stores/{store_id}/read` API in that both users and computed usersets are returned.\n\nBody parameters `tuple_key.object` and `tuple_key.relation` are all required.\nA `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`.\nThe response will return a tree whose leaves are the specific users and usersets. Union, intersection and difference operator are located in the intermediate nodes.\n\n## Example\nTo expand all users that have the `reader` relationship with object `document:2021-budget`, use the Expand API with the following request body\n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\",\n \"relation\": \"reader\"\n },\n \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n}\n```\nOpenFGA's response will be a userset tree of the users and usersets that have read access to the document.\n```json\n{\n \"tree\":{\n \"root\":{\n \"type\":\"document:2021-budget#reader\",\n \"union\":{\n \"nodes\":[\n {\n \"type\":\"document:2021-budget#reader\",\n \"leaf\":{\n \"users\":{\n \"users\":[\n \"user:bob\"\n ]\n }\n }\n },\n {\n \"type\":\"document:2021-budget#reader\",\n \"leaf\":{\n \"computed\":{\n \"userset\":\"document:2021-budget#writer\"\n }\n }\n }\n ]\n }\n }\n }\n}\n```\nThe caller can then call expand API for the `writer` relationship for the `document:2021-budget`.\n### Expand Request with Contextual Tuples\n\nGiven the model\n```python\nmodel\n schema 1.1\n\ntype user\n\ntype folder\n relations\n define owner: [user]\n\ntype document\n relations\n define parent: [folder]\n define viewer: [user] or writer\n define writer: [user] or owner from parent\n```\nand the initial tuples\n```json\n[{\n \"user\": \"user:bob\",\n \"relation\": \"owner\",\n \"object\": \"folder:1\"\n}]\n```\n\nTo expand all `writers` of `document:1` when `document:1` is put in `folder:1`, the first call could be\n\n```json\n{\n \"tuple_key\": {\n \"object\": \"document:1\",\n \"relation\": \"writer\"\n },\n \"contextual_tuples\": {\n \"tuple_keys\": [\n {\n \"user\": \"folder:1\",\n \"relation\": \"parent\",\n \"object\": \"document:1\"\n }\n ]\n }\n}\n```\nthis returns:\n```json\n{\n \"tree\": {\n \"root\": {\n \"name\": \"document:1#writer\",\n \"union\": {\n \"nodes\": [\n {\n \"name\": \"document:1#writer\",\n \"leaf\": {\n \"users\": {\n \"users\": []\n }\n }\n },\n {\n \"name\": \"document:1#writer\",\n \"leaf\": {\n \"tupleToUserset\": {\n \"tupleset\": \"document:1#parent\",\n \"computed\": [\n {\n \"userset\": \"folder:1#owner\"\n }\n ]\n }\n }\n }\n ]\n }\n }\n }\n}\n```\nThis 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`\n```json\n{\n \"tuple_key\": {\n \"object\": \"folder:1\",\n \"relation\": \"owner\"\n }\n}\n```\nwhich gives\n```json\n{\n \"tree\": {\n \"root\": {\n \"name\": \"folder:1#owner\",\n \"leaf\": {\n \"users\": {\n \"users\": [\n \"user:bob\"\n ]\n }\n }\n }\n }\n}\n```\n", + "description": "The Expand API returns all users and usersets that have certain relationship with an object in a certain store.\nThis is different from the `/stores/{store_id}/read` API in that both users and computed usersets are returned.\n\nBody parameters `tuple_key.object` and `tuple_key.relation` are all required.\nA `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`.\nThe response returns a tree whose leaves are the specific users and usersets. Union, intersection and difference operator are located in the intermediate nodes.\n\n## Example\n\nTo expand all users that have the `reader` relationship with object `document:2021-budget`, use the Expand API with the following request body:\n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\",\n \"relation\": \"reader\"\n },\n \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n}\n```\nOpenFGA's response is a userset tree of the users and usersets that have read access to the document.\n```json\n{\n \"tree\":{\n \"root\":{\n \"type\":\"document:2021-budget#reader\",\n \"union\":{\n \"nodes\":[\n {\n \"type\":\"document:2021-budget#reader\",\n \"leaf\":{\n \"users\":{\n \"users\":[\n \"user:bob\"\n ]\n }\n }\n },\n {\n \"type\":\"document:2021-budget#reader\",\n \"leaf\":{\n \"computed\":{\n \"userset\":\"document:2021-budget#writer\"\n }\n }\n }\n ]\n }\n }\n }\n}\n```\nThe caller can then call expand API for the `writer` relationship for the `document:2021-budget`.\n### Expand Request with Contextual Tuples\n\n\nGiven the model\n```python\nmodel\n schema 1.1\n\ntype user\n\ntype folder\n relations\n define owner: [user]\n\ntype document\n relations\n define parent: [folder]\n define viewer: [user] or writer\n define writer: [user] or owner from parent\n```\nand the initial tuples\n```json\n[{\n \"user\": \"user:bob\",\n \"relation\": \"owner\",\n \"object\": \"folder:1\"\n}]\n```\n\nTo expand all `writers` of `document:1` when `document:1` is put in `folder:1`, the first call could be:\n\n```json\n{\n \"tuple_key\": {\n \"object\": \"document:1\",\n \"relation\": \"writer\"\n },\n \"contextual_tuples\": {\n \"tuple_keys\": [\n {\n \"user\": \"folder:1\",\n \"relation\": \"parent\",\n \"object\": \"document:1\"\n }\n ]\n }\n}\n```\nthis returns:\n```json\n{\n \"tree\": {\n \"root\": {\n \"name\": \"document:1#writer\",\n \"union\": {\n \"nodes\": [\n {\n \"name\": \"document:1#writer\",\n \"leaf\": {\n \"users\": {\n \"users\": []\n }\n }\n },\n {\n \"name\": \"document:1#writer\",\n \"leaf\": {\n \"tupleToUserset\": {\n \"tupleset\": \"document:1#parent\",\n \"computed\": [\n {\n \"userset\": \"folder:1#owner\"\n }\n ]\n }\n }\n }\n ]\n }\n }\n }\n}\n```\nThis 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`\n```json\n{\n \"tuple_key\": {\n \"object\": \"folder:1\",\n \"relation\": \"owner\"\n }\n}\n```\nwhich gives\n```json\n{\n \"tree\": {\n \"root\": {\n \"name\": \"folder:1#owner\",\n \"leaf\": {\n \"users\": {\n \"users\": [\n \"user:bob\"\n ]\n }\n }\n }\n }\n}\n```\n", "operationId": "Expand", "responses": { "200": { @@ -1468,7 +1468,7 @@ "/stores/{store_id}/list-objects": { "post": { "summary": "List all objects with user-centric relationship", - "description": "The ListObjects API returns a list of all the objects of the given type that the user has a relation with.\n To arrive at a result, the API uses:\n\n- An authorization model\n- Explicit tuples written through the Write API\n- Contextual tuples present in the request\n- Implicit tuples that exist by virtue of applying set theory. For example:\n\n`document:2021-budget#viewer@document:2021-budget#viewer`\n\nIn the example the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n\nAn `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID will be used.\n\n> **Note:** We recommend you specify authorization model ID for better performance.\n\nYou may also specify `contextual_tuples` that is treated as regular tuples. Each of these tuples may have an associated `condition`.\nYou may also provide a `context` object that is used to evaluate the conditioned tuples in the system.\n\n> **Note:** We recommend you provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.\n\nBy 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.\nThe response contains the related objects in an array in the \"objects\" field of the response and they will be strings in the object format `:` (e.g. \"document:roadmap\").\n\nThe 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.\nThe objects given will not be sorted, and therefore two identical calls can give a given different set of objects.", + "description": "The ListObjects API returns a list of all the objects of the given type that the user has a relation with.\n To arrive at a result, the API uses:\n\n- An [authorization model](/docs/getting-started/configure-model)\n- Explicit tuples written through the Write API\n- Contextual tuples present in the request\n- Implicit tuples that exist by virtue of applying set theory. For example:\n\n`document:2021-budget#viewer@document:2021-budget#viewer`\n\nIn the example the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n\nAn `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID is used.\n\n> **Note:** We recommend you specify authorization model ID for better performance.\n\nYou may also specify `contextual_tuples` that is treated as regular tuples. Each of these tuples may have an associated `condition`.\nYou may also provide a `context` object that is used to evaluate the conditioned tuples in the system.\n\n> **Note:** We recommend you provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.\n\nBy 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.\nThe response contains the related objects in an array in the \"objects\" field of the response and are strings in the object format `:` (e.g. \"document:roadmap\").\n\nThe number of objects in the response array are 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.\nThe objects given are not sorted, and therefore two identical calls can give a given different set of objects.", "operationId": "ListObjects", "responses": { "200": { @@ -1544,7 +1544,7 @@ "/stores/{store_id}/list-users": { "post": { "summary": "List all users with a relationship to an object", - "description": "The ListUsers API returns a list of all the users of a specific type that have a relation to a given object.\n\n To arrive at a result, the API uses:\n\n- An authorization model\n\n- Explicit tuples written through the Write API\n\n- Contextual tuples present in the request\n\n- Implicit tuples that exist by virtue of applying set theory\n\nFor example: `document:2021-budget#viewer@document:2021-budget#viewer`. In this example, the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n\nAn `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID will be used.\n\n> **Note:** We recommend you specify authorization model ID for better performance.\n\nYou may also specify `contextual_tuples` that will be treated as regular tuples. Each of these tuples may have an associated `condition`.\nYou may also provide a `context` object that will be used to evaluate the conditioned tuples in the system.\n\n> **Note:** We recommend you provide a value for all the input parameters of all the conditions. This ensures that all tuples be evaluated correctly.\n\nThe response will contain the related users in an array in the \"users\" field of the response. These results may include specific objects, usersets \nor type-bound public access. Each of these types of results is encoded in its own type and not represented as a string.\n\nIn cases where a type-bound public access result is returned (e.g. `user:*`), it cannot be inferred that all subjects\nof that type have a relation to the object; it is possible that negations exist and checks should still be queried\non 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.\nThe returned users will not be sorted, and therefore two identical calls may yield different sets of users.", + "description": "The ListUsers API returns a list of all the users of a specific type that have a relation to a given object.\n\n To arrive at a result, the API uses:\n\n- An [authorization model](/docs/getting-started/configure-model)\n\n- Explicit tuples written through the Write API\n\n- Contextual tuples present in the request\n\n- Implicit tuples that exist by virtue of applying set theory\n\nFor example: `document:2021-budget#viewer@document:2021-budget#viewer`. In this example, the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n\nAn `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID is used.\n\n> **Note:** We recommend you specify authorization model ID for better performance.\n\nYou may also specify `contextual_tuples` that are treated as regular tuples. Each of these tuples may have an associated `condition`.\nYou may also provide a `context` object used to evaluate the conditioned tuples in the system.\n\n> **Note:** We recommend you provide a value for all the input parameters of all the conditions. This ensures that all tuples be evaluated correctly.\n\nThe response contains the related users in an array in the \"users\" field of the response. These results may include specific objects, usersets \nor type-bound public access. Each of these types of results is encoded in its own type and not represented as a string.\n\nIn cases where a type-bound public access result is returned (e.g. `user:*`), it cannot be inferred that all subjects\nof that type have a relation to the object; it is possible that negations exist and checks should still be queried\non individual subjects to ensure access to that document.\nThe number of users in the response array are 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.\nThe returned users are not sorted, and therefore two identical calls may yield different sets of users.", "operationId": "ListUsers", "responses": { "200": { @@ -1620,7 +1620,7 @@ "/stores/{store_id}/read": { "post": { "summary": "Get related tuples", - "description": "The Read API will return the tuples from a certain store that match a query filter specified in the body of the request. \nThe API doesn't guarantee order by any field. \nIt 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. \nIn the body:\n1. `tuple_key` is optional. If not specified, it will return all tuples in the store.\n2. `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:`).\n3. `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`).\n\n## Examples\n### Query for all objects in a type definition\nTo query for all objects that `user:bob` has `reader` relationship in the `document` type definition, call read API with body of\n```json\n{\n \"tuple_key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:\"\n }\n}\n```\nThe API will return tuples and a continuation token, something like\n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis 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.\nThe continuation token will be empty if there are no more tuples to query.\n\n### Query for all stored relationship tuples that have a particular relation and object\nTo query for all users that have `reader` relationship with `document:2021-budget`, call read API with body of \n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\",\n \"relation\": \"reader\"\n }\n}\n```\nThe API will return something like \n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis 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.\n\n### Query for all users with all relationships for a particular document\nTo query for all users that have any relationship with `document:2021-budget`, call read API with body of \n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n }\n}\n```\nThe API will return something like \n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:anne\",\n \"relation\": \"writer\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-05T13:42:12.356Z\"\n },\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis means that `document:2021-budget` has 1 `reader` (`user:bob`) and 1 `writer` (`user:anne`).\n", + "description": "The Read API returns the tuples from a certain store that match a query filter specified in the body of the request. \nThe API doesn't guarantee order by any field. \nIt 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. \nIn the body:\n1. `tuple_key` is optional. If not specified, it returns all tuples in the store.\n2. `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:`).\n3. `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`).\n\n## Examples\n\n### Query for all objects in a type definition\n\nTo query for all objects that `user:bob` has `reader` relationship in the `document` type definition, call read API with body of\n```json\n{\n \"tuple_key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:\"\n }\n}\n```\nThe API returns tuples and a continuation token, similar to:\n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis 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.\nThe continuation token is empty if there are no more tuples to query.\n\n### Query for all stored relationship tuples that have a particular relation and object\n\nTo query for all users that have `reader` relationship with `document:2021-budget`, call read API with body of \n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\",\n \"relation\": \"reader\"\n }\n}\n```\nThe API returns something similar to: \n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis 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 does not return writers such as `user:anne` because it only returns tuples and does not evaluate them.\n\n### Query for all users with all relationships for a particular document\n\nTo query for all users that have any relationship with `document:2021-budget`, call read API with body of \n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n }\n}\n```\nThe API returns something similar to:\n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:anne\",\n \"relation\": \"writer\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-05T13:42:12.356Z\"\n },\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis means that `document:2021-budget` has 1 `reader` (`user:bob`) and 1 `writer` (`user:anne`).\n", "operationId": "Read", "responses": { "200": { @@ -1781,7 +1781,7 @@ "/stores/{store_id}/write": { "post": { "summary": "Add or delete tuples", - "description": "The Write API transactionally updates the tuples for a certain store. Tuples and type definitions allow OpenFGA to determine whether a relationship exists between an object and an user.\n\nIn the body, `writes` adds new tuples and `deletes` removes existing tuples. When deleting a tuple, any `condition` specified with it is ignored.\n\nThe 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.\n\nTo allow writes when an identical tuple already exists in the database, set `\"on_duplicate\": \"ignore\"` on the `writes` object.\nTo allow deletes when a tuple was already removed from the database, set `\"on_missing\": \"ignore\"` on the `deletes` object.\nIf 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.\n\nThe API will not allow you to write tuples such as `document:2021-budget#viewer@document:2021-budget#viewer`, because they are implicit.\nAn `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.\n\n## Example\n### Adding relationships\nTo add `user:anne` as a `writer` for `document:2021-budget`, call write API with the following \n```json\n{\n \"writes\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:anne\",\n \"relation\": \"writer\",\n \"object\": \"document:2021-budget\"\n }\n ],\n \"on_duplicate\": \"ignore\"\n },\n \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n}\n```\n### Removing relationships\nTo remove `user:bob` as a `reader` for `document:2021-budget`, call write API with the following \n```json\n{\n \"deletes\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n }\n ],\n \"on_missing\": \"ignore\"\n }\n}\n```\n", + "description": "The Write API transactionally updates the tuples for a certain store. Tuples and type definitions allow OpenFGA to determine whether a relationship exists between an object and an user.\n\nIn the body, `writes` adds new tuples and `deletes` removes existing tuples. When deleting a tuple, any `condition` specified with it is ignored.\n\nThe 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 throws an error.\n\nTo allow writes when an identical tuple already exists in the database, set `\"on_duplicate\": \"ignore\"` on the `writes` object.\nTo allow deletes when a tuple was already removed from the database, set `\"on_missing\": \"ignore\"` on the `deletes` object.\nIf a Write request contains both idempotent (ignore) and non-idempotent (error) operations, the most restrictive action (error) takes 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.\n\nThe API does not allow you to write tuples such as `document:2021-budget#viewer@document:2021-budget#viewer`, because they are implicit.\nAn `authorization_model_id` may be specified in the body. If it is, model ID is 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 is used.\n\n## Example\n\n### Adding relationships\n\nTo add `user:anne` as a `writer` for `document:2021-budget`, call write API with the following:\n```json\n{\n \"writes\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:anne\",\n \"relation\": \"writer\",\n \"object\": \"document:2021-budget\"\n }\n ],\n \"on_duplicate\": \"ignore\"\n },\n \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n}\n```\n### Removing relationships\n\nTo remove `user:bob` as a `reader` for `document:2021-budget`, call write API with the following:\n```json\n{\n \"deletes\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n }\n ],\n \"on_missing\": \"ignore\"\n }\n}\n```\n", "operationId": "Write", "responses": { "200": { @@ -1955,7 +1955,7 @@ "example": { "view_count": 100 }, - "description": "Additional request context that will be used to evaluate any ABAC conditions encountered\nin the query evaluation." + "description": "Additional request context is used to evaluate any ABAC conditions encountered\nin the query evaluation." } }, "required": [ @@ -2141,7 +2141,7 @@ "additionalProperties": { "$ref": "#/definitions/BatchCheckSingleResult" }, - "description": "map keys are the correlation_id values from the BatchCheckItems in the request" + "description": "Map keys are the `correlation_id` values from the `BatchCheckItems` in the request." } } }, @@ -2177,11 +2177,11 @@ }, "context": { "type": "object", - "description": "Additional request context that will be used to evaluate any ABAC conditions encountered\nin the query evaluation." + "description": "Additional request context that is used to evaluate any ABAC conditions encountered\nin the query evaluation." }, "consistency": { "$ref": "#/definitions/ConsistencyPreference", - "description": "Controls the consistency preference for this request. Default value is UNSPECIFIED, which will have the same behavior as MINIMIZE_LATENCY." + "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which has the same behavior as `MINIMIZE_LATENCY`." } }, "required": [ @@ -2559,7 +2559,7 @@ }, "consistency": { "$ref": "#/definitions/ConsistencyPreference", - "description": "Controls the consistency preference for this request. Default value is UNSPECIFIED, which will have the same behavior as MINIMIZE_LATENCY." + "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`." }, "contextual_tuples": { "$ref": "#/definitions/ContextualTupleKeys" @@ -2758,11 +2758,11 @@ }, "context": { "type": "object", - "description": "Additional request context that will be used to evaluate any ABAC conditions encountered\nin the query evaluation." + "description": "Additional request context that are used to evaluate any ABAC conditions encountered\nin the query evaluation." }, "consistency": { "$ref": "#/definitions/ConsistencyPreference", - "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which will have the same behavior as MINIMIZE_LATENCY." + "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`." } }, "required": [ @@ -2802,7 +2802,7 @@ "continuation_token": { "type": "string", "example": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==", - "description": "The continuation token will be empty if there are no more stores." + "description": "The continuation token is empty if there are no more stores." } }, "required": [ @@ -2854,11 +2854,11 @@ }, "context": { "type": "object", - "description": "Additional request context that will be used to evaluate any ABAC conditions encountered\nin the query evaluation." + "description": "Additional request context used to evaluate any ABAC conditions encountered\nin the query evaluation." }, "consistency": { "$ref": "#/definitions/ConsistencyPreference", - "description": "Controls the consistency preference for this request. Default value is UNSPECIFIED, which will have the same behavior as MINIMIZE_LATENCY." + "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`." } }, "required": [ @@ -3074,7 +3074,7 @@ "continuation_token": { "type": "string", "example": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==", - "description": "The continuation token will be empty if there are no more models." + "description": "The continuation token is empty if there are no more models." } }, "required": [ @@ -3100,7 +3100,7 @@ }, "consistency": { "$ref": "#/definitions/ConsistencyPreference", - "description": "Controls the consistency preference for this request. Default value is UNSPECIFIED, which will have the same behavior as MINIMIZE_LATENCY." + "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`." } } }, @@ -3117,7 +3117,7 @@ "continuation_token": { "type": "string", "example": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==", - "description": "The continuation token will be identical if there are no new changes." + "description": "The continuation token is identical if there are no new changes." } }, "required": [ @@ -3157,7 +3157,7 @@ "continuation_token": { "type": "string", "example": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==", - "description": "The continuation token will be empty if there are no more tuples." + "description": "The continuation token is empty if there are no more tuples." } }, "required": [ @@ -3390,11 +3390,11 @@ }, "context": { "type": "object", - "description": "Additional request context that will be used to evaluate any ABAC conditions encountered\nin the query evaluation." + "description": "Additional request context used to evaluate any ABAC conditions encountered\nin the query evaluation." }, "consistency": { "$ref": "#/definitions/ConsistencyPreference", - "description": "Controls the consistency preference for this request. Default value is UNSPECIFIED, which will have the same behavior as MINIMIZE_LATENCY." + "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`." } }, "required": [ diff --git a/docs/openapiv3/apidocs.openapi.json b/docs/openapiv3/apidocs.openapi.json index f4828157..0d730983 100644 --- a/docs/openapiv3/apidocs.openapi.json +++ b/docs/openapiv3/apidocs.openapi.json @@ -93,7 +93,7 @@ "Assertion": { "properties": { "context": { - "description": "Additional request context that will be used to evaluate any ABAC conditions encountered\nin the query evaluation.", + "description": "Additional request context is used to evaluate any ABAC conditions encountered\nin the query evaluation.", "example": { "view_count": 100 }, @@ -306,7 +306,7 @@ "additionalProperties": { "$ref": "#/components/schemas/BatchCheckSingleResult" }, - "description": "map keys are the correlation_id values from the BatchCheckItems in the request", + "description": "Map keys are the `correlation_id` values from the `BatchCheckItems` in the request.", "example": { "1cd93d8c-8e45-43c6-9a15-cbb3c7f394bc": { "allowed": true, @@ -343,12 +343,12 @@ "$ref": "#/components/schemas/ConsistencyPreference" }, { - "description": "Controls the consistency preference for this request. Default value is UNSPECIFIED, which will have the same behavior as MINIMIZE_LATENCY." + "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which has the same behavior as `MINIMIZE_LATENCY`." } ] }, "context": { - "description": "Additional request context that will be used to evaluate any ABAC conditions encountered\nin the query evaluation.", + "description": "Additional request context that is used to evaluate any ABAC conditions encountered\nin the query evaluation.", "type": "object" }, "contextual_tuples": { @@ -776,7 +776,7 @@ "$ref": "#/components/schemas/ConsistencyPreference" }, { - "description": "Controls the consistency preference for this request. Default value is UNSPECIFIED, which will have the same behavior as MINIMIZE_LATENCY." + "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`." } ] }, @@ -967,12 +967,12 @@ "$ref": "#/components/schemas/ConsistencyPreference" }, { - "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which will have the same behavior as MINIMIZE_LATENCY." + "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`." } ] }, "context": { - "description": "Additional request context that will be used to evaluate any ABAC conditions encountered\nin the query evaluation.", + "description": "Additional request context that are used to evaluate any ABAC conditions encountered\nin the query evaluation.", "type": "object" }, "contextual_tuples": { @@ -1021,7 +1021,7 @@ "ListStoresResponse": { "properties": { "continuation_token": { - "description": "The continuation token will be empty if there are no more stores.", + "description": "The continuation token is empty if there are no more stores.", "example": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==", "type": "string" }, @@ -1057,12 +1057,12 @@ "$ref": "#/components/schemas/ConsistencyPreference" }, { - "description": "Controls the consistency preference for this request. Default value is UNSPECIFIED, which will have the same behavior as MINIMIZE_LATENCY." + "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`." } ] }, "context": { - "description": "Additional request context that will be used to evaluate any ABAC conditions encountered\nin the query evaluation.", + "description": "Additional request context used to evaluate any ABAC conditions encountered\nin the query evaluation.", "type": "object" }, "contextual_tuples": { @@ -1354,7 +1354,7 @@ "type": "array" }, "continuation_token": { - "description": "The continuation token will be empty if there are no more models.", + "description": "The continuation token is empty if there are no more models.", "example": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==", "type": "string" } @@ -1372,7 +1372,7 @@ "$ref": "#/components/schemas/ConsistencyPreference" }, { - "description": "Controls the consistency preference for this request. Default value is UNSPECIFIED, which will have the same behavior as MINIMIZE_LATENCY." + "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`." } ] }, @@ -1409,7 +1409,7 @@ "type": "array" }, "continuation_token": { - "description": "The continuation token will be identical if there are no new changes.", + "description": "The continuation token is identical if there are no new changes.", "example": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==", "type": "string" } @@ -1442,7 +1442,7 @@ "ReadResponse": { "properties": { "continuation_token": { - "description": "The continuation token will be empty if there are no more tuples.", + "description": "The continuation token is empty if there are no more tuples.", "example": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==", "type": "string" }, @@ -1707,12 +1707,12 @@ "$ref": "#/components/schemas/ConsistencyPreference" }, { - "description": "Controls the consistency preference for this request. Default value is UNSPECIFIED, which will have the same behavior as MINIMIZE_LATENCY." + "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`." } ] }, "context": { - "description": "Additional request context that will be used to evaluate any ABAC conditions encountered\nin the query evaluation.", + "description": "Additional request context used to evaluate any ABAC conditions encountered\nin the query evaluation.", "type": "object" }, "contextual_tuples": { @@ -2559,7 +2559,7 @@ }, "/stores": { "get": { - "description": "Returns a paginated list of OpenFGA stores and a continuation token to get additional stores.\nThe continuation token will be empty if there are no more stores.\n", + "description": "Returns a paginated list of OpenFGA stores and a continuation token to get additional stores.\nThe continuation token is empty if there are no more stores.\n", "operationId": "ListStores", "parameters": [ { @@ -2580,7 +2580,7 @@ } }, { - "description": "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", + "description": "The name parameter instructs the API to only include results that match that name./nMultiple results may be returned. Only exact matches are returned; substring matches and regexes are not be evaluated.", "in": "query", "name": "name", "required": false, @@ -2677,7 +2677,7 @@ ] }, "post": { - "description": "Create a unique OpenFGA store which will be used to store authorization models and relationship tuples.", + "description": "Create a unique OpenFGA store which is used to store authorization models and relationship tuples.", "operationId": "CreateStore", "requestBody": { "content": { @@ -3642,7 +3642,7 @@ ] }, "put": { - "description": "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.", + "description": "The WriteAssertions API upserts 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 returns true or false, and optionally a list of contextual tuples.", "operationId": "WriteAssertions", "parameters": [ { @@ -3755,7 +3755,7 @@ }, "/stores/{store_id}/authorization-models": { "get": { - "description": "The ReadAuthorizationModels API returns all the authorization models for a certain store.\nOpenFGA's response contains an array of all authorization models, sorted in descending order of creation.\n\n## Example\nAssume 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:\n```json\n{\n \"authorization_models\": [\n {\n \"id\": \"01G50QVV17PECNVAHX1GG4Y5NC\",\n \"type_definitions\": [...]\n },\n {\n \"id\": \"01G4ZW8F4A07AKQ8RHSVG9RW04\",\n \"type_definitions\": [...]\n },\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nIf there are no more authorization models available, the `continuation_token` field will be empty\n```json\n{\n \"authorization_models\": [\n {\n \"id\": \"01G50QVV17PECNVAHX1GG4Y5NC\",\n \"type_definitions\": [...]\n },\n {\n \"id\": \"01G4ZW8F4A07AKQ8RHSVG9RW04\",\n \"type_definitions\": [...]\n },\n ],\n \"continuation_token\": \"\"\n}\n```\n", + "description": "The ReadAuthorizationModels API returns all the authorization models for a certain store.\nOpenFGA's response contains an array of all authorization models, sorted in descending order of creation.\n\n## Example\n\nAssume 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 returns a response that looks like:\n\n```json\n{\n \"authorization_models\": [\n {\n \"id\": \"01G50QVV17PECNVAHX1GG4Y5NC\",\n \"type_definitions\": [...]\n },\n {\n \"id\": \"01G4ZW8F4A07AKQ8RHSVG9RW04\",\n \"type_definitions\": [...]\n },\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nIf there are no more authorization models available, then `continuation_token` field returns empty:\n\n```json\n{\n \"authorization_models\": [\n {\n \"id\": \"01G50QVV17PECNVAHX1GG4Y5NC\",\n \"type_definitions\": [...]\n },\n {\n \"id\": \"01G4ZW8F4A07AKQ8RHSVG9RW04\",\n \"type_definitions\": [...]\n },\n ],\n \"continuation_token\": \"\"\n}\n```\n", "operationId": "ReadAuthorizationModels", "parameters": [ { @@ -3872,7 +3872,7 @@ ] }, "post": { - "description": "The WriteAuthorizationModel API will add a new authorization model to a store.\nEach item in the `type_definitions` array is a type definition as specified in the field `type_definition`.\nThe response will return the authorization model's ID in the `id` field.\n\n## Example\nTo add an authorization model with `user` and `document` type definitions, call `POST` `authorization-models` API with the body: \n```json\n{\n \"type_definitions\":[\n {\n \"type\":\"user\"\n },\n {\n \"type\":\"document\",\n \"relations\":{\n \"reader\":{\n \"union\":{\n \"child\":[\n {\n \"this\":{}\n },\n {\n \"computedUserset\":{\n \"object\":\"\",\n \"relation\":\"writer\"\n }\n }\n ]\n }\n },\n \"writer\":{\n \"this\":{}\n }\n }\n }\n ]\n}\n```\nOpenFGA's response will include the version id for this authorization model, which will look like \n```\n{\"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"}\n```\n", + "description": "The WriteAuthorizationModel API adds a new authorization model to a store.\nEach item in the `type_definitions` array is a type definition as specified in the field `type_definition`.\nThe response returns the authorization model's ID in the `id` field.\n\n## Example\n\nTo add an authorization model with `user` and `document` type definitions, call `POST` `authorization-models` API with the body: \n```json\n{\n \"type_definitions\":[\n {\n \"type\":\"user\"\n },\n {\n \"type\":\"document\",\n \"relations\":{\n \"reader\":{\n \"union\":{\n \"child\":[\n {\n \"this\":{}\n },\n {\n \"computedUserset\":{\n \"object\":\"\",\n \"relation\":\"writer\"\n }\n }\n ]\n }\n },\n \"writer\":{\n \"this\":{}\n }\n }\n }\n ]\n}\n```\nOpenFGA's response includes the version id for this authorization model, similar to:\n```\n{\"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"}\n```\n", "operationId": "WriteAuthorizationModel", "parameters": [ { @@ -3984,7 +3984,7 @@ }, "/stores/{store_id}/authorization-models/{id}": { "get": { - "description": "The ReadAuthorizationModel API returns an authorization model by its identifier.\nThe response will return the authorization model for the particular version.\n\n## Example\nTo 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:\n```json\n{\n \"authorization_model\":{\n \"id\":\"01G5JAVJ41T49E9TT3SKVS7X1J\",\n \"type_definitions\":[\n {\n \"type\":\"user\"\n },\n {\n \"type\":\"document\",\n \"relations\":{\n \"reader\":{\n \"union\":{\n \"child\":[\n {\n \"this\":{}\n },\n {\n \"computedUserset\":{\n \"object\":\"\",\n \"relation\":\"writer\"\n }\n }\n ]\n }\n },\n \"writer\":{\n \"this\":{}\n }\n }\n }\n ]\n }\n}\n```\nIn the above example, there are 2 types (`user` and `document`). The `document` type has 2 relations (`writer` and `reader`).", + "description": "The ReadAuthorizationModel API returns an authorization model by its identifier.\nThe response returns the authorization model for the particular version.\n\n## Example\n\nTo 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 returns:\n```json\n{\n \"authorization_model\":{\n \"id\":\"01G5JAVJ41T49E9TT3SKVS7X1J\",\n \"type_definitions\":[\n {\n \"type\":\"user\"\n },\n {\n \"type\":\"document\",\n \"relations\":{\n \"reader\":{\n \"union\":{\n \"child\":[\n {\n \"this\":{}\n },\n {\n \"computedUserset\":{\n \"object\":\"\",\n \"relation\":\"writer\"\n }\n }\n ]\n }\n },\n \"writer\":{\n \"this\":{}\n }\n }\n }\n ]\n }\n}\n```\nIn the above example, there are 2 types (`user` and `document`). The `document` type has 2 relations (`writer` and `reader`).", "operationId": "ReadAuthorizationModel", "parameters": [ { @@ -4094,7 +4094,7 @@ }, "/stores/{store_id}/batch-check": { "post": { - "description": "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.\n\nAn 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}$`\n\n> **Note:** The maximum number of checks that can be passed in the `BatchCheck` API is configurable via the [OPENFGA_MAX_CHECKS_PER_BATCH_CHECK](https://openfga.dev/docs/getting-started/setup-openfga/configuration#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.\n\nFor more details on how `Check` functions, review the docs for `/check`.\n\n### Examples\n#### A BatchCheckRequest\n```json\n{\n \"checks\": [\n {\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n \"relation\": \"reader\",\n \"user\": \"user:anne\",\n },\n \"contextual_tuples\": {...}\n \"context\": {}\n \"correlation_id\": \"01JA8PM3QM7VBPGB8KMPK8SBD5\"\n },\n {\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n \"relation\": \"reader\",\n \"user\": \"user:bob\",\n },\n \"contextual_tuples\": {...}\n \"context\": {}\n \"correlation_id\": \"01JA8PMM6A90NV5ET0F28CYSZQ\"\n }\n ]\n}\n```\n\nBelow 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:\n```json\n{\n \"result\": {\n \"01JA8PMM6A90NV5ET0F28CYSZQ\": {\n \"allowed\": false, \n \"error\": {\"message\": \"\"} \n },\n \"01JA8PM3QM7VBPGB8KMPK8SBD5\": {\n \"allowed\": true, \n \"error\": {\"message\": \"\"} \n }\n}\n```\n", + "description": "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.\n\nAn 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}$`\n\n> **Note:** The maximum number of checks that can be passed in the `BatchCheck` API is configurable using the environment variable: `[OPENFGA_MAX_CHECKS_PER_BATCH_CHECK](https://openfga.dev/docs/getting-started/setup-openfga/configuration#OPENFGA_MAX_CHECKS_PER_BATCH_CHECK)`. If `BatchCheck` is called using the SDK, the SDK can split the batch check requests for you.\n\nFor more details on how `Check` functions, review the docs for `/check`.\n\n### Examples\n\n#### A BatchCheckRequest\n```json\n{\n \"checks\": [\n {\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n \"relation\": \"reader\",\n \"user\": \"user:anne\",\n },\n \"contextual_tuples\": {...}\n \"context\": {}\n \"correlation_id\": \"01JA8PM3QM7VBPGB8KMPK8SBD5\"\n },\n {\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n \"relation\": \"reader\",\n \"user\": \"user:bob\",\n },\n \"contextual_tuples\": {...}\n \"context\": {}\n \"correlation_id\": \"01JA8PMM6A90NV5ET0F28CYSZQ\"\n }\n ]\n}\n```\n\nBelow 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:\n```json\n{\n \"result\": {\n \"01JA8PMM6A90NV5ET0F28CYSZQ\": {\n \"allowed\": false, \n \"error\": {\"message\": \"\"} \n },\n \"01JA8PM3QM7VBPGB8KMPK8SBD5\": {\n \"allowed\": true, \n \"error\": {\"message\": \"\"} \n }\n}\n```\n", "operationId": "BatchCheck", "parameters": [ { @@ -4198,7 +4198,7 @@ "description": "Request failed due to internal server error." } }, - "summary": "Send a list of related operations", + "summary": "Check multiple relationships in a single request", "tags": [ "Relationship Queries" ] @@ -4206,7 +4206,7 @@ }, "/stores/{store_id}/changes": { "get": { - "description": "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.\nYou can use the `type` parameter to only get the list of tuple changes that affect objects of that type.\nWhen reading a write tuple change, if it was conditioned, the condition will be returned.\nWhen reading a delete tuple change, the condition will NOT be returned regardless of whether it was originally conditioned or not.\n", + "description": "The ReadChanges API returns a paginated list of tuple changes (additions and deletions) that occurred in a given store, sorted by ascending time. The response includes 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 is returned in order for it to be used when new changes are recorded.\n\nIf the store never had any tuples added or removed, then this token returns empty.\nYou can use the `type` parameter to only get the list of tuple changes that affect objects of that type.\nWhen reading a write tuple change, if it was conditioned, the condition is returned.\nWhen reading a delete tuple change, the condition is NOT returned regardless of whether it was originally conditioned or not.\n", "operationId": "ReadChanges", "parameters": [ { @@ -4243,7 +4243,7 @@ } }, { - "description": "Start date and time of changes to read.\nFormat: ISO 8601 timestamp (e.g., 2022-01-01T00:00:00Z)\nIf a continuation_token is provided along side start_time, the continuation_token will take precedence over start_time.", + "description": "Start date and time of changes to read.\nFormat: ISO 8601 timestamp (e.g., 2022-01-01T00:00:00Z)\nIf a `continuation_token` is provided along side `start_time`, the `continuation_token` takes precedence over `start_time`.", "in": "query", "name": "start_time", "required": false, @@ -4343,7 +4343,7 @@ }, "/stores/{store_id}/check": { "post": { - "description": "The Check API returns whether a given user has a relationship with a given object in a given store.\n\nThe `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:*`.\nTo arrive at a result, the API uses:\n\n- An authorization model\n\n- Explicit tuples written through the Write API\n\n- Contextual tuples present in the request\n\n- Implicit tuples that exist by virtue of applying set theory\n\nFor example: `document:2021-budget#viewer@document:2021-budget#viewer`. In this example, the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`).\n\nA `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`.\nYou 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.\n\n> **Note:** We recommend you specify authorization model id for better performance.\n\nYou may also provide a `context` object that will be used to evaluate the conditioned tuples in the system.\n\n> **Note:** We recommend you provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.\n\nBy 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.\nThe response will return whether the relationship exists in the field `allowed`.\n\nSome 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. \nFor 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.\n## Examples\n### Querying with contextual tuples\nIn order to check if user `user:anne` of type `user` has a `reader` relationship with object `document:2021-budget` given the following contextual tuple\n```json\n{\n \"user\": \"user:anne\",\n \"relation\": \"member\",\n \"object\": \"time_slot:office_hours\"\n}\n```\nthe Check API can be used with the following request body:\n```json\n{\n \"tuple_key\": {\n \"user\": \"user:anne\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"contextual_tuples\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:anne\",\n \"relation\": \"member\",\n \"object\": \"time_slot:office_hours\"\n }\n ]\n },\n \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n}\n```\n### Querying usersets\nSome Checks will always return `true`, even without any tuples. For example, for the following authorization model\n```python\nmodel\n schema 1.1\ntype user\ntype document\n relations\n define reader: [user]\n```\nthe following query\n```json\n{\n \"tuple_key\": {\n \"user\": \"document:2021-budget#reader\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n }\n}\n```\nwill 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`.\n### Querying usersets with difference in the model\nA Check for a userset can yield results that must be treated carefully if the model involves difference. For example, for the following authorization model\n```python\nmodel\n schema 1.1\ntype user\ntype group\n relations\n define member: [user]\ntype document\n relations\n define blocked: [user]\n define reader: [group#member] but not blocked\n```\nthe following query\n```json\n{\n \"tuple_key\": {\n \"user\": \"group:finance#member\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"contextual_tuples\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:anne\",\n \"relation\": \"member\",\n \"object\": \"group:finance\"\n },\n {\n \"user\": \"group:finance#member\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n {\n \"user\": \"user:anne\",\n \"relation\": \"blocked\",\n \"object\": \"document:2021-budget\"\n }\n ]\n },\n}\n```\nwill return `{ \"allowed\": true }`, even though a specific user of the userset `group:finance#member` does not have the `reader` relationship with the given object.\n### Requesting higher consistency\nBy 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.\n```json\n{\n \"tuple_key\": {\n \"user\": \"group:finance#member\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"consistency\": \"HIGHER_CONSISTENCY\"\n}\n```\n", + "description": "The Check API returns whether a given user has a relationship with a given object in a given store.\n\nThe `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:*`.\nTo arrive at a result, the API uses:\n\n- An [authorization model](/docs/getting-started/configure-model)\n\n- Explicit tuples written through the Write API\n\n- Contextual tuples present in the request\n\n- Implicit tuples that exist by virtue of applying set theory\n\nFor example: `document:2021-budget#viewer@document:2021-budget#viewer`. In this example, the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n\nA `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`.\nYou may also provide an `authorization_model_id` in the body. This is used to assert that the input `tuple_key` is valid for the model specified. If not specified, the assertion is made against the latest authorization model ID.\n\n> **Note:** We recommend you specify authorization model id for better performance.\n\nYou may also provide a `context` object that is used to evaluate the conditioned tuples in the system.\n\n> **Note:** We recommend you provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.\n\nBy 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.\nThe response returns whether the relationship exists in the field `allowed`.\n\nSome 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. \nFor 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.\n## Examples\n\n### Querying with contextual tuples\n\nIn order to check if user `user:anne` of type `user` has a `reader` relationship with object `document:2021-budget` given the following contextual tuple:\n```json\n{\n \"user\": \"user:anne\",\n \"relation\": \"member\",\n \"object\": \"time_slot:office_hours\"\n}\n```\nthe Check API can be used with the following request body:\n```json\n{\n \"tuple_key\": {\n \"user\": \"user:anne\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"contextual_tuples\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:anne\",\n \"relation\": \"member\",\n \"object\": \"time_slot:office_hours\"\n }\n ]\n },\n \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n}\n```\n### Querying usersets\n\nSome Checks always return `true`, even without any tuples. For example, for the following authorization model:\n```python\nmodel\n schema 1.1\ntype user\ntype document\n relations\n define reader: [user]\n```\nthe following query:\n```json\n{\n \"tuple_key\": {\n \"user\": \"document:2021-budget#reader\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n }\n}\n```\nalways returns `{ \"allowed\": true }`. This is because usersets are self-defining: the userset `document:2021-budget#reader` always has the `reader` relation with `document:2021-budget`.\n### Querying usersets with difference in the model\n\nA Check for a userset can yield results that must be treated carefully if the model involves difference. For example, for the following authorization model:\n```python\nmodel\n schema 1.1\ntype user\ntype group\n relations\n define member: [user]\ntype document\n relations\n define blocked: [user]\n define reader: [group#member] but not blocked\n```\nthe following query:\n```json\n{\n \"tuple_key\": {\n \"user\": \"group:finance#member\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"contextual_tuples\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:anne\",\n \"relation\": \"member\",\n \"object\": \"group:finance\"\n },\n {\n \"user\": \"group:finance#member\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n {\n \"user\": \"user:anne\",\n \"relation\": \"blocked\",\n \"object\": \"document:2021-budget\"\n }\n ]\n },\n}\n```\nreturns `{ \"allowed\": true }`, even though a specific user of the userset `group:finance#member` does not have the `reader` relationship with the given object.\n### Requesting higher consistency\n\nBy 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.\n```json\n{\n \"tuple_key\": {\n \"user\": \"group:finance#member\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"consistency\": \"HIGHER_CONSISTENCY\"\n}\n```\n", "operationId": "Check", "parameters": [ { @@ -4455,7 +4455,7 @@ }, "/stores/{store_id}/expand": { "post": { - "description": "The Expand API will return all users and usersets that have certain relationship with an object in a certain store.\nThis is different from the `/stores/{store_id}/read` API in that both users and computed usersets are returned.\n\nBody parameters `tuple_key.object` and `tuple_key.relation` are all required.\nA `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`.\nThe response will return a tree whose leaves are the specific users and usersets. Union, intersection and difference operator are located in the intermediate nodes.\n\n## Example\nTo expand all users that have the `reader` relationship with object `document:2021-budget`, use the Expand API with the following request body\n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\",\n \"relation\": \"reader\"\n },\n \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n}\n```\nOpenFGA's response will be a userset tree of the users and usersets that have read access to the document.\n```json\n{\n \"tree\":{\n \"root\":{\n \"type\":\"document:2021-budget#reader\",\n \"union\":{\n \"nodes\":[\n {\n \"type\":\"document:2021-budget#reader\",\n \"leaf\":{\n \"users\":{\n \"users\":[\n \"user:bob\"\n ]\n }\n }\n },\n {\n \"type\":\"document:2021-budget#reader\",\n \"leaf\":{\n \"computed\":{\n \"userset\":\"document:2021-budget#writer\"\n }\n }\n }\n ]\n }\n }\n }\n}\n```\nThe caller can then call expand API for the `writer` relationship for the `document:2021-budget`.\n### Expand Request with Contextual Tuples\n\nGiven the model\n```python\nmodel\n schema 1.1\n\ntype user\n\ntype folder\n relations\n define owner: [user]\n\ntype document\n relations\n define parent: [folder]\n define viewer: [user] or writer\n define writer: [user] or owner from parent\n```\nand the initial tuples\n```json\n[{\n \"user\": \"user:bob\",\n \"relation\": \"owner\",\n \"object\": \"folder:1\"\n}]\n```\n\nTo expand all `writers` of `document:1` when `document:1` is put in `folder:1`, the first call could be\n\n```json\n{\n \"tuple_key\": {\n \"object\": \"document:1\",\n \"relation\": \"writer\"\n },\n \"contextual_tuples\": {\n \"tuple_keys\": [\n {\n \"user\": \"folder:1\",\n \"relation\": \"parent\",\n \"object\": \"document:1\"\n }\n ]\n }\n}\n```\nthis returns:\n```json\n{\n \"tree\": {\n \"root\": {\n \"name\": \"document:1#writer\",\n \"union\": {\n \"nodes\": [\n {\n \"name\": \"document:1#writer\",\n \"leaf\": {\n \"users\": {\n \"users\": []\n }\n }\n },\n {\n \"name\": \"document:1#writer\",\n \"leaf\": {\n \"tupleToUserset\": {\n \"tupleset\": \"document:1#parent\",\n \"computed\": [\n {\n \"userset\": \"folder:1#owner\"\n }\n ]\n }\n }\n }\n ]\n }\n }\n }\n}\n```\nThis 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`\n```json\n{\n \"tuple_key\": {\n \"object\": \"folder:1\",\n \"relation\": \"owner\"\n }\n}\n```\nwhich gives\n```json\n{\n \"tree\": {\n \"root\": {\n \"name\": \"folder:1#owner\",\n \"leaf\": {\n \"users\": {\n \"users\": [\n \"user:bob\"\n ]\n }\n }\n }\n }\n}\n```\n", + "description": "The Expand API returns all users and usersets that have certain relationship with an object in a certain store.\nThis is different from the `/stores/{store_id}/read` API in that both users and computed usersets are returned.\n\nBody parameters `tuple_key.object` and `tuple_key.relation` are all required.\nA `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`.\nThe response returns a tree whose leaves are the specific users and usersets. Union, intersection and difference operator are located in the intermediate nodes.\n\n## Example\n\nTo expand all users that have the `reader` relationship with object `document:2021-budget`, use the Expand API with the following request body:\n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\",\n \"relation\": \"reader\"\n },\n \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n}\n```\nOpenFGA's response is a userset tree of the users and usersets that have read access to the document.\n```json\n{\n \"tree\":{\n \"root\":{\n \"type\":\"document:2021-budget#reader\",\n \"union\":{\n \"nodes\":[\n {\n \"type\":\"document:2021-budget#reader\",\n \"leaf\":{\n \"users\":{\n \"users\":[\n \"user:bob\"\n ]\n }\n }\n },\n {\n \"type\":\"document:2021-budget#reader\",\n \"leaf\":{\n \"computed\":{\n \"userset\":\"document:2021-budget#writer\"\n }\n }\n }\n ]\n }\n }\n }\n}\n```\nThe caller can then call expand API for the `writer` relationship for the `document:2021-budget`.\n### Expand Request with Contextual Tuples\n\n\nGiven the model\n```python\nmodel\n schema 1.1\n\ntype user\n\ntype folder\n relations\n define owner: [user]\n\ntype document\n relations\n define parent: [folder]\n define viewer: [user] or writer\n define writer: [user] or owner from parent\n```\nand the initial tuples\n```json\n[{\n \"user\": \"user:bob\",\n \"relation\": \"owner\",\n \"object\": \"folder:1\"\n}]\n```\n\nTo expand all `writers` of `document:1` when `document:1` is put in `folder:1`, the first call could be:\n\n```json\n{\n \"tuple_key\": {\n \"object\": \"document:1\",\n \"relation\": \"writer\"\n },\n \"contextual_tuples\": {\n \"tuple_keys\": [\n {\n \"user\": \"folder:1\",\n \"relation\": \"parent\",\n \"object\": \"document:1\"\n }\n ]\n }\n}\n```\nthis returns:\n```json\n{\n \"tree\": {\n \"root\": {\n \"name\": \"document:1#writer\",\n \"union\": {\n \"nodes\": [\n {\n \"name\": \"document:1#writer\",\n \"leaf\": {\n \"users\": {\n \"users\": []\n }\n }\n },\n {\n \"name\": \"document:1#writer\",\n \"leaf\": {\n \"tupleToUserset\": {\n \"tupleset\": \"document:1#parent\",\n \"computed\": [\n {\n \"userset\": \"folder:1#owner\"\n }\n ]\n }\n }\n }\n ]\n }\n }\n }\n}\n```\nThis 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`\n```json\n{\n \"tuple_key\": {\n \"object\": \"folder:1\",\n \"relation\": \"owner\"\n }\n}\n```\nwhich gives\n```json\n{\n \"tree\": {\n \"root\": {\n \"name\": \"folder:1#owner\",\n \"leaf\": {\n \"users\": {\n \"users\": [\n \"user:bob\"\n ]\n }\n }\n }\n }\n}\n```\n", "operationId": "Expand", "parameters": [ { @@ -4567,7 +4567,7 @@ }, "/stores/{store_id}/list-objects": { "post": { - "description": "The ListObjects API returns a list of all the objects of the given type that the user has a relation with.\n To arrive at a result, the API uses:\n\n- An authorization model\n- Explicit tuples written through the Write API\n- Contextual tuples present in the request\n- Implicit tuples that exist by virtue of applying set theory. For example:\n\n`document:2021-budget#viewer@document:2021-budget#viewer`\n\nIn the example the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n\nAn `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID will be used.\n\n> **Note:** We recommend you specify authorization model ID for better performance.\n\nYou may also specify `contextual_tuples` that is treated as regular tuples. Each of these tuples may have an associated `condition`.\nYou may also provide a `context` object that is used to evaluate the conditioned tuples in the system.\n\n> **Note:** We recommend you provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.\n\nBy 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.\nThe response contains the related objects in an array in the \"objects\" field of the response and they will be strings in the object format `:` (e.g. \"document:roadmap\").\n\nThe 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.\nThe objects given will not be sorted, and therefore two identical calls can give a given different set of objects.", + "description": "The ListObjects API returns a list of all the objects of the given type that the user has a relation with.\n To arrive at a result, the API uses:\n\n- An [authorization model](/docs/getting-started/configure-model)\n- Explicit tuples written through the Write API\n- Contextual tuples present in the request\n- Implicit tuples that exist by virtue of applying set theory. For example:\n\n`document:2021-budget#viewer@document:2021-budget#viewer`\n\nIn the example the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n\nAn `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID is used.\n\n> **Note:** We recommend you specify authorization model ID for better performance.\n\nYou may also specify `contextual_tuples` that is treated as regular tuples. Each of these tuples may have an associated `condition`.\nYou may also provide a `context` object that is used to evaluate the conditioned tuples in the system.\n\n> **Note:** We recommend you provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.\n\nBy 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.\nThe response contains the related objects in an array in the \"objects\" field of the response and are strings in the object format `:` (e.g. \"document:roadmap\").\n\nThe number of objects in the response array are 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.\nThe objects given are not sorted, and therefore two identical calls can give a given different set of objects.", "operationId": "ListObjects", "parameters": [ { @@ -4679,7 +4679,7 @@ }, "/stores/{store_id}/list-users": { "post": { - "description": "The ListUsers API returns a list of all the users of a specific type that have a relation to a given object.\n\n To arrive at a result, the API uses:\n\n- An authorization model\n\n- Explicit tuples written through the Write API\n\n- Contextual tuples present in the request\n\n- Implicit tuples that exist by virtue of applying set theory\n\nFor example: `document:2021-budget#viewer@document:2021-budget#viewer`. In this example, the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n\nAn `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID will be used.\n\n> **Note:** We recommend you specify authorization model ID for better performance.\n\nYou may also specify `contextual_tuples` that will be treated as regular tuples. Each of these tuples may have an associated `condition`.\nYou may also provide a `context` object that will be used to evaluate the conditioned tuples in the system.\n\n> **Note:** We recommend you provide a value for all the input parameters of all the conditions. This ensures that all tuples be evaluated correctly.\n\nThe response will contain the related users in an array in the \"users\" field of the response. These results may include specific objects, usersets \nor type-bound public access. Each of these types of results is encoded in its own type and not represented as a string.\n\nIn cases where a type-bound public access result is returned (e.g. `user:*`), it cannot be inferred that all subjects\nof that type have a relation to the object; it is possible that negations exist and checks should still be queried\non 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.\nThe returned users will not be sorted, and therefore two identical calls may yield different sets of users.", + "description": "The ListUsers API returns a list of all the users of a specific type that have a relation to a given object.\n\n To arrive at a result, the API uses:\n\n- An [authorization model](/docs/getting-started/configure-model)\n\n- Explicit tuples written through the Write API\n\n- Contextual tuples present in the request\n\n- Implicit tuples that exist by virtue of applying set theory\n\nFor example: `document:2021-budget#viewer@document:2021-budget#viewer`. In this example, the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n\nAn `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID is used.\n\n> **Note:** We recommend you specify authorization model ID for better performance.\n\nYou may also specify `contextual_tuples` that are treated as regular tuples. Each of these tuples may have an associated `condition`.\nYou may also provide a `context` object used to evaluate the conditioned tuples in the system.\n\n> **Note:** We recommend you provide a value for all the input parameters of all the conditions. This ensures that all tuples be evaluated correctly.\n\nThe response contains the related users in an array in the \"users\" field of the response. These results may include specific objects, usersets \nor type-bound public access. Each of these types of results is encoded in its own type and not represented as a string.\n\nIn cases where a type-bound public access result is returned (e.g. `user:*`), it cannot be inferred that all subjects\nof that type have a relation to the object; it is possible that negations exist and checks should still be queried\non individual subjects to ensure access to that document.\nThe number of users in the response array are 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.\nThe returned users are not sorted, and therefore two identical calls may yield different sets of users.", "operationId": "ListUsers", "parameters": [ { @@ -4791,7 +4791,7 @@ }, "/stores/{store_id}/read": { "post": { - "description": "The Read API will return the tuples from a certain store that match a query filter specified in the body of the request. \nThe API doesn't guarantee order by any field. \nIt 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. \nIn the body:\n1. `tuple_key` is optional. If not specified, it will return all tuples in the store.\n2. `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:`).\n3. `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`).\n\n## Examples\n### Query for all objects in a type definition\nTo query for all objects that `user:bob` has `reader` relationship in the `document` type definition, call read API with body of\n```json\n{\n \"tuple_key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:\"\n }\n}\n```\nThe API will return tuples and a continuation token, something like\n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis 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.\nThe continuation token will be empty if there are no more tuples to query.\n\n### Query for all stored relationship tuples that have a particular relation and object\nTo query for all users that have `reader` relationship with `document:2021-budget`, call read API with body of \n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\",\n \"relation\": \"reader\"\n }\n}\n```\nThe API will return something like \n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis 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.\n\n### Query for all users with all relationships for a particular document\nTo query for all users that have any relationship with `document:2021-budget`, call read API with body of \n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n }\n}\n```\nThe API will return something like \n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:anne\",\n \"relation\": \"writer\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-05T13:42:12.356Z\"\n },\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis means that `document:2021-budget` has 1 `reader` (`user:bob`) and 1 `writer` (`user:anne`).\n", + "description": "The Read API returns the tuples from a certain store that match a query filter specified in the body of the request. \nThe API doesn't guarantee order by any field. \nIt 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. \nIn the body:\n1. `tuple_key` is optional. If not specified, it returns all tuples in the store.\n2. `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:`).\n3. `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`).\n\n## Examples\n\n### Query for all objects in a type definition\n\nTo query for all objects that `user:bob` has `reader` relationship in the `document` type definition, call read API with body of\n```json\n{\n \"tuple_key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:\"\n }\n}\n```\nThe API returns tuples and a continuation token, similar to:\n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis 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.\nThe continuation token is empty if there are no more tuples to query.\n\n### Query for all stored relationship tuples that have a particular relation and object\n\nTo query for all users that have `reader` relationship with `document:2021-budget`, call read API with body of \n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\",\n \"relation\": \"reader\"\n }\n}\n```\nThe API returns something similar to: \n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis 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 does not return writers such as `user:anne` because it only returns tuples and does not evaluate them.\n\n### Query for all users with all relationships for a particular document\n\nTo query for all users that have any relationship with `document:2021-budget`, call read API with body of \n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n }\n}\n```\nThe API returns something similar to:\n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:anne\",\n \"relation\": \"writer\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-05T13:42:12.356Z\"\n },\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis means that `document:2021-budget` has 1 `reader` (`user:bob`) and 1 `writer` (`user:anne`).\n", "operationId": "Read", "parameters": [ { @@ -5024,7 +5024,7 @@ }, "/stores/{store_id}/write": { "post": { - "description": "The Write API transactionally updates the tuples for a certain store. Tuples and type definitions allow OpenFGA to determine whether a relationship exists between an object and an user.\n\nIn the body, `writes` adds new tuples and `deletes` removes existing tuples. When deleting a tuple, any `condition` specified with it is ignored.\n\nThe 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.\n\nTo allow writes when an identical tuple already exists in the database, set `\"on_duplicate\": \"ignore\"` on the `writes` object.\nTo allow deletes when a tuple was already removed from the database, set `\"on_missing\": \"ignore\"` on the `deletes` object.\nIf 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.\n\nThe API will not allow you to write tuples such as `document:2021-budget#viewer@document:2021-budget#viewer`, because they are implicit.\nAn `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.\n\n## Example\n### Adding relationships\nTo add `user:anne` as a `writer` for `document:2021-budget`, call write API with the following \n```json\n{\n \"writes\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:anne\",\n \"relation\": \"writer\",\n \"object\": \"document:2021-budget\"\n }\n ],\n \"on_duplicate\": \"ignore\"\n },\n \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n}\n```\n### Removing relationships\nTo remove `user:bob` as a `reader` for `document:2021-budget`, call write API with the following \n```json\n{\n \"deletes\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n }\n ],\n \"on_missing\": \"ignore\"\n }\n}\n```\n", + "description": "The Write API transactionally updates the tuples for a certain store. Tuples and type definitions allow OpenFGA to determine whether a relationship exists between an object and an user.\n\nIn the body, `writes` adds new tuples and `deletes` removes existing tuples. When deleting a tuple, any `condition` specified with it is ignored.\n\nThe 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 throws an error.\n\nTo allow writes when an identical tuple already exists in the database, set `\"on_duplicate\": \"ignore\"` on the `writes` object.\nTo allow deletes when a tuple was already removed from the database, set `\"on_missing\": \"ignore\"` on the `deletes` object.\nIf a Write request contains both idempotent (ignore) and non-idempotent (error) operations, the most restrictive action (error) takes 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.\n\nThe API does not allow you to write tuples such as `document:2021-budget#viewer@document:2021-budget#viewer`, because they are implicit.\nAn `authorization_model_id` may be specified in the body. If it is, model ID is 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 is used.\n\n## Example\n\n### Adding relationships\n\nTo add `user:anne` as a `writer` for `document:2021-budget`, call write API with the following:\n```json\n{\n \"writes\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:anne\",\n \"relation\": \"writer\",\n \"object\": \"document:2021-budget\"\n }\n ],\n \"on_duplicate\": \"ignore\"\n },\n \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n}\n```\n### Removing relationships\n\nTo remove `user:bob` as a `reader` for `document:2021-budget`, call write API with the following:\n```json\n{\n \"deletes\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n }\n ],\n \"on_missing\": \"ignore\"\n }\n}\n```\n", "operationId": "Write", "parameters": [ { diff --git a/openfga/v1/openfga_service.proto b/openfga/v1/openfga_service.proto index f5da5a90..c2130811 100644 --- a/openfga/v1/openfga_service.proto +++ b/openfga/v1/openfga_service.proto @@ -27,19 +27,19 @@ service OpenFGAService { tags: ["Relationship Tuples"] operation_id: "Read" description: - "The Read API will return the tuples from a certain store that match a " + "The Read API returns the tuples from a certain store that match a " "query filter specified in the body of the request. \n" "The API doesn't guarantee order by any field. \n" "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. \n" "In the body:\n" - "1. `tuple_key` is optional. If not specified, it will return all tuples in the store.\n" + "1. `tuple_key` is optional. If not specified, it returns all tuples in the store.\n" "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:`).\n" "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`).\n\n" - "## Examples\n" - "### Query for all objects in a type definition\n" + "## Examples\n\n" + "### Query for all objects in a type definition\n\n" "To query for all objects that `user:bob` has `reader` relationship in " "the `document` type definition, call read API with body of\n" "```json\n" @@ -51,7 +51,7 @@ service OpenFGAService { " }\n" "}\n" "```\n" - "The API will return tuples and a continuation token, something like\n" + "The API returns tuples and a continuation token, similar to:\n" "```json\n" "{\n" " \"tuples\": [\n" @@ -69,8 +69,8 @@ service OpenFGAService { "```\n" "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.\n" - "The continuation token will be empty if there are no more tuples to query.\n\n" - "### Query for all stored relationship tuples that have a particular relation and object\n" + "The continuation token is empty if there are no more tuples to query.\n\n" + "### Query for all stored relationship tuples that have a particular relation and object\n\n" "To query for all users that have `reader` relationship with " "`document:2021-budget`, call read API with body of \n" "```json\n" @@ -81,7 +81,7 @@ service OpenFGAService { " }\n" "}\n" "```\n" - "The API will return something like \n" + "The API returns something similar to: \n" "```json\n" "{\n" " \"tuples\": [\n" @@ -98,9 +98,9 @@ service OpenFGAService { "}\n" "```\n" "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 " + "Note that, even if the model said that all `writers` are also `readers`, the API does not return writers such as " "`user:anne` because it only returns tuples and does not evaluate them.\n\n" - "### Query for all users with all relationships for a particular document\n" + "### Query for all users with all relationships for a particular document\n\n" "To query for all users that have any relationship with " "`document:2021-budget`, call read API with body of \n" "```json\n" @@ -110,7 +110,7 @@ service OpenFGAService { " }\n" "}\n" "```\n" - "The API will return something like \n" + "The API returns something similar to:\n" "```json\n" "{\n" " \"tuples\": [\n" @@ -154,17 +154,17 @@ service OpenFGAService { "type definitions allow OpenFGA to determine whether a " "relationship exists between an object and an user.\n\n" "In the body, `writes` adds new tuples and `deletes` removes existing tuples. When deleting a tuple, any `condition` specified with it is ignored.\n\n" - "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.\n\n" + "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 throws an error.\n\n" "To allow writes when an identical tuple already exists in the database, set `\"on_duplicate\": \"ignore\"` on the `writes` object.\n" "To allow deletes when a tuple was already removed from the database, set `\"on_missing\": \"ignore\"` on the `deletes` object.\n" - "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.\n\n" - "The API will not allow you to write tuples such as `document:2021-budget#viewer@document:2021-budget#viewer`, because they are implicit.\n" - "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.\n\n" - "## Example\n" - "### Adding relationships\n" + "If a Write request contains both idempotent (ignore) and non-idempotent (error) operations, the most restrictive action (error) takes 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.\n\n" + "The API does not allow you to write tuples such as `document:2021-budget#viewer@document:2021-budget#viewer`, because they are implicit.\n" + "An `authorization_model_id` may be specified in the body. If it is, model ID is 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 is used.\n\n" + "## Example\n\n" + "### Adding relationships\n\n" "To add `user:anne` as a `writer` for `document:2021-budget`, call " - "write API with the following \n" + "write API with the following:\n" "```json\n" "{\n" " \"writes\": {\n" @@ -180,9 +180,9 @@ service OpenFGAService { " \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n" "}\n" "```\n" - "### Removing relationships\n" + "### Removing relationships\n\n" "To remove `user:bob` as a `reader` for `document:2021-budget`, call " - "write API with the following \n" + "write API with the following:\n" "```json\n" "{\n" " \"deletes\": {\n" @@ -214,24 +214,24 @@ service OpenFGAService { "The Check API returns whether a given user has a relationship with a given object in a given store.\n\n" "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:*`.\n" "To arrive at a result, the API uses:\n\n" - "- An authorization model\n\n" + "- An [authorization model](/docs/getting-started/configure-model)\n\n" "- Explicit tuples written through the Write API\n\n" "- Contextual tuples present in the request\n\n" "- Implicit tuples that exist by virtue of applying set theory\n\n" - "For example: `document:2021-budget#viewer@document:2021-budget#viewer`. In this example, the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`).\n\n" + "For example: `document:2021-budget#viewer@document:2021-budget#viewer`. In this example, the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n\n" "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`.\n" - "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.\n\n" + "You may also provide an `authorization_model_id` in the body. This is used to assert that the input `tuple_key` is valid for the model specified. " + "If not specified, the assertion is made against the latest authorization model ID.\n\n" "> **Note:** We recommend you specify authorization model id for better performance.\n\n" - "You may also provide a `context` object that will be used to evaluate the conditioned tuples in the system.\n\n" + "You may also provide a `context` object that is used to evaluate the conditioned tuples in the system.\n\n" "> **Note:** We recommend you provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.\n\n" "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.\n" - "The response will return whether the relationship exists in the field `allowed`.\n\n" + "The response returns whether the relationship exists in the field `allowed`.\n\n" "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. \n" "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.\n" - "## Examples\n" - "### Querying with contextual tuples\n" - "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\n" + "## Examples\n\n" + "### Querying with contextual tuples\n\n" + "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:\n" "```json\n" "{\n" " \"user\": \"user:anne\",\n" @@ -259,8 +259,8 @@ service OpenFGAService { " \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n" "}\n" "```\n" - "### Querying usersets\n" - "Some Checks will always return `true`, even without any tuples. For example, for the following authorization model\n" + "### Querying usersets\n\n" + "Some Checks always return `true`, even without any tuples. For example, for the following authorization model:\n" "```python\n" "model\n" " schema 1.1\n" @@ -269,7 +269,7 @@ service OpenFGAService { " relations\n" " define reader: [user]\n" "```\n" - "the following query\n" + "the following query:\n" "```json\n" "{\n" " \"tuple_key\": {\n" @@ -279,9 +279,9 @@ service OpenFGAService { " }\n" "}\n" "```\n" - "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`.\n" - "### Querying usersets with difference in the model\n" - "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\n" + "always returns `{ \"allowed\": true }`. This is because usersets are self-defining: the userset `document:2021-budget#reader` always has the `reader` relation with `document:2021-budget`.\n" + "### Querying usersets with difference in the model\n\n" + "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:\n" "```python\n" "model\n" " schema 1.1\n" @@ -294,7 +294,7 @@ service OpenFGAService { " define blocked: [user]\n" " define reader: [group#member] but not blocked\n" "```\n" - "the following query\n" + "the following query:\n" "```json\n" "{\n" " \"tuple_key\": {\n" @@ -323,8 +323,8 @@ service OpenFGAService { " },\n" "}\n" "```\n" - "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.\n" - "### Requesting higher consistency\n" + "returns `{ \"allowed\": true }`, even though a specific user of the userset `group:finance#member` does not have the `reader` relationship with the given object.\n" + "### Requesting higher consistency\n\n" "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.\n" "```json\n" "{\n" @@ -346,7 +346,7 @@ service OpenFGAService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - summary: "Send a list of related operations" + summary: "Check multiple relationships in a single request" tags: ["Relationship Queries"] operation_id: "BatchCheck" description: @@ -358,9 +358,9 @@ service OpenFGAService { "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}$`\n\n" - "> **Note:** The maximum number of checks that can be passed in the `BatchCheck` API is configurable via the [OPENFGA_MAX_CHECKS_PER_BATCH_CHECK](https://openfga.dev/docs/getting-started/setup-openfga/configuration#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.\n\n" + "> **Note:** The maximum number of checks that can be passed in the `BatchCheck` API is configurable using the environment variable: `[OPENFGA_MAX_CHECKS_PER_BATCH_CHECK](https://openfga.dev/docs/getting-started/setup-openfga/configuration#OPENFGA_MAX_CHECKS_PER_BATCH_CHECK)`. If `BatchCheck` is called using the SDK, the SDK can split the batch check requests for you.\n\n" "For more details on how `Check` functions, review the docs for `/check`.\n\n" - "### Examples\n" + "### Examples\n\n" "#### A BatchCheckRequest\n" "```json\n" "{\n" @@ -416,17 +416,17 @@ service OpenFGAService { tags: ["Relationship Queries"] operation_id: "Expand" description: - "The Expand API will return all users and usersets " + "The Expand API returns all users and usersets " "that have certain relationship with an object in a certain store.\n" "This is different from the `/stores/{store_id}/read` API in that both users and " "computed usersets are returned.\n\n" "Body parameters `tuple_key.object` and `tuple_key.relation` are all required.\n" "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`.\n" - "The response will return a tree whose leaves are the specific users and usersets. " + "The response returns a tree whose leaves are the specific users and usersets. " "Union, intersection and difference operator are located in the intermediate nodes.\n\n" - "## Example\n" + "## Example\n\n" "To expand all users that have the `reader` relationship with object `document:2021-budget`, " - "use the Expand API with the following request body\n" + "use the Expand API with the following request body:\n" "```json\n" "{\n" " \"tuple_key\": {\n" @@ -436,7 +436,7 @@ service OpenFGAService { " \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n" "}\n" "```\n" - "OpenFGA's response will be a userset tree of the users and usersets that have " + "OpenFGA's response is a userset tree of the users and usersets that have " "read access to the document.\n" "```json\n" "{\n" @@ -470,7 +470,7 @@ service OpenFGAService { "}\n" "```\n" "The caller can then call expand API for the `writer` relationship for the `document:2021-budget`.\n" - "### Expand Request with Contextual Tuples\n" + "### Expand Request with Contextual Tuples\n\n" "\n" "Given the model\n" "```python\n" @@ -498,7 +498,7 @@ service OpenFGAService { "}]\n" "```\n" "\n" - "To expand all `writers` of `document:1` when `document:1` is put in `folder:1`, the first call could be\n" + "To expand all `writers` of `document:1` when `document:1` is put in `folder:1`, the first call could be:\n" "\n" "```json\n" "{\n" @@ -591,8 +591,8 @@ service OpenFGAService { description: "The ReadAuthorizationModels API returns all the authorization models for a certain store.\n" "OpenFGA's response contains an array of all authorization models, sorted in descending order of creation.\n\n" - "## Example\n" - "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:\n" + "## Example\n\n" + "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 returns a response that looks like:\n\n" "```json\n" "{\n" " \"authorization_models\": [\n" @@ -608,7 +608,7 @@ service OpenFGAService { " \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n" "}\n" "```\n" - "If there are no more authorization models available, the `continuation_token` field will be empty\n" + "If there are no more authorization models available, then `continuation_token` field returns empty:\n\n" "```json\n" "{\n" " \"authorization_models\": [\n" @@ -637,11 +637,11 @@ service OpenFGAService { operation_id: "ReadAuthorizationModel" description: "The ReadAuthorizationModel API returns an authorization model by its identifier.\n" - "The response will return the authorization model for the particular version.\n\n" - "## Example\n" + "The response returns the authorization model for the particular version.\n\n" + "## Example\n\n" "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:\n" + "`id` path parameter. The API returns:\n" "```json\n" "{\n" " \"authorization_model\":{\n" @@ -693,12 +693,12 @@ service OpenFGAService { tags: ["Authorization Models"] operation_id: "WriteAuthorizationModel" description: - "The WriteAuthorizationModel API will add a new authorization model " + "The WriteAuthorizationModel API adds a new authorization model " "to a store.\n" "Each item in the `type_definitions` array is a type " "definition as specified in the field `type_definition`.\n" - "The response will return the authorization model's ID in the `id` field.\n\n" - "## Example\n" + "The response returns the authorization model's ID in the `id` field.\n\n" + "## Example\n\n" "To add an authorization model with `user` and `document` type definitions, call `POST` " "`authorization-models` API with the body: \n" "```json\n" @@ -733,8 +733,8 @@ service OpenFGAService { " ]\n" "}\n" "```\n" - "OpenFGA's response will include the version id for this authorization model, " - "which will look like \n" + "OpenFGA's response includes the version id for this authorization model, " + "similar to:\n" "```\n" "{\"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"}\n" "```\n" @@ -761,10 +761,10 @@ service OpenFGAService { tags: ["Assertions"] operation_id: "WriteAssertions" description: - "The WriteAssertions API will upsert new assertions for an authorization model id, " + "The WriteAssertions API upserts 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." + "returns true or false, and optionally a list of contextual tuples." responses: { key: "204" value: { @@ -796,14 +796,14 @@ service OpenFGAService { tags: ["Relationship Tuples"] operation_id: "ReadChanges" description: - "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 " + "The ReadChanges API returns a paginated list of tuple changes (additions and deletions) that occurred " + "in a given store, sorted by ascending time. The response includes 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.\n" + "the same token is returned in order for it to be used when new changes are recorded.\n\n" + "If the store never had any tuples added or removed, then this token returns empty.\n" "You can use the `type` parameter to only get the list of tuple changes that affect objects of that type.\n" - "When reading a write tuple change, if it was conditioned, the condition will be returned.\n" - "When reading a delete tuple change, the condition will NOT be returned regardless of whether it was originally conditioned or not.\n" + "When reading a write tuple change, if it was conditioned, the condition is returned.\n" + "When reading a delete tuple change, the condition is NOT returned regardless of whether it was originally conditioned or not.\n" }; } @@ -817,7 +817,7 @@ service OpenFGAService { summary: "Create a store" tags: ["Stores"] operation_id: "CreateStore" - description: "Create a unique OpenFGA store which will be used to store authorization models and relationship tuples." + description: "Create a unique OpenFGA store which is used to store authorization models and relationship tuples." responses: { key: "201" value: { @@ -895,7 +895,7 @@ service OpenFGAService { operation_id: "ListStores" description: "Returns a paginated list of OpenFGA stores and a continuation token to get additional stores.\n" - "The continuation token will be empty if there are no more stores.\n" + "The continuation token is empty if there are no more stores.\n" }; } @@ -929,24 +929,24 @@ service OpenFGAService { description: "The ListObjects API returns a list of all the objects of the given type that the user has a relation with.\n " "To arrive at a result, the API uses:\n\n" - "- An authorization model\n" + "- An [authorization model](/docs/getting-started/configure-model)\n" "- Explicit tuples written through the Write API\n" "- Contextual tuples present in the request\n" "- Implicit tuples that exist by virtue of applying set theory. For example:\n\n" "`document:2021-budget#viewer@document:2021-budget#viewer`\n\n" "In the example the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n\n" "An `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization " - "model ID will be used.\n\n" + "model ID is used.\n\n" "> **Note:** We recommend you specify authorization model ID for better performance.\n\n" "You may also specify `contextual_tuples` that is treated as regular tuples. Each of these tuples may have an associated `condition`.\n" "You may also provide a `context` object that is used to evaluate the conditioned tuples in the system.\n\n" "> **Note:** We recommend you provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.\n\n" "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.\n" - "The response contains the related objects in an array in the \"objects\" field of the response and they will " - "be strings in the object format `:` (e.g. \"document:roadmap\").\n\n" - "The number of objects in the response array will be limited by the execution timeout specified in the flag `OPENFGA_LIST_OBJECTS_DEADLINE` " + "The response contains the related objects in an array in the \"objects\" field of the response and are " + "strings in the object format `:` (e.g. \"document:roadmap\").\n\n" + "The number of objects in the response array are 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.\n" - "The objects given will not be sorted, and therefore two identical calls can give a given different set of objects." + "The objects given are not sorted, and therefore two identical calls can give a given different set of objects." }; } @@ -963,25 +963,25 @@ service OpenFGAService { description: "The ListUsers API returns a list of all the users of a specific type that have a relation to a given object.\n\n " "To arrive at a result, the API uses:\n\n" - "- An authorization model\n\n" + "- An [authorization model](/docs/getting-started/configure-model)\n\n" "- Explicit tuples written through the Write API\n\n" "- Contextual tuples present in the request\n\n" "- Implicit tuples that exist by virtue of applying set theory\n\n" "For example: `document:2021-budget#viewer@document:2021-budget#viewer`. In this example, the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n\n" "An `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization " - "model ID will be used.\n\n" + "model ID is used.\n\n" "> **Note:** We recommend you specify authorization model ID for better performance.\n\n" - "You may also specify `contextual_tuples` that will be treated as regular tuples. Each of these tuples may have an associated `condition`.\n" - "You may also provide a `context` object that will be used to evaluate the conditioned tuples in the system.\n\n" + "You may also specify `contextual_tuples` that are treated as regular tuples. Each of these tuples may have an associated `condition`.\n" + "You may also provide a `context` object used to evaluate the conditioned tuples in the system.\n\n" "> **Note:** We recommend you provide a value for all the input parameters of all the conditions. This ensures that all tuples be evaluated correctly.\n\n" - "The response will contain the related users in an array in the \"users\" field of the response. These results may include specific objects, usersets \n" + "The response contains the related users in an array in the \"users\" field of the response. These results may include specific objects, usersets \n" "or type-bound public access. Each of these types of results is encoded in its own type and not represented as a string.\n\n" "In cases where a type-bound public access result is returned (e.g. `user:*`), it cannot be inferred that all subjects\n" "of that type have a relation to the object; it is possible that negations exist and checks should still be queried\n" - "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` " + "on individual subjects to ensure access to that document.\n" + "The number of users in the response array are 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.\n" - "The returned users will not be sorted, and therefore two identical calls may yield different sets of users." + "The returned users are not sorted, and therefore two identical calls may yield different sets of users." }; } } @@ -1030,11 +1030,11 @@ message ListObjectsRequest { openfga.v1.ContextualTupleKeys contextual_tuples = 6 [json_name = "contextual_tuples"]; - // Additional request context that will be used to evaluate any ABAC conditions encountered + // Additional request context that are used to evaluate any ABAC conditions encountered // in the query evaluation. google.protobuf.Struct context = 7; - // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which will have the same behavior as MINIMIZE_LATENCY. + // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`. ConsistencyPreference consistency = 8 [(validate.rules).enum.defined_only = true]; } @@ -1097,11 +1097,11 @@ message ListUsersRequest { (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {max_items: 100} ]; - // Additional request context that will be used to evaluate any ABAC conditions encountered + // Additional request context used to evaluate any ABAC conditions encountered // in the query evaluation. google.protobuf.Struct context = 7; - // Controls the consistency preference for this request. Default value is UNSPECIFIED, which will have the same behavior as MINIMIZE_LATENCY. + // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`. ConsistencyPreference consistency = 8 [(validate.rules).enum.defined_only = true]; } @@ -1157,11 +1157,11 @@ message StreamedListObjectsRequest { openfga.v1.ContextualTupleKeys contextual_tuples = 6 [json_name = "contextual_tuples"]; - // Additional request context that will be used to evaluate any ABAC conditions encountered + // Additional request context used to evaluate any ABAC conditions encountered // in the query evaluation. google.protobuf.Struct context = 7; - // Controls the consistency preference for this request. Default value is UNSPECIFIED, which will have the same behavior as MINIMIZE_LATENCY. + // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`. ConsistencyPreference consistency = 8 [(validate.rules).enum.defined_only = true]; } @@ -1208,7 +1208,7 @@ message ReadRequest { (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {example: "\"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\""} ]; - // Controls the consistency preference for this request. Default value is UNSPECIFIED, which will have the same behavior as MINIMIZE_LATENCY. + // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`. ConsistencyPreference consistency = 5 [(validate.rules).enum.defined_only = true]; } @@ -1257,7 +1257,7 @@ message ReadResponse { (validate.rules).string.max_bytes = 5120, (validate.rules).string.pattern = "^$|^[A-Za-z0-9-_]+={0,2}$", (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = { - description: "The continuation token will be empty if there are no more tuples." + description: "The continuation token is empty if there are no more tuples." example: "\"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"" } ]; @@ -1362,11 +1362,11 @@ message CheckRequest { example: "false" }]; - // Additional request context that will be used to evaluate any ABAC conditions encountered + // Additional request context that is used to evaluate any ABAC conditions encountered // in the query evaluation. google.protobuf.Struct context = 6; - // Controls the consistency preference for this request. Default value is UNSPECIFIED, which will have the same behavior as MINIMIZE_LATENCY. + // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which has the same behavior as `MINIMIZE_LATENCY`. ConsistencyPreference consistency = 7 [(validate.rules).enum.defined_only = true]; } @@ -1455,7 +1455,7 @@ message BatchCheckItem { message BatchCheckResponse { map result = 1 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = { example: '{"1cd93d8c-8e45-43c6-9a15-cbb3c7f394bc": {"allowed": true, "error": {"message": ""}}}' - description: "map keys are the correlation_id values from the BatchCheckItems in the request" + description: "Map keys are the `correlation_id` values from the `BatchCheckItems` in the request." }]; } @@ -1497,7 +1497,7 @@ message ExpandRequest { (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {example: "\"01G5JAVJ41T49E9TT3SKVS7X1J\""} ]; - // Controls the consistency preference for this request. Default value is UNSPECIFIED, which will have the same behavior as MINIMIZE_LATENCY. + // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`. ConsistencyPreference consistency = 4 [(validate.rules).enum.defined_only = true]; openfga.v1.ContextualTupleKeys contextual_tuples = 5 [json_name = "contextual_tuples"]; @@ -1632,7 +1632,7 @@ message ReadAuthorizationModelsResponse { (validate.rules).string.max_bytes = 5120, (validate.rules).string.pattern = "^$|^[A-Za-z0-9-_]+={0,2}$", (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = { - description: "The continuation token will be empty if there are no more models." + description: "The continuation token is empty if there are no more models." example: "\"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"" } ]; @@ -1729,7 +1729,7 @@ message ReadChangesRequest { description: "Start date and time of changes to read.\n" "Format: ISO 8601 timestamp (e.g., 2022-01-01T00:00:00Z)\n" - "If a continuation_token is provided along side start_time, the continuation_token will take precedence over start_time." + "If a `continuation_token` is provided along side `start_time`, the `continuation_token` takes precedence over `start_time`." example: "2021-01-01T00:00:00.000Z" } ]; @@ -1743,7 +1743,7 @@ message ReadChangesResponse { (validate.rules).string.max_bytes = 5120, (validate.rules).string.pattern = "^$|^[A-Za-z0-9-_]+={0,2}$", (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = { - description: "The continuation token will be identical if there are no new changes." + description: "The continuation token is identical if there are no new changes." example: "\"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"" } ]; @@ -1865,8 +1865,8 @@ message ListStoresRequest { (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = { example: "\"my-store-name\"" description: - "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" + "The name parameter instructs the API to only include results that match that name./n" + "Multiple results may be returned. Only exact matches are returned; substring matches and regexes are not be evaluated." } ]; } @@ -1879,7 +1879,7 @@ message ListStoresResponse { (validate.rules).string.max_bytes = 5120, (validate.rules).string.pattern = "^$|^[A-Za-z0-9-_]+={0,2}$", (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = { - description: "The continuation token will be empty if there are no more stores." + description: "The continuation token is empty if there are no more stores." example: "\"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"" } ]; @@ -1932,7 +1932,7 @@ message Assertion { (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {max_items: 20} ]; - // Additional request context that will be used to evaluate any ABAC conditions encountered + // Additional request context is used to evaluate any ABAC conditions encountered // in the query evaluation. google.protobuf.Struct context = 4 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {example: '{"view_count": 100}'}]; } diff --git a/proto/openfga/v1/openfga_service.pb.go b/proto/openfga/v1/openfga_service.pb.go index 294d4890..5a7f53fd 100644 --- a/proto/openfga/v1/openfga_service.pb.go +++ b/proto/openfga/v1/openfga_service.pb.go @@ -36,10 +36,10 @@ type ListObjectsRequest struct { Relation string `protobuf:"bytes,4,opt,name=relation,proto3" json:"relation,omitempty"` User string `protobuf:"bytes,5,opt,name=user,proto3" json:"user,omitempty"` ContextualTuples *ContextualTupleKeys `protobuf:"bytes,6,opt,name=contextual_tuples,proto3" json:"contextual_tuples,omitempty"` - // Additional request context that will be used to evaluate any ABAC conditions encountered + // Additional request context that are used to evaluate any ABAC conditions encountered // in the query evaluation. Context *structpb.Struct `protobuf:"bytes,7,opt,name=context,proto3" json:"context,omitempty"` - // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which will have the same behavior as MINIMIZE_LATENCY. + // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`. Consistency ConsistencyPreference `protobuf:"varint,8,opt,name=consistency,proto3,enum=openfga.v1.ConsistencyPreference" json:"consistency,omitempty"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache @@ -183,10 +183,10 @@ type ListUsersRequest struct { Relation string `protobuf:"bytes,4,opt,name=relation,proto3" json:"relation,omitempty"` UserFilters []*UserTypeFilter `protobuf:"bytes,5,rep,name=user_filters,proto3" json:"user_filters,omitempty"` ContextualTuples []*TupleKey `protobuf:"bytes,6,rep,name=contextual_tuples,proto3" json:"contextual_tuples,omitempty"` - // Additional request context that will be used to evaluate any ABAC conditions encountered + // Additional request context used to evaluate any ABAC conditions encountered // in the query evaluation. Context *structpb.Struct `protobuf:"bytes,7,opt,name=context,proto3" json:"context,omitempty"` - // Controls the consistency preference for this request. Default value is UNSPECIFIED, which will have the same behavior as MINIMIZE_LATENCY. + // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`. Consistency ConsistencyPreference `protobuf:"varint,8,opt,name=consistency,proto3,enum=openfga.v1.ConsistencyPreference" json:"consistency,omitempty"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache @@ -330,10 +330,10 @@ type StreamedListObjectsRequest struct { Relation string `protobuf:"bytes,4,opt,name=relation,proto3" json:"relation,omitempty"` User string `protobuf:"bytes,5,opt,name=user,proto3" json:"user,omitempty"` ContextualTuples *ContextualTupleKeys `protobuf:"bytes,6,opt,name=contextual_tuples,proto3" json:"contextual_tuples,omitempty"` - // Additional request context that will be used to evaluate any ABAC conditions encountered + // Additional request context used to evaluate any ABAC conditions encountered // in the query evaluation. Context *structpb.Struct `protobuf:"bytes,7,opt,name=context,proto3" json:"context,omitempty"` - // Controls the consistency preference for this request. Default value is UNSPECIFIED, which will have the same behavior as MINIMIZE_LATENCY. + // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`. Consistency ConsistencyPreference `protobuf:"varint,8,opt,name=consistency,proto3,enum=openfga.v1.ConsistencyPreference" json:"consistency,omitempty"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache @@ -476,7 +476,7 @@ type ReadRequest struct { TupleKey *ReadRequestTupleKey `protobuf:"bytes,2,opt,name=tuple_key,proto3" json:"tuple_key,omitempty"` PageSize *wrapperspb.Int32Value `protobuf:"bytes,3,opt,name=page_size,proto3" json:"page_size,omitempty"` ContinuationToken string `protobuf:"bytes,4,opt,name=continuation_token,proto3" json:"continuation_token,omitempty"` - // Controls the consistency preference for this request. Default value is UNSPECIFIED, which will have the same behavior as MINIMIZE_LATENCY. + // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`. Consistency ConsistencyPreference `protobuf:"varint,5,opt,name=consistency,proto3,enum=openfga.v1.ConsistencyPreference" json:"consistency,omitempty"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache @@ -875,10 +875,10 @@ type CheckRequest struct { AuthorizationModelId string `protobuf:"bytes,4,opt,name=authorization_model_id,proto3" json:"authorization_model_id,omitempty"` // Defaults to false. Making it true has performance implications. Trace bool `protobuf:"varint,5,opt,name=trace,proto3" json:"trace,omitempty"` - // Additional request context that will be used to evaluate any ABAC conditions encountered + // Additional request context that is used to evaluate any ABAC conditions encountered // in the query evaluation. Context *structpb.Struct `protobuf:"bytes,6,opt,name=context,proto3" json:"context,omitempty"` - // Controls the consistency preference for this request. Default value is UNSPECIFIED, which will have the same behavior as MINIMIZE_LATENCY. + // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which has the same behavior as `MINIMIZE_LATENCY`. Consistency ConsistencyPreference `protobuf:"varint,7,opt,name=consistency,proto3,enum=openfga.v1.ConsistencyPreference" json:"consistency,omitempty"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache @@ -1433,7 +1433,7 @@ type ExpandRequest struct { StoreId string `protobuf:"bytes,1,opt,name=store_id,proto3" json:"store_id,omitempty"` TupleKey *ExpandRequestTupleKey `protobuf:"bytes,2,opt,name=tuple_key,proto3" json:"tuple_key,omitempty"` AuthorizationModelId string `protobuf:"bytes,3,opt,name=authorization_model_id,proto3" json:"authorization_model_id,omitempty"` - // Controls the consistency preference for this request. Default value is UNSPECIFIED, which will have the same behavior as MINIMIZE_LATENCY. + // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`. Consistency ConsistencyPreference `protobuf:"varint,4,opt,name=consistency,proto3,enum=openfga.v1.ConsistencyPreference" json:"consistency,omitempty"` ContextualTuples *ContextualTupleKeys `protobuf:"bytes,5,opt,name=contextual_tuples,proto3" json:"contextual_tuples,omitempty"` unknownFields protoimpl.UnknownFields @@ -2858,7 +2858,7 @@ type Assertion struct { TupleKey *AssertionTupleKey `protobuf:"bytes,1,opt,name=tuple_key,proto3" json:"tuple_key,omitempty"` Expectation bool `protobuf:"varint,2,opt,name=expectation,proto3" json:"expectation,omitempty"` ContextualTuples []*TupleKey `protobuf:"bytes,3,rep,name=contextual_tuples,proto3" json:"contextual_tuples,omitempty"` - // Additional request context that will be used to evaluate any ABAC conditions encountered + // Additional request context is used to evaluate any ABAC conditions encountered // in the query evaluation. Context *structpb.Struct `protobuf:"bytes,4,opt,name=context,proto3" json:"context,omitempty"` unknownFields protoimpl.UnknownFields @@ -3020,10 +3020,10 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + "\x13ReadRequestTupleKey\x12O\n" + "\x04user\x18\x01 \x01(\tB;\x92A\x10J\v\"user:anne\"x\x80\x04\xfaB%r#(\x80\x042\x1b^[^\\s]{1,511}:[^\\s]{1,511}$\xd0\x01\x01R\x04user\x12E\n" + "\brelation\x18\x02 \x01(\tB)\x92A\fJ\b\"reader\"x2\xfaB\x17r\x152\x10^[^:#@\\s]{1,50}$\xd0\x01\x01R\brelation\x12N\n" + - "\x06object\x18\x03 \x01(\tB6\x92A\x1bJ\x16\"document:2021-budget\"x\x80\x02\xfaB\x15r\x132\x0e^[^\\s]{2,256}$\xd0\x01\x01R\x06object\"\xc3\x02\n" + + "\x06object\x18\x03 \x01(\tB6\x92A\x1bJ\x16\"document:2021-budget\"x\x80\x02\xfaB\x15r\x132\x0e^[^\\s]{2,256}$\xd0\x01\x01R\x06object\"\xbe\x02\n" + "\fReadResponse\x12.\n" + - "\x06tuples\x18\x01 \x03(\v2\x11.openfga.v1.TupleB\x03\xe0A\x02R\x06tuples\x12\x82\x02\n" + - "\x12continuation_token\x18\x02 \x01(\tB\xd1\x01\x92A\xa7\x012AThe continuation token will be empty if there are no more tuples.Jb\"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\xe0A\x02\xfaB r\x1e(\x80(2\x19^$|^[A-Za-z0-9-_]+={0,2}$R\x12continuation_token\"\x83\x03\n" + + "\x06tuples\x18\x01 \x03(\v2\x11.openfga.v1.TupleB\x03\xe0A\x02R\x06tuples\x12\xfd\x01\n" + + "\x12continuation_token\x18\x02 \x01(\tB\xcc\x01\x92A\xa2\x012 **Note:** We recommend you specify authorization model id for better performance.\n" + "\n" + - "You may also provide a `context` object that will be used to evaluate the conditioned tuples in the system.\n" + + "You may also provide a `context` object that is used to evaluate the conditioned tuples in the system.\n" + "\n" + "> **Note:** We recommend you provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.\n" + "\n" + "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.\n" + - "The response will return whether the relationship exists in the field `allowed`.\n" + + "The response returns whether the relationship exists in the field `allowed`.\n" + "\n" + "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. \n" + "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.\n" + "## Examples\n" + + "\n" + "### Querying with contextual tuples\n" + - "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\n" + + "\n" + + "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:\n" + "```json\n" + "{\n" + " \"user\": \"user:anne\",\n" + @@ -3422,7 +3431,8 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + "}\n" + "```\n" + "### Querying usersets\n" + - "Some Checks will always return `true`, even without any tuples. For example, for the following authorization model\n" + + "\n" + + "Some Checks always return `true`, even without any tuples. For example, for the following authorization model:\n" + "```python\n" + "model\n" + " schema 1.1\n" + @@ -3431,7 +3441,7 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + " relations\n" + " define reader: [user]\n" + "```\n" + - "the following query\n" + + "the following query:\n" + "```json\n" + "{\n" + " \"tuple_key\": {\n" + @@ -3441,9 +3451,10 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + " }\n" + "}\n" + "```\n" + - "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`.\n" + + "always returns `{ \"allowed\": true }`. This is because usersets are self-defining: the userset `document:2021-budget#reader` always has the `reader` relation with `document:2021-budget`.\n" + "### Querying usersets with difference in the model\n" + - "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\n" + + "\n" + + "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:\n" + "```python\n" + "model\n" + " schema 1.1\n" + @@ -3456,7 +3467,7 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + " define blocked: [user]\n" + " define reader: [group#member] but not blocked\n" + "```\n" + - "the following query\n" + + "the following query:\n" + "```json\n" + "{\n" + " \"tuple_key\": {\n" + @@ -3485,8 +3496,9 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + " },\n" + "}\n" + "```\n" + - "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.\n" + + "returns `{ \"allowed\": true }`, even though a specific user of the userset `group:finance#member` does not have the `reader` relationship with the given object.\n" + "### Requesting higher consistency\n" + + "\n" + "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.\n" + "```json\n" + "{\n" + @@ -3498,18 +3510,19 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + " \"consistency\": \"HIGHER_CONSISTENCY\"\n" + "}\n" + "```\n" + - "*\x05Check\x82\xd3\xe4\x93\x02\x1d:\x01*\"\x18/stores/{store_id}/check\x12\x80\x13\n" + + "*\x05Check\x82\xd3\xe4\x93\x02\x1d:\x01*\"\x18/stores/{store_id}/check\x12\x95\x13\n" + "\n" + - "BatchCheck\x12\x1d.openfga.v1.BatchCheckRequest\x1a\x1e.openfga.v1.BatchCheckResponse\"\xb2\x12\x92A\x85\x12\n" + - "\x14Relationship Queries\x12!Send a list of related operations\x1a\xbd\x11The `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.\n" + + "BatchCheck\x12\x1d.openfga.v1.BatchCheckRequest\x1a\x1e.openfga.v1.BatchCheckResponse\"\xc7\x12\x92A\x9a\x12\n" + + "\x14Relationship Queries\x120Check multiple relationships in a single request\x1a\xc3\x11The `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.\n" + "\n" + "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}$`\n" + "\n" + - "> **Note:** The maximum number of checks that can be passed in the `BatchCheck` API is configurable via the [OPENFGA_MAX_CHECKS_PER_BATCH_CHECK](https://openfga.dev/docs/getting-started/setup-openfga/configuration#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.\n" + + "> **Note:** The maximum number of checks that can be passed in the `BatchCheck` API is configurable using the environment variable: `[OPENFGA_MAX_CHECKS_PER_BATCH_CHECK](https://openfga.dev/docs/getting-started/setup-openfga/configuration#OPENFGA_MAX_CHECKS_PER_BATCH_CHECK)`. If `BatchCheck` is called using the SDK, the SDK can split the batch check requests for you.\n" + "\n" + "For more details on how `Check` functions, review the docs for `/check`.\n" + "\n" + "### Examples\n" + + "\n" + "#### A BatchCheckRequest\n" + "```json\n" + "{\n" + @@ -3553,17 +3566,18 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + "}\n" + "```\n" + "*\n" + - "BatchCheck\x82\xd3\xe4\x93\x02#:\x01*\"\x1e/stores/{store_id}/batch-check\x12\xf7\x1d\n" + - "\x06Expand\x12\x19.openfga.v1.ExpandRequest\x1a\x1a.openfga.v1.ExpandResponse\"\xb5\x1d\x92A\x8d\x1d\n" + - "\x14Relationship Queries\x12+Expand relationships in userset tree format\x1a\xbf\x1cThe Expand API will return all users and usersets that have certain relationship with an object in a certain store.\n" + + "BatchCheck\x82\xd3\xe4\x93\x02#:\x01*\"\x1e/stores/{store_id}/batch-check\x12\xee\x1d\n" + + "\x06Expand\x12\x19.openfga.v1.ExpandRequest\x1a\x1a.openfga.v1.ExpandResponse\"\xac\x1d\x92A\x84\x1d\n" + + "\x14Relationship Queries\x12+Expand relationships in userset tree format\x1a\xb6\x1cThe Expand API returns all users and usersets that have certain relationship with an object in a certain store.\n" + "This is different from the `/stores/{store_id}/read` API in that both users and computed usersets are returned.\n" + "\n" + "Body parameters `tuple_key.object` and `tuple_key.relation` are all required.\n" + "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`.\n" + - "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.\n" + + "The response returns a tree whose leaves are the specific users and usersets. Union, intersection and difference operator are located in the intermediate nodes.\n" + "\n" + "## Example\n" + - "To expand all users that have the `reader` relationship with object `document:2021-budget`, use the Expand API with the following request body\n" + + "\n" + + "To expand all users that have the `reader` relationship with object `document:2021-budget`, use the Expand API with the following request body:\n" + "```json\n" + "{\n" + " \"tuple_key\": {\n" + @@ -3573,7 +3587,7 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + " \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n" + "}\n" + "```\n" + - "OpenFGA's response will be a userset tree of the users and usersets that have read access to the document.\n" + + "OpenFGA's response is a userset tree of the users and usersets that have read access to the document.\n" + "```json\n" + "{\n" + " \"tree\":{\n" + @@ -3608,6 +3622,7 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + "The caller can then call expand API for the `writer` relationship for the `document:2021-budget`.\n" + "### Expand Request with Contextual Tuples\n" + "\n" + + "\n" + "Given the model\n" + "```python\n" + "model\n" + @@ -3634,7 +3649,7 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + "}]\n" + "```\n" + "\n" + - "To expand all `writers` of `document:1` when `document:1` is put in `folder:1`, the first call could be\n" + + "To expand all `writers` of `document:1` when `document:1` is put in `folder:1`, the first call could be:\n" + "\n" + "```json\n" + "{\n" + @@ -3714,14 +3729,16 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + " }\n" + "}\n" + "```\n" + - "*\x06Expand\x82\xd3\xe4\x93\x02\x1e:\x01*\"\x19/stores/{store_id}/expand\x12\xde\n" + + "*\x06Expand\x82\xd3\xe4\x93\x02\x1e:\x01*\"\x19/stores/{store_id}/expand\x12\xdf\n" + "\n" + - "\x17ReadAuthorizationModels\x12*.openfga.v1.ReadAuthorizationModelsRequest\x1a+.openfga.v1.ReadAuthorizationModelsResponse\"\xe9\t\x92A\xb6\t\n" + - "\x14Authorization Models\x12\x1cGet all authorization models\x1a\xe6\bThe ReadAuthorizationModels API returns all the authorization models for a certain store.\n" + + "\x17ReadAuthorizationModels\x12*.openfga.v1.ReadAuthorizationModelsRequest\x1a+.openfga.v1.ReadAuthorizationModelsResponse\"\xea\t\x92A\xb7\t\n" + + "\x14Authorization Models\x12\x1cGet all authorization models\x1a\xe7\bThe ReadAuthorizationModels API returns all the authorization models for a certain store.\n" + "OpenFGA's response contains an array of all authorization models, sorted in descending order of creation.\n" + "\n" + "## Example\n" + - "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:\n" + + "\n" + + "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 returns a response that looks like:\n" + + "\n" + "```json\n" + "{\n" + " \"authorization_models\": [\n" + @@ -3737,7 +3754,8 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + " \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n" + "}\n" + "```\n" + - "If there are no more authorization models available, the `continuation_token` field will be empty\n" + + "If there are no more authorization models available, then `continuation_token` field returns empty:\n" + + "\n" + "```json\n" + "{\n" + " \"authorization_models\": [\n" + @@ -3753,15 +3771,15 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + " \"continuation_token\": \"\"\n" + "}\n" + "```\n" + - "*\x17ReadAuthorizationModels\x82\xd3\xe4\x93\x02)\x12'/stores/{store_id}/authorization-models\x12\xf6\n" + + "*\x17ReadAuthorizationModels\x82\xd3\xe4\x93\x02)\x12'/stores/{store_id}/authorization-models\x12\xef\n" + "\n" + - "\x16ReadAuthorizationModel\x12).openfga.v1.ReadAuthorizationModelRequest\x1a*.openfga.v1.ReadAuthorizationModelResponse\"\x84\n" + - "\x92A\xcc\t\n" + - "\x14Authorization Models\x12%Get an authorization model by version\x1a\xf4\bThe ReadAuthorizationModel API returns an authorization model by its identifier.\n" + - "The response will return the authorization model for the particular version.\n" + + "\x16ReadAuthorizationModel\x12).openfga.v1.ReadAuthorizationModelRequest\x1a*.openfga.v1.ReadAuthorizationModelResponse\"\xfd\t\x92A\xc5\t\n" + + "\x14Authorization Models\x12%Get an authorization model by version\x1a\xed\bThe ReadAuthorizationModel API returns an authorization model by its identifier.\n" + + "The response returns the authorization model for the particular version.\n" + "\n" + "## Example\n" + - "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:\n" + + "\n" + + "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 returns:\n" + "```json\n" + "{\n" + " \"authorization_model\":{\n" + @@ -3797,15 +3815,15 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + " }\n" + "}\n" + "```\n" + - "In the above example, there are 2 types (`user` and `document`). The `document` type has 2 relations (`writer` and `reader`).*\x16ReadAuthorizationModel\x82\xd3\xe4\x93\x02.\x12,/stores/{store_id}/authorization-models/{id}\x12\xfd\n" + + "In the above example, there are 2 types (`user` and `document`). The `document` type has 2 relations (`writer` and `reader`).*\x16ReadAuthorizationModel\x82\xd3\xe4\x93\x02.\x12,/stores/{store_id}/authorization-models/{id}\x12\xe8\n" + "\n" + - "\x17WriteAuthorizationModel\x12*.openfga.v1.WriteAuthorizationModelRequest\x1a+.openfga.v1.WriteAuthorizationModelResponse\"\x88\n" + - "\x92A\xd2\t\n" + - "\x14Authorization Models\x12 Create a new authorization model\x1a\xac\bThe WriteAuthorizationModel API will add a new authorization model to a store.\n" + + "\x17WriteAuthorizationModel\x12*.openfga.v1.WriteAuthorizationModelRequest\x1a+.openfga.v1.WriteAuthorizationModelResponse\"\xf3\t\x92A\xbd\t\n" + + "\x14Authorization Models\x12 Create a new authorization model\x1a\x97\bThe WriteAuthorizationModel API adds a new authorization model to a store.\n" + "Each item in the `type_definitions` array is a type definition as specified in the field `type_definition`.\n" + - "The response will return the authorization model's ID in the `id` field.\n" + + "The response returns the authorization model's ID in the `id` field.\n" + "\n" + "## Example\n" + + "\n" + "To add an authorization model with `user` and `document` type definitions, call `POST` `authorization-models` API with the body: \n" + "```json\n" + "{\n" + @@ -3839,31 +3857,33 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + " ]\n" + "}\n" + "```\n" + - "OpenFGA's response will include the version id for this authorization model, which will look like \n" + + "OpenFGA's response includes the version id for this authorization model, similar to:\n" + "```\n" + "{\"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"}\n" + "```\n" + "*\x17WriteAuthorizationModelJP\n" + "\x03201\x12I\n" + "\x16A successful response.\x12/\n" + - "-\x1a+.openfga.v1.WriteAuthorizationModelResponse\x82\xd3\xe4\x93\x02,:\x01*\"'/stores/{store_id}/authorization-models\x12\xe8\x04\n" + - "\x0fWriteAssertions\x12\".openfga.v1.WriteAssertionsRequest\x1a#.openfga.v1.WriteAssertionsResponse\"\x8b\x04\x92A\xc6\x03\n" + + "-\x1a+.openfga.v1.WriteAuthorizationModelResponse\x82\xd3\xe4\x93\x02,:\x01*\"'/stores/{store_id}/authorization-models\x12\xe0\x04\n" + + "\x0fWriteAssertions\x12\".openfga.v1.WriteAssertionsRequest\x1a#.openfga.v1.WriteAssertionsResponse\"\x83\x04\x92A\xbe\x03\n" + "\n" + - "Assertions\x12(Upsert authorization model ID assertions\x1a\xb2\x02The 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.*\x0fWriteAssertionsJH\n" + + "Assertions\x12(Upsert authorization model ID assertions\x1a\xaa\x02The WriteAssertions API upserts 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 returns true or false, and optionally a list of contextual tuples.*\x0fWriteAssertionsJH\n" + "\x03204\x12A\n" + "\x16A successful response.\x12'\n" + "%\x1a#.openfga.v1.WriteAssertionsResponse\x82\xd3\xe4\x93\x02;:\x01*\x1a6/stores/{store_id}/assertions/{authorization_model_id}\x12\xbd\x02\n" + "\x0eReadAssertions\x12!.openfga.v1.ReadAssertionsRequest\x1a\".openfga.v1.ReadAssertionsResponse\"\xe3\x01\x92A\xa1\x01\n" + "\n" + - "Assertions\x12%Get authorization model ID assertions\x1a\\The ReadAssertions API returns all the assertions stored for a given authorization model id.*\x0eReadAssertions\x82\xd3\xe4\x93\x028\x126/stores/{store_id}/assertions/{authorization_model_id}\x12\xd2\a\n" + - "\vReadChanges\x12\x1e.openfga.v1.ReadChangesRequest\x1a\x1f.openfga.v1.ReadChangesResponse\"\x81\a\x92A\xdb\x06\n" + - "\x13Relationship Tuples\x12\x15Get all tuple changes\x1a\x9f\x06The 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.\n" + + "Assertions\x12%Get authorization model ID assertions\x1a\\The ReadAssertions API returns all the assertions stored for a given authorization model id.*\x0eReadAssertions\x82\xd3\xe4\x93\x028\x126/stores/{store_id}/assertions/{authorization_model_id}\x12\xc1\a\n" + + "\vReadChanges\x12\x1e.openfga.v1.ReadChangesRequest\x1a\x1f.openfga.v1.ReadChangesResponse\"\xf0\x06\x92A\xca\x06\n" + + "\x13Relationship Tuples\x12\x15Get all tuple changes\x1a\x8e\x06The ReadChanges API returns a paginated list of tuple changes (additions and deletions) that occurred in a given store, sorted by ascending time. The response includes 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 is returned in order for it to be used when new changes are recorded.\n" + + "\n" + + "If the store never had any tuples added or removed, then this token returns empty.\n" + "You can use the `type` parameter to only get the list of tuple changes that affect objects of that type.\n" + - "When reading a write tuple change, if it was conditioned, the condition will be returned.\n" + - "When reading a delete tuple change, the condition will NOT be returned regardless of whether it was originally conditioned or not.\n" + - "*\vReadChanges\x82\xd3\xe4\x93\x02\x1c\x12\x1a/stores/{store_id}/changes\x12\xbb\x02\n" + - "\vCreateStore\x12\x1e.openfga.v1.CreateStoreRequest\x1a\x1f.openfga.v1.CreateStoreResponse\"\xea\x01\x92A\xd4\x01\n" + - "\x06Stores\x12\x0eCreate a store\x1agCreate a unique OpenFGA store which will be used to store authorization models and relationship tuples.*\vCreateStoreJD\n" + + "When reading a write tuple change, if it was conditioned, the condition is returned.\n" + + "When reading a delete tuple change, the condition is NOT returned regardless of whether it was originally conditioned or not.\n" + + "*\vReadChanges\x82\xd3\xe4\x93\x02\x1c\x12\x1a/stores/{store_id}/changes\x12\xb6\x02\n" + + "\vCreateStore\x12\x1e.openfga.v1.CreateStoreRequest\x1a\x1f.openfga.v1.CreateStoreResponse\"\xe5\x01\x92A\xcf\x01\n" + + "\x06Stores\x12\x0eCreate a store\x1abCreate a unique OpenFGA store which is used to store authorization models and relationship tuples.*\vCreateStoreJD\n" + "\x03201\x12=\n" + "\x16A successful response.\x12#\n" + "!\x1a\x1f.openfga.v1.CreateStoreResponse\x82\xd3\xe4\x93\x02\f:\x01*\"\a/stores\x12\x8e\x02\n" + @@ -3878,23 +3898,23 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + "\x16A successful response.\x12#\n" + "!\x1a\x1f.openfga.v1.DeleteStoreResponse\x82\xd3\xe4\x93\x02\x14*\x12/stores/{store_id}\x12\xaf\x01\n" + "\bGetStore\x12\x1b.openfga.v1.GetStoreRequest\x1a\x1c.openfga.v1.GetStoreResponse\"h\x92AK\n" + - "\x06Stores\x12\vGet a store\x1a*Returns an OpenFGA store by its identifier*\bGetStore\x82\xd3\xe4\x93\x02\x14\x12\x12/stores/{store_id}\x12\xa9\x02\n" + + "\x06Stores\x12\vGet a store\x1a*Returns an OpenFGA store by its identifier*\bGetStore\x82\xd3\xe4\x93\x02\x14\x12\x12/stores/{store_id}\x12\xa4\x02\n" + "\n" + - "ListStores\x12\x1d.openfga.v1.ListStoresRequest\x1a\x1e.openfga.v1.ListStoresResponse\"\xdb\x01\x92A\xc8\x01\n" + - "\x06Stores\x12\x0fList all stores\x1a\xa0\x01Returns a paginated list of OpenFGA stores and a continuation token to get additional stores.\n" + - "The continuation token will be empty if there are no more stores.\n" + + "ListStores\x12\x1d.openfga.v1.ListStoresRequest\x1a\x1e.openfga.v1.ListStoresResponse\"\xd6\x01\x92A\xc3\x01\n" + + "\x06Stores\x12\x0fList all stores\x1a\x9b\x01Returns a paginated list of OpenFGA stores and a continuation token to get additional stores.\n" + + "The continuation token is empty if there are no more stores.\n" + "*\n" + "ListStores\x82\xd3\xe4\x93\x02\t\x12\a/stores\x12\xd8\x04\n" + "\x13StreamedListObjects\x12&.openfga.v1.StreamedListObjectsRequest\x1a'.openfga.v1.StreamedListObjectsResponse\"\xed\x03\x92A\xb6\x03\n" + "\x14Relationship Queries\x12+Stream all objects with a user relationship\x1a\xdb\x02The Streamed ListObjects API is very similar to the the ListObjects API, with two differences: \n" + "1. Instead of collecting all objects before returning a response, it streams them to the client as they are collected. \n" + "2. The number of results returned is only limited by the execution timeout specified in the flag `OPENFGA_LIST_OBJECTS_DEADLINE`. \n" + - "*\x13StreamedListObjects\x82\xd3\xe4\x93\x02-:\x01*\"(/stores/{store_id}/streamed-list-objects0\x01\x12\xd8\x11\n" + - "\vListObjects\x12\x1e.openfga.v1.ListObjectsRequest\x1a\x1f.openfga.v1.ListObjectsResponse\"\x87\x11\x92A\xd9\x10\n" + - "\x14Relationship Queries\x12/List all objects with user-centric relationship\x1a\x82\x10The ListObjects API returns a list of all the objects of the given type that the user has a relation with.\n" + + "*\x13StreamedListObjects\x82\xd3\xe4\x93\x02-:\x01*\"(/stores/{store_id}/streamed-list-objects0\x01\x12\xeb\x11\n" + + "\vListObjects\x12\x1e.openfga.v1.ListObjectsRequest\x1a\x1f.openfga.v1.ListObjectsResponse\"\x9a\x11\x92A\xec\x10\n" + + "\x14Relationship Queries\x12/List all objects with user-centric relationship\x1a\x95\x10The ListObjects API returns a list of all the objects of the given type that the user has a relation with.\n" + " To arrive at a result, the API uses:\n" + "\n" + - "- An authorization model\n" + + "- An [authorization model](/docs/getting-started/configure-model)\n" + "- Explicit tuples written through the Write API\n" + "- Contextual tuples present in the request\n" + "- Implicit tuples that exist by virtue of applying set theory. For example:\n" + @@ -3903,7 +3923,7 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + "\n" + "In the example the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n" + "\n" + - "An `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID will be used.\n" + + "An `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID is used.\n" + "\n" + "> **Note:** We recommend you specify authorization model ID for better performance.\n" + "\n" + @@ -3913,16 +3933,16 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + "> **Note:** We recommend you provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.\n" + "\n" + "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.\n" + - "The response contains the related objects in an array in the \"objects\" field of the response and they will be strings in the object format `:` (e.g. \"document:roadmap\").\n" + + "The response contains the related objects in an array in the \"objects\" field of the response and are strings in the object format `:` (e.g. \"document:roadmap\").\n" + "\n" + - "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.\n" + - "The objects given will not be sorted, and therefore two identical calls can give a given different set of objects.*\vListObjects\x82\xd3\xe4\x93\x02$:\x01*\"\x1f/stores/{store_id}/list-objects\x12\xde\x11\n" + - "\tListUsers\x12\x1c.openfga.v1.ListUsersRequest\x1a\x1d.openfga.v1.ListUsersResponse\"\x93\x11\x92A\xe7\x10\n" + - "\x14Relationship Queries\x12/List all users with a relationship to an object\x1a\x92\x10The ListUsers API returns a list of all the users of a specific type that have a relation to a given object.\n" + + "The number of objects in the response array are 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.\n" + + "The objects given are not sorted, and therefore two identical calls can give a given different set of objects.*\vListObjects\x82\xd3\xe4\x93\x02$:\x01*\"\x1f/stores/{store_id}/list-objects\x12\xe6\x11\n" + + "\tListUsers\x12\x1c.openfga.v1.ListUsersRequest\x1a\x1d.openfga.v1.ListUsersResponse\"\x9b\x11\x92A\xef\x10\n" + + "\x14Relationship Queries\x12/List all users with a relationship to an object\x1a\x9a\x10The ListUsers API returns a list of all the users of a specific type that have a relation to a given object.\n" + "\n" + " To arrive at a result, the API uses:\n" + "\n" + - "- An authorization model\n" + + "- An [authorization model](/docs/getting-started/configure-model)\n" + "\n" + "- Explicit tuples written through the Write API\n" + "\n" + @@ -3932,22 +3952,23 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + "\n" + "For example: `document:2021-budget#viewer@document:2021-budget#viewer`. In this example, the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n" + "\n" + - "An `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID will be used.\n" + + "An `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID is used.\n" + "\n" + "> **Note:** We recommend you specify authorization model ID for better performance.\n" + "\n" + - "You may also specify `contextual_tuples` that will be treated as regular tuples. Each of these tuples may have an associated `condition`.\n" + - "You may also provide a `context` object that will be used to evaluate the conditioned tuples in the system.\n" + + "You may also specify `contextual_tuples` that are treated as regular tuples. Each of these tuples may have an associated `condition`.\n" + + "You may also provide a `context` object used to evaluate the conditioned tuples in the system.\n" + "\n" + "> **Note:** We recommend you provide a value for all the input parameters of all the conditions. This ensures that all tuples be evaluated correctly.\n" + "\n" + - "The response will contain the related users in an array in the \"users\" field of the response. These results may include specific objects, usersets \n" + + "The response contains the related users in an array in the \"users\" field of the response. These results may include specific objects, usersets \n" + "or type-bound public access. Each of these types of results is encoded in its own type and not represented as a string.\n" + "\n" + "In cases where a type-bound public access result is returned (e.g. `user:*`), it cannot be inferred that all subjects\n" + "of that type have a relation to the object; it is possible that negations exist and checks should still be queried\n" + - "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.\n" + - "The returned users will not be sorted, and therefore two identical calls may yield different sets of users.*\tListUsers\x82\xd3\xe4\x93\x02\":\x01*\"\x1d/stores/{store_id}/list-usersB\xa1\x01\n" + + "on individual subjects to ensure access to that document.\n" + + "The number of users in the response array are 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.\n" + + "The returned users are not sorted, and therefore two identical calls may yield different sets of users.*\tListUsers\x82\xd3\xe4\x93\x02\":\x01*\"\x1d/stores/{store_id}/list-usersB\xa1\x01\n" + "\x0ecom.openfga.v1B\x13OpenfgaServiceProtoP\x01Z1github.com/openfga/api/proto/openfga/v1;openfgav1\xa2\x02\x03OXX\xaa\x02\n" + "Openfga.V1\xca\x02\n" + "Openfga\\V1\xe2\x02\x16Openfga\\V1\\GPBMetadata\xea\x02\vOpenfga::V1b\x06proto3" From ee03f6b3690e571e45fb84013e8ed2e0d4b276ca Mon Sep 17 00:00:00 2001 From: amanda-vanscoy Date: Fri, 25 Sep 2026 14:53:14 -0400 Subject: [PATCH 4/4] Address comments --- docs/openapiv2/apidocs.swagger.json | 28 +++++++------- docs/openapiv3/apidocs.openapi.json | 28 +++++++------- openfga/v1/openfga_service.proto | 29 ++++++++------- proto/openfga/v1/openfga_service.pb.go | 51 +++++++++++++------------- 4 files changed, 69 insertions(+), 67 deletions(-) diff --git a/docs/openapiv2/apidocs.swagger.json b/docs/openapiv2/apidocs.swagger.json index 5b5685c7..64ee5953 100644 --- a/docs/openapiv2/apidocs.swagger.json +++ b/docs/openapiv2/apidocs.swagger.json @@ -764,8 +764,8 @@ }, "/stores/{store_id}/assertions/{authorization_model_id}": { "get": { - "summary": "Get authorization model ID assertions", - "description": "The ReadAssertions API returns all the assertions stored for a given authorization model id.", + "summary": "Get assertions for a model", + "description": "The ReadAssertions API returns all the assertions stored for a given authorization model ID.", "operationId": "ReadAssertions", "responses": { "200": { @@ -836,7 +836,7 @@ ] }, "put": { - "summary": "Upsert authorization model ID assertions", + "summary": "Upsert assertions for a model", "description": "The WriteAssertions API upserts 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 returns true or false, and optionally a list of contextual tuples.", "operationId": "WriteAssertions", "responses": { @@ -1070,8 +1070,8 @@ }, "/stores/{store_id}/authorization-models/{id}": { "get": { - "summary": "Get an authorization model by version", - "description": "The ReadAuthorizationModel API returns an authorization model by its identifier.\nThe response returns the authorization model for the particular version.\n\n## Example\n\nTo 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 returns:\n```json\n{\n \"authorization_model\":{\n \"id\":\"01G5JAVJ41T49E9TT3SKVS7X1J\",\n \"type_definitions\":[\n {\n \"type\":\"user\"\n },\n {\n \"type\":\"document\",\n \"relations\":{\n \"reader\":{\n \"union\":{\n \"child\":[\n {\n \"this\":{}\n },\n {\n \"computedUserset\":{\n \"object\":\"\",\n \"relation\":\"writer\"\n }\n }\n ]\n }\n },\n \"writer\":{\n \"this\":{}\n }\n }\n }\n ]\n }\n}\n```\nIn the above example, there are 2 types (`user` and `document`). The `document` type has 2 relations (`writer` and `reader`).", + "summary": "Get an authorization model by its ID", + "description": "The response returns the authorization model for the particular ID.\nAuthorization Models in OpenFGA are [immutable](/docs/getting-started/immutable-models), new versions can be created, but existing ones cannot be deleted or modified.\n\n## Example\n\nTo 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 returns:\n```json\n{\n \"authorization_model\":{\n \"id\":\"01G5JAVJ41T49E9TT3SKVS7X1J\",\n \"type_definitions\":[\n {\n \"type\":\"user\"\n },\n {\n \"type\":\"document\",\n \"relations\":{\n \"reader\":{\n \"union\":{\n \"child\":[\n {\n \"this\":{}\n },\n {\n \"computedUserset\":{\n \"object\":\"\",\n \"relation\":\"writer\"\n }\n }\n ]\n }\n },\n \"writer\":{\n \"this\":{}\n }\n }\n }\n ]\n }\n}\n```\nIn the above example, there are 2 types (`user` and `document`). The `document` type has 2 relations (`writer` and `reader`).", "operationId": "ReadAuthorizationModel", "responses": { "200": { @@ -1144,7 +1144,7 @@ }, "/stores/{store_id}/batch-check": { "post": { - "summary": "Check multiple relationships in a single request", + "summary": "Check multiple authorizations in a single request", "description": "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.\n\nAn 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}$`\n\n> **Note:** The maximum number of checks that can be passed in the `BatchCheck` API is configurable using the environment variable: `[OPENFGA_MAX_CHECKS_PER_BATCH_CHECK](https://openfga.dev/docs/getting-started/setup-openfga/configuration#OPENFGA_MAX_CHECKS_PER_BATCH_CHECK)`. If `BatchCheck` is called using the SDK, the SDK can split the batch check requests for you.\n\nFor more details on how `Check` functions, review the docs for `/check`.\n\n### Examples\n\n#### A BatchCheckRequest\n```json\n{\n \"checks\": [\n {\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n \"relation\": \"reader\",\n \"user\": \"user:anne\",\n },\n \"contextual_tuples\": {...}\n \"context\": {}\n \"correlation_id\": \"01JA8PM3QM7VBPGB8KMPK8SBD5\"\n },\n {\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n \"relation\": \"reader\",\n \"user\": \"user:bob\",\n },\n \"contextual_tuples\": {...}\n \"context\": {}\n \"correlation_id\": \"01JA8PMM6A90NV5ET0F28CYSZQ\"\n }\n ]\n}\n```\n\nBelow 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:\n```json\n{\n \"result\": {\n \"01JA8PMM6A90NV5ET0F28CYSZQ\": {\n \"allowed\": false, \n \"error\": {\"message\": \"\"} \n },\n \"01JA8PM3QM7VBPGB8KMPK8SBD5\": {\n \"allowed\": true, \n \"error\": {\"message\": \"\"} \n }\n}\n```\n", "operationId": "BatchCheck", "responses": { @@ -1467,7 +1467,7 @@ }, "/stores/{store_id}/list-objects": { "post": { - "summary": "List all objects with user-centric relationship", + "summary": "List objects a user is related to", "description": "The ListObjects API returns a list of all the objects of the given type that the user has a relation with.\n To arrive at a result, the API uses:\n\n- An [authorization model](/docs/getting-started/configure-model)\n- Explicit tuples written through the Write API\n- Contextual tuples present in the request\n- Implicit tuples that exist by virtue of applying set theory. For example:\n\n`document:2021-budget#viewer@document:2021-budget#viewer`\n\nIn the example the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n\nAn `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID is used.\n\n> **Note:** We recommend you specify authorization model ID for better performance.\n\nYou may also specify `contextual_tuples` that is treated as regular tuples. Each of these tuples may have an associated `condition`.\nYou may also provide a `context` object that is used to evaluate the conditioned tuples in the system.\n\n> **Note:** We recommend you provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.\n\nBy 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.\nThe response contains the related objects in an array in the \"objects\" field of the response and are strings in the object format `:` (e.g. \"document:roadmap\").\n\nThe number of objects in the response array are 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.\nThe objects given are not sorted, and therefore two identical calls can give a given different set of objects.", "operationId": "ListObjects", "responses": { @@ -1619,7 +1619,7 @@ }, "/stores/{store_id}/read": { "post": { - "summary": "Get related tuples", + "summary": "Get stored relationship tuples", "description": "The Read API returns the tuples from a certain store that match a query filter specified in the body of the request. \nThe API doesn't guarantee order by any field. \nIt 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. \nIn the body:\n1. `tuple_key` is optional. If not specified, it returns all tuples in the store.\n2. `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:`).\n3. `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`).\n\n## Examples\n\n### Query for all objects in a type definition\n\nTo query for all objects that `user:bob` has `reader` relationship in the `document` type definition, call read API with body of\n```json\n{\n \"tuple_key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:\"\n }\n}\n```\nThe API returns tuples and a continuation token, similar to:\n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis 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.\nThe continuation token is empty if there are no more tuples to query.\n\n### Query for all stored relationship tuples that have a particular relation and object\n\nTo query for all users that have `reader` relationship with `document:2021-budget`, call read API with body of \n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\",\n \"relation\": \"reader\"\n }\n}\n```\nThe API returns something similar to: \n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis 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 does not return writers such as `user:anne` because it only returns tuples and does not evaluate them.\n\n### Query for all users with all relationships for a particular document\n\nTo query for all users that have any relationship with `document:2021-budget`, call read API with body of \n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n }\n}\n```\nThe API returns something similar to:\n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:anne\",\n \"relation\": \"writer\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-05T13:42:12.356Z\"\n },\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis means that `document:2021-budget` has 1 `reader` (`user:bob`) and 1 `writer` (`user:anne`).\n", "operationId": "Read", "responses": { @@ -2559,7 +2559,7 @@ }, "consistency": { "$ref": "#/definitions/ConsistencyPreference", - "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`." + "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which has the same behavior as `MINIMIZE_LATENCY`." }, "contextual_tuples": { "$ref": "#/definitions/ContextualTupleKeys" @@ -2762,7 +2762,7 @@ }, "consistency": { "$ref": "#/definitions/ConsistencyPreference", - "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`." + "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which has the same behavior as `MINIMIZE_LATENCY`." } }, "required": [ @@ -2858,7 +2858,7 @@ }, "consistency": { "$ref": "#/definitions/ConsistencyPreference", - "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`." + "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which has the same behavior as `MINIMIZE_LATENCY`." } }, "required": [ @@ -2953,7 +2953,7 @@ "NULL_VALUE" ], "default": "NULL_VALUE", - "description": "Represents a JSON `null`.\n\n`NullValue` is a sentinel, using an enum with only one value to represent\nthe null value for the `Value` type union.\n\nA field of type `NullValue` with any value other than `0` is considered\ninvalid. Most ProtoJSON serializers will emit a Value with a `null_value` set\nas a JSON `null` regardless of the integer value, and so will round trip to\na `0` value.\n\n - NULL_VALUE: Null value." + "description": "`NullValue` is a singleton enumeration to represent the null value for the\n`Value` type union.\n\nThe JSON representation for `NullValue` is JSON `null`.\n\n - NULL_VALUE: Null value." }, "Object": { "type": "object", @@ -3100,7 +3100,7 @@ }, "consistency": { "$ref": "#/definitions/ConsistencyPreference", - "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`." + "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which has the same behavior as `MINIMIZE_LATENCY`." } } }, @@ -3394,7 +3394,7 @@ }, "consistency": { "$ref": "#/definitions/ConsistencyPreference", - "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`." + "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which has the same behavior as `MINIMIZE_LATENCY`." } }, "required": [ diff --git a/docs/openapiv3/apidocs.openapi.json b/docs/openapiv3/apidocs.openapi.json index 0d730983..de1ca30f 100644 --- a/docs/openapiv3/apidocs.openapi.json +++ b/docs/openapiv3/apidocs.openapi.json @@ -776,7 +776,7 @@ "$ref": "#/components/schemas/ConsistencyPreference" }, { - "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`." + "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which has the same behavior as `MINIMIZE_LATENCY`." } ] }, @@ -967,7 +967,7 @@ "$ref": "#/components/schemas/ConsistencyPreference" }, { - "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`." + "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which has the same behavior as `MINIMIZE_LATENCY`." } ] }, @@ -1057,7 +1057,7 @@ "$ref": "#/components/schemas/ConsistencyPreference" }, { - "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`." + "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which has the same behavior as `MINIMIZE_LATENCY`." } ] }, @@ -1220,7 +1220,7 @@ }, "NullValue": { "default": "NULL_VALUE", - "description": "Represents a JSON `null`.\n\n`NullValue` is a sentinel, using an enum with only one value to represent\nthe null value for the `Value` type union.\n\nA field of type `NullValue` with any value other than `0` is considered\ninvalid. Most ProtoJSON serializers will emit a Value with a `null_value` set\nas a JSON `null` regardless of the integer value, and so will round trip to\na `0` value.\n\n - NULL_VALUE: Null value.", + "description": "`NullValue` is a singleton enumeration to represent the null value for the\n`Value` type union.\n\nThe JSON representation for `NullValue` is JSON `null`.\n\n - NULL_VALUE: Null value.", "enum": [ "NULL_VALUE" ], @@ -1372,7 +1372,7 @@ "$ref": "#/components/schemas/ConsistencyPreference" }, { - "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`." + "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which has the same behavior as `MINIMIZE_LATENCY`." } ] }, @@ -1707,7 +1707,7 @@ "$ref": "#/components/schemas/ConsistencyPreference" }, { - "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`." + "description": "Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which has the same behavior as `MINIMIZE_LATENCY`." } ] }, @@ -3534,7 +3534,7 @@ }, "/stores/{store_id}/assertions/{authorization_model_id}": { "get": { - "description": "The ReadAssertions API returns all the assertions stored for a given authorization model id.", + "description": "The ReadAssertions API returns all the assertions stored for a given authorization model ID.", "operationId": "ReadAssertions", "parameters": [ { @@ -3636,7 +3636,7 @@ "description": "Request failed due to internal server error." } }, - "summary": "Get authorization model ID assertions", + "summary": "Get assertions for a model", "tags": [ "Assertions" ] @@ -3747,7 +3747,7 @@ "description": "Request failed due to internal server error." } }, - "summary": "Upsert authorization model ID assertions", + "summary": "Upsert assertions for a model", "tags": [ "Assertions" ] @@ -3984,7 +3984,7 @@ }, "/stores/{store_id}/authorization-models/{id}": { "get": { - "description": "The ReadAuthorizationModel API returns an authorization model by its identifier.\nThe response returns the authorization model for the particular version.\n\n## Example\n\nTo 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 returns:\n```json\n{\n \"authorization_model\":{\n \"id\":\"01G5JAVJ41T49E9TT3SKVS7X1J\",\n \"type_definitions\":[\n {\n \"type\":\"user\"\n },\n {\n \"type\":\"document\",\n \"relations\":{\n \"reader\":{\n \"union\":{\n \"child\":[\n {\n \"this\":{}\n },\n {\n \"computedUserset\":{\n \"object\":\"\",\n \"relation\":\"writer\"\n }\n }\n ]\n }\n },\n \"writer\":{\n \"this\":{}\n }\n }\n }\n ]\n }\n}\n```\nIn the above example, there are 2 types (`user` and `document`). The `document` type has 2 relations (`writer` and `reader`).", + "description": "The response returns the authorization model for the particular ID.\nAuthorization Models in OpenFGA are [immutable](/docs/getting-started/immutable-models), new versions can be created, but existing ones cannot be deleted or modified.\n\n## Example\n\nTo 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 returns:\n```json\n{\n \"authorization_model\":{\n \"id\":\"01G5JAVJ41T49E9TT3SKVS7X1J\",\n \"type_definitions\":[\n {\n \"type\":\"user\"\n },\n {\n \"type\":\"document\",\n \"relations\":{\n \"reader\":{\n \"union\":{\n \"child\":[\n {\n \"this\":{}\n },\n {\n \"computedUserset\":{\n \"object\":\"\",\n \"relation\":\"writer\"\n }\n }\n ]\n }\n },\n \"writer\":{\n \"this\":{}\n }\n }\n }\n ]\n }\n}\n```\nIn the above example, there are 2 types (`user` and `document`). The `document` type has 2 relations (`writer` and `reader`).", "operationId": "ReadAuthorizationModel", "parameters": [ { @@ -4086,7 +4086,7 @@ "description": "Request failed due to internal server error." } }, - "summary": "Get an authorization model by version", + "summary": "Get an authorization model by its ID", "tags": [ "Authorization Models" ] @@ -4198,7 +4198,7 @@ "description": "Request failed due to internal server error." } }, - "summary": "Check multiple relationships in a single request", + "summary": "Check multiple authorizations in a single request", "tags": [ "Relationship Queries" ] @@ -4671,7 +4671,7 @@ "description": "Request failed due to internal server error." } }, - "summary": "List all objects with user-centric relationship", + "summary": "List objects a user is related to", "tags": [ "Relationship Queries" ] @@ -4895,7 +4895,7 @@ "description": "Request failed due to internal server error." } }, - "summary": "Get related tuples", + "summary": "Get stored relationship tuples", "tags": [ "Relationship Tuples" ] diff --git a/openfga/v1/openfga_service.proto b/openfga/v1/openfga_service.proto index c2130811..9abc2f31 100644 --- a/openfga/v1/openfga_service.proto +++ b/openfga/v1/openfga_service.proto @@ -23,7 +23,7 @@ service OpenFGAService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - summary: "Get related tuples" + summary: "Get stored relationship tuples" tags: ["Relationship Tuples"] operation_id: "Read" description: @@ -346,7 +346,7 @@ service OpenFGAService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - summary: "Check multiple relationships in a single request" + summary: "Check multiple authorizations in a single request" tags: ["Relationship Queries"] operation_id: "BatchCheck" description: @@ -632,12 +632,13 @@ service OpenFGAService { option (google.api.http) = {get: "/stores/{store_id}/authorization-models/{id}"}; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - summary: "Get an authorization model by version" + summary: "Get an authorization model by its ID" tags: ["Authorization Models"] operation_id: "ReadAuthorizationModel" description: - "The ReadAuthorizationModel API returns an authorization model by its identifier.\n" - "The response returns the authorization model for the particular version.\n\n" + "The response returns the authorization model for the particular ID.\n" + "Authorization Models in OpenFGA are [immutable](/docs/getting-started/immutable-models), " + "new versions can be created, but existing ones cannot be deleted or modified.\n\n" "## Example\n\n" "To retrieve the authorization model with ID `01G5JAVJ41T49E9TT3SKVS7X1J` for the store, " "call the `GET` authorization-models by ID API with `01G5JAVJ41T49E9TT3SKVS7X1J` as the " @@ -757,7 +758,7 @@ service OpenFGAService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - summary: "Upsert authorization model ID assertions" + summary: "Upsert assertions for a model" tags: ["Assertions"] operation_id: "WriteAssertions" description: @@ -781,10 +782,10 @@ service OpenFGAService { option (google.api.http) = {get: "/stores/{store_id}/assertions/{authorization_model_id}"}; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - summary: "Get authorization model ID assertions" + summary: "Get assertions for a model" tags: ["Assertions"] operation_id: "ReadAssertions" - description: "The ReadAssertions API returns all the assertions stored for a given authorization model id." + description: "The ReadAssertions API returns all the assertions stored for a given authorization model ID." }; } @@ -923,7 +924,7 @@ service OpenFGAService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - summary: "List all objects with user-centric relationship" + summary: "List objects a user is related to" tags: ["Relationship Queries"] operation_id: "ListObjects" description: @@ -1034,7 +1035,7 @@ message ListObjectsRequest { // in the query evaluation. google.protobuf.Struct context = 7; - // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`. + // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which has the same behavior as `MINIMIZE_LATENCY`. ConsistencyPreference consistency = 8 [(validate.rules).enum.defined_only = true]; } @@ -1101,7 +1102,7 @@ message ListUsersRequest { // in the query evaluation. google.protobuf.Struct context = 7; - // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`. + // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which has the same behavior as `MINIMIZE_LATENCY`. ConsistencyPreference consistency = 8 [(validate.rules).enum.defined_only = true]; } @@ -1161,7 +1162,7 @@ message StreamedListObjectsRequest { // in the query evaluation. google.protobuf.Struct context = 7; - // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`. + // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which has the same behavior as `MINIMIZE_LATENCY`. ConsistencyPreference consistency = 8 [(validate.rules).enum.defined_only = true]; } @@ -1208,7 +1209,7 @@ message ReadRequest { (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {example: "\"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\""} ]; - // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`. + // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which has the same behavior as `MINIMIZE_LATENCY`. ConsistencyPreference consistency = 5 [(validate.rules).enum.defined_only = true]; } @@ -1497,7 +1498,7 @@ message ExpandRequest { (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {example: "\"01G5JAVJ41T49E9TT3SKVS7X1J\""} ]; - // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`. + // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which has the same behavior as `MINIMIZE_LATENCY`. ConsistencyPreference consistency = 4 [(validate.rules).enum.defined_only = true]; openfga.v1.ContextualTupleKeys contextual_tuples = 5 [json_name = "contextual_tuples"]; diff --git a/proto/openfga/v1/openfga_service.pb.go b/proto/openfga/v1/openfga_service.pb.go index 5a7f53fd..54de5016 100644 --- a/proto/openfga/v1/openfga_service.pb.go +++ b/proto/openfga/v1/openfga_service.pb.go @@ -39,7 +39,7 @@ type ListObjectsRequest struct { // Additional request context that are used to evaluate any ABAC conditions encountered // in the query evaluation. Context *structpb.Struct `protobuf:"bytes,7,opt,name=context,proto3" json:"context,omitempty"` - // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`. + // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which has the same behavior as `MINIMIZE_LATENCY`. Consistency ConsistencyPreference `protobuf:"varint,8,opt,name=consistency,proto3,enum=openfga.v1.ConsistencyPreference" json:"consistency,omitempty"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache @@ -186,7 +186,7 @@ type ListUsersRequest struct { // Additional request context used to evaluate any ABAC conditions encountered // in the query evaluation. Context *structpb.Struct `protobuf:"bytes,7,opt,name=context,proto3" json:"context,omitempty"` - // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`. + // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which has the same behavior as `MINIMIZE_LATENCY`. Consistency ConsistencyPreference `protobuf:"varint,8,opt,name=consistency,proto3,enum=openfga.v1.ConsistencyPreference" json:"consistency,omitempty"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache @@ -333,7 +333,7 @@ type StreamedListObjectsRequest struct { // Additional request context used to evaluate any ABAC conditions encountered // in the query evaluation. Context *structpb.Struct `protobuf:"bytes,7,opt,name=context,proto3" json:"context,omitempty"` - // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`. + // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which has the same behavior as `MINIMIZE_LATENCY`. Consistency ConsistencyPreference `protobuf:"varint,8,opt,name=consistency,proto3,enum=openfga.v1.ConsistencyPreference" json:"consistency,omitempty"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache @@ -476,7 +476,7 @@ type ReadRequest struct { TupleKey *ReadRequestTupleKey `protobuf:"bytes,2,opt,name=tuple_key,proto3" json:"tuple_key,omitempty"` PageSize *wrapperspb.Int32Value `protobuf:"bytes,3,opt,name=page_size,proto3" json:"page_size,omitempty"` ContinuationToken string `protobuf:"bytes,4,opt,name=continuation_token,proto3" json:"continuation_token,omitempty"` - // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`. + // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which has the same behavior as `MINIMIZE_LATENCY`. Consistency ConsistencyPreference `protobuf:"varint,5,opt,name=consistency,proto3,enum=openfga.v1.ConsistencyPreference" json:"consistency,omitempty"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache @@ -1433,7 +1433,7 @@ type ExpandRequest struct { StoreId string `protobuf:"bytes,1,opt,name=store_id,proto3" json:"store_id,omitempty"` TupleKey *ExpandRequestTupleKey `protobuf:"bytes,2,opt,name=tuple_key,proto3" json:"tuple_key,omitempty"` AuthorizationModelId string `protobuf:"bytes,3,opt,name=authorization_model_id,proto3" json:"authorization_model_id,omitempty"` - // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which have the same behavior as `MINIMIZE_LATENCY`. + // Controls the consistency preference for this request. Default value is `UNSPECIFIED`, which has the same behavior as `MINIMIZE_LATENCY`. Consistency ConsistencyPreference `protobuf:"varint,4,opt,name=consistency,proto3,enum=openfga.v1.ConsistencyPreference" json:"consistency,omitempty"` ContextualTuples *ContextualTupleKeys `protobuf:"bytes,5,opt,name=contextual_tuples,proto3" json:"contextual_tuples,omitempty"` unknownFields protoimpl.UnknownFields @@ -3207,10 +3207,10 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + "Assertions\x12:\n" + "\n" + "assertions\x18\x01 \x03(\v2\x15.openfga.v1.AssertionB\x03\xe0A\x02R\n" + - "assertions2\x92\xee\x01\n" + - "\x0eOpenFGAService\x12\x84\x1d\n" + - "\x04Read\x12\x17.openfga.v1.ReadRequest\x1a\x18.openfga.v1.ReadResponse\"\xc8\x1c\x92A\xa2\x1c\n" + - "\x13Relationship Tuples\x12\x12Get related tuples\x1a\xf0\x1bThe Read API returns the tuples from a certain store that match a query filter specified in the body of the request. \n" + + "assertions2\xcb\xee\x01\n" + + "\x0eOpenFGAService\x12\x90\x1d\n" + + "\x04Read\x12\x17.openfga.v1.ReadRequest\x1a\x18.openfga.v1.ReadResponse\"\xd4\x1c\x92A\xae\x1c\n" + + "\x13Relationship Tuples\x12\x1eGet stored relationship tuples\x1a\xf0\x1bThe Read API returns the tuples from a certain store that match a query filter specified in the body of the request. \n" + "The API doesn't guarantee order by any field. \n" + "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. \n" + "In the body:\n" + @@ -3510,10 +3510,10 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + " \"consistency\": \"HIGHER_CONSISTENCY\"\n" + "}\n" + "```\n" + - "*\x05Check\x82\xd3\xe4\x93\x02\x1d:\x01*\"\x18/stores/{store_id}/check\x12\x95\x13\n" + + "*\x05Check\x82\xd3\xe4\x93\x02\x1d:\x01*\"\x18/stores/{store_id}/check\x12\x96\x13\n" + "\n" + - "BatchCheck\x12\x1d.openfga.v1.BatchCheckRequest\x1a\x1e.openfga.v1.BatchCheckResponse\"\xc7\x12\x92A\x9a\x12\n" + - "\x14Relationship Queries\x120Check multiple relationships in a single request\x1a\xc3\x11The `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.\n" + + "BatchCheck\x12\x1d.openfga.v1.BatchCheckRequest\x1a\x1e.openfga.v1.BatchCheckResponse\"\xc8\x12\x92A\x9b\x12\n" + + "\x14Relationship Queries\x121Check multiple authorizations in a single request\x1a\xc3\x11The `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.\n" + "\n" + "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}$`\n" + "\n" + @@ -3771,11 +3771,12 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + " \"continuation_token\": \"\"\n" + "}\n" + "```\n" + - "*\x17ReadAuthorizationModels\x82\xd3\xe4\x93\x02)\x12'/stores/{store_id}/authorization-models\x12\xef\n" + + "*\x17ReadAuthorizationModels\x82\xd3\xe4\x93\x02)\x12'/stores/{store_id}/authorization-models\x12\xbf\v\n" + + "\x16ReadAuthorizationModel\x12).openfga.v1.ReadAuthorizationModelRequest\x1a*.openfga.v1.ReadAuthorizationModelResponse\"\xcd\n" + + "\x92A\x95\n" + "\n" + - "\x16ReadAuthorizationModel\x12).openfga.v1.ReadAuthorizationModelRequest\x1a*.openfga.v1.ReadAuthorizationModelResponse\"\xfd\t\x92A\xc5\t\n" + - "\x14Authorization Models\x12%Get an authorization model by version\x1a\xed\bThe ReadAuthorizationModel API returns an authorization model by its identifier.\n" + - "The response returns the authorization model for the particular version.\n" + + "\x14Authorization Models\x12$Get an authorization model by its ID\x1a\xbe\tThe response returns the authorization model for the particular ID.\n" + + "Authorization Models in OpenFGA are [immutable](/docs/getting-started/immutable-models), new versions can be created, but existing ones cannot be deleted or modified.\n" + "\n" + "## Example\n" + "\n" + @@ -3864,16 +3865,16 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + "*\x17WriteAuthorizationModelJP\n" + "\x03201\x12I\n" + "\x16A successful response.\x12/\n" + - "-\x1a+.openfga.v1.WriteAuthorizationModelResponse\x82\xd3\xe4\x93\x02,:\x01*\"'/stores/{store_id}/authorization-models\x12\xe0\x04\n" + - "\x0fWriteAssertions\x12\".openfga.v1.WriteAssertionsRequest\x1a#.openfga.v1.WriteAssertionsResponse\"\x83\x04\x92A\xbe\x03\n" + + "-\x1a+.openfga.v1.WriteAuthorizationModelResponse\x82\xd3\xe4\x93\x02,:\x01*\"'/stores/{store_id}/authorization-models\x12\xd5\x04\n" + + "\x0fWriteAssertions\x12\".openfga.v1.WriteAssertionsRequest\x1a#.openfga.v1.WriteAssertionsResponse\"\xf8\x03\x92A\xb3\x03\n" + "\n" + - "Assertions\x12(Upsert authorization model ID assertions\x1a\xaa\x02The WriteAssertions API upserts 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 returns true or false, and optionally a list of contextual tuples.*\x0fWriteAssertionsJH\n" + + "Assertions\x12\x1dUpsert assertions for a model\x1a\xaa\x02The WriteAssertions API upserts 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 returns true or false, and optionally a list of contextual tuples.*\x0fWriteAssertionsJH\n" + "\x03204\x12A\n" + "\x16A successful response.\x12'\n" + - "%\x1a#.openfga.v1.WriteAssertionsResponse\x82\xd3\xe4\x93\x02;:\x01*\x1a6/stores/{store_id}/assertions/{authorization_model_id}\x12\xbd\x02\n" + - "\x0eReadAssertions\x12!.openfga.v1.ReadAssertionsRequest\x1a\".openfga.v1.ReadAssertionsResponse\"\xe3\x01\x92A\xa1\x01\n" + + "%\x1a#.openfga.v1.WriteAssertionsResponse\x82\xd3\xe4\x93\x02;:\x01*\x1a6/stores/{store_id}/assertions/{authorization_model_id}\x12\xb2\x02\n" + + "\x0eReadAssertions\x12!.openfga.v1.ReadAssertionsRequest\x1a\".openfga.v1.ReadAssertionsResponse\"\xd8\x01\x92A\x96\x01\n" + "\n" + - "Assertions\x12%Get authorization model ID assertions\x1a\\The ReadAssertions API returns all the assertions stored for a given authorization model id.*\x0eReadAssertions\x82\xd3\xe4\x93\x028\x126/stores/{store_id}/assertions/{authorization_model_id}\x12\xc1\a\n" + + "Assertions\x12\x1aGet assertions for a model\x1a\\The ReadAssertions API returns all the assertions stored for a given authorization model ID.*\x0eReadAssertions\x82\xd3\xe4\x93\x028\x126/stores/{store_id}/assertions/{authorization_model_id}\x12\xc1\a\n" + "\vReadChanges\x12\x1e.openfga.v1.ReadChangesRequest\x1a\x1f.openfga.v1.ReadChangesResponse\"\xf0\x06\x92A\xca\x06\n" + "\x13Relationship Tuples\x12\x15Get all tuple changes\x1a\x8e\x06The ReadChanges API returns a paginated list of tuple changes (additions and deletions) that occurred in a given store, sorted by ascending time. The response includes 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 is returned in order for it to be used when new changes are recorded.\n" + "\n" + @@ -3909,9 +3910,9 @@ const file_openfga_v1_openfga_service_proto_rawDesc = "" + "\x14Relationship Queries\x12+Stream all objects with a user relationship\x1a\xdb\x02The Streamed ListObjects API is very similar to the the ListObjects API, with two differences: \n" + "1. Instead of collecting all objects before returning a response, it streams them to the client as they are collected. \n" + "2. The number of results returned is only limited by the execution timeout specified in the flag `OPENFGA_LIST_OBJECTS_DEADLINE`. \n" + - "*\x13StreamedListObjects\x82\xd3\xe4\x93\x02-:\x01*\"(/stores/{store_id}/streamed-list-objects0\x01\x12\xeb\x11\n" + - "\vListObjects\x12\x1e.openfga.v1.ListObjectsRequest\x1a\x1f.openfga.v1.ListObjectsResponse\"\x9a\x11\x92A\xec\x10\n" + - "\x14Relationship Queries\x12/List all objects with user-centric relationship\x1a\x95\x10The ListObjects API returns a list of all the objects of the given type that the user has a relation with.\n" + + "*\x13StreamedListObjects\x82\xd3\xe4\x93\x02-:\x01*\"(/stores/{store_id}/streamed-list-objects0\x01\x12\xdd\x11\n" + + "\vListObjects\x12\x1e.openfga.v1.ListObjectsRequest\x1a\x1f.openfga.v1.ListObjectsResponse\"\x8c\x11\x92A\xde\x10\n" + + "\x14Relationship Queries\x12!List objects a user is related to\x1a\x95\x10The ListObjects API returns a list of all the objects of the given type that the user has a relation with.\n" + " To arrive at a result, the API uses:\n" + "\n" + "- An [authorization model](/docs/getting-started/configure-model)\n" +