openapi: 3.2.0
info:
  title: APIHUB Registry – External Auth API
  description: 'Public-facing API contract for APIHUB. This API is intended for external and integration clients and covers package/catalog operations, publication workflows, search, user/profile actions, and selected administration capabilities secured by APIHUB authentication schemes.

    '
  contact:
    name: Netcracker Opensource Group
    email: opensourcegroup@netcracker.com
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: '2026.1'
  x-api-kind: BWC
servers:
- url: https://{apihub}.qubership.org
  description: Primary APIHUB server endpoint (use the apihub variable to select production, development, or staging).
  variables:
    apihub:
      description: APIHUB subdomain/environment selector (apihub=production, dev.apihub=development, staging.apihub=staging).
      enum:
      - apihub
      - dev.apihub
      - staging.apihub
      default: apihub
security:
- BearerAuth: []
- CookieAuth: []
- api-key: []
- PersonalAccessToken: []
tags:
- name: Auth
  description: APIs for auth integrations.
paths:
  /api/v1/system/configuration:
    get:
      tags:
      - Auth
      summary: System configuration
      deprecated: true
      description: Global parameters of system configuration.
      operationId: getSystemConfiguration
      security:
      - {}
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - autoRedirect
                properties:
                  ssoIntegrationEnabled:
                    type: boolean
                  autoRedirect:
                    type: boolean
                  defaultWorkspaceId:
                    description: Id of the workspace, which is used by default while working with the system.
                    type: string
                    example: WSPACE1
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v2/system/configuration:
    get:
      tags:
      - Auth
      summary: System configuration
      description: Global parameters of system configuration.
      operationId: getSystemConfigurationV2
      security:
      - {}
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - authConfig
                properties:
                  defaultWorkspaceId:
                    description: Id of the workspace, which is used by default while working with the system.
                    type: string
                    example: WSPACE1
                  authConfig:
                    type: object
                    required:
                    - identityProviders
                    properties:
                      identityProviders:
                        type: array
                        minItems: 1
                        items:
                          type: object
                          required:
                          - id
                          - type
                          - displayName
                          - imageSvg
                          - loginStartEndpoint
                          properties:
                            id:
                              type: string
                            type:
                              type: string
                              enum:
                              - internal
                              - external
                            displayName:
                              type: string
                            imageSvg:
                              type: string
                            loginStartEndpoint:
                              type: string
                            refreshTokenEndpoint:
                              type: string
                      autoLogin:
                        type: boolean
                  extensions:
                    description: List of enabled extension services for apihub
                    type: array
                    items:
                      description: Extension item
                      type: object
                      properties:
                        name:
                          description: Unique name of the extension service
                          type: string
                          example: linter
                        baseUrl:
                          description: URL of the extension service
                          type: string
                          example: http://example.com
                        pathPrefix:
                          description: path for routing
                          type: string
                          example: api-linter
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v1/logout:
    post:
      tags:
      - Auth
      summary: User logout
      description: Logs out the authenticated user and invalidates all active sessions.
      operationId: logoutUser
      security:
      - BearerAuth: []
      - CookieAuth: []
      responses:
        '204':
          description: No content
          content: {}
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Unauthorized:
                  $ref: '#/components/examples/Unauthorized'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /login/sso/saml:
    get:
      x-nc-api-audience: noBWC
      tags:
      - Auth
      summary: SAML authentication (legacy)
      deprecated: true
      description: 'Starts the SAML authentication process in APIHUB (legacy endpoint).


        This is a deprecated endpoint. Use `/api/v1/login/sso/{idpId}` instead.


        In case of successful authentication, the request will be redirected to the **redirectUri** and

        the response will contain cookie with access token for future API calls.

        All subsequent APIHUB calls must use this token in a **CookieAuth** or **BearerAuth** authentication.

        '
      operationId: getLoginSsoSaml
      security:
      - {}
      - RefreshTokenAuth: []
      parameters:
      - name: redirectUri
        in: query
        description: URI, where user must be redirected in case of successful APIHUB authentication.
        required: false
        schema:
          type: string
          format: uri
          example: https://apihub.qubership.org/portal
      responses:
        '302':
          description: Found - Redirect to SAML identity provider
          headers:
            Location:
              description: URL of the SAML identity provider for authentication
              schema:
                type: string
                format: uri
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                IncorrectInputParams:
                  $ref: '#/components/examples/IncorrectInputParameters'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v2/auth/saml:
    post:
      x-nc-api-audience: noBWC
      tags:
      - Auth
      summary: SAML authentication
      deprecated: true
      description: 'Starts the SAML authentication process in APIHUB.


        In case of successful authentication, the request will be redirected to the **redirectUri** and

        the response will contain cookie with access token for future API calls.

        All subsequent APIHUB calls must use this token in a **BearerAuth** authentication.

        '
      operationId: postAuthSAML
      security:
      - {}
      parameters:
      - name: redirectUri
        in: query
        description: URI, where user must be redirected in case of successful APIHUB authentication.
        required: true
        schema:
          type: string
          format: uri
          example: https://apihub.qubership.org/portal
      responses:
        '302':
          description: Found
          headers:
            Set-Cookie:
              description: A base64 encoded userView cookie, containing the user data and access token.
              schema:
                type: string
                example: userView=eyJ0b2tlbiI6ImV5SmhiR2NpT2lKSVV6STFOaUlzSW10cFpDSTZJbk5sWTNKbGRDMXBaQ0lzSW5SNWNDSTZJa3BYVkNKOS5leUpGZUhSbGJuTnBiMjV6SWpwN2ZTd2lSM0p2ZFhCeklqcGJYU3dpU1VRaU9pSmxkbVZzTURJeE9TSXNJazVoYldVaU9pSmxkbVZzTURJeE9TSXNJbUYxWkNJNld5SWlYU3dpWlhod0lqb3hOamMwTURZNU1UVTRMQ0pwWVhRaU9qRTJOelF3TWpVNU5UZ3NJbTVpWmlJNk1UWTNOREF5TlRrMU9Dd2ljM1ZpSWpvaVpYWmxiREF5TVRraWZRLk45d2poeGhLRkoyTlEzNXpCaGw0VEs4VFBOS3RoeDE5czNQQnNheTNkclEiLCJyZW5ld1Rva2VuIjoiZXlKaGJHY2lPaUpJVXpJMU5pSXNJbXRwWkNJNkluTmxZM0psZEMxcFpDSXNJblI1Y0NJNklrcFhWQ0o5LmV5SkZlSFJsYm5OcGIyNXpJanA3ZlN3aVIzSnZkWEJ6SWpwYlhTd2lTVVFpT2lKbGRtVnNNREl4T1NJc0lrNWhiV1VpT2lKbGRtVnNNREl4T1NJc0ltRjFaQ0k2V3lJaVhTd2laWGh3SWpveE5qYzJOakUzT1RVNExDSnBZWFFpT2pFMk56UXdNalU1TlRnc0ltNWlaaUk2TVRZM05EQXlOVGsxT0N3aWMzVmlJam9pWlhabGJEQXlNVGtpZlEuUnRyZEEwNkJrN2lIQnA1bVRYUE1PSnVJdmhtQ0FudHRnVlBqNGZicXN6WSIsInVzZXIiOnsiaWQiOiJldmVsMDIxOSIsImVtYWlsIjoiZXZnZW5paS5lbGl6YXJvdkBuZXRjcmFja2VyLmNvbSIsIm5hbWUiOiJFdmdlbmlpIEVsaXphcm92IiwiYXZhdGFyVXJsIjoiL2FwaS92Mi91c2Vycy9ldmVsMDIxOS9wcm9maWxlL2F2YXRhciJ9fQ==;
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                IncorrectInputParams:
                  $ref: '#/components/examples/IncorrectInputParameters'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
