Emporix Resources API

openapi: 3.2.0
info:
  title: Emporix Resources API
  version: ''
  contact:
    name: Emporix
    url: https://emporix.com
    email: documentation@emporix.com
  description: 'Operations tagged Resources across 2 of this provider''s published API definitions: emporix-iam-openapi.yml, emporix-iam-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.emporix.io
security:
- OAuth2: []
tags:
- name: Resources
paths:
  /iam/{tenant}/resources:
    parameters:
    - $ref: '#/components/parameters/tenant'
    get:
      tags:
      - Resources
      summary: Retrieving all resources
      deprecated: true
      description: 'Retrieves all resources of a given tenant. You can filter the results by using query parameters.


        **Note**: This endpoint is deprecated.'
      operationId: GET-iam-list-tenant-resources
      parameters:
      - $ref: '#/components/parameters/tenant'
      - $ref: '#/components/parameters/trait_paged_pageSize'
      - $ref: '#/components/parameters/trait_paged_pageNumber'
      - $ref: '#/components/parameters/trait_sort'
      - $ref: '#/components/parameters/trait_name_query_param'
      - $ref: '#/components/parameters/trait_description_query_param'
      - $ref: '#/components/parameters/trait_metadataModifiedAt_query_param'
      - $ref: '#/components/parameters/trait_acceptLanguage_header'
      - $ref: '#/components/parameters/X-Total-Count'
      responses:
        '200':
          description: The request was successful. A list of resources is returned.
          headers:
            X-Total-Count:
              description: Total number of retrieved resources.
              schema:
                type: integer
                format: int32
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ResourceQueryDocument'
              examples:
                example:
                  value:
                  - id: Z843dc9e-a3f6-4573-bb01-a8ae21d2d4af
                    name:
                      en: Example name
                      de: Beispielname
                    description:
                      en: Example resource description
                      de: Beispiel Berechtigungsbeschreibung
                    code: serviceName.resource
                    metadata:
                      version: 1
                      createdAt: '2022-01-04 10:44:51.871Z'
                      modifiedAt: '2022-01-05 12:44:51.456Z'
        '400':
          description: Request was syntactically incorrect. Details will be provided in the response payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    code: 400
                    status: Bad Request
                    message: Accept-Language validation failed.
                    details:
                    - 'Following languages are not supported: ''ru'''
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
      security:
      - OAuth2:
        - iam.resource_read
    servers:
    - url: https://api.emporix.io
  /iam/{tenant}/resources/{resourceId}:
    parameters:
    - $ref: '#/components/parameters/tenant'
    - $ref: '#/components/parameters/resourceId'
    get:
      tags:
      - Resources
      summary: Retrieving a resource
      deprecated: true
      description: 'Retrieves details of a specified resource.


        **Note**: This endpoint is deprecated.'
      operationId: GET-iam-retrieve-resource
      parameters:
      - $ref: '#/components/parameters/tenant'
      - $ref: '#/components/parameters/resourceId'
      - $ref: '#/components/parameters/trait_acceptLanguage_header'
      responses:
        '200':
          description: The request was successful. Resource details are returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceQueryDocument'
              example:
                id: Z843dc9e-a3f6-4573-bb01-a8ae21d2d4af
                name:
                  en: Example name
                  de: Beispielname
                description:
                  en: Example resource description
                  de: Beispiel Berechtigungsbeschreibung
                code: serviceName.resource
                metadata:
                  version: 1
                  createdAt: '2022-01-04 10:44:51.871Z'
                  modifiedAt: '2022-01-05 12:44:51.456Z'
        '400':
          $ref: '#/components/responses/Bad_request_400'
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
        '404':
          description: Given resources cannot be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    resourceId: 084bcaf6-66b8-4ddd-9489-65c5f6449e94
                    code: 404
                    status: Not Found
                    message: Error while getting resource
                    details:
                    - Resource with id '084bcaf6-66b8-4ddd-9489-65c5f6449e94' not found
      security:
      - OAuth2:
        - iam.resource_read
    servers:
    - url: https://api.emporix.io
