openapi: 3.0.3
info:
  title: Skylark Access Management API
  description: >
    The Skylark Access Management API provides endpoints to create, update, and retrieve
    device accesses within the T IoT Hub ecosystem. It allows integration with Skylark
    for secure credential and status management, following TMF RealizingResource standards.
  version: 1.0.0
  x-hub: t-iot-hub
  x-api-category: "DT IoT"
  contact:
    name: Deutsche Telekom IoT GmbH
    email: iot-orchestrator@t-systems.com
    url: "https://iot.telekom.de"
  license:
    name: Deutsche Telekom AG
    url: https://hub.iot.telekom.com/docs
servers:
  - url: https://<server>/skylark-access-management/v1
    description: Skylark Access Management API
security:
  - oAuth:
      - ro%sam
      - rw%sam
tags:
  - name: Skylark Access Management
    description: Operations related to Skylark device access management
paths:
  /{tenantName}/access:
    get:
      tags:
        - Skylark Access Management
      summary: Retrieve accesses
      description: >-
        Returns a list of Skylark accesses mapped to TMF RealizingResource.

        Filtering grammar for the `filter` query parameter:
        - String fields (eq only): contractId, name, productOfferingId, createdBy, username
        - Date fields: createdAt, startDateTime, endDateTime support >, >=, <, <=, = operators
          (createdAt is filter-only and not returned in the payload)
        - Combine conditions with '&' for AND and ';' for OR
        
        Examples are provided in the parameter section below.
      operationId: getAccesses
      parameters:
        - $ref: "#/components/parameters/tenant_name"
        - $ref: "#/components/parameters/page_size"
        - $ref: "#/components/parameters/page_number"
        - $ref: "#/components/parameters/skylark_filter"
      responses:
        '200':
          description: List of accesses as TMF RealizingResource
          headers:
            Link:
              description: >
                RFC 5988 web linking header with pagination URLs.
                Contains rel="first", rel="last" and optionally rel="prev"/rel="next"
                based on pageNumber/pageSize and total result count.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/RealizingResource"
        '400':
          $ref: "#/components/responses/bad_request_validation_error"
        '401':
          $ref: "#/components/responses/unauthorized_error"
        '403':
          $ref: "#/components/responses/forbidden_error"
        '429':
          $ref: "#/components/responses/too_many_requests_error"
        '500':
          $ref: "#/components/responses/internal_server_error"
        '503':
          $ref: "#/components/responses/service_unavailable_error"
    post:
      tags:
        - Skylark Access Management
      summary: Create access
      description: >-
        Creates a Skylark access for a specific Pay-Per-Use (PPU) contract.
        
        Payload includes contractId (required), optional deviceName, optional username and optional password.
        The response is mapped to TMF RealizingResource; validity period is returned in validFor where endDateTime
        corresponds to Skylark's expiresAt.
      operationId: createAccess
      parameters:
        - $ref: "#/components/parameters/content_type_json"
        - $ref: "#/components/parameters/tenant_name"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SkylarkAccessCreateRequest"
            examples:
              CreateSkylarkAccessExample:
                $ref: "#/components/examples/CreateSkylarkAccessExample"
      responses:
        '201':
          description: Access created and mapped to RealizingResource
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RealizingResource"
              examples:
                CreateSkylarkAccessResponseExample:
                  $ref: "#/components/examples/CreateSkylarkAccessResponseExample"
        '400':
          $ref: "#/components/responses/bad_request_validation_error"
        '401':
          $ref: "#/components/responses/unauthorized_error"
        '403':
          $ref: "#/components/responses/forbidden_error"
        '415':
          $ref: "#/components/responses/unsupported_media_type_error"
        '429':
          $ref: "#/components/responses/too_many_requests_error"
        '500':
          $ref: "#/components/responses/internal_server_error"
        '503':
          $ref: "#/components/responses/service_unavailable_error"
  /{tenantName}/access/batch/{taskId}:
    get:
      tags:
        - Skylark Access Management
      summary: Retrieve a Task by ID
      description: >
        Retrieves the status of a batch access creation Task by its unique identifier.

        The response payload depends on the Task state:
        - ACKNOWLEDGED / IN_PROGRESS / TERMINATED: returns base Task information only
        - DONE: includes created RealizingResources
        - FAILED: includes Problems only (no resources were created)
        - REJECTED: includes Problems only (request was rejected before processing)
        Clients are expected to poll this endpoint until the Task reaches a terminal state.
      operationId: getTaskById
      parameters:
        - $ref: "#/components/parameters/tenant_name"
        - name: taskId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the Task.
      responses:
        '200':
          description: Task retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
              examples:
                acknowledged:
                  $ref: "#/components/examples/Task_Acknowledged"
                done:
                  $ref: "#/components/examples/Task_Done"
                rejected:
                  $ref: "#/components/examples/Task_Rejected"
        '400':
          $ref: "#/components/responses/bad_request_validation_error"
        '401':
          $ref: "#/components/responses/unauthorized_error"
        '403':
          $ref: "#/components/responses/forbidden_error"
        '404':
          $ref: "#/components/responses/not_found_error"
        '429':
          $ref: "#/components/responses/too_many_requests_error"
        '500':
          $ref: "#/components/responses/internal_server_error"
        '503':
          $ref: "#/components/responses/service_unavailable_error"
  /{tenantName}/access/batch:
    post:
      tags:
        - Skylark Access Management
      summary: Create accesses in batch
      description: >-
        Creates multiple Skylark accesses for a Pay-Per-Use (PPU) contract.

        The request supports two mutually exclusive modes:
        
        - Provide an explicit list of access items via 'accesses'
          (each entry requires 'deviceName' and may optionally include 'username' and 'password'), or
        - Provide 'numberOfAccesses' to auto-generate that many accesses
          for the given 'deviceName'.

        Exactly one of 'accesses' or 'numberOfAccesses' must be provided.
      operationId: createAccessBatch
      parameters:
        - $ref: "#/components/parameters/content_type_json"
        - $ref: "#/components/parameters/tenant_name"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SkylarkAccessCreateBatchRequest"
            examples:
              ByCount:
                $ref: "#/components/examples/BatchCreateByCount"
              PredefinedList:
                $ref: "#/components/examples/BatchCreatePredefinedList"
      responses:
        '202':
          description: Batch create task acknowledged (asynchronous processing)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchJobResponse'
              examples:
                acknowledged:
                  $ref: "#/components/examples/BatchJob_Acknowledged"
        '400':
          $ref: "#/components/responses/bad_request_validation_error"
        '401':
          $ref: "#/components/responses/unauthorized_error"
        '403':
          $ref: "#/components/responses/forbidden_error"
        '404':
          $ref: "#/components/responses/not_found_error"
        '415':
          $ref: "#/components/responses/unsupported_media_type_error"
        '429':
          $ref: "#/components/responses/too_many_requests_error"
        '500':
          $ref: "#/components/responses/internal_server_error"
        '503':
          $ref: "#/components/responses/service_unavailable_error"
  /{tenantName}/access/batchUpdate:
    post:
      tags:
        - Skylark Access Management
      summary: Batch update Skylark accesses
      description: >-
        Updates multiple existing Skylark accesses in batch mode.
        This endpoint supports Pay-Per-Use (PPU) accesses only.

        Supported operation types:
        - **update** — update password and/or status for provided access IDs
        - **terminate** — terminate provided access IDs
      operationId: batchUpdateAccesses
      parameters:
        - $ref: "#/components/parameters/content_type_json"
        - $ref: "#/components/parameters/tenant_name"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SkylarkAccessBatchUpdateRequest"
            examples:
              UpdatePasswordExample:
                summary: Update multiple accesses (password)
                value:
                  operationType: "update"
                  accessesIdList:
                    - "tenantXYZ_2201000124"
                    - "eosx_3500485472"
                  operationBody:
                    password: "newSecurePass"

              UpdateStatusExample:
                summary: Update multiple accesses (status)
                value:
                  operationType: "update"
                  accessesIdList:
                    - "eosx_2201000124"
                    - "eosx_3500485472"
                  operationBody:
                    status: "SUSPENDED"

              TerminateExample:
                summary: Terminate accesses (PPU only)
                value:
                  operationType: "terminate"
                  accessesIdList:
                    - "eosx_2201000124"
                    - "eosx_3500485472"
                  operationBody: { }
      responses:
        '202':
          description: Batch update task acknowledged (asynchronous processing)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchJobResponse'
              examples:
                acknowledged:
                  $ref: "#/components/examples/BatchJob_Acknowledged"
        "400":
          $ref: "#/components/responses/bad_request_validation_error"
        "401":
          $ref: "#/components/responses/unauthorized_error"
        "403":
          $ref: "#/components/responses/forbidden_error"
        "404":
          $ref: "#/components/responses/not_found_error"
        "415":
          $ref: "#/components/responses/unsupported_media_type_error"
        "429":
          $ref: "#/components/responses/too_many_requests_error"
        "500":
          $ref: "#/components/responses/internal_server_error"
        "503":
          $ref: "#/components/responses/service_unavailable_error"
  /{tenantName}/access/{id}:
    get:
      tags:
        - Skylark Access Management
      summary: Retrieve a single access by ID
      description: >
        Retrieves a specific Skylark access entry for the given tenant using its unique identifier.
        The identifier usually matches the access username or a system-generated ID.
        This endpoint never returns plaintext passwords.
        Passwords may only be included in create or update responses when explicitly available.
      operationId: getAccessById
      parameters:
        - $ref: '#/components/parameters/tenant_name'
        - name: id
          in: path
          required: true
          description: Unique identifier of the access (typically the access username; may be tenant-prefixed).
          schema:
            type: string
          example: tenantXYZ_sensor_001
      responses:
        '200':
          description: Access retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RealizingResource'
              examples:
                getById:
                  $ref: '#/components/examples/GetSkylarkAccessByIdResponse'
        '400':
          $ref: '#/components/responses/bad_request_validation_error'
        '401':
          $ref: '#/components/responses/unauthorized_error'
        '403':
          $ref: '#/components/responses/forbidden_error'
        '404':
          $ref: '#/components/responses/not_found_error'
        '429':
          $ref: '#/components/responses/too_many_requests_error'
        '500':
          $ref: '#/components/responses/internal_server_error'
        '503':
          $ref: '#/components/responses/service_unavailable_error'
    patch:
      tags:
        - Skylark Access Management
      summary: Update Skylark access credentials or state
      description: >
        Updates an existing Skylark access entry by modifying its password or lifecycle status.
        Supported status values are ACTIVE and SUSPENDED.
      operationId: updateAccess
      parameters:
        - $ref: "#/components/parameters/content_type_merge_patch"
        - $ref: '#/components/parameters/tenant_name'
        - name: id
          in: path
          required: true
          description: The unique identifier of the access to update.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/SkylarkAccessUpdateRequest'
            examples:
              StatusOnly:
                summary: Update access status
                value:
                  status: 'ACTIVE'
              PasswordOnly:
                summary: Update password
                value:
                  password: 'new-secure-pass123'
              BothFields:
                summary: Update both password and status
                value:
                  password: 'temporary-pass456'
                  status: 'SUSPENDED'
      responses:
        '200':
          description: Access updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RealizingResource'
        '400':
          $ref: '#/components/responses/bad_request_validation_error'
        '401':
          $ref: '#/components/responses/unauthorized_error'
        '403':
          $ref: '#/components/responses/forbidden_error'
        '404':
          $ref: '#/components/responses/not_found_error'
        '415':
          $ref: "#/components/responses/unsupported_media_type_error"
        '429':
          $ref: '#/components/responses/too_many_requests_error'
        '500':
          $ref: '#/components/responses/internal_server_error'
        '503':
          $ref: '#/components/responses/service_unavailable_error'
