Elhub Identity API

openapi: 3.2.0
info:
  title: Elhub Identity API
  version: '1.0'
  description: 'Operations tagged identity across 2 of this provider''s published API definitions: elhub-flex-information-system-main-api-openapi.json, elhub-postgrest-openapi-3-0-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://test.flex.internal:6443/api/v1
  description: Development
- url: http://localhost:3000/
tags:
- name: Identity
  description: Identity
paths:
  /identity:
    summary: Identity
    description: ''
    get:
      operationId: list_identity
      summary: List Identity
      tags:
      - Identity
      parameters:
      - in: query
        schema:
          type: string
          pattern: ^eq\.[0-9]+$
        example: eq.55
        description: Unique surrogate identifier.
        name: id
      - in: query
        schema:
          type: string
          pattern: ^eq\.[0-9]+$
        example: eq.55
        description: Reference to the entity using the identity.
        name: entity_id
      - in: query
        schema:
          type: string
          pattern: ^eq\.[0-9]+$
        example: eq.55
        description: Name of the entity using the identity.
        name: entity_name
      - in: query
        schema:
          type: string
          pattern: ^eq\.[0-9]+$
        example: eq.55
        description: Reference to the party assumed by the entity.
        name: party_id
      - in: query
        schema:
          type: string
          pattern: ^eq\.[0-9]+$
        example: eq.55
        description: Name of the party assumed by the entity.
        name: party_name
      - description: Filtering Columns
        in: query
        name: select
        schema:
          type: string
      - description: Ordering
        in: query
        name: order
        schema:
          type: string
      - description: Limiting and Pagination
        in: query
        name: offset
        schema:
          type: string
      - description: Limiting and Pagination
        in: query
        name: limit
        schema:
          type: string
      - in: query
        name: embed
        schema:
          type: string
        description: Comma-separated list of related resources to embed in the response.
      - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/identity_response'
                type: array
          description: OK
        '206':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/identity_response'
                type: array
          description: Partial Content
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/error_message'
                - $ref: '#/components/schemas/empty_object'
          description: Not Found
        '406':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
          description: Not Acceptable
        '416':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
          description: Range Not Satisfiable
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
          description: Internal Server Error
      security:
      - bearerAuth:
        - read:data:identity
      - {}
    servers:
    - url: https://test.flex.internal:6443/api/v1
      description: Development
  /identity/{id}:
    summary: Identity - single
    description: ''
    parameters:
    - in: path
      name: id
      required: true
      schema:
        format: bigint
        type: integer
      example: 14
    get:
      operationId: read_identity
      summary: Read Identity
      tags:
      - Identity
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/identity_response'
          description: OK
          links:
            entity_id:
              operationId: read_entity
              parameters:
                path.id: $response.body#/entity_id
              description: The `entity_id` value returned in the response can be used as the `id` parameter in `GET /entity/{id}`.
            entity_name:
              operationId: read_entity
              parameters:
                path.id: $response.body#/entity_name
              description: The `entity_name` value returned in the response can be used as the `id` parameter in `GET /entity/{id}`.
            party_id:
              operationId: read_party
              parameters:
                path.id: $response.body#/party_id
              description: The `party_id` value returned in the response can be used as the `id` parameter in `GET /party/{id}`.
            party_name:
              operationId: read_party
              parameters:
                path.id: $response.body#/party_name
              description: The `party_name` value returned in the response can be used as the `id` parameter in `GET /party/{id}`.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/error_message'
                - $ref: '#/components/schemas/empty_object'
          description: Not Found
        '406':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
          description: Not Acceptable
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
          description: Internal Server Error
      security:
      - bearerAuth:
        - read:data:identity
      - {}
      parameters:
      - in: query
        name: embed
        schema:
          type: string
        description: Comma-separated list of related resources to embed in the response.
      - $ref: '#/components/parameters/ApiVersion'
    servers:
    - url: https://test.flex.internal:6443/api/v1
      description: Development