components:
  responses:
    Unauthorized_401:
      description: Given request is unauthorized - the authorization token is invalid or has expired. It usually means that tenant from the token does not match tenant from path.
      content:
        application/json:
          schema:
            type: object
            properties:
              fault:
                type: object
                properties:
                  faultstring:
                    type: string
                  detail:
                    type: object
                    properties:
                      errorcode:
                        type: string
          examples:
            Invalid Access Token:
              value:
                fault:
                  faultstring: Invalid Access Token
                  detail:
                    errorcode: keymanagement.service.invalid_access_token
            Unauthorized:
              value: {}
    Forbidden_403:
      description: Scope validation failed, details will be provided in response message
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
              message:
                type: string
              status:
                type: string
              details:
                type: array
                items:
                  type: string
          examples:
            'Scope is missing ':
              value:
                code: 403
                message: Scope validation failed
                status: Forbidden
                details:
                - Missing required scopes '[scope_name]'
    Bad_request_400:
      description: Unsupported language provided.
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
              status:
                type: string
              message:
                type: string
              details:
                type: array
                items:
                  type: string
          examples:
            Unsupported language:
              value:
                code: 400
                status: Bad Request
                message: Language header validation failed
                details:
                - 'Following languages are not supported: ''ru'''
  schemas:
    ErrorResponse:
      required:
      - code
      - message
      - status
      type: object
      properties:
        resourceId:
          type:
          - string
          - 'null'
        code:
          type: integer
          format: int32
        status:
          type: string
        message:
          type: string
        details:
          type: array
          items:
            type: string
    ResourceQueryDocument:
      type: object
      properties:
        id:
          type: string
          description: Resource unique identifier generated when the resource is created.
        name:
          type: object
          additionalProperties:
            type: string
          description: Localized resource name in the form of a map of translations.
        description:
          type: object
          additionalProperties:
            type: string
          description: Localized resource description in the form of a map of translations.
        code:
          type: string
          description: Resource unique code identifier.
        metadata:
          $ref: '#/components/schemas/ResourcesMetadataQueryDocument'
      description: Resource definition associated with this access control.
    ResourcesMetadataQueryDocument:
      required:
      - createdAt
      - version
      type: object
      properties:
        version:
          type: integer
          description: Resource document version.
          format: int32
        createdAt:
          type: string
          description: Timestamp indicating when the resource was created.
          format: date-time
        modifiedAt:
          type: string
          description: Timestamp indicating when the resource was last modified.
          format: date-time
      description: Resource metadata.
  parameters:
    trait_metadataModifiedAt_query_param:
      name: metadataModifiedAt
      in: query
      required: false
      schema:
        type: string
        example: '2022-01-01'
      description: 'Search by given resources that contain the `metadata.modifiedAt` date field with a date later than the specified value. The format is as follows: ''''yyyy-MM-dd''''.

        '
    X-Total-Count:
      name: X-Total-Count
      in: header
      required: false
      schema:
        type: boolean
        example: true
        default: false
      description: 'Flag indicating whether the total number of retrieved items should be returned.

        '
    trait_acceptLanguage_header:
      name: Accept-Language
      in: header
      required: false
      schema:
        type: string
      description: 'List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields. If the value is specified, then it must be present in the tenant configuration.

        * If the header is set to a particular language or a list of languages, all localized fields are retrieved as strings.

        * If the header is set to `*`, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.

        * If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.

        '
    trait_description_query_param:
      name: description
      in: query
      required: false
      schema:
        type: string
      description: Search by the description of the the given resource, it is conformed against all of the specified accepted-languages.
    trait_paged_pageNumber:
      name: pageNumber
      in: query
      description: 'Page number to be retrieved. The number of the first page is 1.

        '
      schema:
        default: 1
        minimum: 1
        type: integer
    resourceId:
      name: resourceId
      in: path
      required: true
      schema:
        type: string
      description: Unique identifier of a resource.
    trait_sort:
      name: sort
      in: query
      description: "List of properties used to sort the results, separated by colons. The order of properties indicates their priority in sorting.\n\nPossible values:\n* `{fieldName}`\n* `{fieldName}:asc`\n* `{fieldName}:desc`\n\n**Note:** If you want to sort the results by localized properties, the possible values are as follows:\n  * `{fieldName}.{language}`\n  * `{fieldName}.{language}:asc`\n  * `{fieldName}.{language}:desc`\n\nIf the sorting direction is not specified, the fields are sorted in ascending order."
      schema:
        type: string
    trait_paged_pageSize:
      name: pageSize
      in: query
      description: 'Number of items to be retrieved per page.

        '
      schema:
        default: 60
        minimum: 1
        type: integer
    trait_name_query_param:
      name: name
      in: query
      required: false
      schema:
        type: string
      description: 'Search by the name of a given resource. The value is conformed against all of the specified accepted languages.

        '
    tenant:
      name: tenant
      in: path
      required: true
      description: 'Your Emporix tenant name.


        **Note**: The tenant name should always be written in lowercase.

        '
      schema:
        pattern: ^[a-z][a-z0-9]+$
        minLength: 3
        maxLength: 16
        type: string
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.emporix.io/oauth/token
          scopes:
            iam.access_read: ''
            iam.access_manage: ''
            iam.assignment_create_own: ''
            iam.assignment_manage: ''
            iam.assignment_delete_own: ''
            iam.permission_read: ''
            iam.permission_create: ''
            iam.permission_update: ''
            iam.permission_delete: ''
            iam.role_read: ''
            iam.role_create: ''
            iam.role_update: ''
            iam.role_delete: ''
            iam.group_read: ''
            iam.group_read_own: ''
            iam.user_read: ''
            iam.user_read_own: ''
            iam.user_create: ''
            iam.user_update: ''
            iam.user_delete: ''
            iam.scope_manage: ''
            iam.scope_read: ''
            iam.scope_read_own: ''
            iam.resource_read: ''
            iam.template_read: ''
x-refined-from:
- emporix-iam-openapi.yml
- emporix-iam-openapi.yml