components:
  examples:
    InternalServerError:
      description: 'Example: default internal server error response'
      value:
        status: 500
        code: APIHUB-8000
        reason: InternalServerError
        message: InternalServerError
    IncorrectInputParameters:
      description: Incorrect input parameters
      value:
        status: 400
        code: APIHUB-COMMON-4001
        message: Incorrect input parameters
    Unauthorized:
      description: Unauthorized access
      value:
        status: 401
        code: APIHUB-4101
        message: Authentication required
  schemas:
    ErrorResponse:
      description: Standard error response returned for failed requests. Includes HTTP status, internal error code, human-readable message, optional message parameters, and optional debug details (non-production only).
      type: object
      properties:
        status:
          description: HTTP status code as an integer; expected to match the actual HTTP response status.
          type: number
        code:
          description: Internal string error code. Mandatory in response.
          type: string
        message:
          description: Human-readable error message describing what went wrong; intended for diagnostics and safe client display.
          type: string
        params:
          type: object
          description: Optional key/value parameters used to format or contextualize the error message (for example, identifiers or field names).
          example:
            id: 12345
            type: string
        debug:
          description: Optional debug details (for example, stack traces). Returned only in development/test environments when verbose logging is enabled; do not rely on this field in production because it may contain sensitive data.
          type: string
      required:
      - status
      - code
      - message
  securitySchemes:
    BearerAuth:
      type: http
      description: 'Bearer token authentication (JWT). Default security scheme for API usage. Provide Authorization: Bearer <token>.'
      scheme: bearer
      bearerFormat: JWT
    CookieAuth:
      type: apiKey
      in: cookie
      name: apihub-access-token
      description: Authentication via the `apihub-access-token` cookie.
    api-key:
      type: apiKey
      description: API key authentication. Send the key in the api-key header.
      name: api-key
      in: header
    BasicAuth:
      type: http
      description: Login/password authentication.
      scheme: basic
    PersonalAccessToken:
      type: apiKey
      description: Personal access token authentication. Send the token in the X-Personal-Access-Token header; use for user-issued/script access.
      name: X-Personal-Access-Token
      in: header
    RefreshTokenAuth:
      type: apiKey
      in: cookie
      name: apihub-refresh-token
      description: Authentication via refresh token cookie
externalDocs:
  description: Find out more about this project and repository documentation
  url: https://github.com/Netcracker/qubership-apihub