OpenFGA Authorization Models API

swagger: '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
schemes:
- https
consumes:
- application/json
produces:
- application/json
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.
          schema:
            $ref: '#/definitions/ReadAuthorizationModelsResponse'
        '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: page_size
        in: query
        required: false
        type: integer
        format: int32
      - name: continuation_token
        in: query
        required: false
        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.
          schema:
            $ref: '#/definitions/WriteAuthorizationModelResponse'
        '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: body
        in: body
        required: true
        schema:
          type: object
          properties:
            type_definitions:
              type: array
              items:
                type: object
                $ref: '#/definitions/TypeDefinition'
              minItems: 1
            schema_version:
              type: string
            conditions:
              type: object
              additionalProperties:
                $ref: '#/definitions/Condition'
          required:
          - type_definitions
          - schema_version
      tags:
      - Authorization Models
  /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.
          schema:
            $ref: '#/definitions/ReadAuthorizationModelResponse'
        '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: id
        in: path
        required: true
        type: string
      tags:
      - Authorization Models
definitions:
  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
  ReadAuthorizationModelResponse:
    type: object
    properties:
      authorization_model:
        $ref: '#/definitions/AuthorizationModel'
  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
  ConditionMetadata:
    type: object
    properties:
      module:
        type: string
      source_info:
        $ref: '#/definitions/SourceInfo'
  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
  Wildcard:
    type: object
  ReadAuthorizationModelsResponse:
    type: object
    properties:
      authorization_models:
        type: array
        items:
          type: object
          $ref: '#/definitions/AuthorizationModel'
      continuation_token:
        type: string
        example: eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==
        description: The continuation token will be empty if there are no more models.
    required:
    - authorization_models
  UnprocessableContentErrorCode:
    type: string
    enum:
    - no_throttled_error_code
    - throttled_timeout_error
    default: no_throttled_error_code
  Usersets:
    type: object
    properties:
      child:
        type: array
        items:
          type: object
          $ref: '#/definitions/Userset'
    required:
    - child
  InternalErrorMessageResponse:
    type: object
    example:
      code: internal_error
      message: Internal Server Error
    properties:
      code:
        $ref: '#/definitions/InternalErrorCode'
      message:
        type: string
  RelationReference:
    type: object
    properties:
      type:
        type: string
        example: group
      relation:
        type: string
        example: member
      wildcard:
        $ref: '#/definitions/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
  v1.Difference:
    type: object
    properties:
      base:
        $ref: '#/definitions/Userset'
      subtract:
        $ref: '#/definitions/Userset'
    required:
    - base
    - subtract
  Metadata:
    type: object
    properties:
      relations:
        type: object
        additionalProperties:
          $ref: '#/definitions/RelationMetadata'
      module:
        type: string
      source_info:
        $ref: '#/definitions/SourceInfo'
  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
  RelationMetadata:
    type: object
    properties:
      directly_related_user_types:
        type: array
        items:
          type: object
          $ref: '#/definitions/RelationReference'
      module:
        type: string
      source_info:
        $ref: '#/definitions/SourceInfo'
  ConditionParamTypeRef:
    type: object
    properties:
      type_name:
        $ref: '#/definitions/TypeName'
      generic_types:
        type: array
        items:
          type: object
          $ref: '#/definitions/ConditionParamTypeRef'
    required:
    - type_name
  v1.TupleToUserset:
    type: object
    properties:
      tupleset:
        $ref: '#/definitions/ObjectRelation'
        title: The target object/relation
      computedUserset:
        $ref: '#/definitions/ObjectRelation'
    required:
    - tupleset
    - computedUserset
  WriteAuthorizationModelResponse:
    type: object
    properties:
      authorization_model_id:
        type: string
        example: 01G5JAVJ41T49E9TT3SKVS7X1J
    required:
    - authorization_model_id
  ForbiddenResponse:
    type: object
    example:
      code: forbidden
      message: the principal is not authorized to perform the action
    properties:
      code:
        $ref: '#/definitions/AuthErrorCode'
      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
  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: '#/definitions/TypeDefinition'
      conditions:
        type: object
        additionalProperties:
          $ref: '#/definitions/Condition'
    required:
    - id
    - schema_version
    - type_definitions
  UnauthenticatedResponse:
    type: object
    example:
      code: unauthenticated
      message: unauthenticated
    properties:
      code:
        $ref: '#/definitions/ErrorCode'
      message:
        type: string
  Userset:
    type: object
    properties:
      this:
        $ref: '#/definitions/DirectUserset'
      computedUserset:
        $ref: '#/definitions/ObjectRelation'
      tupleToUserset:
        $ref: '#/definitions/v1.TupleToUserset'
      union:
        $ref: '#/definitions/Usersets'
      intersection:
        $ref: '#/definitions/Usersets'
      difference:
        $ref: '#/definitions/v1.Difference'
  SourceInfo:
    type: object
    properties:
      file:
        type: string
  DirectUserset:
    type: object
    description: 'A DirectUserset is a sentinel message for referencing

      the direct members specified by an object/relation mapping.'
  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: '#/definitions/Userset'
      metadata:
        $ref: '#/definitions/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
  ValidationErrorMessageResponse:
    type: object
    example:
      code: validation_error
      message: Generic validation error
    properties:
      code:
        $ref: '#/definitions/ErrorCode'
      message:
        type: string
  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: '#/definitions/ConditionParamTypeRef'
        description: A map of parameter names to the parameter's defined type reference.
      metadata:
        $ref: '#/definitions/ConditionMetadata'
    required:
    - name
    - expression
  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
  PathUnknownErrorMessageResponse:
    type: object
    example:
      code: undefined_endpoint
      message: Endpoint not enabled
    properties:
      code:
        $ref: '#/definitions/NotFoundErrorCode'
      message:
        type: string