Emporix Scopes API

openapi: 3.2.0
info:
  title: Emporix Scopes API
  version: ''
  contact:
    name: Emporix
    url: https://emporix.com
    email: documentation@emporix.com
  description: 'Operations tagged Scopes 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: Scopes
paths:
  /iam/{tenant}/scopes:
    parameters:
    - $ref: '#/components/parameters/tenant'
    get:
      tags:
      - Scopes
      summary: Retrieving all scopes
      description: Retrieves all scopes for the tenant. Results can be filtered and sorted using query parameters.
      operationId: GET-iam-list-tenant-scopes
      parameters:
      - $ref: '#/components/parameters/tenant'
      - $ref: '#/components/parameters/trait_paged_pageNumber'
      - $ref: '#/components/parameters/trait_paged_pageSize'
      - $ref: '#/components/parameters/trait_sort'
      - $ref: '#/components/parameters/trait_q_query_param'
      - $ref: '#/components/parameters/X-Total-Count'
      responses:
        '200':
          description: The request was successful. A list of scopes is returned.
          headers:
            X-Total-Count:
              description: Total number of retrieved scopes.
              schema:
                type: integer
                format: int32
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomScopeQueryDocument'
              examples:
                Scopes list:
                  value:
                  - id: custom.scope
                    description:
                      en: Example scope description
                      de: Beispielbeschreibung
                    domain: example_domain
                    predefined: false
                    metadata:
                      version: 1
                      createdAt: '2022-01-04 10:44:51.871Z'
                      modifiedAt: '2022-01-05 12:44:51.456Z'
                  - id: iam.access_read
                    description:
                      en: Read access to access controls
                    domain: iam
                    predefined: true
                    metadata:
                      version: 1
                      createdAt: '2022-01-04 10:44:51.871Z'
                      modifiedAt: '2022-01-05 12:44:51.456Z'
                Empty scopes list:
                  value: []
        '400':
          $ref: '#/components/responses/Bad_request_400'
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
      security:
      - OAuth2:
        - iam.scope_read
    servers:
    - url: https://api.emporix.io
  /iam/{tenant}/scopes/{scopeId}:
    parameters:
    - $ref: '#/components/parameters/tenant'
    - $ref: '#/components/parameters/scopeId'
    get:
      tags:
      - Scopes
      summary: Retrieving a scope
      description: Retrieves details of a specified scope.
      operationId: GET-iam-retrieve-scope
      parameters:
      - $ref: '#/components/parameters/trait_acceptLanguage_header'
      responses:
        '200':
          description: The request was successful. Scope details are returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomScopeQueryDocument'
              examples:
                example:
                  value:
                    id: custom.scope
                    description:
                      en: Example scope description
                      de: Beispielbeschreibung
                    domain: example_domain
                    predefined: false
                    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: unknown.scope
                    code: 404
                    status: Not Found
                    message: Scope not found
      security:
      - OAuth2:
        - iam.scope_read
    put:
      tags:
      - Scopes
      summary: Upserting a custom scope
      description: 'Creates a custom scope when it does not exist, or updates it when it already exists for the tenant.

        If `metadata.version` is provided, optimistic locking is applied for updates.'
      operationId: PUT-iam-upsert-custom-scope
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomScopeUpsertRequest'
            examples:
              example:
                value:
                  description:
                    en: Example scope description
                    de: Beispielbeschreibung
                  domain: example_domain
                  metadata:
                    version: 1
      responses:
        '201':
          description: The request was successful. The scope has been created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomScopeIdResponse'
              examples:
                example:
                  value:
                    id: custom.scope
        '204':
          description: The request was successful. The scope has been updated.
        '400':
          $ref: '#/components/responses/Bad_request_400'
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
      security:
      - OAuth2:
        - iam.scope_manage
    delete:
      tags:
      - Scopes
      summary: Deleting a custom scope
      description: 'Deletes a custom scope for the tenant.


        **Note**: The scope is removed and cannot be used anymore, but it may still appear on custom credentials that were already created before the deletion.'
      operationId: DELETE-iam-delete-custom-scope
      responses:
        '204':
          description: The request was successful. The scope has been deleted.
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
      security:
      - OAuth2:
        - iam.scope_manage
    servers:
    - url: https://api.emporix.io
