{ "components": { "schemas": { "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" }, "maxItems": 20, "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" }, "AuthenticationErrorMessageResponse": { "example": { "code": "unauthorized_principal", "message": "Missing permissions to perform operation" }, "properties": { "code": { "$ref": "#/components/schemas/errormessages.AuthErrorCode" }, "message": { "type": "string" } }, "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": "array" } }, "required": [ "id", "schema_version", "type_definitions" ], "type": "object" }, "BatchCheckItem": { "properties": { "context": { "type": "object" }, "contextual_tuples": { "$ref": "#/components/schemas/ContextualTupleKeys" }, "correlation_id": { "description": "correlation_id must be a string containing only letters, numbers, or hyphens, with length ≤ 36 characters.", "example": "1cd93d8c-8e45-43c6-9a15-cbb3c7f394bc", "type": "string" }, "tuple_key": { "$ref": "#/components/schemas/CheckRequestTupleKey" } }, "required": [ "tuple_key", "correlation_id" ], "type": "object" }, "BatchCheckResponse": { "properties": { "result": { "additionalProperties": { "$ref": "#/components/schemas/BatchCheckSingleResult" }, "description": "map keys are the correlation_id values from the BatchCheckItems in the request", "example": { "1cd93d8c-8e45-43c6-9a15-cbb3c7f394bc": { "allowed": true, "error": { "message": "" } } }, "type": "object" } }, "type": "object" }, "BatchCheckSingleResult": { "properties": { "allowed": { "type": "boolean" }, "error": { "$ref": "#/components/schemas/CheckError" } }, "type": "object" }, "CheckError": { "properties": { "input_error": { "$ref": "#/components/schemas/v1.ErrorCode" }, "internal_error": { "$ref": "#/components/schemas/v1.InternalErrorCode" }, "message": { "type": "string" } }, "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": { "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" }, "parameters": { "additionalProperties": { "$ref": "#/components/schemas/ConditionParamTypeRef" }, "description": "A map of parameter names to the parameter's defined type reference.", "type": "object" } }, "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": "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" }, "maxItems": 100, "type": "array" } }, "required": [ "tuple_keys" ], "type": "object" }, "DirectUserset": { "description": "A DirectUserset is a sentinel message for referencing\nthe direct members specified by an object/relation mapping.", "type": "object" }, "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" }, "ExpansionOperation": { "default": "EXPANSION_OPERATION_UNSPECIFIED", "enum": [ "EXPANSION_OPERATION_UNSPECIFIED", "EXPANSION_OPERATION_INSERT", "EXPANSION_OPERATION_DELETE" ], "title": "Expansion operation type", "type": "string" }, "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" }, "ListUsersResponse": { "properties": { "users": { "items": { "$ref": "#/components/schemas/User" }, "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": "array" } }, "required": [ "nodes" ], "type": "object" }, "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" }, "ReadAssertionsResponse": { "properties": { "assertions": { "items": { "$ref": "#/components/schemas/Assertion" }, "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": "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": "array" }, "continuation_token": { "description": "The continuation token will be identical if there are no new changes.", "example": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==", "type": "string" } }, "required": [ "changes" ], "type": "object" }, "ReadExpansionsEvent": { "properties": { "as_fresh_as": { "description": "Freshness guarantee for this event. All tuple changes with timestamps strictly\nbefore this value have been fully materialized into the index.", "format": "date-time", "type": "string" }, "from": { "type": "string" }, "id": { "type": "string" }, "object_id": { "type": "string" }, "object_type": { "type": "string" }, "operation": { "$ref": "#/components/schemas/ExpansionOperation" }, "relation": { "type": "string" }, "subject_id": { "type": "string" }, "subject_relation": { "type": "string" }, "subject_type": { "type": "string" }, "tuple_written_at": { "description": "Deprecated: Use as_fresh_as instead. This field will be removed in a future release.", "format": "date-time", "type": "string" } }, "title": "Expansion event containing authorization data", "type": "object" }, "ReadExpansionsFreshness": { "properties": { "as_fresh_as": { "format": "date-time", "type": "string" } }, "title": "Freshness event indicating how up-to-date the index is", "type": "object" }, "ReadExpansionsHeartbeat": { "title": "Heartbeat message to keep connection alive while actively processing tuple changes", "type": "object" }, "ReadExpansionsResponse": { "properties": { "closed": { "$ref": "#/components/schemas/ReadExpansionsStreamClosed" }, "event": { "$ref": "#/components/schemas/ReadExpansionsEvent" }, "freshness": { "$ref": "#/components/schemas/ReadExpansionsFreshness" }, "heartbeat": { "$ref": "#/components/schemas/ReadExpansionsHeartbeat" } }, "title": "Response containing expansion events, heartbeats, or stream closed notifications", "type": "object" }, "ReadExpansionsStreamClosed": { "properties": { "reason": { "$ref": "#/components/schemas/StreamClosedReason" } }, "title": "Stream closed message indicating reason for closure", "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": "array" } }, "required": [ "tuples", "continuation_token" ], "type": "object" }, "RelationMetadata": { "properties": { "directly_related_user_types": { "items": { "$ref": "#/components/schemas/RelationReference" }, "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" }, "ResourceExhaustedErrorCode": { "default": "no_resource_exhausted_error", "description": "- no_resource_exhausted_error: no error\n - rate_limit_exceeded: operation failed due to exceeding rate limit.\n - auth_rate_limit_exceeded: rate limit error during authentication.", "enum": [ "no_resource_exhausted_error", "rate_limit_exceeded", "auth_rate_limit_exceeded" ], "title": "ResourceExhaustedErrorCodeEnums", "type": "string" }, "ResourceExhaustedErrorMessageResponse": { "example": { "code": "rate_limit_exceeded", "message": "Rate Limit exceeded" }, "properties": { "code": { "$ref": "#/components/schemas/ResourceExhaustedErrorCode" }, "message": { "type": "string" } }, "type": "object" }, "SearchStoreLogsResponse": { "properties": { "continuation_token": { "description": "The continuation token will be identical if there are no new changes.", "example": "eyJzdGFydF9vZmZzZXQiOiAwLCAibWF4X2hpdHMiOiAxMDB9==", "type": "string" }, "logs": { "items": { "type": "object" }, "type": "array" } }, "type": "object" }, "SourceInfo": { "properties": { "file": { "type": "string" } }, "type": "object" }, "Status": { "properties": { "code": { "format": "int32", "type": "integer" }, "details": { "items": { "$ref": "#/components/schemas/Any" }, "type": "array" }, "message": { "type": "string" } }, "type": "object" }, "StreamClosedReason": { "default": "STREAM_CLOSED_REASON_UNSPECIFIED", "enum": [ "STREAM_CLOSED_REASON_UNSPECIFIED", "STREAM_CLOSED_REASON_CONNECTION_LIFETIME_EXCEEDED" ], "title": "Stream closed reason", "type": "string" }, "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": { "allOf": [ { "$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" }, "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": "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": "array" } }, "required": [ "child" ], "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": { "on_missing": { "default": "error", "description": "On 'error', the API returns an error when deleting a tuple that does not exist. On 'ignore', deletes of non-existent tuples are treated as no-ops.", "enum": [ "error", "ignore" ], "example": "ignore", "type": "string" }, "tuple_keys": { "items": { "$ref": "#/components/schemas/TupleKeyWithoutCondition" }, "minItems": 1, "type": "array" } }, "required": [ "tuple_keys" ], "type": "object" }, "WriteRequestWrites": { "properties": { "on_duplicate": { "default": "error", "description": "On 'error' ( or unspecified ), the API returns an error if an identical tuple already exists. On 'ignore', identical writes are treated as no-ops (matching on user, relation, object, and RelationshipCondition).", "enum": [ "error", "ignore" ], "example": "ignore", "type": "string" }, "tuple_keys": { "items": { "$ref": "#/components/schemas/TupleKey" }, "minItems": 1, "type": "array" } }, "required": [ "tuple_keys" ], "type": "object" }, "WriteResponse": { "type": "object" }, "errormessages.AbortedMessageResponse": { "example": { "code": "10", "message": "transaction conflict" }, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "errormessages.AuthErrorCode": { "default": "no_auth_error", "description": "- no_auth_error: no error\n - auth_failure: generic authentication error. Details available via message field.\n - auth_failed_invalid_subject: authentication failure due to invalid subject.\n - auth_failed_invalid_audience: authentication failure due to invalid audience.\n - auth_failed_invalid_issuer: authentication failure due to invalid issuer.\n - invalid_claims: authentication failure due to invalid claims.\n - auth_failed_invalid_bearer_token: authentication failure due to invalid bearer token.\n - missing_customer_in_bearer_token: authentication failure with customer id missing in bearer token.\n - missing_store_in_bearer_token: authentication failure with store id missing in bearer token.\n - store_mismatch_in_bearer_token: authentication failure due to store mismatch from bearer token.\n - customer_mismatch_in_bearer_token: authentication failure due to customer id in the request being different from the customer id in the bearer token.\n - bearer_token_missing: bearer token missing in request.\n - unauthenticated: unauthenticated.\n - insufficient_permissions: insufficient permissions.\n - unauthorized_principal: authentication denial due to unauthorized principal.", "enum": [ "no_auth_error", "auth_failure", "auth_failed_invalid_subject", "auth_failed_invalid_audience", "auth_failed_invalid_issuer", "invalid_claims", "auth_failed_invalid_bearer_token", "missing_customer_in_bearer_token", "missing_store_in_bearer_token", "store_mismatch_in_bearer_token", "customer_mismatch_in_bearer_token", "bearer_token_missing", "unauthenticated", "insufficient_permissions", "unauthorized_principal" ], "title": "AuthErrorCodeEnums", "type": "string" }, "errormessages.ErrorCode": { "default": "no_error", "description": "- no_error: no error\n - validation_error: generic validation error.\n - authorization_model_not_found: authorization model not found.\n - authorization_model_resolution_too_complex: too many rewrite rules to be resolved.\n - invalid_write_input: invalid write input.\n - cannot_allow_duplicate_tuples_in_one_request: duplicate tuples in one request.\n - cannot_allow_duplicate_types_in_one_request: duplicate types in one request.\n - cannot_allow_multiple_references_to_one_relation: cannot use a relation to define itself.\n - invalid_continuation_token: invalid continuation token.\n - invalid_tuple_set: invalid tuple set.\n - invalid_check_input: invalid check input.\n - invalid_expand_input: invalid expand input.\n - unsupported_user_set: unsupported user set.\n - invalid_object_format: invalid object format.\n - token_issuer_already_registered: token issuers already registered.\n - write_failed_due_to_invalid_input: write request failed due to invalid input.\n - authorization_model_assertions_not_found: no assertions found for authorization model.\n - latest_authorization_model_not_found: latest authorization model not found.\n - type_not_found: type not found.\n - relation_not_found: relation not found.\n - empty_relation_definition: empty relation definition.\n - invalid_user: invalid user.\n - invalid_token_issuer: invalid token issuer.\n - invalid_tuple: invalid tuple.\n - unknown_relation: unknown relation.\n - store_id_invalid_length: store id has invalid length.\n - issuer_url_invalid_uri: issuer url has invalid URI.\n - issuer_url_required_absolute_path: issuer url is not absolute path.\n - assertions_too_many_items: assertions have too many items.\n - id_too_long: ID is too long.\n - invalid_environment: invalid environment is specified.\n - authorization_model_id_too_long: authorization model id is too long.\n - tuple_key_value_not_specified: tuple key value is not specified.\n - tuple_keys_too_many_or_too_few_items: tuple keys have too few or too many items.\n - page_size_invalid: page size is outside of acceptable range.\n - param_missing_value: params value is missing.\n - difference_base_missing_value: difference's base value is missing.\n - subtract_base_missing_value: subtract base value is missing.\n - object_too_long: object length is too long.\n - relation_too_long: relation length is too long.\n - type_definitions_too_few_items: type definitions do not have enough item.\n - type_invalid_length: type length is invalid.\n - type_invalid_pattern: type does not match expected pattern.\n - relations_too_few_items: relations have too few items.\n - relations_too_long: relations' length is too long.\n - relations_invalid_pattern: relations do not match expected pattern.\n - object_invalid_pattern: object does not match expected pattern.\n - query_string_type_continuation_token_mismatch: type in the query string and the continuation token don't match.\n - invalid_contextual_tuple: Invalid contextual tuple.\n - duplicate_contextual_tuple: Duplicate contextual tuple.", "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", "token_issuer_already_registered", "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_token_issuer", "invalid_tuple", "unknown_relation", "store_id_invalid_length", "issuer_url_invalid_uri", "issuer_url_required_absolute_path", "assertions_too_many_items", "id_too_long", "invalid_environment", "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", "invalid_contextual_tuple", "duplicate_contextual_tuple" ], "title": "ErrorCodeEnums", "type": "string" }, "errormessages.InternalErrorCode": { "default": "no_internal_error", "description": "- no_internal_error: no error\n - internal_error: generic internal error.\n - auth_internal_error: internal error due to authentication error.\n - auth_failed_error_fetching_well_known_jwks: authentication failure due to internal error in fetching well-known/jwks.json.\n - cancelled: internal error - request being cancelled.\n - deadline_exceeded: internal error - deadline exceeded.\n - already_exists: internal error - already exists.\n - resource_exhausted: internal error - resource exhausted.\n - failed_precondition: internal error - failed precondition.\n - aborted: internal error - aborted.\n - out_of_range: internal error - out of range.\n - unavailable: internal error - unavailable.\n - data_loss: internal error - data loss.", "enum": [ "no_internal_error", "internal_error", "auth_internal_error", "auth_failed_error_fetching_well_known_jwks", "cancelled", "deadline_exceeded", "already_exists", "resource_exhausted", "failed_precondition", "aborted", "out_of_range", "unavailable", "data_loss" ], "title": "InternalErrorCodeEnums", "type": "string" }, "errormessages.InternalErrorMessageResponse": { "example": { "code": "internal_error", "message": "Internal Server Error" }, "properties": { "code": { "$ref": "#/components/schemas/errormessages.InternalErrorCode" }, "message": { "type": "string" } }, "type": "object" }, "errormessages.NotFoundErrorCode": { "default": "no_not_found_error", "description": "- no_not_found_error: no error\n - undefined_endpoint: undefined endpoint.\n - store_id_not_found: store ID not found\n - resource_not_found: generic not found.\n - unimplemented: method is unimplemented", "enum": [ "no_not_found_error", "undefined_endpoint", "store_id_not_found", "resource_not_found", "unimplemented" ], "title": "NotFoundErrorCodeEnums", "type": "string" }, "errormessages.PathUnknownErrorMessageResponse": { "example": { "code": "undefined_endpoint", "message": "Endpoint not enabled" }, "properties": { "code": { "$ref": "#/components/schemas/errormessages.NotFoundErrorCode" }, "message": { "type": "string" } }, "type": "object" }, "errormessages.UnprocessableContentErrorCode": { "default": "no_throttled_error_code", "enum": [ "no_throttled_error_code", "throttled_timeout_error" ], "title": "- no_throttled_error_code: no error\n - throttled_timeout_error: 3500 level errors are timeout due to throttling", "type": "string" }, "errormessages.UnprocessableContentMessageResponse": { "example": { "code": "throttled_timeout_error", "message": "timeout due to throttling on complex request" }, "properties": { "code": { "$ref": "#/components/schemas/errormessages.UnprocessableContentErrorCode" }, "message": { "type": "string" } }, "type": "object" }, "errormessages.ValidationErrorMessageResponse": { "example": { "code": "validation_error", "message": "Generic validation error" }, "properties": { "code": { "$ref": "#/components/schemas/errormessages.ErrorCode" }, "message": { "type": "string" } }, "type": "object" }, "v1.Difference": { "properties": { "base": { "$ref": "#/components/schemas/Userset" }, "subtract": { "$ref": "#/components/schemas/Userset" } }, "required": [ "base", "subtract" ], "type": "object" }, "v1.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", "invalid_start_time" ], "type": "string" }, "v1.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" }, "v1.TupleToUserset": { "properties": { "computedUserset": { "$ref": "#/components/schemas/ObjectRelation" }, "tupleset": { "allOf": [ { "$ref": "#/components/schemas/ObjectRelation" }, { "title": "The target object/relation" } ] } }, "required": [ "tupleset", "computedUserset" ], "type": "object" } }, "securitySchemes": { "ClientCredentials": { "flows": { "clientCredentials": { "scopes": { "check:tuples": "Allows checking tuples", "create:stores": "Allows creation of stores", "delete:stores": "Allows deletion of stores", "expand:tuples": "Allows expanding tuples", "list:objects": "Allows reading results of list objects", "list:users": "Allows reading results of list users", "read:assertions": "Allows reading assertions", "read:authorization_models": "Allows reading authorization models", "read:changes": "Allows reading changes", "read:expansions": "Allows reading index expansions", "read:stores": "Allows reading of stores", "read:tuples": "Allows reading tuples", "search:logs": "Allows searching store logs", "write:assertions": "Allows updating assertions", "write:authorization_models": "Allows writing authorization models", "write:tuples": "Allows writing tuples" }, "tokenUrl": "https://auth.fga.dev/oauth/token" } }, "type": "oauth2" } } }, "info": { "contact": { "name": "Auth0", "url": "https://docs.fga.dev/support" }, "description": "Auth0 Fine-Grained Authorization (FGA) enables developers to design authorization models, from coarse grained to fine grained, in a way that's centralized, flexible, fast, scalable, and easy to use.", "title": "Auth0 Fine-Grained Authorization (FGA)", "version": "1" }, "openapi": "3.0.3", "paths": { "/stores/{store_id}/assertions/{authorization_model_id}": { "get": { "description": "The ReadAssertions API returns all the assertions stored for a given authorization model ID. An assertion is an object that contains a tuple key, and the expectation of whether a call to the Check API of that tuple key returns true or false.", "operationId": "ReadAssertions", "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/errormessages.ValidationErrorMessageResponse" } } }, "description": "Request failed due to invalid input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to authentication errors." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to forbidden permission." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.PathUnknownErrorMessageResponse" } } }, "description": "Request failed due to incorrect path." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.AbortedMessageResponse" } } }, "description": "Request was aborted due a transaction conflict." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.UnprocessableContentMessageResponse" } } }, "description": "Request timeout due to throttling on complex query." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedErrorMessageResponse" } } }, "description": "Request failed due to too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.InternalErrorMessageResponse" } } }, "description": "Request failed due to internal server error." } }, "security": [ { "ClientCredentials": [ "read:assertions" ] } ], "summary": "Get assertions for a model", "tags": [ "Assertions" ], "x-ratelimit": { "enterprise_basic_v1": "10 RPS", "free": "10 RPS" } }, "put": { "description": "The WriteAssertions API upserts new assertions for an authorization model ID, or overwrites the existing ones. An assertion is an object that contains a tuple key, and the expectation of whether a call to the Check API of that tuple key returns true or false.", "operationId": "WriteAssertions", "parameters": [ { "in": "path", "name": "store_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "authorization_model_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "assertions": { "items": { "$ref": "#/components/schemas/Assertion" }, "maxItems": 100, "type": "array" } }, "required": [ "assertions" ], "type": "object" } } }, "required": true }, "responses": { "204": { "description": "A successful response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.ValidationErrorMessageResponse" } } }, "description": "Request failed due to invalid input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to authentication errors." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to forbidden permission." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.PathUnknownErrorMessageResponse" } } }, "description": "Request failed due to incorrect path." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.AbortedMessageResponse" } } }, "description": "Request was aborted due a transaction conflict." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.UnprocessableContentMessageResponse" } } }, "description": "Request timeout due to throttling on complex query." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedErrorMessageResponse" } } }, "description": "Request failed due to too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.InternalErrorMessageResponse" } } }, "description": "Request failed due to internal server error." } }, "security": [ { "ClientCredentials": [ "write:assertions" ] } ], "summary": "Upsert assertions for a model", "tags": [ "Assertions" ], "x-ratelimit": { "enterprise_basic_v1": "10 RPM", "free": "10 RPM" } } }, "/stores/{store_id}/authorization-models": { "get": { "description": "The ReadAuthorizationModels API returns all the authorization models for a certain store.\nAuth0 FGA's response contains an array of all authorization models, sorted in descending order of creation.\n\n## Example\n\nAssume that a store's authorization model has been configured twice. To get all the authorization models that have been created in this store, call `GET authorization-models`. The API returns a response that looks like:\n```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 is empty:\n```json\n{\n \"authorization_models\": [\n {\n \"id\": \"01G50QVV17PECNVAHX1GG4Y5NC\",\n \"type_definitions\": [...]\n },\n {\n \"id\": \"01G4ZW8F4A07AKQ8RHSVG9RW04\",\n \"type_definitions\": [...]\n },\n ],\n \"continuation_token\": \"\"\n}\n```\n", "operationId": "ReadAuthorizationModels", "parameters": [ { "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/errormessages.ValidationErrorMessageResponse" } } }, "description": "Request failed due to invalid input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to authentication errors." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to forbidden permission." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.PathUnknownErrorMessageResponse" } } }, "description": "Request failed due to incorrect path." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.AbortedMessageResponse" } } }, "description": "Request was aborted due a transaction conflict." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.UnprocessableContentMessageResponse" } } }, "description": "Request timeout due to throttling on complex query." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedErrorMessageResponse" } } }, "description": "Request failed due to too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.InternalErrorMessageResponse" } } }, "description": "Request failed due to internal server error." } }, "security": [ { "ClientCredentials": [ "read:authorization_models" ] } ], "summary": "Get all authorization models", "tags": [ "Authorization Models" ], "x-ratelimit": { "enterprise_basic_v1": "30 RPM", "free": "30 RPM" } }, "post": { "description": "The WriteAuthorizationModel API adds a new authorization model to a store.\nEach item in the `type_definitions` array is a type definition as specified in the field `type_definition`.\nThe response returns the authorization model's ID in the `authorization_model_id` field.\n\n## Example\n\nTo add an authorization model with `user` and `document` type definitions, call the `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```\nAuth0 FGA's response includes the version ID for this authorization model, similar to:\n```json\n{\"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"}\n```\n", "operationId": "WriteAuthorizationModel", "parameters": [ { "in": "path", "name": "store_id", "required": true, "schema": { "type": "string" } } ], "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" }, "minItems": 1, "type": "array" } }, "required": [ "type_definitions", "schema_version" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WriteAuthorizationModelResponse" } } }, "description": "A successful response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.ValidationErrorMessageResponse" } } }, "description": "Request failed due to invalid input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to authentication errors." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to forbidden permission." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.PathUnknownErrorMessageResponse" } } }, "description": "Request failed due to incorrect path." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.AbortedMessageResponse" } } }, "description": "Request was aborted due a transaction conflict." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.UnprocessableContentMessageResponse" } } }, "description": "Request timeout due to throttling on complex query." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedErrorMessageResponse" } } }, "description": "Request failed due to too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.InternalErrorMessageResponse" } } }, "description": "Request failed due to internal server error." } }, "security": [ { "ClientCredentials": [ "write:authorization_models" ] } ], "summary": "Create a new authorization model", "tags": [ "Authorization Models" ], "x-ratelimit": { "enterprise_basic_v1": "10 RPM", "free": "10 RPM" } } }, "/stores/{store_id}/authorization-models/{id}": { "get": { "description": "The ReadAuthorizationModel API returns an authorization model by its identifier.\nThe response returns the authorization model for the particular ID.\n\nAuthorization models in Auth0 FGA are [immutable](https://docs.fga.dev/modeling/immutable-models). You can create new versions, but you cannot delete or modify existing ones.\n\n## Example\n\nTo retrieve the authorization model with ID `01G5JAVJ41T49E9TT3SKVS7X1J` for the store, call the `GET` authorization-models by ID API with `01G5JAVJ41T49E9TT3SKVS7X1J` as the `id` path parameter. The API returns:\n```json\n{\n \"authorization_model\":{\n \"id\":\"01G5JAVJ41T49E9TT3SKVS7X1J\",\n \"type_definitions\":[\n {\n \"type\":\"user\"\n },\n {\n \"type\":\"document\",\n \"relations\":{\n \"reader\":{\n \"union\":{\n \"child\":[\n {\n \"this\":{}\n },\n {\n \"computedUserset\":{\n \"object\":\"\",\n \"relation\":\"writer\"\n }\n }\n ]\n }\n },\n \"writer\":{\n \"this\":{}\n }\n }\n }\n ]\n }\n}\n```\nIn the above example, there are 2 types (`user` and `document`). The `document` type has 2 relations (`writer` and `reader`).", "operationId": "ReadAuthorizationModel", "parameters": [ { "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/errormessages.ValidationErrorMessageResponse" } } }, "description": "Request failed due to invalid input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to authentication errors." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to forbidden permission." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.PathUnknownErrorMessageResponse" } } }, "description": "Request failed due to incorrect path." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.AbortedMessageResponse" } } }, "description": "Request was aborted due a transaction conflict." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.UnprocessableContentMessageResponse" } } }, "description": "Request timeout due to throttling on complex query." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedErrorMessageResponse" } } }, "description": "Request failed due to too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.InternalErrorMessageResponse" } } }, "description": "Request failed due to internal server error." } }, "security": [ { "ClientCredentials": [ "read:authorization_models" ] } ], "summary": "Get an authorization model by its ID", "tags": [ "Authorization Models" ], "x-ratelimit": { "enterprise_basic_v1": "30 RPM", "free": "30 RPM" } } }, "/stores/{store_id}/batch-check": { "post": { "description": "The `BatchCheck` API functions nearly identically to `Check`, but instead of checking a single user-object relationship BatchCheck accepts a list of relationships to check and returns a map containing `BatchCheckItem` response for each check it received.\n\nAn associated `correlation_id` is required for each check in the batch. This ID is used to correlate a check to the appropriate response. It is a string consisting of only alphanumeric characters or hyphens with a maximum length of 36 characters. This `correlation_id` is used to map the result of each check to the item which was checked, so it must be unique for each item in the batch. We recommend using a UUID or ULID as the `correlation_id`, but you can use whatever unique identifier you need as long as it matches this regex pattern: `^[\\w\\d-]{1,36}$`\n\n> **Note:** The maximum number of checks that can be passed in a single `BatchCheck` request is 50. If `BatchCheck` is called using the SDK, the SDK can split the batch check requests for you.\n\nFor more details on how `Check` functions, review the [Check](https://docs.fga.dev/api/service/relationship-queries/check) docs.\n\n### Examples\n\n#### A BatchCheckRequest\n\n```json\n{\n \"checks\": [\n {\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n \"relation\": \"reader\",\n \"user\": \"user:anne\",\n },\n \"contextual_tuples\": {...}\n \"context\": {}\n \"correlation_id\": \"01JA8PM3QM7VBPGB8KMPK8SBD5\"\n },\n {\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n \"relation\": \"reader\",\n \"user\": \"user:bob\",\n },\n \"contextual_tuples\": {...}\n \"context\": {}\n \"correlation_id\": \"01JA8PMM6A90NV5ET0F28CYSZQ\"\n }\n ]\n}\n```\n\nBelow is a possible response to the above request. Note that the result map's keys are the `correlation_id` values from the checked items in the request:\n```json\n{\n \"result\": {\n \"01JA8PMM6A90NV5ET0F28CYSZQ\": {\n \"allowed\": false, \n \"error\": {\"message\": \"\"} \n },\n \"01JA8PM3QM7VBPGB8KMPK8SBD5\": {\n \"allowed\": true, \n \"error\": {\"message\": \"\"} \n }\n}\n```\n", "operationId": "BatchCheck", "parameters": [ { "in": "path", "name": "store_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "authorization_model_id": { "example": "01G5JAVJ41T49E9TT3SKVS7X1J", "type": "string" }, "checks": { "items": { "$ref": "#/components/schemas/BatchCheckItem" }, "minItems": 1, "type": "array" }, "consistency": { "$ref": "#/components/schemas/ConsistencyPreference" } }, "required": [ "checks" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCheckResponse" } } }, "description": "A successful response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.ValidationErrorMessageResponse" } } }, "description": "Request failed due to invalid input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to authentication errors." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to forbidden permission." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.PathUnknownErrorMessageResponse" } } }, "description": "Request failed due to incorrect path." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.AbortedMessageResponse" } } }, "description": "Request was aborted due a transaction conflict." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.UnprocessableContentMessageResponse" } } }, "description": "Request timeout due to throttling on complex query." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedErrorMessageResponse" } } }, "description": "Request failed due to too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.InternalErrorMessageResponse" } } }, "description": "Request failed due to internal server error." } }, "security": [ { "ClientCredentials": [ "check:tuples" ] } ], "summary": "Check multiple authorizations in a single request", "tags": [ "Relationship Queries" ], "x-ratelimit": "/sandcastle.v1.Auth0FGAService/Check" } }, "/stores/{store_id}/changes": { "get": { "description": "The ReadChanges API returns a paginated list of tuple changes (additions and deletions) that occurred in a given store, sorted by ascending time. The response includes a continuation token that is used to get the next set of changes. If there are no changes after the provided continuation token, the same token is returned so you can use it when new changes are recorded. If the store never had any tuples added or removed, this token is empty.\n\nYou can use the `type` parameter to only get the list of tuple changes that affect objects of that type.\nWhen reading a write tuple change, if it was conditioned, the condition is returned.\nWhen reading a delete tuple change, the condition is NOT returned regardless of whether it was originally conditioned or not.\n\n> **Note:** ReadChanges is rate limited per store. The limit depends on your plan. See [Subscription plans](https://docs.fga.dev/subscription-plans).", "operationId": "ReadChanges", "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" } }, { "description": "Start date and time of changes to read.\nFormat: ISO 8601 timestamp (e.g., 2022-01-01T00:00:00Z)\nIf a continuation_token is provided along side start_time, the continuation_token will take precedence over start_time.", "in": "query", "name": "start_time", "required": false, "schema": { "format": "date-time", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadChangesResponse" } } }, "description": "A successful response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.ValidationErrorMessageResponse" } } }, "description": "Request failed due to invalid input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to authentication errors." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to forbidden permission." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.PathUnknownErrorMessageResponse" } } }, "description": "Request failed due to incorrect path." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.AbortedMessageResponse" } } }, "description": "Request was aborted due a transaction conflict." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.UnprocessableContentMessageResponse" } } }, "description": "Request timeout due to throttling on complex query." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedErrorMessageResponse" } } }, "description": "Request failed due to too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.InternalErrorMessageResponse" } } }, "description": "Request failed due to internal server error." } }, "security": [ { "ClientCredentials": [ "read:changes" ] } ], "summary": "Get all tuple changes", "tags": [ "Relationship Tuples" ], "x-ratelimit": { "enterprise_basic_v1": "10 RPS", "free": "5 RPS" } } }, "/stores/{store_id}/check": { "post": { "description": "The Check API returns whether a given user has a relationship with a given object in a given store.\n\nThe `user` field of the request can be a specific target, such as `user:anne`, or a userset (set of users) such as `group:marketing#member` or a type-bound public access `user:*`.\n\nTo arrive at a result, the API uses:\n\n- An [authorization model](https://docs.fga.dev/fga-concepts#what-is-an-authorization-model)\n- Explicit tuples written through the Write API\n- Contextual tuples present in the request\n- Implicit tuples that exist by virtue of applying set theory\n\nFor example: `document:2021-budget#viewer@document:2021-budget#viewer`. In this example, the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n\nA `contextual_tuples` object may also be included in the body of the request. This object contains one field `tuple_keys`, which is an array of tuple keys. Each of these tuples may have an associated `condition`.\n\nYou may also provide an `authorization_model_id` in the body. This is used to assert that the input `tuple_key` is valid for the model specified. If not specified, the assertion is made against the latest authorization model ID.\n\n> **Note:** We recommend you specify an authorization model ID for better performance.\n\nYou may also provide a `context` object that is used to evaluate the conditioned tuples in the system.\n\n> **Note:** We recommend you provide a value for all the input parameters of all the conditions, to ensure that all tuples are evaluated correctly.\n\nBy default, the Check API caches results for a short time to optimize performance. You may specify a value of `HIGHER_CONSISTENCY` for the optional `consistency` parameter in the body to inform the server that higher consistency is preferred at the expense of increased latency. Consideration should be given to the increased latency if requesting higher consistency.\n\nThe response returns whether the relationship exists in the field `allowed`.\n\nSome exceptions apply, but in general, if a Check API responds with `{allowed: true}`, then you can expect the equivalent ListObjects query to return the object, and vice versa. \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\n## Examples\n\n### Querying with contextual tuples\n\nIn order to check if user `user:anne` of type `user` has a `reader` relationship with object `document:2021-budget` given the following contextual tuple:\n```json\n{\n \"user\": \"user:anne\",\n \"relation\": \"member\",\n \"object\": \"time_slot:office_hours\"\n}\n```\nthe Check API can be used with the following request body:\n```json\n{\n \"tuple_key\": {\n \"user\": \"user:anne\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"contextual_tuples\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:anne\",\n \"relation\": \"member\",\n \"object\": \"time_slot:office_hours\"\n }\n ]\n },\n \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n}\n```\n### Querying usersets\n\nSome Checks always return `true`, even without any tuples. For example, for the following authorization model:\n```python\nmodel\n schema 1.1\ntype user\ntype document\n relations\n define reader: [user]\n```\nthe following query:\n```json\n{\n \"tuple_key\": {\n \"user\": \"document:2021-budget#reader\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n }\n}\n```\nalways returns `{ \"allowed\": true }`. This is because usersets are self-defining: the userset `document:2021-budget#reader` always has the `reader` relation with `document:2021-budget`.\n\n### Querying usersets with difference in the model\n\nA Check for a userset can yield results that must be treated carefully if the model involves difference. For example, for the following authorization model:\n```python\nmodel\n schema 1.1\ntype user\ntype group\n relations\n define member: [user]\ntype document\n relations\n define blocked: [user]\n define reader: [group#member] but not blocked\n```\nthe following query:\n```json\n{\n \"tuple_key\": {\n \"user\": \"group:finance#member\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"contextual_tuples\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:anne\",\n \"relation\": \"member\",\n \"object\": \"group:finance\"\n },\n {\n \"user\": \"group:finance#member\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n {\n \"user\": \"user:anne\",\n \"relation\": \"blocked\",\n \"object\": \"document:2021-budget\"\n }\n ]\n },\n}\n```\nreturns `{ \"allowed\": true }`, even though a specific user of the userset `group:finance#member` does not have the `reader` relationship with the given object.\n\n### Requesting higher consistency\n\nBy default, the Check API caches results for a short time to optimize performance. You may request higher consistency to inform the server that higher consistency should be preferred at the expense of increased latency. Care should be taken when requesting higher consistency due to the increased latency.\n```json\n{\n \"tuple_key\": {\n \"user\": \"group:finance#member\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"consistency\": \"HIGHER_CONSISTENCY\"\n}\n```\n", "operationId": "Check", "parameters": [ { "in": "path", "name": "store_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "authorization_model_id": { "example": "01G5JAVJ41T49E9TT3SKVS7X1J", "type": "string" }, "consistency": { "allOf": [ { "$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 }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckResponse" } } }, "description": "A successful response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.ValidationErrorMessageResponse" } } }, "description": "Request failed due to invalid input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to authentication errors." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to forbidden permission." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.PathUnknownErrorMessageResponse" } } }, "description": "Request failed due to incorrect path." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.AbortedMessageResponse" } } }, "description": "Request was aborted due a transaction conflict." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.UnprocessableContentMessageResponse" } } }, "description": "Request timeout due to throttling on complex query." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedErrorMessageResponse" } } }, "description": "Request failed due to too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.InternalErrorMessageResponse" } } }, "description": "Request failed due to internal server error." } }, "security": [ { "ClientCredentials": [ "check:tuples" ] } ], "summary": "Check user authorization", "tags": [ "Relationship Queries" ], "x-ratelimit": { "enterprise_basic_v1": "500 RPS", "free": "20 RPS" } } }, "/stores/{store_id}/expand": { "post": { "description": "The Expand API returns all users and usersets that have certain relationship with an object in a certain store. Use it to reason about and debug a certain relationship.\n\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 both required.\nThe response returns a tree whose leaves are the specific users and usersets. Union, intersection and difference operator are located in the intermediate nodes.\n\n## Example\n\nTo expand all users that have the `reader` relationship with object `document:2021-budget`, use the Expand API with the following request body:\n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\",\n \"relation\": \"reader\"\n },\n \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n}\n```\nAuth0 FGA's response is a userset tree of the users and usersets that have read access to the document.\n```json\n{\n \"tree\":{\n \"root\":{\n \"type\":\"document:2021-budget#reader\",\n \"union\":{\n \"nodes\":[\n {\n \"type\":\"document:2021-budget#reader\",\n \"leaf\":{\n \"users\":{\n \"users\":[\n \"user:bob\"\n ]\n }\n }\n },\n {\n \"type\":\"document:2021-budget#reader\",\n \"leaf\":{\n \"computed\":{\n \"userset\":\"document:2021-budget#writer\"\n }\n }\n }\n ]\n }\n }\n }\n}\n```\nThe caller can then call Expand API for the `writer` relationship for the `document:2021-budget`.", "operationId": "Expand", "parameters": [ { "in": "path", "name": "store_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "authorization_model_id": { "example": "01G5JAVJ41T49E9TT3SKVS7X1J", "type": "string" }, "consistency": { "allOf": [ { "$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." } ] }, "contextual_tuples": { "$ref": "#/components/schemas/ContextualTupleKeys" }, "tuple_key": { "$ref": "#/components/schemas/ExpandRequestTupleKey" } }, "required": [ "tuple_key" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExpandResponse" } } }, "description": "A successful response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.ValidationErrorMessageResponse" } } }, "description": "Request failed due to invalid input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to authentication errors." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to forbidden permission." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.PathUnknownErrorMessageResponse" } } }, "description": "Request failed due to incorrect path." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.AbortedMessageResponse" } } }, "description": "Request was aborted due a transaction conflict." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.UnprocessableContentMessageResponse" } } }, "description": "Request timeout due to throttling on complex query." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedErrorMessageResponse" } } }, "description": "Request failed due to too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.InternalErrorMessageResponse" } } }, "description": "Request failed due to internal server error." } }, "security": [ { "ClientCredentials": [ "expand:tuples" ] } ], "summary": "Expand relationships in userset tree format", "tags": [ "Relationship Queries" ], "x-ratelimit": { "enterprise_basic_v1": "30 RPM", "free": "30 RPM" } } }, "/stores/{store_id}/indexes/{index_id}/expansions": { "get": { "description": "The ReadExpansions API streams pre-computed permission expansion events and index freshness events from a permissions index.\nEach expansion event represents the addition or removal of a resolved `(subject, relation, object)` tuple from the indexed FGA relationship.\nWhen called without a `from` cursor, the stream first delivers the full current set of expansion events, then continues emitting events as the underlying index is updated. When resuming a previously-closed stream, clients should provide a `from` cursor. The ReadExpansions API will resume streaming from that previously checkpointed position, without replaying the full history.\nClients must provide the ID of the expected authorization model via the `authorization_model_id` parameter.\nIn addition to expansion events, the stream emits:\n- Freshness events indicating how up-to-date the index is at a given point in the stream.\n- Periodic heartbeat messages to keep the connection alive.\n- A stream-closed message when the server terminates the connection, including the reason for closure.\nThe server will terminate streams periodically for traffic management. Clients must be prepared to reconnect in order to receive further expansions.\n### Event deduplication\nEach expansion event carries an `id` field. The same logical event always produces the same `id` regardless of how many times it is redelivered. Downstream consumers can use this field to deduplicate events.\n## Examples\n### Stream all expansions from the beginning\nTo stream all expansions for index `01YCP46JKYM8FJCQ37NMBYHE5X` in store `01G5JAVJ41T49E9TT3SKVS7X1J`, call the ReadExpansions API. The stream will emit events like\n```json\n{\n \"result\": {\n \"event\": {\n \"id\": \"051c6d4d930b2810aa92c4711b31629a\",\n \"from\": \"eyJpZCI6IjAxWUNQNDZKS1lNOEZKQ1EzN05NQllIRTVYIn0=\",\n \"subject_type\": \"user\",\n \"subject_id\": \"anne\",\n \"object_type\": \"document\",\n \"object_id\": \"2021-budget\",\n \"relation\": \"viewer\",\n \"operation\": \"EXPANSION_OPERATION_INSERT\",\n \"tuple_written_at\": \"2026-04-27T17:00:00Z\",\n \"as_fresh_as\": \"2026-04-27T17:00:00Z\"\n }\n }\n}\n{\n \"result\": {\n \"freshness\": {\n \"as_fresh_as\": \"2026-04-27T17:36:00.282718Z\"\n }\n }\n}\n{\n \"result\": {\n \"heartbeat\": {}\n }\n}\n{\n \"result\": {\n \"closed\": {\n \"reason\": \"STREAM_CLOSED_REASON_CONNECTION_LIFETIME_EXCEEDED\"\n }\n }\n}\n```\n### Resume a stream from a checkpoint\nTo resume streaming without replaying events already processed, pass the `from` cursor returned in the last received event. The stream will pick up from that position.\n", "operationId": "ReadExpansions", "parameters": [ { "in": "path", "name": "store_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "index_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "authorization_model_id", "required": true, "schema": { "type": "string" } }, { "description": "Optional continuation token for resuming stream", "in": "query", "name": "from", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "error": { "$ref": "#/components/schemas/Status" }, "result": { "$ref": "#/components/schemas/ReadExpansionsResponse" } }, "title": "Stream result of ReadExpansionsResponse", "type": "object" } } }, "description": "A successful response.(streaming responses)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.ValidationErrorMessageResponse" } } }, "description": "Request failed due to invalid input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to authentication errors." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to forbidden permission." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.PathUnknownErrorMessageResponse" } } }, "description": "Request failed due to incorrect path." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.AbortedMessageResponse" } } }, "description": "Request was aborted due a transaction conflict." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.UnprocessableContentMessageResponse" } } }, "description": "Request timeout due to throttling on complex query." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedErrorMessageResponse" } } }, "description": "Request failed due to too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.InternalErrorMessageResponse" } } }, "description": "Request failed due to internal server error." } }, "security": [ { "ClientCredentials": [ "read:expansions" ] } ], "summary": "Stream expansion events from a permissions index", "tags": [ "Permissions Index" ], "x-ratelimit": { "enterprise_basic_v1": "1 RPS", "free": "1 RPS" } } }, "/stores/{store_id}/list-objects": { "post": { "description": "The ListObjects API returns a list of all the objects of the given type that the user has a relation with.\n\nTo arrive at a result, the API uses:\n\n- An [authorization model](https://docs.fga.dev/fga-concepts#what-is-an-authorization-model)\n- Explicit tuples written through the Write API\n- Contextual tuples present in the request\n- Implicit tuples that exist by virtue of applying set theory\n\nFor example: `document:2021-budget#viewer@document:2021-budget#viewer`. In this example, the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n\nAn `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID is used.\n\n> **Note:** We recommend you specify an authorization model ID for better performance.\n\nYou may also specify `contextual_tuples` that are treated as regular tuples. Each of these tuples may have an associated `condition`.\n\nYou may also provide a `context` object that is used to evaluate the conditioned tuples in the system.\n\n> **Note:** We recommend you provide a value for all the input parameters of all the conditions, to ensure that all tuples are evaluated correctly.\n\nBy default, the ListObjects 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 consistency is preferred at the expense of increased latency. Consideration should be given to the increased latency if requesting higher consistency.\n\nThe response contains the related objects in an array in the \"objects\" field of the response, as strings in the object format `:` (e.g. \"document:roadmap\").\n\nThe number of objects in the response array is at most 10000, and is limited by an execution timeout of 3 seconds, whichever is hit first.\nThe objects given are not sorted, and therefore two identical calls can give a different set of objects.", "operationId": "ListObjects", "parameters": [ { "in": "path", "name": "store_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "authorization_model_id": { "example": "01G5JAVJ41T49E9TT3SKVS7X1J", "type": "string" }, "consistency": { "allOf": [ { "$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 }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListObjectsResponse" } } }, "description": "A successful response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.ValidationErrorMessageResponse" } } }, "description": "Request failed due to invalid input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to authentication errors." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to forbidden permission." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.PathUnknownErrorMessageResponse" } } }, "description": "Request failed due to incorrect path." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.AbortedMessageResponse" } } }, "description": "Request was aborted due a transaction conflict." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.UnprocessableContentMessageResponse" } } }, "description": "Request timeout due to throttling on complex query." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedErrorMessageResponse" } } }, "description": "Request failed due to too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.InternalErrorMessageResponse" } } }, "description": "Request failed due to internal server error." } }, "security": [ { "ClientCredentials": [ "list:objects" ] } ], "summary": "List objects a user is related to", "tags": [ "Relationship Queries" ], "x-ratelimit": { "enterprise_basic_v1": "20 RPS", "free": "10 RPM" } } }, "/stores/{store_id}/list-users": { "post": { "description": "The ListUsers API returns a list of all the users of a specific type that have a relation to a given object.\n\nTo arrive at a result, the API uses:\n\n- An [authorization model](https://docs.fga.dev/fga-concepts#what-is-an-authorization-model)\n- Explicit tuples written through the Write API\n- Contextual tuples present in the request\n- Implicit tuples that exist by virtue of applying set theory\n\nFor example: `document:2021-budget#viewer@document:2021-budget#viewer`. In this example, the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`.\n\nAn `authorization_model_id` may be specified in the body. If it is not specified, the latest authorization model ID is used.\n\n> **Note:** We recommend you specify an authorization model ID for better performance.\n\nYou may also specify `contextual_tuples` that are treated as regular tuples. Each of these tuples may have an associated `condition`.\n\nYou may also provide a `context` object that is used to evaluate the conditioned tuples in the system.\n\n> **Note:** We recommend you provide a value for all the input parameters of all the conditions, to ensure that all tuples are evaluated correctly.\n\nThe response contains the related users in an array in the \"users\" field of the response. These results may include specific objects, usersets or type-bound public access. Each of these types of results is encoded in its own type and not represented as a string.\n\nIn cases where a type-bound public access result is returned (e.g. `user:*`), it cannot be inferred that all subjects of that type have a relation to the object; it is possible that negations exist and checks should still be queried on individual subjects to ensure access to that document.\n\nThe number of users in the response array is at most 250, and is limited by an execution timeout of 3 seconds, whichever is hit first.\nThe users given are not sorted, and therefore two identical calls can give a different set of users.", "operationId": "ListUsers", "parameters": [ { "in": "path", "name": "store_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "authorization_model_id": { "example": "01G5JAVJ41T49E9TT3SKVS7X1J", "type": "string" }, "consistency": { "allOf": [ { "$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" }, "maxItems": 100, "type": "array" }, "object": { "allOf": [ { "$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" }, "maxItems": 1, "minItems": 1, "type": "array" } }, "required": [ "object", "relation", "user_filters" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUsersResponse" } } }, "description": "A successful response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.ValidationErrorMessageResponse" } } }, "description": "Request failed due to invalid input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to authentication errors." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to forbidden permission." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.PathUnknownErrorMessageResponse" } } }, "description": "Request failed due to incorrect path." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.AbortedMessageResponse" } } }, "description": "Request was aborted due a transaction conflict." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.UnprocessableContentMessageResponse" } } }, "description": "Request timeout due to throttling on complex query." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedErrorMessageResponse" } } }, "description": "Request failed due to too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.InternalErrorMessageResponse" } } }, "description": "Request failed due to internal server error." } }, "security": [ { "ClientCredentials": [ "list:users" ] } ], "summary": "List users related to an object", "tags": [ "Relationship Queries" ], "x-ratelimit": { "enterprise_basic_v1": "5 RPS", "free": "10 RPM" } } }, "/stores/{store_id}/logs": { "get": { "description": "The SearchStoreLogs API will return a paginated list of logs for a given store, sorted by ascending time. \nThe response will include a continuation token that is used to get the next set of logs. If there are no logs after the provided continuation token, the same token will be returned in order for it to be used when new logs are recorded. If the store never had any logs, this token will be empty.\nThe number of logs in the response array will be at most **100**.\n", "operationId": "SearchStoreLogs", "parameters": [ { "in": "path", "name": "store_id", "required": true, "schema": { "type": "string" } }, { "description": "Start time for the period of interest.\nISO 8601 (RFC3339) Date-Time Format in UTC. If not provided, defaults to 7 days (log retention period) before the current time. \nIf a `continuation_token` is provided along side `start_time`, the `continuation_token` will take precedence over `start_time`.", "in": "query", "name": "start_time", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "End time for the period of interest.\nISO 8601 (RFC3339) Date-Time Format in UTC. If not provided, defaults to the current time.\n", "in": "query", "name": "end_time", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "in": "query", "name": "page_size", "required": false, "schema": { "default": "50", "format": "int64", "type": "string" } }, { "in": "query", "name": "continuation_token", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "description": "Sort order for the logs returned. Defaults to `timestamp:1 which returns logs in ascending order (oldest logs first).`.", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchStoreLogsResponse" } } }, "description": "A successful response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.ValidationErrorMessageResponse" } } }, "description": "Request failed due to invalid input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to authentication errors." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to forbidden permission." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.PathUnknownErrorMessageResponse" } } }, "description": "Request failed due to incorrect path." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.AbortedMessageResponse" } } }, "description": "Request was aborted due a transaction conflict." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.UnprocessableContentMessageResponse" } } }, "description": "Request timeout due to throttling on complex query." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedErrorMessageResponse" } } }, "description": "Request failed due to too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.InternalErrorMessageResponse" } } }, "description": "Request failed due to internal server error." } }, "security": [ { "ClientCredentials": [ "search:logs" ] } ], "summary": "Search logs for a store.", "tags": [ "Logs" ], "x-ratelimit": { "enterprise_basic_v1": "8 RPS", "free": "1 RPS" } } }, "/stores/{store_id}/read": { "post": { "description": "The Read API returns the tuples from a certain store that match a query filter specified in the body of the request. \nThe API doesn't guarantee order by any field. \nIt is different from the `/stores/{store_id}/expand` API in that it only returns relationship tuples that are stored in the system and satisfy the query. \n\nIn the body:\n1. `tuple_key` is optional. If not specified, it returns all tuples in the store.\n2. `tuple_key.object` is mandatory if `tuple_key` is specified. It can be a full object (e.g., `type:object_id`) or type only (e.g., `type:`).\n3. `tuple_key.user` is mandatory if `tuple_key` is specified in the case the `tuple_key.object` is a type only.\n\n## Examples\n\n### Query for all objects in a type definition\n\nTo query for all objects that `user:bob` has `reader` relationship in the `document` type definition, call Read API with body of\n```json\n{\n \"tuple_key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:\"\n }\n}\n```\nThe API returns tuples and a continuation token, similar to:\n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis means that `user:bob` has a `reader` relationship with 1 document `document:2021-budget`. Note that this API, unlike the List Objects API, does not evaluate the tuples in the store.\nThe continuation token is empty if there are no more tuples to query.\n\n### Query for all stored relationship tuples that have a particular relation and object\n\nTo query for all users that have `reader` relationship with `document:2021-budget`, call Read API with body of \n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\",\n \"relation\": \"reader\"\n }\n}\n```\nThe API returns something similar to:\n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis means that `document:2021-budget` has 1 `reader` (`user:bob`). Note that, even if the model said that all `writers` are also `readers`, the API does not return writers such as `user:anne` because it only returns tuples and does not evaluate them.\n\n### Query for all users with all relationships for a particular document\n\nTo query for all users that have any relationship with `document:2021-budget`, call Read API with body of \n```json\n{\n \"tuple_key\": {\n \"object\": \"document:2021-budget\"\n }\n}\n```\nThe API returns something similar to:\n```json\n{\n \"tuples\": [\n {\n \"key\": {\n \"user\": \"user:anne\",\n \"relation\": \"writer\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-05T13:42:12.356Z\"\n },\n {\n \"key\": {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n },\n \"timestamp\": \"2021-10-06T15:32:11.128Z\"\n }\n ],\n \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nThis means that `document:2021-budget` has 1 `reader` (`user:bob`) and 1 `writer` (`user:anne`).\n", "operationId": "Read", "parameters": [ { "in": "path", "name": "store_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "consistency": { "allOf": [ { "$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", "maximum": 100, "minimum": 1, "type": "integer" }, "tuple_key": { "$ref": "#/components/schemas/ReadRequestTupleKey" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadResponse" } } }, "description": "A successful response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.ValidationErrorMessageResponse" } } }, "description": "Request failed due to invalid input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to authentication errors." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to forbidden permission." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.PathUnknownErrorMessageResponse" } } }, "description": "Request failed due to incorrect path." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.AbortedMessageResponse" } } }, "description": "Request was aborted due a transaction conflict." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.UnprocessableContentMessageResponse" } } }, "description": "Request timeout due to throttling on complex query." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedErrorMessageResponse" } } }, "description": "Request failed due to too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.InternalErrorMessageResponse" } } }, "description": "Request failed due to internal server error." } }, "security": [ { "ClientCredentials": [ "read:tuples" ] } ], "summary": "Get stored relationship tuples", "tags": [ "Relationship Tuples" ], "x-ratelimit": { "enterprise_basic_v1": "100 RPS", "free": "25 RPS" } } }, "/stores/{store_id}/streamed-list-objects": { "post": { "description": "The Streamed ListObjects API is very similar to the [ListObjects](https://docs.fga.dev/api/service/relationship-queries/list-objects) API, with two differences:\n\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 an execution timeout of 3 seconds.\n", "operationId": "StreamedListObjects", "parameters": [ { "in": "path", "name": "store_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "authorization_model_id": { "example": "01G5JAVJ41T49E9TT3SKVS7X1J", "type": "string" }, "consistency": { "allOf": [ { "$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 }, "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/errormessages.ValidationErrorMessageResponse" } } }, "description": "Request failed due to invalid input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to authentication errors." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to forbidden permission." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.PathUnknownErrorMessageResponse" } } }, "description": "Request failed due to incorrect path." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.AbortedMessageResponse" } } }, "description": "Request was aborted due a transaction conflict." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.UnprocessableContentMessageResponse" } } }, "description": "Request timeout due to throttling on complex query." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedErrorMessageResponse" } } }, "description": "Request failed due to too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.InternalErrorMessageResponse" } } }, "description": "Request failed due to internal server error." } }, "security": [ { "ClientCredentials": [ "list:objects" ] } ], "summary": "[EXPERIMENTAL] Stream objects a user is related to", "tags": [ "Relationship Queries" ], "x-ratelimit": { "enterprise_basic_v1": "20 RPS", "free": "10 RPM" } } }, "/stores/{store_id}/write": { "post": { "description": "The Write API transactionally updates the tuples for a certain store. Tuples and type definitions allow Auth0 FGA to determine whether a relationship exists between an object and a user.\n\nIn the body, `writes` adds new tuples and `deletes` removes existing tuples. When deleting a tuple, any `condition` specified with it is ignored.\n\nThe API is not idempotent by default: if, later on, you try to add the same tuple key (even if the `condition` is different), or if you try to delete a non-existing tuple, it throws an error.\n\nTo allow writes when an identical tuple already exists in the database, set `\"on_duplicate\": \"ignore\"` on the `writes` object.\nTo allow deletes when a tuple was already removed from the database, set `\"on_missing\": \"ignore\"` on the `deletes` object.\nIf a Write request contains both idempotent (ignore) and non-idempotent (error) operations, the most restrictive action (error) takes precedence. If a condition fails for a sub-request with an error flag, the entire transaction is rolled back. This gives developers explicit control over the atomicity of the requests.\n\nThe API does not allow you to write tuples such as `document:2021-budget#viewer@document:2021-budget#viewer`, because they are implicit.\n\nAn `authorization_model_id` may be specified in the body. If it is, it is used to assert that each written tuple (not deleted) is valid for the model specified. If it is not specified, the latest authorization model ID is used.\n\n> **Note:** Each Write API call allows at most **40** tuples.\n\n## Example\n\n### Adding relationships\n\nTo add `user:anne` as a `writer` for `document:2021-budget`, call Write API with the following:\n```json\n{\n \"writes\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:anne\",\n \"relation\": \"writer\",\n \"object\": \"document:2021-budget\"\n }\n ],\n \"on_duplicate\": \"ignore\"\n },\n \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"\n}\n```\n### Removing relationships\n\nTo remove `user:bob` as a `reader` for `document:2021-budget`, call Write API with the following:\n```json\n{\n \"deletes\": {\n \"tuple_keys\": [\n {\n \"user\": \"user:bob\",\n \"relation\": \"reader\",\n \"object\": \"document:2021-budget\"\n }\n ],\n \"on_missing\": \"ignore\"\n }\n}\n```\n", "operationId": "Write", "parameters": [ { "in": "path", "name": "store_id", "required": true, "schema": { "type": "string" } } ], "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 }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WriteResponse" } } }, "description": "A successful response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.ValidationErrorMessageResponse" } } }, "description": "Request failed due to invalid input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to authentication errors." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorMessageResponse" } } }, "description": "Request failed due to forbidden permission." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.PathUnknownErrorMessageResponse" } } }, "description": "Request failed due to incorrect path." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.AbortedMessageResponse" } } }, "description": "Request was aborted due a transaction conflict." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.UnprocessableContentMessageResponse" } } }, "description": "Request timeout due to throttling on complex query." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceExhaustedErrorMessageResponse" } } }, "description": "Request failed due to too many requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errormessages.InternalErrorMessageResponse" } } }, "description": "Request failed due to internal server error." } }, "security": [ { "ClientCredentials": [ "write:tuples" ] } ], "summary": "Add or delete tuples", "tags": [ "Relationship Tuples" ], "x-ratelimit": { "enterprise_basic_v1": "150 RPS", "free": "20 RPS" } } } }, "tags": [ { "name": "Auth0FGAService" } ] }