components:
  schemas:
    identity_response:
      summary: Response - Identity
      description: Response schema - Resource uniquely identifying a user by linking its entity and the potentially assumed party.
      type: object
      properties:
        id:
          description: Unique surrogate identifier.
          format: bigint
          type: integer
          readOnly: true
          example: 44
        entity_id:
          description: Reference to the entity using the identity.
          format: bigint
          type: integer
          readOnly: true
          example: 3
        entity_name:
          description: Name of the entity using the identity.
          format: text
          type: string
          readOnly: true
          example: Martin Andersen
        party_id:
          description: Reference to the party assumed by the entity.
          format: bigint
          type: integer
          readOnly: true
          nullable: true
          example: 17
        party_name:
          description: Name of the party assumed by the entity.
          format: text
          type: string
          readOnly: true
          nullable: true
          example: Andersen SO
        entity:
          description: Embedded entity
          oneOf:
          - $ref: '#/components/schemas/entity_response'
          - type: 'null'
          nullable: true
        party:
          description: Embedded party
          oneOf:
          - $ref: '#/components/schemas/party_response'
          - type: 'null'
          nullable: true
      required:
      - id
      - entity_id
      - entity_name
    entity_type:
      description: The type of the entity, e.g Person, Organisation
      format: text
      type: string
      example: person
      enum:
      - person
      - organisation
    error_message:
      description: Error message returned from the API.
      type: object
      properties:
        code:
          type: string
          pattern: ^[A-Z0-9]+$
          description: The error code.
          example: PT418
        details:
          type:
          - string
          - 'null'
          description: Detailed information about the error.
        hint:
          type:
          - string
          - 'null'
          description: A hint to help resolve the error.
        message:
          type: string
          description: The error message.
          example: error
      required:
      - code
      - message
    party_status:
      description: The status of the party.
      format: text
      type: string
      default: new
      enum:
      - new
      - active
      - inactive
      - suspended
      - terminated
      example: active
    party_business_id_type:
      description: The type of the business identifier.
      format: text
      type: string
      default: uuid
      enum:
      - gln
      - uuid
      - eic_x
      - org
      example: gln
    party_response:
      summary: Response - Party
      description: 'Response schema - The body that interacts with the Flexibility Information System


        A party is the thing that is authorized to access or modify data in the Flexiblity Information System.


        Example party types:


        * Service Provider

        * System Operator

        * End User'
      type: object
      properties:
        id:
          description: Unique surrogate identifier.
          format: bigint
          type: integer
          readOnly: true
          example: 11
        business_id:
          description: The business identifier of the party. Format depends on `business_id_type`.
          format: text
          type: string
          example: '1337099000000'
        business_id_type:
          $ref: '#/components/schemas/party_business_id_type'
          default: uuid
        entity_id:
          description: Reference to the entity that is the parent of the party.
          format: bigint
          type: integer
          example: 30
        name:
          description: Name of the party. Maximum 128 characters.
          format: text
          type: string
          example: Flex Energy Supplier
        role:
          $ref: '#/components/schemas/party_role'
        type:
          $ref: '#/components/schemas/party_type'
        status:
          $ref: '#/components/schemas/party_status'
          default: new
        recorded_at:
          description: When the resource was recorded (created or updated) in the system.
          format: date-time
          type: string
          readOnly: true
          example: '2023-12-31T23:59:00+00:00'
        recorded_by:
          description: The identity that recorded the resource.
          format: bigint
          type: integer
          readOnly: true
          example: 145
        entity:
          description: Embedded entity
          oneOf:
          - $ref: '#/components/schemas/entity_response'
          - type: 'null'
          nullable: true
      required:
      - id
      - business_id
      - business_id_type
      - entity_id
      - name
      - role
      - type
      - status
      - recorded_at
      - recorded_by
    party_role:
      description: The role of the party. Currently maps to 1:1 to `type`. E.g. system_operator, service_provider.
      format: text
      type: string
      example: flex_energy_supplier
      enum:
      - flex_balance_responsible_party
      - flex_end_user
      - flex_energy_supplier
      - flex_flexibility_information_system_operator
      - flex_market_operator
      - flex_organisation
      - flex_service_provider
      - flex_system_operator
      - flex_third_party
    party_type:
      description: The type of the party, e.g SystemOperator, ServiceProvider
      format: text
      type: string
      example: energy_supplier
      enum:
      - balance_responsible_party
      - end_user
      - energy_supplier
      - flexibility_information_system_operator
      - market_operator
      - organisation
      - service_provider
      - system_operator
      - third_party
    entity_response:
      summary: Response - Entity
      description: 'Response schema - Entity - Natural or legal person


        An entity is a natural or legal person that can be a party in the Flexibility Information System.


        Example entity types:


        * Person

        * Organisation'
      type: object
      properties:
        id:
          description: 'Unique surrogate identifier.


            Note:

            This is a Primary Key.'
          format: bigint
          type: integer
          readOnly: true
          example: 14
        business_id:
          description: The business identifier of the entity. Format depends on `business_id_type`.
          format: text
          type: string
          example: '13370000000'
        business_id_type:
          $ref: '#/components/schemas/entity_business_id_type'
        name:
          description: Name of the entity. Maximum 128 characters.
          format: text
          type: string
          example: John Smith
        type:
          $ref: '#/components/schemas/entity_type'
        recorded_at:
          description: When the resource was recorded (created or updated) in the system.
          format: date-time
          type: string
          readOnly: true
          example: '2023-12-31T23:59:00+00:00'
        recorded_by:
          description: The identity that recorded the resource.
          format: bigint
          type: integer
          readOnly: true
          example: 145
        client:
          description: Embedded entity_client
          oneOf:
          - type: array
            items:
              $ref: '#/components/schemas/entity_client_response'
          - type: 'null'
          nullable: true
        party:
          description: Embedded party
          oneOf:
          - type: array
            items:
              $ref: '#/components/schemas/party_response'
          - type: 'null'
          nullable: true
        party_membership:
          description: Embedded party_membership
          oneOf:
          - type: array
            items:
              $ref: '#/components/schemas/party_membership_response'
          - type: 'null'
          nullable: true
        identity:
          description: Embedded identity
          oneOf:
          - type: array
            items:
              $ref: '#/components/schemas/identity_response'
          - type: 'null'
          nullable: true
      required:
      - id
      - business_id
      - business_id_type
      - name
      - type
      - recorded_at
      - recorded_by
    auth_scope:
      description: Authorization scopes.
      format: text
      type: string
      enum:
      - manage:attachment
      - manage:attachment:service_providing_group_product_application_attachment
      - manage:auth
      - manage:data
      - manage:data:accounting_point_grid_location
      - manage:data:controllable_unit
      - manage:data:controllable_unit_service_provider
      - manage:data:controllable_unit_suspension
      - manage:data:controllable_unit_suspension_comment
      - manage:data:entity
      - manage:data:entity_client
      - manage:data:notification
      - manage:data:party
      - manage:data:party_membership
      - manage:data:service_provider_product_application
      - manage:data:service_provider_product_application_comment
      - manage:data:service_provider_product_suspension
      - manage:data:service_provider_product_suspension_comment
      - manage:data:service_providing_group
      - manage:data:service_providing_group_grid_prequalification
      - manage:data:service_providing_group_grid_prequalification_comment
      - manage:data:service_providing_group_grid_suspension
      - manage:data:service_providing_group_grid_suspension_comment
      - manage:data:service_providing_group_membership
      - manage:data:service_providing_group_product_application
      - manage:data:service_providing_group_product_application_comment
      - manage:data:service_providing_group_product_suspension
      - manage:data:service_providing_group_product_suspension_comment
      - manage:data:system_operator_product_type
      - manage:data:technical_resource
      - read:attachment
      - read:attachment:service_providing_group_product_application_attachment
      - read:attachment:service_providing_group_product_application_attachment_history
      - read:auth
      - read:data
      - read:data:accounting_point
      - read:data:accounting_point_balance_responsible_party
      - read:data:accounting_point_bidding_zone
      - read:data:accounting_point_end_user
      - read:data:accounting_point_energy_supplier
      - read:data:accounting_point_grid_location
      - read:data:accounting_point_grid_location_history
      - read:data:accounting_point_metering_grid_area
      - read:data:controllable_unit
      - read:data:controllable_unit_history
      - read:data:controllable_unit_service_provider
      - read:data:controllable_unit_service_provider_history
      - read:data:controllable_unit_summary
      - read:data:controllable_unit_suspension
      - read:data:controllable_unit_suspension_comment
      - read:data:controllable_unit_suspension_comment_history
      - read:data:controllable_unit_suspension_history
      - read:data:entity
      - read:data:entity_client
      - read:data:event
      - read:data:identity
      - read:data:metering_grid_area
      - read:data:notice
      - read:data:notification
      - read:data:party
      - read:data:party_history
      - read:data:party_membership
      - read:data:party_membership_history
      - read:data:product_type
      - read:data:service_provider_product_application
      - read:data:service_provider_product_application_comment
      - read:data:service_provider_product_application_comment_history
      - read:data:service_provider_product_application_history
      - read:data:service_provider_product_suspension
      - read:data:service_provider_product_suspension_comment
      - read:data:service_provider_product_suspension_comment_history
      - read:data:service_provider_product_suspension_history
      - read:data:service_providing_group
      - read:data:service_providing_group_grid_prequalification
      - read:data:service_providing_group_grid_prequalification_comment
      - read:data:service_providing_group_grid_prequalification_comment_history
      - read:data:service_providing_group_grid_prequalification_history
      - read:data:service_providing_group_grid_suspension
      - read:data:service_providing_group_grid_suspension_comment
      - read:data:service_providing_group_grid_suspension_comment_history
      - read:data:service_providing_group_grid_suspension_history
      - read:data:service_providing_group_history
      - read:data:service_providing_group_membership
      - read:data:service_providing_group_membership_history
      - read:data:service_providing_group_power_per_substation
      - read:data:service_providing_group_product_application
      - read:data:service_providing_group_product_application_comment
      - read:data:service_providing_group_product_application_comment_history
      - read:data:service_providing_group_product_application_history
      - read:data:service_providing_group_product_suspension
      - read:data:service_providing_group_product_suspension_comment
      - read:data:service_providing_group_product_suspension_comment_history
      - read:data:service_providing_group_product_suspension_history
      - read:data:service_providing_group_summary
      - read:data:system_operator_product_type
      - read:data:system_operator_product_type_history
      - read:data:technical_resource
      - read:data:technical_resource_history
      - read:grid
      - read:grid:line
      - read:grid:substation
      - read:grid:substation_cluster
      - use:auth
      - use:data
      - use:data:controllable_unit
      - use:data:controllable_unit:lookup
      - use:data:entity
      - use:data:entity:lookup
    entity_client_response:
      summary: Response - Entity client
      description: Response schema - Client linked to an entity for client credentials and JWT grant authentication methods.
      type: object
      properties:
        id:
          description: Unique surrogate identifier.
          format: bigint
          type: integer
          readOnly: true
          example: 14
        entity_id:
          description: Reference to the entity that this client is attached to.
          format: bigint
          type: integer
          example: 30
        name:
          description: Name of the client.
          format: text
          type: string
          maxLength: 256
          nullable: true
          example: Laptop
        client_id:
          description: The identifier of the entity. For use with client credentials authentication method.
          format: text
          type: string
          readOnly: true
          example: addr@flex.test
        party_id:
          description: Reference to the party this client allows to assume. A null value means the client cannot assume any party.
          format: bigint
          type: integer
          nullable: true
          example: 30
        scopes:
          description: 'List of scopes granted to the user when it logs in as an entity or when it acts as the party. When assuming a party through party membership, the least privileged set of scopes will be kept.

            Scopes are inspired from OAuth 2.0 and allow refinement of access control and privilege delegation mechanisms.'
          type: array
          items:
            $ref: '#/components/schemas/auth_scope'
          nullable: false
          example:
          - read:data
        client_secret:
          description: The secret of the entity. For use with client credentials authentication method. Input as plain text but stored encrypted.
          format: text
          type: string
          minLength: 12
          nullable: true
          example: mysupersecretpassword
        public_key:
          description: The public key of the entity (X.509 SubjectPublicKeyInfo). For use with JWT grant authentication method.
          format: text
          type: string
          nullable: true
          pattern: ^-----BEGIN PUBLIC KEY-----\nMIIB[-A-Za-z0-9+/\n]*={0,3}\n-----END PUBLIC KEY-----$
          example: '-----BEGIN PUBLIC KEY-----

            MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAq3DnhgYgLVJknvDA3clA

            TozPtjI7yauqD/ZuqgZn4KzzzkQ4BzJar4jRygpzbghlFn0Luk1mdVKzPUgYj0V

            kbRlHyYfxahbgOHixOOnXkKXrtZW7yWGjXPqy/ZJ/+kFBNPAzxy7fDuAzKfU3Rn5

            0sBakg95pua14W1oE4rtd4/U+sg2maCq6HgGdCLLxRWwXA8IBtvHZ48i6kxiz9tu

            -----END PUBLIC KEY-----'
        recorded_at:
          description: When the resource was recorded (created or updated) in the system.
          format: date-time
          type: string
          readOnly: true
          example: '2023-12-31T23:59:00+00:00'
        recorded_by:
          description: The identity that recorded the resource.
          format: bigint
          type: integer
          readOnly: true
          example: 145
        entity:
          description: Embedded entity
          oneOf:
          - $ref: '#/components/schemas/entity_response'
          - type: 'null'
          nullable: true
        party:
          description: Embedded party
          oneOf:
          - $ref: '#/components/schemas/party_response'
          - type: 'null'
          nullable: true
      required:
      - id
      - entity_id
      - client_id
      - scopes
      - recorded_at
      - recorded_by
    party_membership_response:
      summary: Response - Party Membership
      description: Response schema - The relation between a party and entity.
      type: object
      properties:
        id:
          description: Unique surrogate identifier.
          format: bigint
          type: integer
          readOnly: true
          example: 44
        party_id:
          description: Reference to the party that the membership links to an entity.
          format: bigint
          type: integer
          example: 379
        entity_id:
          description: Reference to the entity that the party represents.
          format: bigint
          type: integer
          example: 30
        scopes:
          description: List of scopes granted to the entity when it acts as the party. Scopes are inspired from OAuth 2.0 and allow refinement of access control and privilege delegation mechanisms.
          type: array
          items:
            $ref: '#/components/schemas/auth_scope'
          nullable: false
          example:
          - read:data
        recorded_at:
          description: When the resource was recorded (created or updated) in the system.
          format: date-time
          type: string
          readOnly: true
          example: '2023-12-31T23:59:00+00:00'
        recorded_by:
          description: The identity that recorded the resource.
          format: bigint
          type: integer
          readOnly: true
          example: 145
        party:
          description: Embedded party
          oneOf:
          - $ref: '#/components/schemas/party_response'
          - type: 'null'
          nullable: true
        entity:
          description: Embedded entity
          oneOf:
          - $ref: '#/components/schemas/entity_response'
          - type: 'null'
          nullable: true
      required:
      - id
      - party_id
      - entity_id
      - scopes
      - recorded_at
      - recorded_by
    entity_business_id_type:
      description: The type of the business identifier.
      format: text
      type: string
      example: pid
      enum:
      - pid
      - org
      - email
    empty_object:
      description: An empty object
      type: object
      properties: {}
      additionalProperties: false
    identity:
      properties:
        id:
          description: 'Note:

            This is a Primary Key.<pk/>'
          format: bigint
          type: integer
        entity_id:
          description: 'Note:

            This is a Foreign Key to `entity.id`.<fk table=''entity'' column=''id''/>'
          format: bigint
          type: integer
        entity_name:
          format: text
          type: string
        party_id:
          description: 'Note:

            This is a Foreign Key to `party.id`.<fk table=''party'' column=''id''/>'
          format: bigint
          type: integer
        party_name:
          format: text
          type: string
      type: object
  parameters:
    ApiVersion:
      name: Api-Version
      in: header
      required: true
      description: 'The API version to use. Must be a supported version date. See the [changelog](https://elhub.github.io/flex-information-system/changelog/) for available versions.

        '
      schema:
        type: string
        enum:
        - '2026-06-08'
        example: '2026-06-08'
  securitySchemes:
    bearerAuth:
      description: Bearer token using a JWT
      type: http
      scheme: Bearer
      bearerFormat: JWT
    JWT:
      description: Add the token prepending "Bearer " (without quotes) to it
      in: header
      name: Authorization
      type: apiKey
x-refined-from:
- elhub-flex-information-system-main-api-openapi.json
- elhub-postgrest-openapi-3-0-openapi.json