components:
  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
    CustomScopeUpsertRequest:
      type: object
      description: Payload for creating or updating a scope.
      properties:
        description:
          type: object
          additionalProperties:
            type: string
          description: Localized description as a map of language codes to text.
        domain:
          type: string
          description: Domain identifier for the scope.
        metadata:
          type: object
          description: Metadata for the scope. Only `version` is supported, for optimistic locking on updates.
          properties:
            version:
              type: integer
              format: int32
              description: Document version. When provided on update, must match the stored version.
          additionalProperties: false
    CustomScopeMetadataQueryDocument:
      required:
      - createdAt
      - version
      type: object
      properties:
        version:
          type: integer
          description: Scope document version.
          format: int32
        createdAt:
          type: string
          description: Timestamp indicating when the scope was created.
          format: date-time
        modifiedAt:
          type: string
          description: Timestamp indicating when the scope was last modified.
          format: date-time
      description: Scope metadata.
    CustomScopeIdResponse:
      type: object
      example:
        id: custom.scope
      properties:
        id:
          type: string
    CustomScopeQueryDocument:
      type: object
      description: Definition of a scope.
      properties:
        id:
          type: string
          description: Scope identifier.
        description:
          type: object
          additionalProperties:
            type: string
          description: Localized description as a map of language codes to text.
        domain:
          type: string
          description: Domain identifier for the scope.
        predefined:
          type: boolean
          readOnly: true
          description: Indicates whether this scope is predefined in the system or was created by a user.
        metadata:
          $ref: '#/components/schemas/CustomScopeMetadataQueryDocument'
  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'''
  parameters:
    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_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
    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_q_query_param:
      name: q
      in: query
      required: false
      schema:
        type: string
        example: id:in(exampleId1,exampleId2)
      description: "Standard query parameter used to search for specific values.   \n* Searching for an item by string property: `q=id:31065d5b-b62e`, where `id` is the field name and `31065d5b-b62e` is its required value.   \n* Searching for an item by localized field property: `q=name.en:T-s` where `name` is the name of the field, `en` is a language code and `T-s` is a required value of this field.   This query works only for localized fields, which are stored in a Map format where `key` is a language code and `value` is translation to particular language.   + Searching for items by date property. All numer-based property queries are valid also for dates. In that case the date should be placed within double quotes: `q=metadata.createdAt:(>=\"2021-05-18T07:27:27.455Z\" AND <\"2021-05-20T07:27:27.455Z\")`   + Searching for items with non existing or empty property: `q=name.en:null` where `name.en` is a name of fields that has value `null`.   + Searching for items with existing property: `q=attributes:exists` where `attributes` is a name of field that has `non null` value.   + Searching for items by multiple specific values: `q=id:(5c3325baa9812100098ff48f,5c3325d1a9812100098ff494)` where `id` is name of field and strings within a bracket are it''s required value.   + Searching for items by multiple fields: `q=id:5c3325baa9812100098ff48f name.en:T-s` where `id` and ''name.en'' are the names of fields. All documents that contain given values of these fields are returned. Multiple fields separated by space can be specified. Multiple values for each field can be also specified in a format presented above.   + Searching for items with string fields conforming to a regex: `q=name.en:~ABCD12` or `q=name.en:(~AB CD)` - in case of searching for strings with space, where `name` is the name of field and `ABCD12` or `AB CD` is it''s querying regex.'\n"
    trait_paged_pageSize:
      name: pageSize
      in: query
      description: 'Number of items to be retrieved per page.

        '
      schema:
        default: 60
        minimum: 1
        type: integer
    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
    scopeId:
      name: scopeId
      in: path
      required: true
      description: 'Unique identifier of a scope. Only letters, digits, periods (`.`), hyphens (`-`), and underscores (`_`) are allowed.

        '
      schema:
        type: string
        example: custom.scope
  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