openapi: 3.0.1
info:
  contact:
    name: Polarion REST API Support
    url: https://support.sw.siemens.com/
  description: <h5>About</h5>The Polarion REST API lets you interact with Polarion programmatically. Use this API to integrate Polarion with your applications. This page documents the REST resources, including the HTTP response codes and example requests and responses. <br/><br/>For a detailed description of the REST API and how to use it, see the <a href="https://docs.sw.siemens.com/en-US/doc/230235217/PL20250606201928474.polarion_help_sc.xid2134849/xid2134871" target="_blank">REST API User Guide</a> (available on Support Center).
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  title: Polarion REST Account API
  version: v1
servers:
- url: https://example.com/polarion/rest/v1
security:
- bearerAuth: []
tags:
- name: Account
paths:
  /token:
    post:
      tags:
      - Account
      summary: Login to get the bearer token for protected endpoints
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  default: password
                  description: Defines the method obtaining the access token.
                  enum:
                  - password
                  - applicationSession
                  - urn:ietf:params:oauth:grant-type:token-exchange
                  - refresh_token
                authenticatorId:
                  type: string
                  default: Siemens.TCPCM.AuthenticationMethod.TcPCM
                  description: TcPCM authentication method to be used with the provided credentials.
                  enum:
                  - Siemens.TCPCM.AuthenticationMethod.TcPCM
                  - Siemens.TCPCM.AuthenticationMethod.Windows
                  - Siemens.TCPCM.AuthenticationMethod.SamAuth
                client_id:
                  type: string
                  default: TcPCM
                  description: Uniquely identifies the application making the request for authentication purposes.
                client_secret:
                  type: string
                  default: Your_Client_Secret
                  description: Confidential key used alongside the client_id to securely authenticate the application making the request.
                username:
                  type: string
                  default: Administrator
                  description: TcPCM or Windows user name depending on the authenticatorId.
                password:
                  type: string
                  default: ''
                  description: Corresponding password of the username.
                subject_token_type:
                  type: string
                  description: Type of the token to be exchanged for the login. Only "urn:ietf:params:oauth:token-type:access_token" is supported.
                  enum:
                  - urn:ietf:params:oauth:token-type:access_token
                subject_token:
                  type: string
                  description: Value of the exchanged token.
                tcpcmSessionKey:
                  type: string
                  description: Session identifier that can be obtained via the TcPCM client application plugin.
                refresh_token:
                  type: string
                  description: Refresh token that you obtained via the initial authentication.
              required:
              - grant_type
              - client_id
              - client_secret
      responses:
        '200':
          description: Successful login
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                    description: Bearer token for authorization
                  token_type:
                    type: string
                    description: Only "bearer" is supported
                  expires_in:
                    type: integer
                    description: Seconds until the token expires
                  refresh_token:
                    type: string
                    description: Token to be used for resetting the expiration date
                  as:client_id:
                    type: string
                    description: Requested client id
                  as:TcPCMAuthenticatorId:
                    type: string
                    description: Requested authenticator id
                  .issued:
                    type: string
                    description: Login timestamp
                  .expires:
                    type: string
                    description: Expiration date
                required:
                - access_token
                - token_type
                - expires_in
                - refresh_token
                - as:client_id
                - as:TcPCMAuthenticatorId
                - .issued
                - .expires
        '400':
          description: Bad request. Login failed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error title
                  error_description:
                    type: string
                    description: Detailed error description
                required:
                - error
                - error_description
        '500':
          description: Server error. Login failed.
          content:
            text/html:
              schema:
                type: string
                description: Error description
      description: 'TcPCM supports three different login flows:

        1. **Resource Owner Password flow**: Use the *username* and *password* with the *grant\_type* "password" and *authenticatorId* "Siemens.TCPCM.AuthenticationMethod.TcPCM" or "Siemens.TCPCM.AuthenticationMethod.Windows".

        2. **Token Exchange flow**: Use the *subject\_token\_type* and *subject\_token* with the *grant\_type* "urn:ietf:params:oauth:grant-type:token-exchange" and *authenticatorId* "Siemens.TCPCM.AuthenticationMethod.SamAuth".

        3. **Custom flow**: Use the *tcpcmSessionKey* with the *grant\_type* "applicationSession" without *authenticatorId*.


        Refresh token flow:

        * The refresh token can be used to generate a new bearer token without re-authenticating.

        * The *grant\_type* must be set to "refresh\_token" and the *refresh\_token* must be provided that was obtained via the initial authentication.'
  /api/v1/Account/Logout:
    get:
      tags:
      - Account
      summary: Logout and invalidate tokens
      operationId: Account_Logout
      security:
      - bearerHttpAuthentication: []
      parameters:
      - name: refreshTokenId
        in: query
        description: Refresh Token Id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully logged out.
        '401':
          description: Indicates that the requested resource requires authentication.
        '500':
          description: Indicates that a generic error has occurred on the server.
      deprecated: false
      description: Please note that the *refreshTokenId* needs to be transferred as a query parameter.
  /api/v1/Account/DeleteRefreshToken:
    get:
      tags:
      - Account
      summary: Delete RefreshToken
      operationId: Account_DeleteRefreshToken
      parameters:
      - name: refreshTokenId
        in: query
        description: Refresh Token Id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: RefreshToken successfully removed.
        '500':
          description: Indicates that a generic error has occurred on the server.
      deprecated: false
components:
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http