openapi: 3.0.0 info: title: Auth0 Authentication actions Relationship Queries API description: Auth0 Authentication API. Endpoints for authentication and authorization using OpenID Connect, OAuth 2.0, SAML, WS-Federation, and Passwordless flows. version: 1.0.0 servers: - url: '{auth0_domain}' description: The Authentication API is served over HTTPS. variables: auth0_domain: description: Auth0 domain default: https://demo.us.auth0.com tags: - name: Relationship Queries paths: /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" operationId: BatchCheck responses: '200': description: A successful response. schema: $ref: '#/definitions/BatchCheckResponse' '400': description: Request failed due to invalid input. schema: $ref: '#/definitions/ValidationErrorMessageResponse' '401': description: Not authenticated. schema: $ref: '#/definitions/UnauthenticatedResponse' '403': description: Forbidden. schema: $ref: '#/definitions/ForbiddenResponse' '404': description: Request failed due to incorrect path. schema: $ref: '#/definitions/PathUnknownErrorMessageResponse' '409': description: Request was aborted due a transaction conflict. schema: $ref: '#/definitions/AbortedMessageResponse' '422': description: Request timed out due to excessive request throttling. schema: $ref: '#/definitions/UnprocessableContentMessageResponse' '500': description: Request failed due to internal server error. schema: $ref: '#/definitions/InternalErrorMessageResponse' parameters: - name: store_id in: path required: true type: string - name: body in: body required: true schema: type: object properties: checks: type: array items: type: object $ref: '#/definitions/BatchCheckItem' minItems: 1 authorization_model_id: type: string example: 01G5JAVJ41T49E9TT3SKVS7X1J consistency: $ref: '#/definitions/ConsistencyPreference' required: - checks tags: - Relationship Queries /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" operationId: Check responses: '200': description: A successful response. schema: $ref: '#/definitions/CheckResponse' '400': description: Request failed due to invalid input. schema: $ref: '#/definitions/ValidationErrorMessageResponse' '401': description: Not authenticated. schema: $ref: '#/definitions/UnauthenticatedResponse' '403': description: Forbidden. schema: $ref: '#/definitions/ForbiddenResponse' '404': description: Request failed due to incorrect path. schema: $ref: '#/definitions/PathUnknownErrorMessageResponse' '409': description: Request was aborted due a transaction conflict. schema: $ref: '#/definitions/AbortedMessageResponse' '422': description: Request timed out due to excessive request throttling. schema: $ref: '#/definitions/UnprocessableContentMessageResponse' '500': description: Request failed due to internal server error. schema: $ref: '#/definitions/InternalErrorMessageResponse' parameters: - name: store_id in: path required: true type: string - name: body in: body required: true schema: type: object properties: tuple_key: $ref: '#/definitions/CheckRequestTupleKey' contextual_tuples: $ref: '#/definitions/ContextualTupleKeys' authorization_model_id: type: string example: 01G5JAVJ41T49E9TT3SKVS7X1J trace: type: boolean example: false description: Defaults to false. Making it true has performance implications. readOnly: true context: type: object description: 'Additional request context that will be used to evaluate any ABAC conditions encountered in 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. required: - tuple_key tags: - Relationship Queries /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" operationId: Expand responses: '200': description: A successful response. schema: $ref: '#/definitions/ExpandResponse' '400': description: Request failed due to invalid input. schema: $ref: '#/definitions/ValidationErrorMessageResponse' '401': description: Not authenticated. schema: $ref: '#/definitions/UnauthenticatedResponse' '403': description: Forbidden. schema: $ref: '#/definitions/ForbiddenResponse' '404': description: Request failed due to incorrect path. schema: $ref: '#/definitions/PathUnknownErrorMessageResponse' '409': description: Request was aborted due a transaction conflict. schema: $ref: '#/definitions/AbortedMessageResponse' '422': description: Request timed out due to excessive request throttling. schema: $ref: '#/definitions/UnprocessableContentMessageResponse' '500': description: Request failed due to internal server error. schema: $ref: '#/definitions/InternalErrorMessageResponse' parameters: - name: store_id in: path required: true type: string - name: body in: body required: true schema: type: object properties: tuple_key: $ref: '#/definitions/ExpandRequestTupleKey' authorization_model_id: type: string example: 01G5JAVJ41T49E9TT3SKVS7X1J 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. contextual_tuples: $ref: '#/definitions/ContextualTupleKeys' required: - tuple_key tags: - Relationship Queries /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." operationId: ListObjects responses: '200': description: A successful response. schema: $ref: '#/definitions/ListObjectsResponse' '400': description: Request failed due to invalid input. schema: $ref: '#/definitions/ValidationErrorMessageResponse' '401': description: Not authenticated. schema: $ref: '#/definitions/UnauthenticatedResponse' '403': description: Forbidden. schema: $ref: '#/definitions/ForbiddenResponse' '404': description: Request failed due to incorrect path. schema: $ref: '#/definitions/PathUnknownErrorMessageResponse' '409': description: Request was aborted due a transaction conflict. schema: $ref: '#/definitions/AbortedMessageResponse' '422': description: Request timed out due to excessive request throttling. schema: $ref: '#/definitions/UnprocessableContentMessageResponse' '500': description: Request failed due to internal server error. schema: $ref: '#/definitions/InternalErrorMessageResponse' parameters: - name: store_id in: path required: true type: string - name: body in: body required: true schema: type: object properties: authorization_model_id: type: string example: 01G5JAVJ41T49E9TT3SKVS7X1J type: type: string example: document relation: type: string example: reader user: type: string example: user:anne maxLength: 512 minLength: 1 contextual_tuples: $ref: '#/definitions/ContextualTupleKeys' context: type: object description: 'Additional request context that will be used to evaluate any ABAC conditions encountered in 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. required: - type - relation - user tags: - Relationship Queries /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." operationId: ListUsers responses: '200': description: A successful response. schema: $ref: '#/definitions/ListUsersResponse' '400': description: Request failed due to invalid input. schema: $ref: '#/definitions/ValidationErrorMessageResponse' '401': description: Not authenticated. schema: $ref: '#/definitions/UnauthenticatedResponse' '403': description: Forbidden. schema: $ref: '#/definitions/ForbiddenResponse' '404': description: Request failed due to incorrect path. schema: $ref: '#/definitions/PathUnknownErrorMessageResponse' '409': description: Request was aborted due a transaction conflict. schema: $ref: '#/definitions/AbortedMessageResponse' '422': description: Request timed out due to excessive request throttling. schema: $ref: '#/definitions/UnprocessableContentMessageResponse' '500': description: Request failed due to internal server error. schema: $ref: '#/definitions/InternalErrorMessageResponse' parameters: - name: store_id in: path required: true type: string - name: body in: body required: true schema: type: object properties: authorization_model_id: type: string example: 01G5JAVJ41T49E9TT3SKVS7X1J object: $ref: '#/definitions/Object' example: document:example relation: type: string example: reader user_filters: type: array example: - type: user - type: group relation: member items: type: object $ref: '#/definitions/UserTypeFilter' description: The type of results returned. Only accepts exactly one value. maxItems: 1 minItems: 1 contextual_tuples: type: array items: type: object $ref: '#/definitions/TupleKey' maxItems: 100 context: type: object description: 'Additional request context that will be used to evaluate any ABAC conditions encountered in 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. required: - object - relation - user_filters tags: - Relationship Queries /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" operationId: StreamedListObjects responses: '200': description: A successful response.(streaming responses) schema: type: object properties: result: $ref: '#/definitions/StreamedListObjectsResponse' error: $ref: '#/definitions/Status' title: Stream result of StreamedListObjectsResponse '400': description: Request failed due to invalid input. schema: $ref: '#/definitions/ValidationErrorMessageResponse' '401': description: Not authenticated. schema: $ref: '#/definitions/UnauthenticatedResponse' '403': description: Forbidden. schema: $ref: '#/definitions/ForbiddenResponse' '404': description: Request failed due to incorrect path. schema: $ref: '#/definitions/PathUnknownErrorMessageResponse' '409': description: Request was aborted due a transaction conflict. schema: $ref: '#/definitions/AbortedMessageResponse' '422': description: Request timed out due to excessive request throttling. schema: $ref: '#/definitions/UnprocessableContentMessageResponse' '500': description: Request failed due to internal server error. schema: $ref: '#/definitions/InternalErrorMessageResponse' parameters: - name: store_id in: path required: true type: string - name: body in: body required: true schema: type: object properties: authorization_model_id: type: string example: 01G5JAVJ41T49E9TT3SKVS7X1J type: type: string example: document relation: type: string example: reader user: type: string example: user:anne maxLength: 512 minLength: 1 contextual_tuples: $ref: '#/definitions/ContextualTupleKeys' context: type: object description: 'Additional request context that will be used to evaluate any ABAC conditions encountered in 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. required: - type - relation - user tags: - Relationship Queries definitions: PathUnknownErrorMessageResponse: type: object example: code: undefined_endpoint message: Endpoint not enabled properties: code: $ref: '#/definitions/NotFoundErrorCode' message: type: string UserTypeFilter: type: object properties: type: type: string example: group relation: type: string example: member required: - type RelationshipCondition: type: object properties: name: type: string example: condition1 description: A reference (by name) of the relationship condition defined in the authorization model. maxLength: 256 context: type: object description: 'Additional context/data to persist along with the condition. The keys must match the parameters defined by the condition, and the value types must match the parameter type definitions.' required: - name TupleKey: type: object properties: user: type: string example: user:anne maxLength: 512 relation: type: string example: reader maxLength: 50 object: type: string example: document:2021-budget maxLength: 256 condition: $ref: '#/definitions/RelationshipCondition' required: - user - relation - object InternalErrorCode: type: string enum: - no_internal_error - internal_error - deadline_exceeded - already_exists - resource_exhausted - failed_precondition - aborted - out_of_range - unavailable - data_loss default: no_internal_error CheckResponse: type: object properties: allowed: type: boolean example: true resolution: type: string description: For internal use only. Leaf: type: object properties: users: $ref: '#/definitions/Users' computed: $ref: '#/definitions/Computed' tupleToUserset: $ref: '#/definitions/UsersetTree.TupleToUserset' 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." ContextualTupleKeys: type: object properties: tuple_keys: type: array items: type: object $ref: '#/definitions/TupleKey' maxItems: 100 required: - tuple_keys ExpandRequestTupleKey: type: object properties: relation: type: string example: reader maxLength: 50 object: type: string example: document:2021-budget maxLength: 256 required: - relation - object BatchCheckSingleResult: type: object properties: allowed: type: boolean error: $ref: '#/definitions/CheckError' AbortedMessageResponse: type: object example: code: '10' message: transaction conflict properties: code: type: string message: type: string UsersetUser: type: object properties: type: type: string example: group id: type: string example: fga relation: type: string example: member description: 'Userset. A set or group of users, represented in the `:#` format `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. See: https://openfga.dev/docs/modeling/building-blocks/usersets#what-is-a-userset' required: - type - id - relation ListObjectsResponse: type: object properties: objects: type: array example: - document:roadmap - document:planning items: type: string required: - objects AuthErrorCode: type: string enum: - no_auth_error - auth_failed_invalid_subject - auth_failed_invalid_audience - auth_failed_invalid_issuer - invalid_claims - auth_failed_invalid_bearer_token - bearer_token_missing - unauthenticated - forbidden default: no_auth_error Computed: type: object properties: userset: type: string required: - userset CheckRequestTupleKey: type: object properties: user: type: string example: user:anne maxLength: 512 relation: type: string example: reader maxLength: 50 object: type: string example: document:2021-budget maxLength: 256 required: - user - relation - object Node: type: object properties: name: type: string leaf: $ref: '#/definitions/Leaf' difference: $ref: '#/definitions/UsersetTree.Difference' union: $ref: '#/definitions/Nodes' intersection: $ref: '#/definitions/Nodes' required: - name BatchCheckItem: type: object properties: tuple_key: $ref: '#/definitions/CheckRequestTupleKey' contextual_tuples: $ref: '#/definitions/ContextualTupleKeys' context: type: object correlation_id: type: string example: 1cd93d8c-8e45-43c6-9a15-cbb3c7f394bc description: correlation_id must be a string containing only letters, numbers, or hyphens, with length ≤ 36 characters. required: - tuple_key - correlation_id Any: type: object properties: '@type': type: string additionalProperties: {} ConsistencyPreference: type: string enum: - UNSPECIFIED - MINIMIZE_LATENCY - HIGHER_CONSISTENCY 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." example: MINIMIZE_LATENCY Users: type: object properties: users: type: array items: type: string required: - users NotFoundErrorCode: type: string enum: - no_not_found_error - undefined_endpoint - store_id_not_found - unimplemented default: no_not_found_error User: type: object properties: object: $ref: '#/definitions/Object' userset: $ref: '#/definitions/UsersetUser' wildcard: $ref: '#/definitions/TypedWildcard' description: 'User. Represents any possible value for a user (subject or principal). Can be a: - Specific user object e.g.: ''user:will'', ''folder:marketing'', ''org:contoso'', ...) - Specific userset (e.g. ''group:engineering#member'') - Public-typed wildcard (e.g. ''user:*'') See https://openfga.dev/docs/concepts#what-is-a-user' ExpandResponse: type: object properties: tree: $ref: '#/definitions/UsersetTree' Status: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: type: object $ref: '#/definitions/Any' Nodes: type: object properties: nodes: type: array items: type: object $ref: '#/definitions/Node' required: - nodes ValidationErrorMessageResponse: type: object example: code: validation_error message: Generic validation error properties: code: $ref: '#/definitions/ErrorCode' message: type: string UnprocessableContentMessageResponse: type: object example: code: throttled_timeout_error message: timeout due to throttling on complex request properties: code: $ref: '#/definitions/UnprocessableContentErrorCode' message: type: string ErrorCode: type: string 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 - invalid_start_time default: no_error ForbiddenResponse: type: object example: code: forbidden message: the principal is not authorized to perform the action properties: code: $ref: '#/definitions/AuthErrorCode' message: type: string InternalErrorMessageResponse: type: object example: code: internal_error message: Internal Server Error properties: code: $ref: '#/definitions/InternalErrorCode' message: type: string TypedWildcard: type: object properties: type: type: string example: employee description: 'Type bound public access. Normally represented using the `:*` syntax `employee:*` represents every object of type `employee`, including those not currently present in the system See https://openfga.dev/docs/concepts#what-is-type-bound-public-access' required: - type UsersetTree: type: object properties: root: $ref: '#/definitions/Node' description: A UsersetTree contains the result of an Expansion. UnauthenticatedResponse: type: object example: code: unauthenticated message: unauthenticated properties: code: $ref: '#/definitions/ErrorCode' message: type: string BatchCheckResponse: type: object properties: result: type: object example: 1cd93d8c-8e45-43c6-9a15-cbb3c7f394bc: allowed: true error: message: '' additionalProperties: $ref: '#/definitions/BatchCheckSingleResult' description: map keys are the correlation_id values from the BatchCheckItems in the request CheckError: type: object properties: input_error: $ref: '#/definitions/ErrorCode' internal_error: $ref: '#/definitions/InternalErrorCode' message: type: string UsersetTree.TupleToUserset: type: object properties: tupleset: type: string computed: type: array items: type: object $ref: '#/definitions/Computed' required: - tupleset - computed Object: type: object properties: type: type: string example: document id: type: string example: 0bcdf6fa-a6aa-4730-a8eb-9cf172ff16d9 description: 'Object represents an OpenFGA Object. An Object is composed of a type and identifier (e.g. ''document:1'') See https://openfga.dev/docs/concepts#what-is-an-object' required: - type - id UsersetTree.Difference: type: object properties: base: $ref: '#/definitions/Node' subtract: $ref: '#/definitions/Node' required: - base - subtract StreamedListObjectsResponse: type: object properties: object: type: string example: document:roadmap description: The response for a StreamedListObjects RPC. required: - object ListUsersResponse: type: object properties: users: type: array items: type: object $ref: '#/definitions/User' required: - users UnprocessableContentErrorCode: type: string enum: - no_throttled_error_code - throttled_timeout_error default: no_throttled_error_code