OpenFGA Authorization Models API

openapi: 3.2.0
info:
  title: OpenFGA Assertions Authorization Models 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
tags:
- name: Authorization Models
paths:
  /stores/{store_id}/authorization-models:
    get:
      summary: Return all the authorization models for a particular store
      description: "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\": \"01G50QVV17PECNVAHX1GG4Y5NC\",\n      \"type_definitions\": [...]\n    },\n    {\n      \"id\": \"01G4ZW8F4A07AKQ8RHSVG9RW04\",\n      \"type_definitions\": [...]\n    },\n  ],\n  \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\"\n}\n```\nIf there are no more authorization models available, the `continuation_token` field will be empty\n```json\n{\n  \"authorization_models\": [\n    {\n      \"id\": \"01G50QVV17PECNVAHX1GG4Y5NC\",\n      \"type_definitions\": [...]\n    },\n    {\n      \"id\": \"01G4ZW8F4A07AKQ8RHSVG9RW04\",\n      \"type_definitions\": [...]\n    },\n  ],\n  \"continuation_token\": \"\"\n}\n```\n"
      operationId: ReadAuthorizationModels
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadAuthorizationModelsResponse'
        '400':
          description: Request failed due to invalid input.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorMessageResponse'
        '401':
          description: Not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthenticatedResponse'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
        '404':
          description: Request failed due to incorrect path.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PathUnknownErrorMessageResponse'
        '409':
          description: Request was aborted due a transaction conflict.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AbortedMessageResponse'
        '422':
          description: Request timed out due to excessive request throttling.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableContentMessageResponse'
        '500':
          description: Request failed due to internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalErrorMessageResponse'
      parameters:
      - name: store_id
        in: path
        required: true
        schema:
          type: string
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          format: int32
      - name: continuation_token
        in: query
        required: false
        schema:
          type: string
      tags:
      - Authorization Models
    post:
      summary: Create a new authorization model
      description: "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      \"relations\":{\n        \"reader\":{\n          \"union\":{\n            \"child\":[\n              {\n                \"this\":{}\n              },\n              {\n                \"computedUserset\":{\n                  \"object\":\"\",\n                  \"relation\":\"writer\"\n                }\n              }\n            ]\n          }\n        },\n        \"writer\":{\n          \"this\":{}\n        }\n      }\n    }\n  ]\n}\n```\nOpenFGA's response will include the version id for this authorization model, which will look like \n```\n{\"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"}\n```\n"
      operationId: WriteAuthorizationModel
      responses:
        '201':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WriteAuthorizationModelResponse'
        '400':
          description: Request failed due to invalid input.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorMessageResponse'
        '401':
          description: Not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthenticatedResponse'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
        '404':
          description: Request failed due to incorrect path.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PathUnknownErrorMessageResponse'
        '409':
          description: Request was aborted due a transaction conflict.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AbortedMessageResponse'
        '422':
          description: Request timed out due to excessive request throttling.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableContentMessageResponse'
        '500':
          description: Request failed due to internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalErrorMessageResponse'
      parameters:
      - name: store_id
        in: path
        required: true
        schema:
          type: string
      tags:
      - Authorization Models
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type_definitions:
                  type: array
                  items:
                    type: object
                    $ref: '#/components/schemas/TypeDefinition'
                  minItems: 1
                schema_version:
                  type: string
                conditions:
                  type: object
                  additionalProperties:
                    $ref: '#/components/schemas/Condition'
              required:
              - type_definitions
              - schema_version
        required: true
  /stores/{store_id}/authorization-models/{id}:
    get:
      summary: Return a particular version of an authorization model
      description: "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        \"type\":\"user\"\n      },\n      {\n        \"type\":\"document\",\n        \"relations\":{\n          \"reader\":{\n            \"union\":{\n              \"child\":[\n                {\n                  \"this\":{}\n                },\n                {\n                  \"computedUserset\":{\n                    \"object\":\"\",\n                    \"relation\":\"writer\"\n                  }\n                }\n              ]\n            }\n          },\n          \"writer\":{\n            \"this\":{}\n          }\n        }\n      }\n    ]\n  }\n}\n```\nIn the above example, there are 2 types (`user` and `document`). The `document` type has 2 relations (`writer` and `reader`)."
      operationId: ReadAuthorizationModel
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadAuthorizationModelResponse'
        '400':
          description: Request failed due to invalid input.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorMessageResponse'
        '401':
          description: Not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthenticatedResponse'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
        '404':
          description: Request failed due to incorrect path.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PathUnknownErrorMessageResponse'
        '409':
          description: Request was aborted due a transaction conflict.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AbortedMessageResponse'
        '422':
          description: Request timed out due to excessive request throttling.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableContentMessageResponse'
        '500':
          description: Request failed due to internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalErrorMessageResponse'
      parameters:
      - name: store_id
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      tags:
      - Authorization Models
