diff --git a/docs/openapiv3/apidocs.swagger.json b/docs/openapiv3/apidocs.swagger.json new file mode 100644 index 00000000..738bb1db --- /dev/null +++ b/docs/openapiv3/apidocs.swagger.json @@ -0,0 +1,3383 @@ +{ + "openapi": "3.0.0", + "info": { + "contact": { + "email": "community@openfga.dev", + "name": "OpenFGA", + "url": "https://openfga.dev" + }, + "description": "A high performance and flexible authorization/permission engine built for developers and inspired by Google Zanzibar.", + "license": { + "name": "Apache-2.0", + "url": "https://github.com/openfga/openfga/blob/main/LICENSE" + }, + "title": "OpenFGA", + "version": "1.x" + }, + "servers": [], + "paths": { + "/stores": { + "get": { + "parameters": [ + { + "in": "query", + "name": "page_size", + "required": false, + "schema": { + "format": "int32", + "type": "integer" + } + }, + { + "in": "query", + "name": "continuation_token", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListStoresResponse" + } + } + }, + "description": "A successful response." + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ValidationErrorMessageResponse" + } + } + }, + "description": "Request failed due to invalid input." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthenticatedResponse" + } + } + }, + "description": "Not authenticated." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PathUnknownErrorMessageResponse" + } + } + }, + "description": "Request failed due to incorrect path." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AbortedMessageResponse" + } + } + }, + "description": "Request was aborted due a transaction conflict." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnprocessableContentMessageResponse" + } + } + }, + "description": "Request timed out due to excessive request throttling." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InternalErrorMessageResponse" + } + } + }, + "description": "Request failed due to internal server error." + } + }, + "tags": [ + "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", + "operationId": "ListStores", + "summary": "List all stores" + }, + "post": { + "responses": { + "201": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateStoreResponse" + } + } + }, + "description": "A successful response." + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ValidationErrorMessageResponse" + } + } + }, + "description": "Request failed due to invalid input." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthenticatedResponse" + } + } + }, + "description": "Not authenticated." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PathUnknownErrorMessageResponse" + } + } + }, + "description": "Request failed due to incorrect path." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AbortedMessageResponse" + } + } + }, + "description": "Request was aborted due a transaction conflict." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnprocessableContentMessageResponse" + } + } + }, + "description": "Request timed out due to excessive request throttling." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InternalErrorMessageResponse" + } + } + }, + "description": "Request failed due to internal server error." + } + }, + "tags": [ + "Stores" + ], + "description": "Create a unique OpenFGA store which will be used to store authorization models and relationship tuples.", + "operationId": "CreateStore", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateStoreRequest" + } + } + }, + "required": true + }, + "summary": "Create a store" + } + }, + "/stores/{store_id}": { + "delete": { + "parameters": [ + { + "in": "path", + "name": "store_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "A successful response." + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ValidationErrorMessageResponse" + } + } + }, + "description": "Request failed due to invalid input." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthenticatedResponse" + } + } + }, + "description": "Not authenticated." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PathUnknownErrorMessageResponse" + } + } + }, + "description": "Request failed due to incorrect path." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AbortedMessageResponse" + } + } + }, + "description": "Request was aborted due a transaction conflict." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnprocessableContentMessageResponse" + } + } + }, + "description": "Request timed out due to excessive request throttling." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InternalErrorMessageResponse" + } + } + }, + "description": "Request failed due to internal server error." + } + }, + "tags": [ + "Stores" + ], + "description": "Delete an OpenFGA store. This does not delete the data associated with the store, like tuples or authorization models.", + "operationId": "DeleteStore", + "summary": "Delete a store" + }, + "get": { + "parameters": [ + { + "in": "path", + "name": "store_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetStoreResponse" + } + } + }, + "description": "A successful response." + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ValidationErrorMessageResponse" + } + } + }, + "description": "Request failed due to invalid input." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthenticatedResponse" + } + } + }, + "description": "Not authenticated." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PathUnknownErrorMessageResponse" + } + } + }, + "description": "Request failed due to incorrect path." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AbortedMessageResponse" + } + } + }, + "description": "Request was aborted due a transaction conflict." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnprocessableContentMessageResponse" + } + } + }, + "description": "Request timed out due to excessive request throttling." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InternalErrorMessageResponse" + } + } + }, + "description": "Request failed due to internal server error." + } + }, + "tags": [ + "Stores" + ], + "description": "Returns an OpenFGA store by its identifier", + "operationId": "GetStore", + "summary": "Get a store" + } + }, + "/stores/{store_id}/assertions/{authorization_model_id}": { + "get": { + "parameters": [ + { + "in": "path", + "name": "store_id", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "path", + "name": "authorization_model_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReadAssertionsResponse" + } + } + }, + "description": "A successful response." + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ValidationErrorMessageResponse" + } + } + }, + "description": "Request failed due to invalid input." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthenticatedResponse" + } + } + }, + "description": "Not authenticated." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PathUnknownErrorMessageResponse" + } + } + }, + "description": "Request failed due to incorrect path." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AbortedMessageResponse" + } + } + }, + "description": "Request was aborted due a transaction conflict." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnprocessableContentMessageResponse" + } + } + }, + "description": "Request timed out due to excessive request throttling." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InternalErrorMessageResponse" + } + } + }, + "description": "Request failed due to internal server error." + } + }, + "tags": [ + "Assertions" + ], + "description": "The ReadAssertions API will return, for a given authorization model id, all the assertions stored for it. ", + "operationId": "ReadAssertions", + "summary": "Read assertions for an authorization model ID" + }, + "put": { + "parameters": [ + { + "in": "path", + "name": "store_id", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "path", + "name": "authorization_model_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "A successful response." + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ValidationErrorMessageResponse" + } + } + }, + "description": "Request failed due to invalid input." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthenticatedResponse" + } + } + }, + "description": "Not authenticated." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PathUnknownErrorMessageResponse" + } + } + }, + "description": "Request failed due to incorrect path." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AbortedMessageResponse" + } + } + }, + "description": "Request was aborted due a transaction conflict." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnprocessableContentMessageResponse" + } + } + }, + "description": "Request timed out due to excessive request throttling." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InternalErrorMessageResponse" + } + } + }, + "description": "Request failed due to internal server error." + } + }, + "tags": [ + "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", + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "assertions": { + "items": { + "$ref": "#/components/schemas/Assertion", + "maximum": 100, + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "assertions" + ], + "type": "object" + } + } + }, + "required": true + }, + "summary": "Upsert assertions for an authorization model ID" + } + }, + "/stores/{store_id}/authorization-models": { + "get": { + "parameters": [ + { + "in": "path", + "name": "store_id", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "page_size", + "required": false, + "schema": { + "format": "int32", + "type": "integer" + } + }, + { + "in": "query", + "name": "continuation_token", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReadAuthorizationModelsResponse" + } + } + }, + "description": "A successful response." + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ValidationErrorMessageResponse" + } + } + }, + "description": "Request failed due to invalid input." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthenticatedResponse" + } + } + }, + "description": "Not authenticated." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PathUnknownErrorMessageResponse" + } + } + }, + "description": "Request failed due to incorrect path." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AbortedMessageResponse" + } + } + }, + "description": "Request was aborted due a transaction conflict." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnprocessableContentMessageResponse" + } + } + }, + "description": "Request timed out due to excessive request throttling." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InternalErrorMessageResponse" + } + } + }, + "description": "Request failed due to internal server error." + } + }, + "tags": [ + "Authorization Models" + ], + "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", + "operationId": "ReadAuthorizationModels", + "summary": "Return all the authorization models for a particular store" + }, + "post": { + "parameters": [ + { + "in": "path", + "name": "store_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "201": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WriteAuthorizationModelResponse" + } + } + }, + "description": "A successful response." + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ValidationErrorMessageResponse" + } + } + }, + "description": "Request failed due to invalid input." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthenticatedResponse" + } + } + }, + "description": "Not authenticated." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PathUnknownErrorMessageResponse" + } + } + }, + "description": "Request failed due to incorrect path." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AbortedMessageResponse" + } + } + }, + "description": "Request was aborted due a transaction conflict." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnprocessableContentMessageResponse" + } + } + }, + "description": "Request timed out due to excessive request throttling." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InternalErrorMessageResponse" + } + } + }, + "description": "Request failed due to internal server error." + } + }, + "tags": [ + "Authorization Models" + ], + "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", + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "conditions": { + "additionalProperties": { + "$ref": "#/components/schemas/Condition" + }, + "type": "object" + }, + "schema_version": { + "type": "string" + }, + "type_definitions": { + "items": { + "$ref": "#/components/schemas/TypeDefinition", + "minimum": 1, + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "type_definitions", + "schema_version" + ], + "type": "object" + } + } + }, + "required": true + }, + "summary": "Create a new authorization model" + } + }, + "/stores/{store_id}/authorization-models/{id}": { + "get": { + "parameters": [ + { + "in": "path", + "name": "store_id", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReadAuthorizationModelResponse" + } + } + }, + "description": "A successful response." + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ValidationErrorMessageResponse" + } + } + }, + "description": "Request failed due to invalid input." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthenticatedResponse" + } + } + }, + "description": "Not authenticated." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PathUnknownErrorMessageResponse" + } + } + }, + "description": "Request failed due to incorrect path." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AbortedMessageResponse" + } + } + }, + "description": "Request was aborted due a transaction conflict." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnprocessableContentMessageResponse" + } + } + }, + "description": "Request timed out due to excessive request throttling." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InternalErrorMessageResponse" + } + } + }, + "description": "Request failed due to internal server error." + } + }, + "tags": [ + "Authorization Models" + ], + "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", + "summary": "Return a particular version of an authorization model" + } + }, + "/stores/{store_id}/changes": { + "get": { + "parameters": [ + { + "in": "path", + "name": "store_id", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "type", + "required": false, + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "page_size", + "required": false, + "schema": { + "format": "int32", + "type": "integer" + } + }, + { + "in": "query", + "name": "continuation_token", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReadChangesResponse" + } + } + }, + "description": "A successful response." + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ValidationErrorMessageResponse" + } + } + }, + "description": "Request failed due to invalid input." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthenticatedResponse" + } + } + }, + "description": "Not authenticated." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PathUnknownErrorMessageResponse" + } + } + }, + "description": "Request failed due to incorrect path." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AbortedMessageResponse" + } + } + }, + "description": "Request was aborted due a transaction conflict." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnprocessableContentMessageResponse" + } + } + }, + "description": "Request timed out due to excessive request throttling." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InternalErrorMessageResponse" + } + } + }, + "description": "Request failed due to internal server error." + } + }, + "tags": [ + "Relationship Tuples" + ], + "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", + "summary": "Return a list of all the tuple changes" + } + }, + "/stores/{store_id}/check": { + "post": { + "parameters": [ + { + "in": "path", + "name": "store_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CheckResponse" + } + } + }, + "description": "A successful response." + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ValidationErrorMessageResponse" + } + } + }, + "description": "Request failed due to invalid input." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthenticatedResponse" + } + } + }, + "description": "Not authenticated." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PathUnknownErrorMessageResponse" + } + } + }, + "description": "Request failed due to incorrect path." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AbortedMessageResponse" + } + } + }, + "description": "Request was aborted due a transaction conflict." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnprocessableContentMessageResponse" + } + } + }, + "description": "Request timed out due to excessive request throttling." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InternalErrorMessageResponse" + } + } + }, + "description": "Request failed due to internal server error." + } + }, + "tags": [ + "Relationship Queries" + ], + "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", + "operationId": "Check", + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "authorization_model_id": { + "example": "01G5JAVJ41T49E9TT3SKVS7X1J", + "type": "string" + }, + "consistency": { + "$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." + }, + "context": { + "description": "Additional request context that will be used to evaluate any ABAC conditions encountered\nin the query evaluation.", + "type": "object" + }, + "contextual_tuples": { + "$ref": "#/components/schemas/ContextualTupleKeys" + }, + "trace": { + "description": "Defaults to false. Making it true has performance implications.", + "example": false, + "readOnly": true, + "type": "boolean" + }, + "tuple_key": { + "$ref": "#/components/schemas/CheckRequestTupleKey" + } + }, + "required": [ + "tuple_key" + ], + "type": "object" + } + } + }, + "required": true + }, + "summary": "Check whether a user is authorized to access an object" + } + }, + "/stores/{store_id}/expand": { + "post": { + "parameters": [ + { + "in": "path", + "name": "store_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExpandResponse" + } + } + }, + "description": "A successful response." + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ValidationErrorMessageResponse" + } + } + }, + "description": "Request failed due to invalid input." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthenticatedResponse" + } + } + }, + "description": "Not authenticated." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PathUnknownErrorMessageResponse" + } + } + }, + "description": "Request failed due to incorrect path." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AbortedMessageResponse" + } + } + }, + "description": "Request was aborted due a transaction conflict." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnprocessableContentMessageResponse" + } + } + }, + "description": "Request timed out due to excessive request throttling." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InternalErrorMessageResponse" + } + } + }, + "description": "Request failed due to internal server error." + } + }, + "tags": [ + "Relationship Queries" + ], + "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.\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`.", + "operationId": "Expand", + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "authorization_model_id": { + "example": "01G5JAVJ41T49E9TT3SKVS7X1J", + "type": "string" + }, + "consistency": { + "$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." + }, + "tuple_key": { + "$ref": "#/components/schemas/ExpandRequestTupleKey" + } + }, + "required": [ + "tuple_key" + ], + "type": "object" + } + } + }, + "required": true + }, + "summary": "Expand all relationships in userset tree format, and following userset rewrite rules. Useful to reason about and debug a certain relationship" + } + }, + "/stores/{store_id}/list-objects": { + "post": { + "parameters": [ + { + "in": "path", + "name": "store_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListObjectsResponse" + } + } + }, + "description": "A successful response." + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ValidationErrorMessageResponse" + } + } + }, + "description": "Request failed due to invalid input." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthenticatedResponse" + } + } + }, + "description": "Not authenticated." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PathUnknownErrorMessageResponse" + } + } + }, + "description": "Request failed due to incorrect path." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AbortedMessageResponse" + } + } + }, + "description": "Request was aborted due a transaction conflict." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnprocessableContentMessageResponse" + } + } + }, + "description": "Request timed out due to excessive request throttling." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InternalErrorMessageResponse" + } + } + }, + "description": "Request failed due to internal server error." + } + }, + "tags": [ + "Relationship Queries" + ], + "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.", + "operationId": "ListObjects", + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "authorization_model_id": { + "example": "01G5JAVJ41T49E9TT3SKVS7X1J", + "type": "string" + }, + "consistency": { + "$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." + }, + "context": { + "description": "Additional request context that will be used to evaluate any ABAC conditions encountered\nin the query evaluation.", + "type": "object" + }, + "contextual_tuples": { + "$ref": "#/components/schemas/ContextualTupleKeys" + }, + "relation": { + "example": "reader", + "type": "string" + }, + "type": { + "example": "document", + "type": "string" + }, + "user": { + "example": "user:anne", + "maxLength": 512, + "minLength": 1, + "type": "string" + } + }, + "required": [ + "type", + "relation", + "user" + ], + "type": "object" + } + } + }, + "required": true + }, + "summary": "List all objects of the given type that the user has a relation with" + } + }, + "/stores/{store_id}/list-users": { + "post": { + "parameters": [ + { + "in": "path", + "name": "store_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListUsersResponse" + } + } + }, + "description": "A successful response." + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ValidationErrorMessageResponse" + } + } + }, + "description": "Request failed due to invalid input." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthenticatedResponse" + } + } + }, + "description": "Not authenticated." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PathUnknownErrorMessageResponse" + } + } + }, + "description": "Request failed due to incorrect path." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AbortedMessageResponse" + } + } + }, + "description": "Request was aborted due a transaction conflict." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnprocessableContentMessageResponse" + } + } + }, + "description": "Request timed out due to excessive request throttling." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InternalErrorMessageResponse" + } + } + }, + "description": "Request failed due to internal server error." + } + }, + "tags": [ + "Relationship Queries" + ], + "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.", + "operationId": "ListUsers", + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "authorization_model_id": { + "example": "01G5JAVJ41T49E9TT3SKVS7X1J", + "type": "string" + }, + "consistency": { + "$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." + }, + "context": { + "description": "Additional request context that will be used to evaluate any ABAC conditions encountered\nin the query evaluation.", + "type": "object" + }, + "contextual_tuples": { + "items": { + "$ref": "#/components/schemas/TupleKey", + "maximum": 20, + "type": "object" + }, + "type": "array" + }, + "object": { + "$ref": "#/components/schemas/Object", + "example": "document:example" + }, + "relation": { + "example": "reader", + "type": "string" + }, + "user_filters": { + "description": "The type of results returned. Only accepts exactly one value.", + "example": [ + { + "type": "user" + }, + { + "relation": "member", + "type": "group" + } + ], + "items": { + "$ref": "#/components/schemas/UserTypeFilter", + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "object", + "relation", + "user_filters" + ], + "type": "object" + } + } + }, + "required": true + }, + "summary": "List the users matching the provided filter who have a certain relation to a particular type." + } + }, + "/stores/{store_id}/read": { + "post": { + "parameters": [ + { + "in": "path", + "name": "store_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReadResponse" + } + } + }, + "description": "A successful response." + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ValidationErrorMessageResponse" + } + } + }, + "description": "Request failed due to invalid input." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthenticatedResponse" + } + } + }, + "description": "Not authenticated." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PathUnknownErrorMessageResponse" + } + } + }, + "description": "Request failed due to incorrect path." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AbortedMessageResponse" + } + } + }, + "description": "Request was aborted due a transaction conflict." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnprocessableContentMessageResponse" + } + } + }, + "description": "Request timed out due to excessive request throttling." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InternalErrorMessageResponse" + } + } + }, + "description": "Request failed due to internal server error." + } + }, + "tags": [ + "Relationship Tuples" + ], + "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.\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", + "operationId": "Read", + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "consistency": { + "$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." + }, + "continuation_token": { + "example": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==", + "type": "string" + }, + "page_size": { + "example": 50, + "format": "int32", + "type": "integer" + }, + "tuple_key": { + "$ref": "#/components/schemas/ReadRequestTupleKey" + } + }, + "type": "object" + } + } + }, + "required": true + }, + "summary": "Get tuples from the store that matches a query, without following userset rewrite rules" + } + }, + "/stores/{store_id}/streamed-list-objects": { + "post": { + "parameters": [ + { + "in": "path", + "name": "store_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "$ref": "#/components/schemas/Status" + }, + "result": { + "$ref": "#/components/schemas/StreamedListObjectsResponse" + } + }, + "title": "Stream result of StreamedListObjectsResponse", + "type": "object" + } + } + }, + "description": "A successful response.(streaming responses)" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ValidationErrorMessageResponse" + } + } + }, + "description": "Request failed due to invalid input." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthenticatedResponse" + } + } + }, + "description": "Not authenticated." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PathUnknownErrorMessageResponse" + } + } + }, + "description": "Request failed due to incorrect path." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AbortedMessageResponse" + } + } + }, + "description": "Request was aborted due a transaction conflict." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnprocessableContentMessageResponse" + } + } + }, + "description": "Request timed out due to excessive request throttling." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InternalErrorMessageResponse" + } + } + }, + "description": "Request failed due to internal server error." + } + }, + "tags": [ + "Relationship Queries" + ], + "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", + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "authorization_model_id": { + "example": "01G5JAVJ41T49E9TT3SKVS7X1J", + "type": "string" + }, + "consistency": { + "$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." + }, + "context": { + "description": "Additional request context that will be used to evaluate any ABAC conditions encountered\nin the query evaluation.", + "type": "object" + }, + "contextual_tuples": { + "$ref": "#/components/schemas/ContextualTupleKeys" + }, + "relation": { + "example": "reader", + "type": "string" + }, + "type": { + "example": "document", + "type": "string" + }, + "user": { + "example": "user:anne", + "maxLength": 512, + "minLength": 1, + "type": "string" + } + }, + "required": [ + "type", + "relation", + "user" + ], + "type": "object" + } + } + }, + "required": true + }, + "summary": "Stream all objects of the given type that the user has a relation with" + } + }, + "/stores/{store_id}/write": { + "post": { + "parameters": [ + { + "in": "path", + "name": "store_id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WriteResponse" + } + } + }, + "description": "A successful response." + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ValidationErrorMessageResponse" + } + } + }, + "description": "Request failed due to invalid input." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthenticatedResponse" + } + } + }, + "description": "Not authenticated." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PathUnknownErrorMessageResponse" + } + } + }, + "description": "Request failed due to incorrect path." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AbortedMessageResponse" + } + } + }, + "description": "Request was aborted due a transaction conflict." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnprocessableContentMessageResponse" + } + } + }, + "description": "Request timed out due to excessive request throttling." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InternalErrorMessageResponse" + } + } + }, + "description": "Request failed due to internal server error." + } + }, + "tags": [ + "Relationship Tuples" + ], + "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: 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.\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 },\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 }\n}\n```\n", + "operationId": "Write", + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "authorization_model_id": { + "example": "01G5JAVJ41T49E9TT3SKVS7X1J", + "type": "string" + }, + "deletes": { + "$ref": "#/components/schemas/WriteRequestDeletes" + }, + "writes": { + "$ref": "#/components/schemas/WriteRequestWrites" + } + }, + "type": "object" + } + } + }, + "required": true + }, + "summary": "Add or delete tuples from the store" + } + } + }, + "components": { + "requestBodies": { + "ListObjectsBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "authorization_model_id": { + "example": "01G5JAVJ41T49E9TT3SKVS7X1J", + "type": "string" + }, + "consistency": { + "$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." + }, + "context": { + "description": "Additional request context that will be used to evaluate any ABAC conditions encountered\nin the query evaluation.", + "type": "object" + }, + "contextual_tuples": { + "$ref": "#/components/schemas/ContextualTupleKeys" + }, + "relation": { + "example": "reader", + "type": "string" + }, + "type": { + "example": "document", + "type": "string" + }, + "user": { + "example": "user:anne", + "maxLength": 512, + "minLength": 1, + "type": "string" + } + }, + "required": [ + "type", + "relation", + "user" + ], + "type": "object" + } + } + }, + "required": true + } + }, + "schemas": { + "AbortedMessageResponse": { + "example": { + "code": "10", + "message": "transaction conflict" + }, + "properties": { + "code": { + "type": "string" + }, + "message": { + "type": "string" + } + }, + "type": "object" + }, + "Any": { + "additionalProperties": {}, + "properties": { + "@type": { + "type": "string" + } + }, + "type": "object" + }, + "Assertion": { + "properties": { + "context": { + "description": "Additional request context that will be used to evaluate any ABAC conditions encountered\nin the query evaluation.", + "example": { + "view_count": 100 + }, + "type": "object" + }, + "contextual_tuples": { + "items": { + "$ref": "#/components/schemas/TupleKey", + "maximum": 20, + "type": "object" + }, + "type": "array" + }, + "expectation": { + "type": "boolean" + }, + "tuple_key": { + "$ref": "#/components/schemas/AssertionTupleKey" + } + }, + "required": [ + "tuple_key", + "expectation" + ], + "type": "object" + }, + "AssertionTupleKey": { + "properties": { + "object": { + "example": "document:2021-budget", + "maxLength": 256, + "type": "string" + }, + "relation": { + "example": "reader", + "maxLength": 50, + "type": "string" + }, + "user": { + "example": "user:anne", + "maxLength": 512, + "type": "string" + } + }, + "required": [ + "object", + "relation", + "user" + ], + "type": "object" + }, + "AuthorizationModel": { + "properties": { + "conditions": { + "additionalProperties": { + "$ref": "#/components/schemas/Condition" + }, + "type": "object" + }, + "id": { + "example": "01G5JAVJ41T49E9TT3SKVS7X1J", + "type": "string" + }, + "schema_version": { + "type": "string" + }, + "type_definitions": { + "example": [ + { + "type": "user" + }, + { + "metadata": { + "relations": { + "reader": { + "directly_related_user_types": [ + { + "type": "user" + } + ] + }, + "writer": { + "directly_related_user_types": [ + { + "type": "user" + } + ] + } + } + }, + "relations": { + "reader": { + "union": { + "child": [ + { + "this": {} + }, + { + "computedUserset": { + "object": "", + "relation": "writer" + } + } + ] + } + }, + "writer": { + "this": {} + } + }, + "type": "document" + } + ], + "items": { + "$ref": "#/components/schemas/TypeDefinition", + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "id", + "schema_version", + "type_definitions" + ], + "type": "object" + }, + "CheckRequestTupleKey": { + "properties": { + "object": { + "example": "document:2021-budget", + "maxLength": 256, + "type": "string" + }, + "relation": { + "example": "reader", + "maxLength": 50, + "type": "string" + }, + "user": { + "example": "user:anne", + "maxLength": 512, + "type": "string" + } + }, + "required": [ + "user", + "relation", + "object" + ], + "type": "object" + }, + "CheckResponse": { + "properties": { + "allowed": { + "example": true, + "type": "boolean" + }, + "resolution": { + "description": "For internal use only.", + "type": "string" + } + }, + "type": "object" + }, + "Computed": { + "properties": { + "userset": { + "type": "string" + } + }, + "required": [ + "userset" + ], + "type": "object" + }, + "Condition": { + "properties": { + "parameters": { + "additionalProperties": { + "$ref": "#/components/schemas/ConditionParamTypeRef" + }, + "description": "A map of parameter names to the parameter's defined type reference.", + "type": "object" + }, + "expression": { + "description": "A Google CEL expression, expressed as a string.", + "type": "string" + }, + "metadata": { + "$ref": "#/components/schemas/ConditionMetadata" + }, + "name": { + "title": "A unique name for the condition", + "type": "string" + } + }, + "required": [ + "name", + "expression" + ], + "type": "object" + }, + "ConditionMetadata": { + "properties": { + "module": { + "type": "string" + }, + "source_info": { + "$ref": "#/components/schemas/SourceInfo" + } + }, + "type": "object" + }, + "ConditionParamTypeRef": { + "properties": { + "generic_types": { + "items": { + "$ref": "#/components/schemas/ConditionParamTypeRef", + "type": "object" + }, + "type": "array" + }, + "type_name": { + "$ref": "#/components/schemas/TypeName" + } + }, + "required": [ + "type_name" + ], + "type": "object" + }, + "ConsistencyPreference": { + "default": "UNSPECIFIED", + "description": "Controls the consistency preferences when calling the query APIs.\n\n - UNSPECIFIED: Default if not set. Behavior will be the same as MINIMIZE_LATENCY.\n - MINIMIZE_LATENCY: Minimize latency at the potential expense of lower consistency.\n - HIGHER_CONSISTENCY: Prefer higher consistency, at the potential expense of increased latency.", + "enum": [ + "UNSPECIFIED", + "MINIMIZE_LATENCY", + "HIGHER_CONSISTENCY" + ], + "example": "MINIMIZE_LATENCY", + "type": "string" + }, + "ContextualTupleKeys": { + "properties": { + "tuple_keys": { + "items": { + "$ref": "#/components/schemas/TupleKey", + "maximum": 20, + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "tuple_keys" + ], + "type": "object" + }, + "CreateStoreRequest": { + "properties": { + "name": { + "example": "my-store-name", + "type": "string" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "CreateStoreResponse": { + "properties": { + "created_at": { + "format": "date-time", + "type": "string" + }, + "id": { + "example": "01YCP46JKYM8FJCQ37NMBYHE5X", + "type": "string" + }, + "name": { + "type": "string" + }, + "updated_at": { + "format": "date-time", + "type": "string" + } + }, + "required": [ + "id", + "name", + "created_at", + "updated_at" + ], + "type": "object" + }, + "DeleteStoreResponse": { + "type": "object" + }, + "DirectUserset": { + "description": "A DirectUserset is a sentinel message for referencing\nthe direct members specified by an object/relation mapping.", + "type": "object" + }, + "ErrorCode": { + "default": "no_error", + "enum": [ + "no_error", + "validation_error", + "authorization_model_not_found", + "authorization_model_resolution_too_complex", + "invalid_write_input", + "cannot_allow_duplicate_tuples_in_one_request", + "cannot_allow_duplicate_types_in_one_request", + "cannot_allow_multiple_references_to_one_relation", + "invalid_continuation_token", + "invalid_tuple_set", + "invalid_check_input", + "invalid_expand_input", + "unsupported_user_set", + "invalid_object_format", + "write_failed_due_to_invalid_input", + "authorization_model_assertions_not_found", + "latest_authorization_model_not_found", + "type_not_found", + "relation_not_found", + "empty_relation_definition", + "invalid_user", + "invalid_tuple", + "unknown_relation", + "store_id_invalid_length", + "assertions_too_many_items", + "id_too_long", + "authorization_model_id_too_long", + "tuple_key_value_not_specified", + "tuple_keys_too_many_or_too_few_items", + "page_size_invalid", + "param_missing_value", + "difference_base_missing_value", + "subtract_base_missing_value", + "object_too_long", + "relation_too_long", + "type_definitions_too_few_items", + "type_invalid_length", + "type_invalid_pattern", + "relations_too_few_items", + "relations_too_long", + "relations_invalid_pattern", + "object_invalid_pattern", + "query_string_type_continuation_token_mismatch", + "exceeded_entity_limit", + "invalid_contextual_tuple", + "duplicate_contextual_tuple", + "invalid_authorization_model", + "unsupported_schema_version", + "cancelled" + ], + "type": "string" + }, + "ExpandRequestTupleKey": { + "properties": { + "object": { + "example": "document:2021-budget", + "maxLength": 256, + "type": "string" + }, + "relation": { + "example": "reader", + "maxLength": 50, + "type": "string" + } + }, + "required": [ + "relation", + "object" + ], + "type": "object" + }, + "ExpandResponse": { + "properties": { + "tree": { + "$ref": "#/components/schemas/UsersetTree" + } + }, + "type": "object" + }, + "GetStoreResponse": { + "properties": { + "created_at": { + "format": "date-time", + "type": "string" + }, + "deleted_at": { + "format": "date-time", + "type": "string" + }, + "id": { + "example": "01YCP46JKYM8FJCQ37NMBYHE5X", + "type": "string" + }, + "name": { + "type": "string" + }, + "updated_at": { + "format": "date-time", + "type": "string" + } + }, + "required": [ + "id", + "name", + "created_at", + "updated_at" + ], + "type": "object" + }, + "InternalErrorCode": { + "default": "no_internal_error", + "enum": [ + "no_internal_error", + "internal_error", + "deadline_exceeded", + "already_exists", + "resource_exhausted", + "failed_precondition", + "aborted", + "out_of_range", + "unavailable", + "data_loss" + ], + "type": "string" + }, + "InternalErrorMessageResponse": { + "example": { + "code": "internal_error", + "message": "Internal Server Error" + }, + "properties": { + "code": { + "$ref": "#/components/schemas/InternalErrorCode" + }, + "message": { + "type": "string" + } + }, + "type": "object" + }, + "Leaf": { + "description": "A leaf node contains either\n- a set of users (which may be individual users, or usersets\n referencing other relations)\n- a computed node, which is the result of a computed userset\n value in the authorization model\n- a tupleToUserset nodes, containing the result of expanding\n a tupleToUserset value in a authorization model.", + "properties": { + "computed": { + "$ref": "#/components/schemas/Computed" + }, + "tupleToUserset": { + "$ref": "#/components/schemas/UsersetTree.TupleToUserset" + }, + "users": { + "$ref": "#/components/schemas/Users" + } + }, + "type": "object" + }, + "ListObjectsResponse": { + "properties": { + "objects": { + "example": [ + "document:roadmap", + "document:planning" + ], + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "objects" + ], + "type": "object" + }, + "ListStoresResponse": { + "properties": { + "continuation_token": { + "description": "The continuation token will be empty if there are no more stores.", + "example": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==", + "type": "string" + }, + "stores": { + "items": { + "$ref": "#/components/schemas/Store", + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "stores", + "continuation_token" + ], + "type": "object" + }, + "ListUsersResponse": { + "properties": { + "users": { + "items": { + "$ref": "#/components/schemas/User", + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "users" + ], + "type": "object" + }, + "Metadata": { + "properties": { + "module": { + "type": "string" + }, + "relations": { + "additionalProperties": { + "$ref": "#/components/schemas/RelationMetadata" + }, + "type": "object" + }, + "source_info": { + "$ref": "#/components/schemas/SourceInfo" + } + }, + "type": "object" + }, + "Node": { + "properties": { + "difference": { + "$ref": "#/components/schemas/UsersetTree.Difference" + }, + "intersection": { + "$ref": "#/components/schemas/Nodes" + }, + "leaf": { + "$ref": "#/components/schemas/Leaf" + }, + "name": { + "type": "string" + }, + "union": { + "$ref": "#/components/schemas/Nodes" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "Nodes": { + "properties": { + "nodes": { + "items": { + "$ref": "#/components/schemas/Node", + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "nodes" + ], + "type": "object" + }, + "NotFoundErrorCode": { + "default": "no_not_found_error", + "enum": [ + "no_not_found_error", + "undefined_endpoint", + "store_id_not_found", + "unimplemented" + ], + "type": "string" + }, + "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.", + "enum": [ + "NULL_VALUE" + ], + "type": "string" + }, + "Object": { + "description": "Object represents an OpenFGA Object.\n\nAn Object is composed of a type and identifier (e.g. 'document:1')\n\nSee https://openfga.dev/docs/concepts#what-is-an-object", + "properties": { + "id": { + "example": "0bcdf6fa-a6aa-4730-a8eb-9cf172ff16d9", + "type": "string" + }, + "type": { + "example": "document", + "type": "string" + } + }, + "required": [ + "type", + "id" + ], + "type": "object" + }, + "ObjectRelation": { + "properties": { + "object": { + "type": "string" + }, + "relation": { + "type": "string" + } + }, + "type": "object" + }, + "PathUnknownErrorMessageResponse": { + "example": { + "code": "undefined_endpoint", + "message": "Endpoint not enabled" + }, + "properties": { + "code": { + "$ref": "#/components/schemas/NotFoundErrorCode" + }, + "message": { + "type": "string" + } + }, + "type": "object" + }, + "ReadAssertionsResponse": { + "properties": { + "assertions": { + "items": { + "$ref": "#/components/schemas/Assertion", + "type": "object" + }, + "type": "array" + }, + "authorization_model_id": { + "example": "01G5JAVJ41T49E9TT3SKVS7X1J", + "type": "string" + } + }, + "required": [ + "authorization_model_id" + ], + "type": "object" + }, + "ReadAuthorizationModelResponse": { + "properties": { + "authorization_model": { + "$ref": "#/components/schemas/AuthorizationModel" + } + }, + "type": "object" + }, + "ReadAuthorizationModelsResponse": { + "properties": { + "authorization_models": { + "items": { + "$ref": "#/components/schemas/AuthorizationModel", + "type": "object" + }, + "type": "array" + }, + "continuation_token": { + "description": "The continuation token will be empty if there are no more models.", + "example": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==", + "type": "string" + } + }, + "required": [ + "authorization_models" + ], + "type": "object" + }, + "ReadChangesResponse": { + "properties": { + "changes": { + "items": { + "$ref": "#/components/schemas/TupleChange", + "type": "object" + }, + "type": "array" + }, + "continuation_token": { + "description": "The continuation token will be identical if there are no new changes.", + "example": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==", + "type": "string" + } + }, + "required": [ + "changes" + ], + "type": "object" + }, + "ReadRequestTupleKey": { + "properties": { + "object": { + "example": "document:2021-budget", + "maxLength": 256, + "type": "string" + }, + "relation": { + "example": "reader", + "maxLength": 50, + "type": "string" + }, + "user": { + "example": "user:anne", + "maxLength": 512, + "type": "string" + } + }, + "type": "object" + }, + "ReadResponse": { + "properties": { + "continuation_token": { + "description": "The continuation token will be empty if there are no more tuples.", + "example": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==", + "type": "string" + }, + "tuples": { + "items": { + "$ref": "#/components/schemas/Tuple", + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "tuples", + "continuation_token" + ], + "type": "object" + }, + "RelationMetadata": { + "properties": { + "directly_related_user_types": { + "items": { + "$ref": "#/components/schemas/RelationReference", + "type": "object" + }, + "type": "array" + }, + "module": { + "type": "string" + }, + "source_info": { + "$ref": "#/components/schemas/SourceInfo" + } + }, + "type": "object" + }, + "RelationReference": { + "description": "RelationReference represents a relation of a particular object type (e.g. 'document#viewer').", + "properties": { + "condition": { + "description": "The name of a condition that is enforced over the allowed relation.", + "type": "string" + }, + "relation": { + "example": "member", + "type": "string" + }, + "type": { + "example": "group", + "type": "string" + }, + "wildcard": { + "$ref": "#/components/schemas/Wildcard" + } + }, + "required": [ + "type" + ], + "type": "object" + }, + "RelationshipCondition": { + "properties": { + "context": { + "description": "Additional context/data to persist along with the condition.\nThe keys must match the parameters defined by the condition, and the value types must\nmatch the parameter type definitions.", + "type": "object" + }, + "name": { + "description": "A reference (by name) of the relationship condition defined in the authorization model.", + "example": "condition1", + "maxLength": 256, + "type": "string" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "SourceInfo": { + "properties": { + "file": { + "type": "string" + } + }, + "type": "object" + }, + "Status": { + "properties": { + "code": { + "format": "int32", + "type": "integer" + }, + "details": { + "items": { + "$ref": "#/components/schemas/Any", + "type": "object" + }, + "type": "array" + }, + "message": { + "type": "string" + } + }, + "type": "object" + }, + "Store": { + "properties": { + "created_at": { + "format": "date-time", + "type": "string" + }, + "deleted_at": { + "format": "date-time", + "type": "string" + }, + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "updated_at": { + "format": "date-time", + "type": "string" + } + }, + "required": [ + "id", + "name", + "created_at", + "updated_at" + ], + "type": "object" + }, + "StreamedListObjectsResponse": { + "description": "The response for a StreamedListObjects RPC.", + "properties": { + "object": { + "example": "document:roadmap", + "type": "string" + } + }, + "required": [ + "object" + ], + "type": "object" + }, + "Tuple": { + "properties": { + "key": { + "$ref": "#/components/schemas/TupleKey" + }, + "timestamp": { + "format": "date-time", + "type": "string" + } + }, + "required": [ + "key", + "timestamp" + ], + "type": "object" + }, + "TupleChange": { + "properties": { + "operation": { + "$ref": "#/components/schemas/TupleOperation" + }, + "timestamp": { + "format": "date-time", + "type": "string" + }, + "tuple_key": { + "$ref": "#/components/schemas/TupleKey" + } + }, + "required": [ + "tuple_key", + "operation", + "timestamp" + ], + "type": "object" + }, + "TupleKey": { + "properties": { + "condition": { + "$ref": "#/components/schemas/RelationshipCondition" + }, + "object": { + "example": "document:2021-budget", + "maxLength": 256, + "type": "string" + }, + "relation": { + "example": "reader", + "maxLength": 50, + "type": "string" + }, + "user": { + "example": "user:anne", + "maxLength": 512, + "type": "string" + } + }, + "required": [ + "user", + "relation", + "object" + ], + "type": "object" + }, + "TupleKeyWithoutCondition": { + "properties": { + "object": { + "example": "document:2021-budget", + "maxLength": 256, + "type": "string" + }, + "relation": { + "example": "reader", + "maxLength": 50, + "type": "string" + }, + "user": { + "example": "user:anne", + "maxLength": 512, + "type": "string" + } + }, + "required": [ + "user", + "relation", + "object" + ], + "type": "object" + }, + "TupleOperation": { + "default": "TUPLE_OPERATION_WRITE", + "enum": [ + "TUPLE_OPERATION_WRITE", + "TUPLE_OPERATION_DELETE" + ], + "title": "buf:lint:ignore ENUM_ZERO_VALUE_SUFFIX", + "type": "string" + }, + "TypeDefinition": { + "properties": { + "metadata": { + "$ref": "#/components/schemas/Metadata", + "description": "A map whose keys are the name of the relation and whose value is the Metadata for that relation.\nIt also holds information around the module name and source file if this model was constructed\nfrom a modular model." + }, + "relations": { + "additionalProperties": { + "$ref": "#/components/schemas/Userset" + }, + "example": { + "reader": { + "union": { + "child": [ + { + "this": {} + }, + { + "computedUserset": { + "object": "", + "relation": "writer" + } + } + ] + } + }, + "writer": { + "this": {} + } + }, + "type": "object" + }, + "type": { + "example": "document", + "type": "string" + } + }, + "required": [ + "type" + ], + "type": "object" + }, + "TypeName": { + "default": "TYPE_NAME_UNSPECIFIED", + "enum": [ + "TYPE_NAME_UNSPECIFIED", + "TYPE_NAME_ANY", + "TYPE_NAME_BOOL", + "TYPE_NAME_STRING", + "TYPE_NAME_INT", + "TYPE_NAME_UINT", + "TYPE_NAME_DOUBLE", + "TYPE_NAME_DURATION", + "TYPE_NAME_TIMESTAMP", + "TYPE_NAME_MAP", + "TYPE_NAME_LIST", + "TYPE_NAME_IPADDRESS" + ], + "type": "string" + }, + "TypedWildcard": { + "description": "Type bound public access.\n\nNormally represented using the `:*` syntax\n\n`employee:*` represents every object of type `employee`, including those not currently present in the system\n\nSee https://openfga.dev/docs/concepts#what-is-type-bound-public-access", + "properties": { + "type": { + "example": "employee", + "type": "string" + } + }, + "required": [ + "type" + ], + "type": "object" + }, + "UnauthenticatedResponse": { + "example": { + "code": "unauthenticated", + "message": "unauthenticated" + }, + "properties": { + "code": { + "$ref": "#/components/schemas/ErrorCode" + }, + "message": { + "type": "string" + } + }, + "type": "object" + }, + "UnprocessableContentErrorCode": { + "default": "no_throttled_error_code", + "enum": [ + "no_throttled_error_code", + "throttled_timeout_error" + ], + "type": "string" + }, + "UnprocessableContentMessageResponse": { + "example": { + "code": "throttled_timeout_error", + "message": "timeout due to throttling on complex request" + }, + "properties": { + "code": { + "$ref": "#/components/schemas/UnprocessableContentErrorCode" + }, + "message": { + "type": "string" + } + }, + "type": "object" + }, + "User": { + "description": "User.\n\nRepresents any possible value for a user (subject or principal). Can be a:\n- Specific user object e.g.: 'user:will', 'folder:marketing', 'org:contoso', ...)\n- Specific userset (e.g. 'group:engineering#member')\n- Public-typed wildcard (e.g. 'user:*')\n\nSee https://openfga.dev/docs/concepts#what-is-a-user", + "properties": { + "object": { + "$ref": "#/components/schemas/Object" + }, + "userset": { + "$ref": "#/components/schemas/UsersetUser" + }, + "wildcard": { + "$ref": "#/components/schemas/TypedWildcard" + } + }, + "type": "object" + }, + "UserTypeFilter": { + "properties": { + "relation": { + "example": "member", + "type": "string" + }, + "type": { + "example": "group", + "type": "string" + } + }, + "required": [ + "type" + ], + "type": "object" + }, + "Users": { + "properties": { + "users": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "users" + ], + "type": "object" + }, + "Userset": { + "properties": { + "computedUserset": { + "$ref": "#/components/schemas/ObjectRelation" + }, + "difference": { + "$ref": "#/components/schemas/v1.Difference" + }, + "intersection": { + "$ref": "#/components/schemas/Usersets" + }, + "this": { + "$ref": "#/components/schemas/DirectUserset" + }, + "tupleToUserset": { + "$ref": "#/components/schemas/v1.TupleToUserset" + }, + "union": { + "$ref": "#/components/schemas/Usersets" + } + }, + "type": "object" + }, + "UsersetTree": { + "description": "A UsersetTree contains the result of an Expansion.", + "properties": { + "root": { + "$ref": "#/components/schemas/Node" + } + }, + "type": "object" + }, + "UsersetTree.Difference": { + "properties": { + "base": { + "$ref": "#/components/schemas/Node" + }, + "subtract": { + "$ref": "#/components/schemas/Node" + } + }, + "required": [ + "base", + "subtract" + ], + "type": "object" + }, + "UsersetTree.TupleToUserset": { + "properties": { + "computed": { + "items": { + "$ref": "#/components/schemas/Computed", + "type": "object" + }, + "type": "array" + }, + "tupleset": { + "type": "string" + } + }, + "required": [ + "tupleset", + "computed" + ], + "type": "object" + }, + "UsersetUser": { + "description": "Userset.\n\nA set or group of users, represented in the `:#` format\n\n`group:fga#member` represents all members of group FGA, not to be confused by `group:fga` which represents the group itself as a specific object.\n\nSee: https://openfga.dev/docs/modeling/building-blocks/usersets#what-is-a-userset", + "properties": { + "id": { + "example": "fga", + "type": "string" + }, + "relation": { + "example": "member", + "type": "string" + }, + "type": { + "example": "group", + "type": "string" + } + }, + "required": [ + "type", + "id", + "relation" + ], + "type": "object" + }, + "Usersets": { + "properties": { + "child": { + "items": { + "$ref": "#/components/schemas/Userset", + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "child" + ], + "type": "object" + }, + "ValidationErrorMessageResponse": { + "example": { + "code": "validation_error", + "message": "Generic validation error" + }, + "properties": { + "code": { + "$ref": "#/components/schemas/ErrorCode" + }, + "message": { + "type": "string" + } + }, + "type": "object" + }, + "Wildcard": { + "type": "object" + }, + "WriteAssertionsResponse": { + "type": "object" + }, + "WriteAuthorizationModelResponse": { + "properties": { + "authorization_model_id": { + "example": "01G5JAVJ41T49E9TT3SKVS7X1J", + "type": "string" + } + }, + "required": [ + "authorization_model_id" + ], + "type": "object" + }, + "WriteRequestDeletes": { + "properties": { + "tuple_keys": { + "items": { + "$ref": "#/components/schemas/TupleKeyWithoutCondition", + "minimum": 1, + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "tuple_keys" + ], + "type": "object" + }, + "WriteRequestWrites": { + "properties": { + "tuple_keys": { + "items": { + "$ref": "#/components/schemas/TupleKey", + "minimum": 1, + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "tuple_keys" + ], + "type": "object" + }, + "WriteResponse": { + "type": "object" + }, + "v1.Difference": { + "properties": { + "base": { + "$ref": "#/components/schemas/Userset" + }, + "subtract": { + "$ref": "#/components/schemas/Userset" + } + }, + "required": [ + "base", + "subtract" + ], + "type": "object" + }, + "v1.TupleToUserset": { + "properties": { + "computedUserset": { + "$ref": "#/components/schemas/ObjectRelation" + }, + "tupleset": { + "$ref": "#/components/schemas/ObjectRelation", + "title": "The target object/relation" + } + }, + "required": [ + "tupleset", + "computedUserset" + ], + "type": "object" + } + } + }, + "tags": [ + { + "name": "OpenFGAService" + } + ] +} diff --git a/scripts/update_swagger.sh b/scripts/update_swagger.sh index 800d032b..dd881aa6 100755 --- a/scripts/update_swagger.sh +++ b/scripts/update_swagger.sh @@ -1,6 +1,6 @@ #!/bin/sh -# This script is used to cleanup swagger file +# This script is used to cleanup swagger file and convert to OpenAPI v3 if [ "$#" -ne 1 ]; then echo "Usage: update_swagger.sh " >&2 exit 1 @@ -8,22 +8,47 @@ fi filename=$1 tmp_filename=$filename.tmp +openapi_v3_dir="docs/openapiv3" +openapi_v3_filename="${openapi_v3_dir}/apidocs.swagger.json" # We also need to cleanup response code that are obsolete because # either i) we override the error code or ii) we override success case where we respond with 201/204 -cat ${filename} | \ +cat ${filename} | jq \ - 'del(.paths[][]."responses"|select(has("400"))."default" ) | del(.paths[][]."responses"|select(has("201"))."200") | del(.paths[][]."responses"|select(has("204"))."200")' > ${tmp_filename} + 'del(.paths[][]."responses"|select(has("400"))."default" ) | del(.paths[][]."responses"|select(has("201"))."200") | del(.paths[][]."responses"|select(has("204"))."200")' >${tmp_filename} mv ${tmp_filename} ${filename} # Add an example value to the ConsistencyPreference to override the default of UNSPECIFIED being shown in the docs -cat ${filename} | \ +cat ${filename} | jq \ - '.definitions.ConsistencyPreference.example = "MINIMIZE_LATENCY"' > ${tmp_filename} + '.definitions.ConsistencyPreference.example = "MINIMIZE_LATENCY"' >${tmp_filename} mv ${tmp_filename} ${filename} # Finally, for 204, there should be no schema -cat ${filename} | \ +cat ${filename} | jq \ - 'del(.paths[][]."responses"."204"."schema")' > ${tmp_filename} + 'del(.paths[][]."responses"."204"."schema")' >${tmp_filename} mv ${tmp_filename} ${filename} + +# Convert OpenAPI v2 to v3 +if command -v api-spec-converter >/dev/null; then + # Check if the directory exists, if not create it + if [ ! -d "${openapi_v3_dir}" ]; then + if ! mkdir -p "${openapi_v3_dir}"; then + echo "Failed to create directory: ${openapi_v3_dir}" >&2 + exit 1 + fi + echo "Created directory: ${openapi_v3_dir}" + fi + + if api-spec-converter --from=swagger_2 --to=openapi_3 --syntax=json ${filename} >${openapi_v3_filename}; then + echo "Converted ${filename} to OpenAPI v3 and saved as ${openapi_v3_filename}" + else + echo "Failed to convert ${filename} to OpenAPI v3" >&2 + exit 1 + fi +else + echo "api-spec-converter not found. Please install it to convert to OpenAPI v3." >&2 + echo "You can install it using: npm install -g api-spec-converter" >&2 + exit 1 +fi