{ "opencollection": "1.0.0", "info": { "name": "OpenFGA", "version": "1.x" }, "items": [ { "info": { "name": "AuthZenService", "type": "folder" }, "items": [ { "info": { "name": "[Experimental] Get AuthZEN PDP configuration and capabilities", "type": "http" }, "http": { "method": "GET", "url": "{{baseUrl}}/.well-known/authzen-configuration/:store_id", "params": [ { "name": "store_id", "value": "", "type": "path", "description": "The store ID for which to retrieve configuration.\nFollowing the AuthZEN spec's multi-tenant pattern, each store has its own discovery endpoint." } ] }, "docs": "[Experimental] The GetConfiguration API returns metadata about the Policy Decision Point (PDP) including its name, version, supported endpoints, and capabilities. This endpoint follows the AuthZEN specification for PDP discovery.\n\nFollowing the AuthZEN spec's multi-tenant pattern, OpenFGA provides a per-store discovery endpoint at `/.well-known/authzen-configuration/{store_id}`. This returns absolute endpoint URLs specific to that store.\n\n## Example Response\n```json\n{\n \"policy_decision_point\": " }, { "info": { "name": "[Experimental] Evaluate whether a subject can perform an action on a resource", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/stores/:store_id/access/v1/evaluation", "params": [ { "name": "store_id", "value": "", "type": "path" } ] }, "docs": "[Experimental] The Evaluation API determines whether a subject is authorized to perform an action on a resource. This endpoint implements the AuthZEN Access Evaluation API specification.\n\n## Request Structure\nThe request requires three components:\n- **subject**: The entity requesting access (e.g., a user or service)\n- **action**: The operation being performed (maps to a relation in the authorization model)\n- **resource**: The object being accessed\n\nEach component has a `type` and `id` field, and" }, { "info": { "name": "[Experimental] Check whether one or more users are authorized to access resources", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/stores/:store_id/access/v1/evaluations", "params": [ { "name": "store_id", "value": "", "type": "path" } ] }, "docs": "[Experimental] The Evaluations API allows batch authorization checks in a single request. It supports request-level defaults for subject, action, resource, and context that can be overridden per evaluation item.\n\n## Evaluation Semantics\nThe `options.evaluations_semantic` field controls how evaluations are processed:\n- `execute_all` (default): Execute all evaluations and return all results\n- `deny_on_first_deny`: Stop processing on first deny decision\n- `permit_on_first_permit`: Stop processing o" }, { "info": { "name": "[Experimental] Search for actions a subject can perform on a resource", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/stores/:store_id/access/v1/search/action", "params": [ { "name": "store_id", "value": "", "type": "path" } ] }, "docs": "[Experimental] The ActionSearch API returns all actions (relations) that a subject can perform on a specific resource. This is useful for answering questions like \"What can Anne do with this document?\" or building dynamic UIs that show only the actions a user is permitted to perform.\n\n## Examples\n### Find all actions a user can perform on a document\n```json\n{\n \"subject\": {\"type\": \"user\", \"id\": \"anne\"},\n \"resource\": {\"type\": \"document\", \"id\": \"roadmap\"}\n}\n```\nResponse:\n```json\n{\n \"results\": [\n" }, { "info": { "name": "[Experimental] Search for resources a subject has access to", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/stores/:store_id/access/v1/search/resource", "params": [ { "name": "store_id", "value": "", "type": "path" } ] }, "docs": "[Experimental] The ResourceSearch API returns all resources of a given type that a subject has a specific action (relation) on. This is useful for answering questions like \"What documents can Anne read?\" or \"What folders can Bob administer?\"\n\nThe resource type filter is required. Results support pagination for large result sets.\n\n## Examples\n### Find all documents a user can read\n```json\n{\n \"subject\": {\"type\": \"user\", \"id\": \"anne\"},\n \"action\": {\"name\": \"can_read\"},\n \"resource\": {\"type\": \"docu" }, { "info": { "name": "[Experimental] Search for subjects with access to a resource", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/stores/:store_id/access/v1/search/subject", "params": [ { "name": "store_id", "value": "", "type": "path" } ] }, "docs": "[Experimental] The SubjectSearch API returns all subjects that have a specific action (relation) on a given resource. This is useful for answering questions like \"Who can read this document?\" or \"Who can administer this folder?\"\n\nResults can be filtered by subject type and support pagination for large result sets.\n\n## Examples\n### Find all users who can read a document\n```json\n{\n \"resource\": {\"type\": \"document\", \"id\": \"roadmap\"},\n \"action\": {\"name\": \"can_read\"},\n \"subject\": {\"type\": \"user\"}\n}" } ] }, { "info": { "name": "Stores", "type": "folder" }, "items": [ { "info": { "name": "List all stores", "type": "http" }, "http": { "method": "GET", "url": "{{baseUrl}}/stores", "params": [ { "name": "page_size", "value": "", "type": "query" }, { "name": "continuation_token", "value": "", "type": "query" }, { "name": "name", "value": "", "type": "query", "description": "The name parameter instructs the API to only include results that match that name.Multiple results may be returned. Only exact matches will be returned; substring matches and regexes will not be evaluated" } ] }, "docs": "Returns a paginated list of OpenFGA stores and a continuation token to get additional stores.\nThe continuation token will be empty if there are no more stores.\n" }, { "info": { "name": "Create a store", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/stores" }, "docs": "Create a unique OpenFGA store which will be used to store authorization models and relationship tuples." }, { "info": { "name": "Get a store", "type": "http" }, "http": { "method": "GET", "url": "{{baseUrl}}/stores/:store_id", "params": [ { "name": "store_id", "value": "", "type": "path" } ] }, "docs": "Returns an OpenFGA store by its identifier" }, { "info": { "name": "Delete a store", "type": "http" }, "http": { "method": "DELETE", "url": "{{baseUrl}}/stores/:store_id", "params": [ { "name": "store_id", "value": "", "type": "path" } ] }, "docs": "Delete an OpenFGA store. This does not delete the data associated with the store, like tuples or authorization models." } ] }, { "info": { "name": "Assertions", "type": "folder" }, "items": [ { "info": { "name": "Read assertions for an authorization model ID", "type": "http" }, "http": { "method": "GET", "url": "{{baseUrl}}/stores/:store_id/assertions/:authorization_model_id", "params": [ { "name": "store_id", "value": "", "type": "path" }, { "name": "authorization_model_id", "value": "", "type": "path" } ] }, "docs": "The ReadAssertions API will return, for a given authorization model id, all the assertions stored for it. " }, { "info": { "name": "Upsert assertions for an authorization model ID", "type": "http" }, "http": { "method": "PUT", "url": "{{baseUrl}}/stores/:store_id/assertions/:authorization_model_id", "params": [ { "name": "store_id", "value": "", "type": "path" }, { "name": "authorization_model_id", "value": "", "type": "path" } ] }, "docs": "The WriteAssertions API will upsert new assertions for an authorization model id, or overwrite the existing ones. An assertion is an object that contains a tuple key, the expectation of whether a call to the Check API of that tuple key will return true or false, and optionally a list of contextual tuples." } ] }, { "info": { "name": "Authorization Models", "type": "folder" }, "items": [ { "info": { "name": "Return all the authorization models for a particular store", "type": "http" }, "http": { "method": "GET", "url": "{{baseUrl}}/stores/:store_id/authorization-models", "params": [ { "name": "store_id", "value": "", "type": "path" }, { "name": "page_size", "value": "", "type": "query" }, { "name": "continuation_token", "value": "", "type": "query" } ] }, "docs": "The ReadAuthorizationModels API will return all the authorization models for a certain store.\nOpenFGA's response will contain an array of all authorization models, sorted in descending order of creation.\n\n## Example\nAssume that a store's authorization model has been configured twice. To get all the authorization models that have been created in this store, call GET authorization-models. The API will return a response that looks like:\n```json\n{\n \"authorization_models\": [\n {\n \"id\": \"01G50" }, { "info": { "name": "Create a new authorization model", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/stores/:store_id/authorization-models", "params": [ { "name": "store_id", "value": "", "type": "path" } ] }, "docs": "The WriteAuthorizationModel API will add a new authorization model to a store.\nEach item in the `type_definitions` array is a type definition as specified in the field `type_definition`.\nThe response will return the authorization model's ID in the `id` field.\n\n## Example\nTo add an authorization model with `user` and `document` type definitions, call POST authorization-models API with the body: \n```json\n{\n \"type_definitions\":[\n {\n \"type\":\"user\"\n },\n {\n \"type\":\"document\",\n " }, { "info": { "name": "Return a particular version of an authorization model", "type": "http" }, "http": { "method": "GET", "url": "{{baseUrl}}/stores/:store_id/authorization-models/:id", "params": [ { "name": "store_id", "value": "", "type": "path" }, { "name": "id", "value": "", "type": "path" } ] }, "docs": "The ReadAuthorizationModel API returns an authorization model by its identifier.\nThe response will return the authorization model for the particular version.\n\n## Example\nTo retrieve the authorization model with ID `01G5JAVJ41T49E9TT3SKVS7X1J` for the store, call the GET authorization-models by ID API with `01G5JAVJ41T49E9TT3SKVS7X1J` as the `id` path parameter. The API will return:\n```json\n{\n \"authorization_model\":{\n \"id\":\"01G5JAVJ41T49E9TT3SKVS7X1J\",\n \"type_definitions\":[\n {\n " } ] }, { "info": { "name": "Relationship Queries", "type": "folder" }, "items": [ { "info": { "name": "Send a list of `check` operations in a single request", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/stores/:store_id/batch-check", "params": [ { "name": "store_id", "value": "", "type": "path" } ] }, "docs": "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 character" }, { "info": { "name": "Check whether a user is authorized to access an object", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/stores/:store_id/check", "params": [ { "name": "store_id", "value": "", "type": "path" } ] }, "docs": "The Check API returns whether a given user has a relationship with a given object in a given store.\nThe `user` field of the request can be a specific target, such as `user:anne`, or a userset (set of users) such as `group:marketing#member` or a type-bound public access `user:*`.\nTo arrive at a result, the API uses: an authorization model, explicit tuples written through the Write API, contextual tuples present in the request, and implicit tuples that exist by virtue of applying set theory (such " }, { "info": { "name": "Expand all relationships in userset tree format, and following userset rewrite rules. Useful to reason about and debug a certain relationship", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/stores/:store_id/expand", "params": [ { "name": "store_id", "value": "", "type": "path" } ] }, "docs": "The Expand API will return all users and usersets that have certain relationship with an object in a certain store.\nThis is different from the `/stores/{store_id}/read` API in that both users and computed usersets are returned.\nBody parameters `tuple_key.object` and `tuple_key.relation` are all required.\nA `contextual_tuples` object may also be included in the body of the request. This object contains one field `tuple_keys`, which is an array of tuple keys. Each of these tuples may have an assoc" }, { "info": { "name": "List all objects of the given type that the user has a relation with", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/stores/:store_id/list-objects", "params": [ { "name": "store_id", "value": "", "type": "path" } ] }, "docs": "The ListObjects API returns a list of all the objects of the given type that the user has a relation with.\n To arrive at a result, the API uses: an authorization model, explicit tuples written through the Write API, contextual tuples present in the request, and implicit tuples that exist by virtue of applying set theory (such as `document:2021-budget#viewer@document:2021-budget#viewer`; the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `docume" }, { "info": { "name": "List the users matching the provided filter who have a certain relation to a particular type.", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/stores/:store_id/list-users", "params": [ { "name": "store_id", "value": "", "type": "path" } ] }, "docs": "The ListUsers API returns a list of all the users of a specific type that have a relation to a given object.\n To arrive at a result, the API uses: an authorization model, explicit tuples written through the Write API, contextual tuples present in the request, and implicit tuples that exist by virtue of applying set theory (such as `document:2021-budget#viewer@document:2021-budget#viewer`; the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `docu" }, { "info": { "name": "Stream all objects of the given type that the user has a relation with", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/stores/:store_id/streamed-list-objects", "params": [ { "name": "store_id", "value": "", "type": "path" } ] }, "docs": "The Streamed ListObjects API is very similar to the the ListObjects API, with two differences: \n1. Instead of collecting all objects before returning a response, it streams them to the client as they are collected. \n2. The number of results returned is only limited by the execution timeout specified in the flag OPENFGA_LIST_OBJECTS_DEADLINE. \n" } ] }, { "info": { "name": "Relationship Tuples", "type": "folder" }, "items": [ { "info": { "name": "Return a list of all the tuple changes", "type": "http" }, "http": { "method": "GET", "url": "{{baseUrl}}/stores/:store_id/changes", "params": [ { "name": "store_id", "value": "", "type": "path" }, { "name": "type", "value": "", "type": "query" }, { "name": "page_size", "value": "", "type": "query" }, { "name": "continuation_token", "value": "", "type": "query" }, { "name": "start_time", "value": "", "type": "query", "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." } ] }, "docs": "The ReadChanges API will return a paginated list of tuple changes (additions and deletions) that occurred in a given store, sorted by ascending time. The response will include a continuation token that is used to get the next set of changes. If there are no changes after the provided continuation token, the same token will be returned in order for it to be used when new changes are recorded. If the store never had any tuples added or removed, this token will be empty.\nYou can use the `type` para" }, { "info": { "name": "Get tuples from the store that matches a query, without following userset rewrite rules", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/stores/:store_id/read", "params": [ { "name": "store_id", "value": "", "type": "path" } ] }, "docs": "The Read API will return the tuples for a certain store that match a query filter specified in the body of the request. \nThe API doesn't guarantee order by any field. \nIt is different from the `/stores/{store_id}/expand` API in that it only returns relationship tuples that are stored in the system and satisfy the query. \nIn the body:\n1. `tuple_key` is optional. If not specified, it will return all tuples in the store.\n2. `tuple_key.object` is mandatory if `tuple_key` is specified. It can be a fu" }, { "info": { "name": "Add or delete tuples from the store", "type": "http" }, "http": { "method": "POST", "url": "{{baseUrl}}/stores/:store_id/write", "params": [ { "name": "store_id", "value": "", "type": "path" } ] }, "docs": "The Write API will transactionally update the tuples for a certain store. Tuples and type definitions allow OpenFGA to determine whether a relationship exists between an object and an user.\nIn the body, `writes` adds new tuples and `deletes` removes existing tuples. When deleting a tuple, any `condition` specified with it is ignored.\nThe API is not idempotent by default: if, later on, you try to add the same tuple key (even if the `condition` is different), or if you try to delete a non-existing" } ] } ], "bundled": true }