> ## Documentation Index > Fetch the complete documentation index at: https://openfga.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # [Experimental] Search for subjects with access to a resource > [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?" Results can be filtered by subject type and support pagination for large result sets. ## Examples ### Find all users who can read a document ```json { "resource": {"type": "document", "id": "roadmap"}, "action": {"name": "can_read"}, "subject": {"type": "user"} } ``` Response: ```json { "results": [ {"type": "user", "id": "anne"}, {"type": "user", "id": "bob"}, {"type": "user", "id": "charlie"} ], "page": {"count": 3} } ``` ### Paginated search with limit ```json { "resource": {"type": "folder", "id": "engineering"}, "action": {"name": "can_view"}, "subject": {"type": "user"}, "page": {"limit": 10} } ``` ### Continue from previous page ```json { "resource": {"type": "folder", "id": "engineering"}, "action": {"name": "can_view"}, "subject": {"type": "user"}, "page": {"token": "eyJsYXN0X2lkIjoiMTAwIn0=", "limit": 10} } ``` ## OpenAPI ````yaml https://raw.githubusercontent.com/openfga/api/refs/heads/main/docs/openapiv3/apidocs.openapi.json post /stores/{store_id}/access/v1/search/subject openapi: 3.0.3 info: contact: email: community@openfga.dev name: OpenFGA url: https://openfga.dev description: >- A high performance and flexible authorization/permission engine built for developers and inspired by Google Zanzibar. license: name: Apache-2.0 url: https://github.com/openfga/openfga/blob/main/LICENSE title: OpenFGA version: 1.x servers: [] security: [] tags: - name: AuthZenService - name: OpenFGAService paths: /stores/{store_id}/access/v1/search/subject: post: tags: - AuthZenService summary: '[Experimental] Search for subjects with access to a resource' description: > [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?" Results can be filtered by subject type and support pagination for large result sets. ## Examples ### Find all users who can read a document ```json { "resource": {"type": "document", "id": "roadmap"}, "action": {"name": "can_read"}, "subject": {"type": "user"} } ``` Response: ```json { "results": [ {"type": "user", "id": "anne"}, {"type": "user", "id": "bob"}, {"type": "user", "id": "charlie"} ], "page": {"count": 3} } ``` ### Paginated search with limit ```json { "resource": {"type": "folder", "id": "engineering"}, "action": {"name": "can_view"}, "subject": {"type": "user"}, "page": {"limit": 10} } ``` ### Continue from previous page ```json { "resource": {"type": "folder", "id": "engineering"}, "action": {"name": "can_view"}, "subject": {"type": "user"}, "page": {"token": "eyJsYXN0X2lkIjoiMTAwIn0=", "limit": 10} } ``` operationId: SubjectSearch parameters: - in: path name: store_id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/SubjectSearchBody' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SubjectSearchResponse' description: A successful response. '400': content: application/json: schema: $ref: '#/components/schemas/ValidationErrorMessageResponse' description: Request failed due to invalid input. '401': content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedResponse' description: Not authenticated. '403': content: application/json: schema: $ref: '#/components/schemas/ForbiddenResponse' description: Forbidden. '404': content: application/json: schema: $ref: '#/components/schemas/PathUnknownErrorMessageResponse' description: Request failed due to incorrect path. '409': content: application/json: schema: $ref: '#/components/schemas/AbortedMessageResponse' description: Request was aborted due a transaction conflict. '422': content: application/json: schema: $ref: '#/components/schemas/UnprocessableContentMessageResponse' description: Request timed out due to excessive request throttling. '500': content: application/json: schema: $ref: '#/components/schemas/InternalErrorMessageResponse' description: Request failed due to internal server error. x-codeSamples: - lang: bash label: curl source: >- # HTTP only: no named client or generated low-level operation in the audited SDK versions. # Set FGA_API_URL to the URL of your OpenFGA server. # Set FGA_STORE_ID to your store ID. # These examples use a server with authentication disabled. # For authenticated servers, see /docs/getting-started/setup-sdk-client. curl -X POST "$FGA_API_URL/stores/$FGA_STORE_ID/access/v1/search/subject" \ -H "content-type: application/json" \ -d '{ "subject": { "type": "user" }, "action": { "name": "reader" }, "resource": { "type": "document", "id": "budget" } }' components: schemas: SubjectSearchBody: properties: action: $ref: '#/components/schemas/Action' context: type: object page: $ref: '#/components/schemas/PageRequest' resource: $ref: '#/components/schemas/Resource' subject: allOf: - $ref: '#/components/schemas/SubjectFilter' - description: >- REQUIRED by AuthZEN Subject Search. Subject `id` may be provided but is ignored. required: - resource - action - subject title: SubjectSearch request type: object SubjectSearchResponse: properties: page: allOf: - $ref: '#/components/schemas/PageResponse' - title: Optional per AuthZEN spec - omit if pagination not supported results: items: allOf: - $ref: '#/components/schemas/Subject' - type: object type: array type: object ValidationErrorMessageResponse: example: code: validation_error message: Generic validation error properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string type: object UnauthenticatedResponse: example: code: unauthenticated message: unauthenticated properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string type: object ForbiddenResponse: example: code: forbidden message: the principal is not authorized to perform the action properties: code: $ref: '#/components/schemas/AuthErrorCode' message: type: string type: object PathUnknownErrorMessageResponse: example: code: undefined_endpoint message: Endpoint not enabled properties: code: $ref: '#/components/schemas/NotFoundErrorCode' message: type: string type: object AbortedMessageResponse: example: code: '10' message: transaction conflict properties: code: type: string message: type: string type: object UnprocessableContentMessageResponse: example: code: throttled_timeout_error message: timeout due to throttling on complex request properties: code: $ref: '#/components/schemas/UnprocessableContentErrorCode' message: type: string type: object InternalErrorMessageResponse: example: code: internal_error message: Internal Server Error properties: code: $ref: '#/components/schemas/InternalErrorCode' message: type: string type: object Action: properties: name: example: can_read type: string properties: type: object required: - name type: object PageRequest: properties: limit: format: int64 title: 'Maximum number of results to return (default: 50, max: 1000)' type: integer token: title: Continuation token from previous response type: string title: Pagination request parameters for search operations type: object Resource: properties: id: example: roadmap type: string properties: type: object type: example: document type: string required: - type - id type: object SubjectFilter: properties: id: description: >- Optional subject id. If present in Subject Search, it is ignored per AuthZEN spec. type: string properties: type: object type: example: user type: string required: - type title: SubjectFilter is used for search operations where only type is required type: object PageResponse: properties: count: format: int64 title: Number of results in this page type: integer next_token: title: Token to retrieve next page (empty if no more results) type: string total: format: int64 title: Total number of results (if known, otherwise 0) type: integer title: Pagination response parameters type: object Subject: properties: id: example: anne type: string properties: type: object type: example: user type: string required: - type - id type: object ErrorCode: default: no_error enum: - no_error - validation_error - authorization_model_not_found - authorization_model_resolution_too_complex - invalid_write_input - cannot_allow_duplicate_tuples_in_one_request - cannot_allow_duplicate_types_in_one_request - cannot_allow_multiple_references_to_one_relation - invalid_continuation_token - invalid_tuple_set - invalid_check_input - invalid_expand_input - unsupported_user_set - invalid_object_format - write_failed_due_to_invalid_input - authorization_model_assertions_not_found - latest_authorization_model_not_found - type_not_found - relation_not_found - empty_relation_definition - invalid_user - invalid_tuple - unknown_relation - store_id_invalid_length - assertions_too_many_items - id_too_long - authorization_model_id_too_long - tuple_key_value_not_specified - tuple_keys_too_many_or_too_few_items - page_size_invalid - param_missing_value - difference_base_missing_value - subtract_base_missing_value - object_too_long - relation_too_long - type_definitions_too_few_items - type_invalid_length - type_invalid_pattern - relations_too_few_items - relations_too_long - relations_invalid_pattern - object_invalid_pattern - query_string_type_continuation_token_mismatch - exceeded_entity_limit - invalid_contextual_tuple - duplicate_contextual_tuple - invalid_authorization_model - unsupported_schema_version - cancelled - invalid_start_time type: string AuthErrorCode: default: no_auth_error enum: - no_auth_error - auth_failed_invalid_subject - auth_failed_invalid_audience - auth_failed_invalid_issuer - invalid_claims - auth_failed_invalid_bearer_token - bearer_token_missing - unauthenticated - forbidden type: string NotFoundErrorCode: default: no_not_found_error enum: - no_not_found_error - undefined_endpoint - store_id_not_found - unimplemented type: string UnprocessableContentErrorCode: default: no_throttled_error_code enum: - no_throttled_error_code - throttled_timeout_error type: string 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 ````