openapi: 3.0.3
info:
  title: OAuth Authorization Server
  description: >-
    The OAuth Authorization Server provides APIs for authentication and authorization.<br>
    Especially, it provides APIs for requesting access tokens and retrieving the public key used for signing Json Web Tokens issued by the OAuth Authorization Server.<br><br>
    <i>Note:</i>The endpoints described below are application provider-specific and environment-specifc.<br>
    Generic pattern: <i>https://&lt;application-provider-name&gt;.piam.&lt;environment&gt;</i><i>.mindsphere.io</i>
    <br><br>
    BaseUrl: https://1000001700.eu1.sws.siemens.com
  version: '3.2.0'
  x-released: yes
  x-visibility: external
tags:
  - name: token_endpoint
    description: OAuth 2.0 Token Endpoint (see RFC 6749)
  - name: token_exchange
    description: OAuth 2.0 Token Exchange Endpoint (see RFC 8693)
  - name: token_keys_endpoint
    description: An endpoint which returns the list of public keys used for token signing (see also RFC 7517, 7518). <i>Note:</i>The RSA modulus and exponent may start with leading "0" byte (in contrast to RFC 7518).
paths:
  /oauth/token:
    post:
      tags:
        - token_endpoint
      operationId: tokenEndpointPostClientCredentialsGrant
      summary: Client Credentials Grant
      description: |
        OAuth 2.0 Client Credentials Grant (see RFC 6749). Endpoint requires client authentication via Authorization header using "Basic" scheme (see RFC 7617). <br>
        <b>Note</b>: Following parameters are not honoured for FDS IAM modular tenant's  authorization flow: <b>"app-name"</b> & <b>"provider-tenant"</b>
      parameters:
        - name: grant_type
          schema:
            type: string
            enum: [client_credentials]
          in: query
          required: true
        - name: iam-action
          schema:
            type: string
            oneOf:
              - title: client_credentials.tenant-impersonation
          in: query
          description: This parameter indicates a request for tenant impersonation. When using this parameter, additional metadata must be provided to clearly specify the target of impersonation (e.g., tenant, ).<br>
            Furthermore, the OAuth client used to generate the access token must have the iam-action.client_credentials.tenant-impersonation scope assigned to it. This scope explicitly authorizes the client to perform impersonation actions under the client credentials grant type.
        - name: tenant
          schema:
            type: string
            oneOf:
              - title: Tenant id.
          in: query
          description: Specifies the tenant that needs to be impersonated. This parameter is required when performing tenant impersonation and must correspond to a valid tenant ID within the system.
        - name: app-name
          schema:
            type: string
            oneOf:
              - title: Name of the application that is provisioned to the tenant passed under tenant param.
          in: query
          description: Specifies the application name (only web/desktop application) for which the impersonation token is being requested. This is particularly relevant in scenarios involving tenant-centric technical users or app-credentials, where the token is intended to act on behalf of a specific application registered under a provider tenant.
        - name: provider-tenant
          schema:
            type: string
            oneOf:
              - title: Name of the provider where application is registered.
          in: query
          description: Identifies the owner of the application referenced in app-name. This is the tenant under which the application is registered and typically represents the provider organization managing the application.
        - name: scope
          schema:
            type: string
            oneOf:
              - title: Requested scopes, space-delimited.
          in: query
          description: This parameter defines the level of access or permissions requested by the client during the token request. It determines what actions the issued access token will be allowed to perform.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessTokenResponse'
        default:
          description: Unauthorized
  /oauth/v2/token:
    post:
      tags:
        - token_exchange
      operationId: apiMeteringExchangeToken
      summary: >-
        Token exchange with impersonation and delegation (v2) - RFC 8693.
      description: >-
        Token exchange endpoint supporting both impersonation and delegation flows as per RFC 8693.
        This endpoint uses the token exchange grant type (urn:ietf:params:oauth:grant-type:token-exchange)
        for cross-tenant and cross-service token exchange scenarios.

        **Supported Flows:**

        1. **Impersonation Flow** (without actor_token)
           - The resulting token represents the same identity as the subject_token
           - Used when a service needs to act on behalf of the user with a different token issuer
           - The 'sub' claim in the exchanged token represents the original subject

        2. **Delegation Flow** (with actor_token)
           - The resulting token contains both subject and actor information
           - Used when a service acts on behalf of a user but needs to identify itself as the actor
           - The 'act' claim in the exchanged token contains the actor's identity
           - Supports composite delegation chains

      requestBody:
        description: Token to exchange
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenExchangeRequestEntity'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenExchangeResponseEntity'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden

  /token_keys:
    get:
      tags:
        - token_keys_endpoint
      operationId: tokenKeysEndpoint
      summary: Token keys endpoint
      description: The endpoint returns the list of public keys used for token signing (see also RFC 7517, 7518). <i>Note:</i>The RSA modulus and exponent may start with leading "0" byte (in contrast to RFC 7518).
      responses:
        default:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenKeysResponse'
