> ## 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] Evaluate whether a subject can perform an action on a resource

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

## Request Structure
The request requires three components:
- **subject**: The entity requesting access (e.g., a user or service)
- **action**: The operation being performed (maps to a relation in the authorization model)
- **resource**: The object being accessed

Each component has a `type` and `id` field, and may include optional `properties` for ABAC (Attribute-Based Access Control) conditions.

## Response
The response contains a `decision` field (boolean) indicating whether access is permitted, and an optional `context` object with additional information such as the evaluation ID or error details.

## ABAC Support
Properties on subject, action, and resource are automatically merged into the evaluation context with prefixes:
- Subject properties: `subject_<property_name>`
- Resource properties: `resource_<property_name>`
- Action properties: `action_<property_name>`

These merged properties can be used in conditions defined in your authorization model.

## Examples
### Basic authorization check
Check if user Anne can read a document:
```json
{
  "subject": {"type": "user", "id": "anne"},
  "action": {"name": "can_read"},
  "resource": {"type": "document", "id": "roadmap"}
}
```
Response when authorized:
```json
{
  "decision": true
}
```
### Using properties for ABAC
Check access with subject and resource attributes:
```json
{
  "subject": {
    "type": "user",
    "id": "anne",
    "properties": {"department": "engineering", "clearance_level": 3}
  },
  "action": {"name": "can_read"},
  "resource": {
    "type": "document",
    "id": "secret-project",
    "properties": {"classification": "confidential", "required_clearance": 2}
  }
}
```
### Using request context
Provide additional context for time-based or environmental conditions:
```json
{
  "subject": {"type": "user", "id": "bob"},
  "action": {"name": "can_access"},
  "resource": {"type": "system", "id": "production"},
  "context": {
    "current_time": "2024-01-15T14:30:00Z",
    "ip_address": "192.168.1.100",
    "is_vpn_connected": true
  }
}
```
### Specifying authorization model
Pin the evaluation to a specific authorization model version using the `Openfga-Authorization-Model-Id` header:
```
POST /stores/{store_id}/access/v1/evaluation
Openfga-Authorization-Model-Id: 01G50QVV17PECNVAHX1GG4Y5NC

{
  "subject": {"type": "user", "id": "anne"},
  "action": {"name": "can_write"},
  "resource": {"type": "document", "id": "budget-2024"}
}
```




## OpenAPI

````yaml https://raw.githubusercontent.com/openfga/api/refs/heads/main/docs/openapiv3/apidocs.openapi.json post /stores/{store_id}/access/v1/evaluation
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/evaluation:
    post:
      tags:
        - AuthZenService
      summary: >-
        [Experimental] Evaluate whether a subject can perform an action on a
        resource
      description: >
        [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.


        ## Request Structure

        The request requires three components:

        - **subject**: The entity requesting access (e.g., a user or service)

        - **action**: The operation being performed (maps to a relation in the
        authorization model)

        - **resource**: The object being accessed


        Each component has a `type` and `id` field, and may include optional
        `properties` for ABAC (Attribute-Based Access Control) conditions.


        ## Response

        The response contains a `decision` field (boolean) indicating whether
        access is permitted, and an optional `context` object with additional
        information such as the evaluation ID or error details.


        ## ABAC Support

        Properties on subject, action, and resource are automatically merged
        into the evaluation context with prefixes:

        - Subject properties: `subject_<property_name>`

        - Resource properties: `resource_<property_name>`

        - Action properties: `action_<property_name>`


        These merged properties can be used in conditions defined in your
        authorization model.


        ## Examples

        ### Basic authorization check

        Check if user Anne can read a document:

        ```json

        {
          "subject": {"type": "user", "id": "anne"},
          "action": {"name": "can_read"},
          "resource": {"type": "document", "id": "roadmap"}
        }

        ```

        Response when authorized:

        ```json

        {
          "decision": true
        }

        ```

        ### Using properties for ABAC

        Check access with subject and resource attributes:

        ```json

        {
          "subject": {
            "type": "user",
            "id": "anne",
            "properties": {"department": "engineering", "clearance_level": 3}
          },
          "action": {"name": "can_read"},
          "resource": {
            "type": "document",
            "id": "secret-project",
            "properties": {"classification": "confidential", "required_clearance": 2}
          }
        }

        ```

        ### Using request context

        Provide additional context for time-based or environmental conditions:

        ```json

        {
          "subject": {"type": "user", "id": "bob"},
          "action": {"name": "can_access"},
          "resource": {"type": "system", "id": "production"},
          "context": {
            "current_time": "2024-01-15T14:30:00Z",
            "ip_address": "192.168.1.100",
            "is_vpn_connected": true
          }
        }

        ```

        ### Specifying authorization model

        Pin the evaluation to a specific authorization model version using the
        `Openfga-Authorization-Model-Id` header:

        ```

        POST /stores/{store_id}/access/v1/evaluation

        Openfga-Authorization-Model-Id: 01G50QVV17PECNVAHX1GG4Y5NC


        {
          "subject": {"type": "user", "id": "anne"},
          "action": {"name": "can_write"},
          "resource": {"type": "document", "id": "budget-2024"}
        }

        ```
      operationId: Evaluation
      parameters:
        - in: path
          name: store_id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvaluationBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvaluationResponse'
          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/evaluation" \
              -H "content-type: application/json" \
              -d '{
              "subject": {
                "type": "user",
                "id": "anne"
              },
              "action": {
                "name": "reader"
              },
              "resource": {
                "type": "document",
                "id": "budget"
              }
            }'
components:
  schemas:
    EvaluationBody:
      properties:
        action:
          $ref: '#/components/schemas/Action'
        context:
          type: object
        resource:
          $ref: '#/components/schemas/Resource'
        subject:
          $ref: '#/components/schemas/Subject'
      required:
        - subject
        - resource
        - action
      type: object
    EvaluationResponse:
      properties:
        context:
          type: object
        decision:
          type: boolean
      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
    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
    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

````