components:
  schemas:
    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
    v1.TupleToUserset:
      type: object
      properties:
        tupleset:
          $ref: '#/components/schemas/ObjectRelation'
          title: The target object/relation
        computedUserset:
          $ref: '#/components/schemas/ObjectRelation'
      required:
      - tupleset
      - computedUserset
    TypeName:
      type: string
      enum:
      - TYPE_NAME_UNSPECIFIED
      - TYPE_NAME_ANY
      - TYPE_NAME_BOOL
      - TYPE_NAME_STRING
      - TYPE_NAME_INT
      - TYPE_NAME_UINT
      - TYPE_NAME_DOUBLE
      - TYPE_NAME_DURATION
      - TYPE_NAME_TIMESTAMP
      - TYPE_NAME_MAP
      - TYPE_NAME_LIST
      - TYPE_NAME_IPADDRESS
      default: TYPE_NAME_UNSPECIFIED
    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
    Condition:
      type: object
      properties:
        name:
          type: string
          title: A unique name for the condition
        expression:
          type: string
          description: A Google CEL expression, expressed as a string.
        parameters:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ConditionParamTypeRef'
          description: A map of parameter names to the parameter's defined type reference.
        metadata:
          $ref: '#/components/schemas/ConditionMetadata'
      required:
      - name
      - expression
    UnprocessableContentMessageResponse:
      type: object
      example:
        code: throttled_timeout_error
        message: timeout due to throttling on complex request
      properties:
        code:
          $ref: '#/components/schemas/UnprocessableContentErrorCode'
        message:
          type: string
    Usersets:
      type: object
      properties:
        child:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/Userset'
      required:
      - child
    PathUnknownErrorMessageResponse:
      type: object
      example:
        code: undefined_endpoint
        message: Endpoint not enabled
      properties:
        code:
          $ref: '#/components/schemas/NotFoundErrorCode'
        message:
          type: string
    SourceInfo:
      type: object
      properties:
        file:
          type: string
    InternalErrorMessageResponse:
      type: object
      example:
        code: internal_error
        message: Internal Server Error
      properties:
        code:
          $ref: '#/components/schemas/InternalErrorCode'
        message:
          type: string
    ConditionParamTypeRef:
      type: object
      properties:
        type_name:
          $ref: '#/components/schemas/TypeName'
        generic_types:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/ConditionParamTypeRef'
      required:
      - type_name
    ObjectRelation:
      type: object
      properties:
        object:
          type: string
        relation:
          type: string
    NotFoundErrorCode:
      type: string
      enum:
      - no_not_found_error
      - undefined_endpoint
      - store_id_not_found
      - unimplemented
      default: no_not_found_error
    AuthorizationModel:
      type: object
      properties:
        id:
          type: string
          example: 01G5JAVJ41T49E9TT3SKVS7X1J
        schema_version:
          type: string
        type_definitions:
          type: array
          example:
          - type: user
          - type: document
            relations:
              reader:
                union:
                  child:
                  - this: {}
                  - computedUserset:
                      object: ''
                      relation: writer
              writer:
                this: {}
            metadata:
              relations:
                reader:
                  directly_related_user_types:
                  - type: user
                writer:
                  directly_related_user_types:
                  - type: user
          items:
            type: object
            $ref: '#/components/schemas/TypeDefinition'
        conditions:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Condition'
      required:
      - id
      - schema_version
      - type_definitions
    TypeDefinition:
      type: object
      properties:
        type:
          type: string
          example: document
        relations:
          type: object
          example:
            reader:
              union:
                child:
                - this: {}
                - computedUserset:
                    object: ''
                    relation: writer
            writer:
              this: {}
          additionalProperties:
            $ref: '#/components/schemas/Userset'
        metadata:
          $ref: '#/components/schemas/Metadata'
          description: 'A map whose keys are the name of the relation and whose value is the Metadata for that relation.

            It also holds information around the module name and source file if this model was constructed

            from a modular model.'
      required:
      - type
    WriteAuthorizationModelResponse:
      type: object
      properties:
        authorization_model_id:
          type: string
          example: 01G5JAVJ41T49E9TT3SKVS7X1J
      required:
      - authorization_model_id
    ReadAuthorizationModelsResponse:
      type: object
      properties:
        authorization_models:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/AuthorizationModel'
        continuation_token:
          type: string
          example: eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==
          description: The continuation token will be empty if there are no more models.
      required:
      - authorization_models
    Wildcard:
      type: object
    Userset:
      type: object
      properties:
        this:
          $ref: '#/components/schemas/DirectUserset'
        computedUserset:
          $ref: '#/components/schemas/ObjectRelation'
        tupleToUserset:
          $ref: '#/components/schemas/v1.TupleToUserset'
        union:
          $ref: '#/components/schemas/Usersets'
        intersection:
          $ref: '#/components/schemas/Usersets'
        difference:
          $ref: '#/components/schemas/v1.Difference'
    RelationMetadata:
      type: object
      properties:
        directly_related_user_types:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/RelationReference'
        module:
          type: string
        source_info:
          $ref: '#/components/schemas/SourceInfo'
    ReadAuthorizationModelResponse:
      type: object
      properties:
        authorization_model:
          $ref: '#/components/schemas/AuthorizationModel'
    RelationReference:
      type: object
      properties:
        type:
          type: string
          example: group
        relation:
          type: string
          example: member
        wildcard:
          $ref: '#/components/schemas/Wildcard'
        condition:
          type: string
          description: The name of a condition that is enforced over the allowed relation.
      description: RelationReference represents a relation of a particular object type (e.g. 'document#viewer').
      required:
      - type
    AbortedMessageResponse:
      type: object
      example:
        code: '10'
        message: transaction conflict
      properties:
        code:
          type: string
        message:
          type: string
    UnauthenticatedResponse:
      type: object
      example:
        code: unauthenticated
        message: unauthenticated
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        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
    UnprocessableContentErrorCode:
      type: string
      enum:
      - no_throttled_error_code
      - throttled_timeout_error
      default: no_throttled_error_code
    ForbiddenResponse:
      type: object
      example:
        code: forbidden
        message: the principal is not authorized to perform the action
      properties:
        code:
          $ref: '#/components/schemas/AuthErrorCode'
        message:
          type: string
    ConditionMetadata:
      type: object
      properties:
        module:
          type: string
        source_info:
          $ref: '#/components/schemas/SourceInfo'
    ValidationErrorMessageResponse:
      type: object
      example:
        code: validation_error
        message: Generic validation error
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
    v1.Difference:
      type: object
      properties:
        base:
          $ref: '#/components/schemas/Userset'
        subtract:
          $ref: '#/components/schemas/Userset'
      required:
      - base
      - subtract
    DirectUserset:
      type: object
      description: 'A DirectUserset is a sentinel message for referencing

        the direct members specified by an object/relation mapping.'
    Metadata:
      type: object
      properties:
        relations:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/RelationMetadata'
        module:
          type: string
        source_info:
          $ref: '#/components/schemas/SourceInfo'