components:
  schemas:
    AccessTokenResponse:
      type: object
      properties:
        access_token:
          type: string
          example: ey...
        token_type:
          type: string
          example: Bearer
        expires_in:
          type: integer
          format: int64
          example: 1800
        scope:
          type: string
          example: api.read api.write
        jti:
          type: string
          example: b019ceb63513456c88f2d67c0e92d35b
    TokenKeysResponse:
      type: object
      properties:
        keys:
          type: array
          items:
            $ref: '#/components/schemas/JsonWebKeyIncl0'

    JsonWebKeyIncl0:
      type: object
      properties:
        kty:
          type: string
          example: "RSA"
        e:
          type: string
          example: "AQAB"
        use:
          type: string
          example: "sig"
        kid:
          type: string
          example: "key-id-1"
        n:
          type: string
          example: "AJYu9cMVw4JUqt_X2F7Q3n68aRdtJljwpcVcIr4kp18xbSFt77U8-6bYbygYtLMHEJt5_i5WrQUbOvmrjz4sO4jQShhhkoKPtd0Uee3Ofm47cRsjRtQm7ZoyI16eTaFfs1ed7vCIIl73ZROYYTBfKsh7GTtvtuJsbLHKJWNTih8fI05gsmX-nyx0JkTBXVjzAOxnzWLJrBnPCO4gPmrKl0c0V7HIW00yrn2XHhnE8nBJBAPgq_AyIPCTVT7n9RVRwCx8P8IWnM_nS4-EZs4cPyauioZ0ua-EV7ybJd7KI-GJ-MZWDT1RhRLycD5aWBzUiEoHGY1WfwnZiKRatrcrz30"
    TokenExchangeRequestEntity:
      type: object
      required:
        - subject_token
        - subject_token_type
        - grant_type
      properties:
        subject_token:
          type: string
          description: The security token representing the subject (identity) on whose behalf the request is made.
          example: 'eyJqa3UiOiJodHRwczovL2lhbWZpdGVwcHJvZC51czEtaW50LnN3cy5zaWVtZW5zLmNvbS90b2tlbl9rZXlzIiwia2lkIjoia2V5LWlkLTYiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9'
        subject_token_type:
          type: string
          description: JWT Token
          enum:
            - urn:ietf:params:oauth:token-type:access_token
            - urn:ietf:params:oauth:token-type:id_token
        actor_token:
          type: string
          description: Token representing the actor performing the exchange. Used for delegation or impersonation scenarios.
          example: 'eyJqa3UiOiJodHRwczovL2lhbWZpdGVwcHJvZC51czEtaW50LnN3cy5zaWVtZW5zLmNvbS90b2tlbl9rZXlzIiwia2lkIjoia2V5LWlkLTYiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9'
        actor_token_type:
          type: string
          description: JWT Token
          enum:
            - urn:ietf:params:oauth:token-type:access_token
        scopes:
          type: string
          description: Requested scopes in  the exchanged token.
          example: 'tokendelegationapi.default'
        grant_type:
          type: string
          description: Only 'urn:ietf:params:oauth:grant-type:token-exchange' is allowed'
          example: "urn:ietf:params:oauth:grant-type:token-exchange"

    TokenExchangeResponseEntity:
      type: object
      properties:
        access_token:
          type: string
          example: 'eyJraWQiOiJrZXktaWQtNiIsImFsZyI6IlJTMjU2IiwidHlwIjoiSldUIiwiamt1IjoiaHR0cHM6Ly94ZmZpdHBwcm9kLnVzMS1pbnQuc3dzLnNpZW1lbnMuY29tL3Rva2VuX2tleXMifQ....'
        token_type:
          type: string
          example: Bearer
        issued_token_type:
          type: string
          example: 'urn:ietf:params:oauth:token-type:access_token'
        expires_in:
          type: integer
          format: int64
          example: 3600
        scope:
          type: string
          example: 'analytics.read'
        jti:
          type: string
          example: '07fc82411c7844d0935a25ed546b0e71'
    WellknownConfigResponse:
      type: object
      properties:
        issuer:
          type: string
        authorization_endpoint:
          type: string
        token_endpoint:
          type: string
        end_session_endpoint:
          type: string
        token_endpoint_auth_methods_supported:
          type: array
          items:
            type: string
        token_endpoint_auth_signing_alg_values_supported:
          type: array
          items:
            type: string
        scopes_supported:
          type: array
          items:
            type: string
        response_types_supported:
          type: array
          items:
            type: string
        subject_types_supported:
          type: array
          items:
            type: string
        claim_types_supported:
          type: array
          items:
            type: string
        claims_supported:
          type: array
          items:
            type: string
        claims_parameter_supported:
          type: boolean
        service_documentation:
          type: string
        ui_locales_supported:
          type: array
          items:
            type: string
        code_challenge_methods_supported:
          type: array
          items:
            type: string