components:
  schemas:
    TimePeriod:
      type: object
      required:
        - startDateTime
        - endDateTime
      properties:
        startDateTime:
          type: string
          format: date-time
        endDateTime:
          type: string
          format: date-time
    RealizingResource:
      type: object
      required:
        - id
        - name
        - status
        - characteristic
        - "@baseType"
        - "@type"
      properties:
        id:
          type: string
          description: Unique identifier of the access (typically the access username; may be system-generated and tenant-prefixed).
        name:
          type: string
          description: Name of the resource, typically the device name
        status:
          type: string
          enum: [ ACTIVE, SUSPENDED, PENDING_ACTIVE ]
          description: >
            Lifecycle status of the resource.
            - PENDING_ACTIVE is server-managed during prepaid activation and is returned only by GET operations.
        characteristic:
          type: array
          description: Characteristics of the resource (e.g., `username`, `password`, `createdBy`)
          items:
            type: object
            required:
              - name
              - value
            properties:
              name:
                type: string
                description: Characteristic name (e.g., `username`, `password`, `createdBy`)
              value:
                type: string
                nullable: true
                readOnly: true
                description: |
                  Value of the characteristic, depending on the name:
                    - `username`: device username
                    - `password`: plaintext password (decrypted on read, only exposed in responses)
                    - `createdBy`: task ID that created the access (server-managed, read-only, may be null)
                    - `contractId`: Pay-Per-Use contract identifier associated with the access
                    - `type`: Access type (e.g. PPU)
                    - `productOffering`: Human-readable product offering name (display value)
                    - `productOfferingId`: Product offering identifier from IoT Store
        relatedProduct:
          type: object
          nullable: true
          description: Related TMF Product linked to this access, if applicable.
          properties:
            id:
              type: string
              description: ID of the related TMF Product.
        validFor:
          $ref: "#/components/schemas/TimePeriod"
        "@baseType":
          type: string
          enum: [ Resource ]
          description: TMF base type
        "@type":
          type: string
          enum: [ RealizingResource ]
          description: TMF resource type
    SkylarkAccessCreateRequest:
      type: object
      required:
        - contractId
      additionalProperties: false
      properties:
        contractId:
          type: string
          description: >
            ID of the Pay-Per-Use (PPU) contract to associate the access with.

        deviceName:
          type: string
          description: >
            Optional display name for the device.
            If provided, it will be tenant-prefixed in the created access.
            If not provided, a tenant-prefixed name is automatically generated.

        username:
          type: string
          description: >
            Optional username for the access.
            If provided, it will be tenant-prefixed in the created access.
            If not provided, a tenant-prefixed username is automatically generated

        password:
          type: string
          description: >
            Optional password for the device.
            If not provided, a secure password is automatically generated by the system.
    SkylarkAccessUpdateRequest:
      type: object
      properties:
        password:
          type: string
          maxLength: 72
          description: >
            New password for the device (not stored in plaintext).
            Validated server-side as max 72 bytes in UTF-8.
        status:
          type: string
          enum: [ ACTIVE, SUSPENDED ]
          description: >
            Lifecycle status of the Skylark access.
            - ACTIVE: Access is enabled and usable
            - SUSPENDED: Access is disabled
      additionalProperties: false
      anyOf:
        - required: [ password ]
        - required: [ status ]
    SkylarkAccessBatchUpdateRequest:
      type: object
      required:
        - operationType
        - accessesIdList
        - operationBody
      additionalProperties: false
      properties:
        operationType:
          type: string
          enum: [ update, terminate ]
          description: |
            Type of batch operation to perform (PPU accesses only).
            - `update` — update password and/or status
            - `terminate` — terminate existing accesses
        accessesIdList:
          type: array
          minItems: 1
          description: List of Skylark access IDs to be processed.
          items:
            type: string
            minLength: 1
        operationBody:
          oneOf:
            - $ref: "#/components/schemas/SkylarkAccessUpdateRequest"
            - type: object
              maxProperties: 0
              description: Empty object required for 'terminate'
      description: Batch update request for Skylark accesses.
    SkylarkAccessCreateBatchRequest:
      type: object
      required:
        - contractId
      additionalProperties: false
      properties:
        contractId:
          type: string
          maxLength: 256
          description: ID of the Pay-Per-Use (PPU) contract to associate the accesses with.

        deviceName:
          type: string
          maxLength: 256
          description: >
            Base device name used when auto-generating accesses.
            Required when using 'numberOfAccesses'.

        accesses:
          type: array
          minItems: 1
          maxItems: 10000
          items:
            type: object
            additionalProperties: false
            required:
              - deviceName
            properties:
              deviceName:
                type: string
                maxLength: 256
              username:
                type: string
                maxLength: 256
              password:
                type: string
                maxLength: 256
        numberOfAccesses:
          type: integer
          minimum: 1
          maximum: 10000
          description: Number of accesses to auto-generate.
      allOf:
        - anyOf:
            - required: [ accesses ]
            - required: [ numberOfAccesses ]
        - not:
            required: [ accesses, numberOfAccesses ]
    Task:
      type: object
      required:
        - id
        - state
        - "@baseType"
        - "@type"
      properties:
        id:
          type: string
          description: >
            Unique identifier of the Task.
            The service currently generates identifiers with a 'job-' prefix.
        href:
          type: string
          description: URI to poll the Task
        state:
          type: string
          enum: [ ACKNOWLEDGED, IN_PROGRESS, DONE, FAILED, REJECTED, TERMINATED ]
        accesses:
          type: array
          description: >
            RealizingResources produced by the task.
            Present only when state is DONE.
          items:
            $ref: "#/components/schemas/RealizingResource"
        errors:
          type: array
          description: >
            Problems associated with the task.
            Present when state is FAILED or REJECTED.
          items:
            $ref: "#/components/schemas/Problem"
        "@baseType":
          type: string
          enum: [ task ]
        "@type":
          type: string
          enum: [ batchCreation ]
      example:
        id: "job-12345"
        state: "ACKNOWLEDGED"
        href: "https://<server>/skylark-access-management/v1/testtenant/access/batch/job-12345"
        "@baseType": "task"
        "@type": "batchCreation"
    BatchJobResponse:
      type: object
      required: [ id, href, state ]
      properties:
        id:
          type: string
          description: Batch task identifier.
        href:
          type: string
          description: URL where the task can be polled.
        state:
          type: string
          enum:
            - ACKNOWLEDGED
            - IN_PROGRESS
            - DONE
            - FAILED
            - REJECTED
            - TERMINATED
          description: >
            Current lifecycle state of the batch task.
            Use GET /access/batch/{taskId} to retrieve the full Task representation.
    Problem:
      type: object
      required:
        - status
        - title
        - detail
        - correlationId
        - "@type"
      properties:
        type:
          type: string
          description: A URI reference or label that identifies the problem type.
        title:
          type: string
          description: Short, human-readable summary of the problem type.
        status:
          type: integer
          format: int32
          description: HTTP status code.
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence.
        instance:
          type: string
          description: A URI reference that identifies the specific occurrence.
        correlationId:
          type: string
          description: Unique id of request.
        externalErrors:
          type: array
          description: External platform errors (if any).
          items:
            type: object
            required:
              - status
              - system
              - errorMessage
            properties:
              status:
                type: integer
                format: int32
              system:
                type: string
              errorMessage:
                type: string
              errorCode:
                type: string
            additionalProperties: true
        relatedParty:
          type: array
          description: Related parties (platform/account context) if applicable.
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              role:
                type: string
            additionalProperties: true
        "@type":
          type: string
          description: TMF type discriminator (e.g., "problem").
          example: problem
      additionalProperties: true
  parameters:
    skylark_filter:
      name: filter
      in: query
      description: >-
        Filter expression for accesses. Use '&' for AND and ';' for OR.<br/><br/>

        <b>Supported fields:</b><br/>
        - String fields (equality only): contractId, name, productOfferingId, createdBy, username.<br/>
          &nbsp;&nbsp;• <i>Note:</i> <b>name</b> filters the top-level <code>RealizingResource.name</code> field.<br/>
          &nbsp;&nbsp;• Other string fields map to <code>characteristic[].name/value</code> entries in the returned resource.<br/>
        - Date fields: createdAt, startDateTime, endDateTime support >, >=, <, <=, = operators.<br/>
          &nbsp;&nbsp;• <i>Note:</i> <b>createdAt</b> is a server-side metadata timestamp used only for filtering.
          It is <b>not included</b> in the returned <code>RealizingResource</code> payload.<br/><br/>

        <b>Operator support:</b><br/>
        - Non-date fields: = or .eq<br/>
        - Date fields: >, >=, <, <=, = and dot-notation (gt, gte, lt, lte, eq)<br/><br/>

        <b>Datetime format:</b><br/>
        - ISO-8601 format expected: <code>YYYY-MM-DDTHH:mm:ss[.SSS]Z</code><br/><br/>

        <b>Evaluation order:</b><br/>
        - '&' applies AND within a group<br/>
        - ';' applies OR between groups<br/><br/>

        <b>URL encoding notice:</b><br/>
        - Special characters (<code>&</code>, <code>;</code>, <code>&gt;</code>, <code>&lt;</code>) must be URL-encoded when calling the API.<br/><br/>

        <b>Examples:</b><br/>
        - name=Sensor&createdAt>=2024-01-01T00:00:00Z;name=Gateway<br/>
        - contractId=ABC123&startDateTime<2025-01-01T00:00:00Z<br/>
        - productOfferingId=Premium;productOfferingId=Basic<br/>
        - endDateTime.lte=2025-12-31T23:59:59Z<br/>
        - createdBy=job-123e4567-e89b-12d3-a456-426614174000
      required: false
      schema:
        type: string
      examples:
        and_or_mix:
          summary: AND within group, OR across groups
          value: name=Sensor&createdAt>=2024-01-01T00:00:00Z;name=Gateway
        contract_activation:
          summary: Contract + activation date before 2025
          value: contractId=ABC123&startDateTime<2025-01-01T00:00:00Z
        product_offer_or:
          summary: Either of two product offers
          value: productOfferingId=Premium;productOfferingId=Basic
        lte_expiration_dot:
          summary: Dot-notation operator for date
          value: endDateTime.lte=2025-12-31T23:59:59Z
        created_by_eq:
          summary: Filter by created task ID
          value: createdBy=job-123e4567-e89b-12d3-a456-426614174000
        username_by_eq:
          summary: Filter by username
          value: username=eos_positioning.user1
    id:
      name: id
      in: path
      description: Unique identifier for the access.
      required: true
      schema:
        type: string
    tenant_name:
      name: tenantName
      in: path
      description: Name of the tenant for which the operation is performed.
      required: true
      schema:
        type: string
    page_size:
      name: pageSize
      in: query
      description: number of items on the page.
      required: false
      schema:
        type: integer
        format: int32
        default: 10
        minimum: 1
        maximum: 100
    page_number:
      name: pageNumber
      in: query
      description: number of the current page.
      required: false
      schema:
        type: integer
        format: int32
        default: 1
        minimum: 1
        maximum: 1000
    content_type_json:
      name: Content-Type
      in: header
      required: true
      description: >
        Must be set to application/json.
        Required due to server-side content-type validation.
      schema:
        type: string
        enum: [ application/json ]
    content_type_merge_patch:
      name: Content-Type
      in: header
      required: true
      description: >
        Must be set to application/merge-patch+json.
        Required due to server-side content-type validation.
      schema:
        type: string
        enum:
          - application/merge-patch+json
  examples:
    BatchCreateByCount:
      summary: Create N accesses for a device
      value:
        contractId: "c-123"
        deviceName: "Auto"
        numberOfAccesses: 2
    BatchCreatePredefinedList:
      summary: Provide explicit list of access definitions
      value:
        contractId: "c-9"
        accesses:
          - deviceName: "D1"
            password: "p1"
          - deviceName: "D2"
            username: "u2"
    BatchJob_Acknowledged:
      summary: Batch job acknowledged
      value:
        id: "job-12345"
        href: "https://<server>/skylark-access-management/v1/testtenant/access/batch/job-12345"
        state: "ACKNOWLEDGED"
    CreateSkylarkAccessExample:
      value:
        contractId: "contract-000"
        deviceName: "device_001"
        username: "sensor_001"
        password: "pass_001"
    CreateSkylarkAccessResponseExample:
      value:
        id: "tenantXYZ_sensor_001"
        name: "tenantXYZ_device_001"
        status: "ACTIVE"
        characteristic:
          - name: "username"
            value: "tenantXYZ_sensor_001"
          - name: "contractId"
            value: "contract-000"
          - name: "type"
            value: "PPU"
          - name: "productOffering"
            value: "Mock Product Offering"
          - name: "productOfferingId"
            value: "Mock_Offering_External_ID"
          - name: "createdBy"
            value: null
          - name: "password"
            value: "pass_001"
        relatedProduct:
          id: "1b89819d-950c-4090-9194-b872350ae288"
        validFor:
          startDateTime: "2026-01-09T10:10:17.881Z"
          endDateTime: "2027-01-09T10:10:17.881Z"
        "@baseType": "Resource"
        "@type": "RealizingResource"
    GetSkylarkAccessByIdResponse:
      summary: Retrieved Skylark access (password not exposed)
      value:
        id: "tenant_example_776"
        name: "tenant_device_001"
        status: "ACTIVE"
        characteristic:
          - name: "username"
            value: "tenant_example_776"
          - name: "contractId"
            value: "contract-123"
          - name: "type"
            value: "PPU"
          - name: "productOffering"
            value: "XYZ"
          - name: "productOfferingId"
            value: "Mock_Offering_External_ID"
          - name: "createdBy"
            value: null
        relatedProduct:
          id: "c2eb54da-ba7c-4d4f-8e65-70c3cee78307"
        validFor:
          startDateTime: "2026-01-12T10:12:20.470Z"
          endDateTime: "2027-01-12T10:12:20.470Z"
        "@baseType": "Resource"
        "@type": "RealizingResource"
    Task_Acknowledged:
      summary: Task acknowledged (accepted for processing)
      value:
        id: "job-fb675b64-3e20-44d7-a3c0-bcb85a45133b"
        state: "ACKNOWLEDGED"
        href: "https://<server>/skylark-access-management/v1/testtenant/access/batch/job-fb675b64-3e20-44d7-a3c0-bcb85a45133b"
        "@baseType": "task"
        "@type": "batchCreation"
    Task_Done:
      summary: Task completed successfully
      value:
        id: "job-b9f798db-703f-44da-8a40-4f29326e8242"
        state: "DONE"
        href: "https://<server>/skylark-access-management/v1/testtenant/access/batch/job-b9f798db-703f-44da-8a40-4f29326e8242"
        accesses:
          - id: "tenantXYZ_sensor_001"
            name: "tenantXYZ_device_001"
            status: "ACTIVE"
            characteristic:
              - name: "username"
                value: "tenantXYZ_sensor_001"
              - name: "contractId"
                value: "contract-123"
            "@baseType": "Resource"
            "@type": "RealizingResource"
        "@baseType": "task"
        "@type": "batchCreation"
    Task_Rejected:
      summary: Task rejected with errors
      value:
        id: "job-c8a39ddc-ace9-40fc-b649-aa3cdec60d17"
        state: "REJECTED"
        errors:
          - type: "Service Unavailable"
            title: "Internal platform error"
            status: 503
            detail: "Tenant Management service unavailable: ECONNREFUSED"
            instance: "https://<server>/skylark-access-management/v1/testtenant/access/batch/job-c8a39ddc-ace9-40fc-b649-aa3cdec60d17"
            correlationId: "2f83fb5d-52d1-49e1-bb3b-bf34d413d129"
            "@type": "problem"
        "@baseType": "task"
        "@type": "batchCreation"
  responses:
    bad_request_validation_error:
      description: Request validation or business rule error.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          examples:
            skylark_username_taken:
              summary: Skylark username already taken
              value:
                type: "Bad Request"
                status: 400
                title: "External platform error"
                detail: "username:tenantXYZ_user_776: username is already taken"
                instance: "https://<server>/skylark-access-management/v1/tenantXYZ/access"
                externalErrors:
                  - status: 400
                    system: "Skylark"
                    errorMessage: "username:tenantXYZ_user_776: username is already taken"
                    errorCode: "2"
                relatedParty: [ ]
                correlationId: "d41a6fac-247f-4ece-9407-123be11e35f5"
                "@type": "problem"
    unauthorized_error:
      description: Authentication information is missing or invalid.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
    forbidden_error:
      description: >-
        Not enough permissions. The client has valid credentials 
        but not enough privileges to perform an action on a resource.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
    not_found_error:
      description: No data could be found by this request and its parameters.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          examples:
            access_not_found:
              summary: Skylark access not found
              value:
                type: "Not Found"
                title: "Resource not found"
                status: 404
                detail: "Skylark Access not found for ID: tenant_example_7777 (tenant: tenantXYZ)"
                instance: "https://<server>/skylark-access-management/v1/tenantXYZ/access/tenant_example_7777"
                externalErrors: [ ]
                relatedParty: [ ]
                correlationId: "57791b77-cae0-47f0-96bf-090bbcd82dce"
                "@type": "problem"
    unsupported_media_type_error:
      description: >
        Unsupported media type. Content-Type does not match the requirements
        defined for this endpoint.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
    too_many_requests_error:
      description: Too many requests sent in a given amount of time.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
    internal_server_error:
      description: Issue on server side.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
    service_unavailable_error:
      description: Service temporarily unavailable.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
  securitySchemes:
    oAuth:
      type: oauth2
      description: This API uses OAuth 2 with the clientCredentials grant flow.
      flows:
        clientCredentials:
          tokenUrl: https://spacegate.telekom.de/auth/realms/default/protocol/openid-connect/token
          scopes:
            ro%sam: read only role
            rw%sam: read-write role