> ## 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] Check whether one or more users are authorized to access resources

> [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.

## Evaluation Semantics
The `options.evaluations_semantic` field controls how evaluations are processed:
- `execute_all` (default): Execute all evaluations and return all results
- `deny_on_first_deny`: Stop processing on first deny decision
- `permit_on_first_permit`: Stop processing on first permit decision

When using `deny_on_first_deny` or `permit_on_first_permit`, the response may include fewer items than the request because processing short-circuits when the condition is met.

## Authorization Model Selection
To pin evaluations to a specific authorization model version, send the `Openfga-Authorization-Model-Id` header. If the header is not provided, the latest model is used.

## Examples
### Basic batch evaluation
Check if a user can perform multiple actions on a document:
```json
{
  "subject": {"type": "user", "id": "anne"},
  "resource": {"type": "document", "id": "roadmap"},
  "evaluations": [
    {"action": {"name": "can_read"}},
    {"action": {"name": "can_write"}},
    {"action": {"name": "can_delete"}}
  ]
}
```
### Using evaluation semantics
Stop on first permitted action (useful for finding any valid permission):
```json
{
  "subject": {"type": "user", "id": "anne"},
  "resource": {"type": "document", "id": "roadmap"},
  "evaluations": [
    {"action": {"name": "can_read"}},
    {"action": {"name": "can_write"}}
  ],
  "options": {
    "evaluations_semantic": "permit_on_first_permit"
  }
}
```
### Overriding defaults per evaluation
Check permissions across multiple resources:
```json
{
  "subject": {"type": "user", "id": "anne"},
  "action": {"name": "can_read"},
  "evaluations": [
    {"resource": {"type": "document", "id": "doc1"}},
    {"resource": {"type": "document", "id": "doc2"}},
    {"resource": {"type": "folder", "id": "folder1"}}
  ]
}
```




## OpenAPI

````yaml https://raw.githubusercontent.com/openfga/api/refs/heads/main/docs/openapiv3/apidocs.openapi.json post /stores/{store_id}/access/v1/evaluations
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/evaluations:
    post:
      tags:
        - AuthZenService
      summary: >-
        [Experimental] Check whether one or more users are authorized to access
        resources
      description: >
        [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.


        ## Evaluation Semantics

        The `options.evaluations_semantic` field controls how evaluations are
        processed:

        - `execute_all` (default): Execute all evaluations and return all
        results

        - `deny_on_first_deny`: Stop processing on first deny decision

        - `permit_on_first_permit`: Stop processing on first permit decision


        When using `deny_on_first_deny` or `permit_on_first_permit`, the
        response may include fewer items than the request because processing
        short-circuits when the condition is met.


        ## Authorization Model Selection

        To pin evaluations to a specific authorization model version, send the
        `Openfga-Authorization-Model-Id` header. If the header is not provided,
        the latest model is used.


        ## Examples

        ### Basic batch evaluation

        Check if a user can perform multiple actions on a document:

        ```json

        {
          "subject": {"type": "user", "id": "anne"},
          "resource": {"type": "document", "id": "roadmap"},
          "evaluations": [
            {"action": {"name": "can_read"}},
            {"action": {"name": "can_write"}},
            {"action": {"name": "can_delete"}}
          ]
        }

        ```

        ### Using evaluation semantics

        Stop on first permitted action (useful for finding any valid
        permission):

        ```json

        {
          "subject": {"type": "user", "id": "anne"},
          "resource": {"type": "document", "id": "roadmap"},
          "evaluations": [
            {"action": {"name": "can_read"}},
            {"action": {"name": "can_write"}}
          ],
          "options": {
            "evaluations_semantic": "permit_on_first_permit"
          }
        }

        ```

        ### Overriding defaults per evaluation

        Check permissions across multiple resources:

        ```json

        {
          "subject": {"type": "user", "id": "anne"},
          "action": {"name": "can_read"},
          "evaluations": [
            {"resource": {"type": "document", "id": "doc1"}},
            {"resource": {"type": "document", "id": "doc2"}},
            {"resource": {"type": "folder", "id": "folder1"}}
          ]
        }

        ```
      operationId: Evaluations
      parameters:
        - in: path
          name: store_id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvaluationsBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvaluationsResponse'
          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/evaluations" \
              -H "content-type: application/json" \
              -d '{
              "evaluations": [
                {
                  "subject": {
                    "type": "user",
                    "id": "anne"
                  },
                  "action": {
                    "name": "reader"
                  },
                  "resource": {
                    "type": "document",
                    "id": "budget"
                  }
                }
              ]
            }'
components:
  schemas:
    EvaluationsBody:
      properties:
        action:
          $ref: '#/components/schemas/Action'
        context:
          type: object
        evaluations:
          description: >-
            Optional. If omitted or empty, behaves like a single Access
            Evaluation request.
          items:
            allOf:
              - $ref: '#/components/schemas/EvaluationsItemRequest'
              - type: object
          type: array
        options:
          allOf:
            - $ref: '#/components/schemas/EvaluationsOptions'
            - title: Options for batch evaluation semantics
        resource:
          $ref: '#/components/schemas/Resource'
        subject:
          $ref: '#/components/schemas/Subject'
      type: object
    EvaluationsResponse:
      properties:
        evaluations:
          items:
            allOf:
              - $ref: '#/components/schemas/EvaluationResponse'
              - 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
    EvaluationsItemRequest:
      properties:
        action:
          $ref: '#/components/schemas/Action'
        context:
          type: object
        resource:
          $ref: '#/components/schemas/Resource'
        subject:
          $ref: '#/components/schemas/Subject'
      type: object
    EvaluationsOptions:
      properties:
        evaluations_semantic:
          allOf:
            - $ref: '#/components/schemas/EvaluationsSemantic'
            - title: Controls how batch evaluations are processed
      title: Options for batch evaluations
      type: object
    Resource:
      properties:
        id:
          example: roadmap
          type: string
        properties:
          type: object
        type:
          example: document
          type: string
      required:
        - type
        - id
      type: object
    Subject:
      properties:
        id:
          example: anne
          type: string
        properties:
          type: object
        type:
          example: user
          type: string
      required:
        - type
        - id
      type: object
    EvaluationResponse:
      properties:
        context:
          type: object
        decision:
          type: boolean
      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
    EvaluationsSemantic:
      default: execute_all
      description: |-
        - execute_all: Execute all evaluations (default behavior)
         - deny_on_first_deny: Stop on first deny decision
         - permit_on_first_permit: Stop on first permit decision
      enum:
        - execute_all
        - deny_on_first_deny
        - permit_on_first_permit
      title: Enum for evaluation semantics
      type: string

````