OpenFGA Assertions API

swagger: '2.0'
info:
  title: OpenFGA Assertions API
  description: A high performance and flexible authorization/permission engine built for developers and inspired by Google Zanzibar.
  version: 1.x
  contact:
    name: OpenFGA
    url: https://openfga.dev
    email: community@openfga.dev
  license:
    name: Apache-2.0
    url: https://github.com/openfga/openfga/blob/main/LICENSE
schemes:
- https
consumes:
- application/json
produces:
- application/json
tags:
- name: Assertions
paths:
  /stores/{store_id}/assertions/{authorization_model_id}:
    get:
      summary: Read assertions for an authorization model ID
      description: 'The ReadAssertions API will return, for a given authorization model id, all the assertions stored for it. '
      operationId: ReadAssertions
      responses:
        '200':
          description: A successful response.
          schema:
            $ref: '#/definitions/ReadAssertionsResponse'
        '400':
          description: Request failed due to invalid input.
          schema:
            $ref: '#/definitions/ValidationErrorMessageResponse'
        '401':
          description: Not authenticated.
          schema:
            $ref: '#/definitions/UnauthenticatedResponse'
        '403':
          description: Forbidden.
          schema:
            $ref: '#/definitions/ForbiddenResponse'
        '404':
          description: Request failed due to incorrect path.
          schema:
            $ref: '#/definitions/PathUnknownErrorMessageResponse'
        '409':
          description: Request was aborted due a transaction conflict.
          schema:
            $ref: '#/definitions/AbortedMessageResponse'
        '422':
          description: Request timed out due to excessive request throttling.
          schema:
            $ref: '#/definitions/UnprocessableContentMessageResponse'
        '500':
          description: Request failed due to internal server error.
          schema:
            $ref: '#/definitions/InternalErrorMessageResponse'
      parameters:
      - name: store_id
        in: path
        required: true
        type: string
      - name: authorization_model_id
        in: path
        required: true
        type: string
      tags:
      - Assertions
    put:
      summary: Upsert assertions for an authorization model ID
      description: 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.
      operationId: WriteAssertions
      responses:
        '204':
          description: A successful response.
        '400':
          description: Request failed due to invalid input.
          schema:
            $ref: '#/definitions/ValidationErrorMessageResponse'
        '401':
          description: Not authenticated.
          schema:
            $ref: '#/definitions/UnauthenticatedResponse'
        '403':
          description: Forbidden.
          schema:
            $ref: '#/definitions/ForbiddenResponse'
        '404':
          description: Request failed due to incorrect path.
          schema:
            $ref: '#/definitions/PathUnknownErrorMessageResponse'
        '409':
          description: Request was aborted due a transaction conflict.
          schema:
            $ref: '#/definitions/AbortedMessageResponse'
        '422':
          description: Request timed out due to excessive request throttling.
          schema:
            $ref: '#/definitions/UnprocessableContentMessageResponse'
        '500':
          description: Request failed due to internal server error.
          schema:
            $ref: '#/definitions/InternalErrorMessageResponse'
      parameters:
      - name: store_id
        in: path
        required: true
        type: string
      - name: authorization_model_id
        in: path
        required: true
        type: string
      - name: body
        in: body
        required: true
        schema:
          type: object
          properties:
            assertions:
              type: array
              items:
                type: object
                $ref: '#/definitions/Assertion'
              maxItems: 100
          required:
          - assertions
      tags:
      - Assertions
definitions:
  TupleKey:
    type: object
    properties:
      user:
        type: string
        example: user:anne
        maxLength: 512
      relation:
        type: string
        example: reader
        maxLength: 50
      object:
        type: string
        example: document:2021-budget
        maxLength: 256
      condition:
        $ref: '#/definitions/RelationshipCondition'
    required:
    - user
    - relation
    - object
  AssertionTupleKey:
    type: object
    properties:
      object:
        type: string
        example: document:2021-budget
        maxLength: 256
      relation:
        type: string
        example: reader
        maxLength: 50
      user:
        type: string
        example: user:anne
        maxLength: 512
    required:
    - object
    - relation
    - user
  UnauthenticatedResponse:
    type: object
    example:
      code: unauthenticated
      message: unauthenticated
    properties:
      code:
        $ref: '#/definitions/ErrorCode'
      message:
        type: string
  NotFoundErrorCode:
    type: string
    enum:
    - no_not_found_error
    - undefined_endpoint
    - store_id_not_found
    - unimplemented
    default: no_not_found_error
  InternalErrorCode:
    type: string
    enum:
    - no_internal_error
    - internal_error
    - deadline_exceeded
    - already_exists
    - resource_exhausted
    - failed_precondition
    - aborted
    - out_of_range
    - unavailable
    - data_loss
    default: no_internal_error
  ErrorCode:
    type: string
    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
    default: no_error
  AbortedMessageResponse:
    type: object
    example:
      code: '10'
      message: transaction conflict
    properties:
      code:
        type: string
      message:
        type: string
  UnprocessableContentErrorCode:
    type: string
    enum:
    - no_throttled_error_code
    - throttled_timeout_error
    default: no_throttled_error_code
  ReadAssertionsResponse:
    type: object
    properties:
      authorization_model_id:
        type: string
        example: 01G5JAVJ41T49E9TT3SKVS7X1J
      assertions:
        type: array
        items:
          type: object
          $ref: '#/definitions/Assertion'
    required:
    - authorization_model_id
  ValidationErrorMessageResponse:
    type: object
    example:
      code: validation_error
      message: Generic validation error
    properties:
      code:
        $ref: '#/definitions/ErrorCode'
      message:
        type: string
  ForbiddenResponse:
    type: object
    example:
      code: forbidden
      message: the principal is not authorized to perform the action
    properties:
      code:
        $ref: '#/definitions/AuthErrorCode'
      message:
        type: string
  AuthErrorCode:
    type: string
    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
    default: no_auth_error
  InternalErrorMessageResponse:
    type: object
    example:
      code: internal_error
      message: Internal Server Error
    properties:
      code:
        $ref: '#/definitions/InternalErrorCode'
      message:
        type: string
  RelationshipCondition:
    type: object
    properties:
      name:
        type: string
        example: condition1
        description: A reference (by name) of the relationship condition defined in the authorization model.
        maxLength: 256
      context:
        type: object
        description: 'Additional context/data to persist along with the condition.

          The keys must match the parameters defined by the condition, and the value types must

          match the parameter type definitions.'
    required:
    - name
  Assertion:
    type: object
    properties:
      tuple_key:
        $ref: '#/definitions/AssertionTupleKey'
      expectation:
        type: boolean
      contextual_tuples:
        type: array
        items:
          type: object
          $ref: '#/definitions/TupleKey'
        maxItems: 20
      context:
        type: object
        example:
          view_count: 100
        description: 'Additional request context that will be used to evaluate any ABAC conditions encountered

          in the query evaluation.'
    required:
    - tuple_key
    - expectation
  PathUnknownErrorMessageResponse:
    type: object
    example:
      code: undefined_endpoint
      message: Endpoint not enabled
    properties:
      code:
        $ref: '#/definitions/NotFoundErrorCode'
      message:
        type: string
  UnprocessableContentMessageResponse:
    type: object
    example:
      code: throttled_timeout_error
      message: timeout due to throttling on complex request
    properties:
      code:
        $ref: '#/definitions/UnprocessableContentErrorCode'
      message:
        type: string