Emporix OAuth API

openapi: 3.2.0
info:
  title: Emporix OAuth API
  version: ''
  contact:
    name: Emporix
    url: https://emporix.com
    email: documentation@emporix.com
  description: 'Operations tagged OAuth across 2 of this provider''s published API definitions: emporix-ai-service-openapi.yml, emporix-ai-service-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.emporix.io
tags:
- name: OAuth
  description: Manage OAuth configurations (Preview)
paths:
  /ai-service/{tenant}/agentic/oauths:
    parameters:
    - $ref: '#/components/parameters/path_tenant'
    - $ref: '#/components/parameters/qParam'
    - $ref: '#/components/parameters/pageSize'
    - $ref: '#/components/parameters/pageNumber'
    - $ref: '#/components/parameters/sort'
    - $ref: '#/components/parameters/fields'
    - $ref: '#/components/parameters/expandOAuth'
    - $ref: '#/components/parameters/header_xTotalCount'
    get:
      summary: Listing OAuth configurations
      operationId: GET-ai-list-oauths
      responses:
        '200':
          description: List of OAuth configurations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OAuthResponse'
              examples:
                OAuths Response:
                  $ref: '#/components/examples/OAuthsResponse'
        '400':
          $ref: '#/components/responses/400_resp_common'
        '401':
          $ref: '#/components/responses/401_resp_common'
        '403':
          $ref: '#/components/responses/403_resp_common'
      description: '{% hint style="danger" %}

        This functionality is in preview mode - some of the features may not be fully operational yet.

        {% endhint %}


        Retrieves OAuth configurations based on the provided query.'
      security:
      - OAuth2:
        - ai.agent_read
      tags:
      - OAuth
    servers:
    - url: https://api.emporix.io
  /ai-service/{tenant}/agentic/oauths/search:
    parameters:
    - $ref: '#/components/parameters/path_tenant'
    post:
      parameters:
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/pageNumber'
      - $ref: '#/components/parameters/sort'
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/expandOAuth'
      - $ref: '#/components/parameters/header_xTotalCount'
      summary: Searching OAuth configurations
      operationId: POST-ai-search-oauths
      responses:
        '200':
          description: List of OAuth configurations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OAuthResponse'
              examples:
                OAuths Response:
                  $ref: '#/components/examples/OAuthsResponse'
        '400':
          $ref: '#/components/responses/400_resp_common'
        '401':
          $ref: '#/components/responses/401_resp_common'
        '403':
          $ref: '#/components/responses/403_resp_common'
      requestBody:
        $ref: '#/components/requestBodies/QParamSearchBody'
      description: '{% hint style="danger" %}

        This functionality is in preview mode - some of the features may not be fully operational yet.

        {% endhint %}


        Searches for OAuth configurations based on the provided query.'
      security:
      - OAuth2:
        - ai.agent_read
      tags:
      - OAuth
    servers:
    - url: https://api.emporix.io
  /ai-service/{tenant}/agentic/oauths/{oauthId}:
    parameters:
    - $ref: '#/components/parameters/path_tenant'
    - schema:
        type: string
      name: oauthId
      in: path
      required: true
    get:
      parameters:
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/expandOAuth'
      summary: Retrieving OAuth configuration by ID
      operationId: GET-ai-retrieve-oauth
      responses:
        '200':
          description: A single OAuth configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthResponse'
              examples:
                OAuth Response:
                  $ref: '#/components/examples/OAuthResponse'
        '401':
          $ref: '#/components/responses/401_resp_common'
        '403':
          $ref: '#/components/responses/403_resp_common'
        '404':
          $ref: '#/components/responses/404_resp_common'
      description: '{% hint style="danger" %}

        This functionality is in preview mode - some of the features may not be fully operational yet.

        {% endhint %}


        Retrieves the OAuth configuration by a given ID.'
      security:
      - OAuth2:
        - ai.agent_read
      tags:
      - OAuth
    put:
      summary: Upserting OAuth configuration
      parameters:
      - $ref: '#/components/parameters/forceDisable'
      operationId: PUT-ai-upsert-oauth
      responses:
        '201':
          description: ID of created OAuth configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdResponse'
              examples:
                Id Of Created OAuth:
                  $ref: '#/components/examples/IdResponse'
        '204':
          description: The resource has been successfully updated.
        '400':
          $ref: '#/components/responses/400_resp_common'
        '401':
          $ref: '#/components/responses/401_resp_common'
        '403':
          $ref: '#/components/responses/403_resp_common'
        '404':
          $ref: '#/components/responses/404_resp_common'
        '409':
          $ref: '#/components/responses/409_resp_common'
      description: '{% hint style="danger" %}

        This functionality is in preview mode - some of the features may not be fully operational yet.

        {% endhint %}


        Updates or creates a specified OAuth configuration by replacing all of its existing data with data from the request body.

        If the `metadata.version` is provided, then optimistic locking is enabled and version must match the version in the database.


        Currently only the `client_credentials` grant type is supported.'
      security:
      - OAuth2:
        - ai.agent_manage
      requestBody:
        $ref: '#/components/requestBodies/oauthUpsertBody'
      tags:
      - OAuth
    patch:
      summary: Partially updating OAuth configuration
      parameters:
      - $ref: '#/components/parameters/forceDisable'
      operationId: PATCH-ai-update-oauth
      responses:
        '204':
          description: No Content
        '400':
          $ref: '#/components/responses/400_resp_common'
        '401':
          $ref: '#/components/responses/401_resp_common'
        '403':
          $ref: '#/components/responses/403_resp_common'
        '404':
          $ref: '#/components/responses/404_resp_common'
      description: '{% hint style="danger" %}

        This functionality is in preview mode - some of the features may not be fully operational yet.

        {% endhint %}


        Partially updates a single OAuth configuration document with given information.

        Single update may contain multiple partial updates in the form of an array. It contains the allowed operations list:

        - `add` (adding an item to the items list)

        - `remove` (removing an item from the items list)

        - `replace` (replacing an item with given ID with new definition)'
      security:
      - OAuth2:
        - ai.agent_manage
      requestBody:
        $ref: '#/components/requestBodies/oauthPatchBody'
      tags:
      - OAuth
    delete:
      parameters:
      - $ref: '#/components/parameters/force'
      summary: Deleting OAuth configuration
      operationId: DELETE-ai-delete-oauth
      responses:
        '204':
          description: Given OAuth configuration has been deleted.
        '400':
          $ref: '#/components/responses/400_resp_common'
        '401':
          $ref: '#/components/responses/401_resp_common'
        '403':
          $ref: '#/components/responses/403_resp_common'
      description: '{% hint style="danger" %}

        This functionality is in preview mode - some of the features may not be fully operational yet.

        {% endhint %}


        Deletes OAuth configuration by given ID.


        ***Important***: If an OAuth configuration is being used by an agent, then delete operation is not possible without `force` flag set to `true`.'
      security:
      - OAuth2:
        - ai.agent_manage
      tags:
      - OAuth
    servers:
    - url: https://api.emporix.io
components:
  parameters:
    qParam:
      in: query
      name: q
      description: 'A standard query parameter is used to search for specific values.


        See: [Standard Practices - Query parameter](https://developer.emporix.io/api-documentation/standard-practices/q-param)

        '
      schema:
        type: string
    forceDisable:
      schema:
        type: boolean
      in: query
      name: force
      example: false
      description: Allows you to disable a given entity even if it is used as a dependency in other entries. In that case, cascade disable is performed.
    sort:
      schema:
        type: string
      in: query
      name: sort
      description: List of properties used to sort the results, separated by colons.
    expandOAuth:
      schema:
        type: string
        enum:
        - token
      in: query
      name: expand
      description: Fields to be expanded in the response. It means that instead of the object IDs, the whole objects are returned in the response.
    header_xTotalCount:
      schema:
        type: boolean
      in: header
      name: X-Total-Count
      description: Flag indicating whether the total number of retrieved results should be returned.
    path_tenant:
      name: tenant
      in: path
      required: true
      schema:
        type: string
      description: 'Your Emporix tenant name.


        **Note**: The tenant name should always be provided in lowercase.

        '
    force:
      schema:
        type: boolean
      in: query
      name: force
      example: false
      description: Allows you to remove a given entity even if it is used as a dependency in other entries. In that case, the removed entity is unassigned from other entries.
    pageNumber:
      schema:
        type: string
      in: query
      name: pageNumber
      description: The page number to be retrieved. The size of the pages should be specified by the `pageSize` parameter.
    pageSize:
      schema:
        type: string
      in: query
      name: pageSize
      description: The number of documents to be retrieved per page.
    fields:
      schema:
        type: string
      in: query
      name: fields
      description: Fields to be returned in the response.
  schemas:
    ErrorMessage:
      type: object
      properties:
        code:
          type: integer
        type:
          type: string
        message:
          type: string
        moreInfo:
          type: string
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              type:
                type: string
              message:
                type: string
              moreInfo:
                type: string
      description: ''
    QParamSearchBody:
      type: object
      properties:
        q:
          type: string
          description: "A standard query parameter is used to search for specific values. \n\nSee: [Standard Practices - Query parameter](https://developer.emporix.io/api-documentation/standard-practices/q-param)\n"
    IdWrapperRequest:
      type: object
      properties:
        id:
          type: string
      required:
      - id
    OAuthResponse:
      allOf:
      - $ref: '#/components/schemas/OAuth'
      - type: object
        properties:
          id:
            type: string
            description: Unique identifier of the entity.
          clientSecretToken:
            $ref: '#/components/schemas/ExpandableTokenResponse'
          metadata:
            $ref: '#/components/schemas/MetadataResponse'
    ExpandedTokenResponse:
      allOf:
      - $ref: '#/components/schemas/IdResponse'
      - type: object
        properties:
          name:
            type: string
            description: Name of the token.
          metadata:
            $ref: '#/components/schemas/MetadataResponse'
    IdResponse:
      type: object
      properties:
        id:
          type: string
          description: Identifier of the resource.
    ErrorMessageFault:
      type: object
      properties:
        fault:
          type: object
          properties:
            faultstring:
              type: string
            detail:
              type: object
              properties:
                errorcode:
                  type: string
    ExpandableTokenResponse:
      oneOf:
      - $ref: '#/components/schemas/IdResponse'
      - $ref: '#/components/schemas/ExpandedTokenResponse'
      description: The full response representing token. If the `expand=token` is **not** used, then only `id` field is returned, otherwise all fields are returned.
    OAuthRequest:
      allOf:
      - $ref: '#/components/schemas/OAuth'
      - type: object
        properties:
          clientSecretToken:
            $ref: '#/components/schemas/IdWrapperRequest'
          metadata:
            $ref: '#/components/schemas/MetadataRequest'
    OAuth:
      type: object
      description: OAuth 2.0 client-credentials settings for authenticating with a self-hosted LLM backend.
      properties:
        url:
          type: string
          format: uri
          description: Token endpoint URL of the OAuth 2.0 authorization server used to request an access token.
        clientId:
          type: string
          description: OAuth 2.0 client identifier registered with the authorization server.
        grantType:
          type: string
          description: OAuth 2.0 grant type used to obtain an access token. Currently only `client_credentials` is supported.
          enum:
          - client_credentials
        scope:
          type: string
          description: Optional space-separated list of scopes to request for the access token.
        enabled:
          type: boolean
          description: Indicates whether the OAuth configuration is enabled.
          example: true
      required:
      - url
      - clientId
      - grantType
    PatchRequest:
      type: array
      description: Partial update operation list.
      items:
        type: object
        properties:
          op:
            anyOf:
            - enum:
              - ADD
              - REMOVE
              - REPLACE
            type: string
          path:
            type: string
            example: /name
          value:
            anyOf:
            - type: string
              description: Value of the string type.
            - type: object
              description: Any part of the details object.
        required:
        - op
        - path
    MetadataResponse:
      allOf:
      - $ref: '#/components/schemas/MetadataRequest'
      - type: object
        properties:
          createdAt:
            description: 'Date and time when the object was created. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-30T13:18:02.379Z`'
            type: string
          modifiedAt:
            description: 'Date and time when the object was last modified. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-30T13:18:02.379Z`'
            type: string
        required:
        - version
        - createdAt
        - modifiedAt
    MetadataRequest:
      type: object
      properties:
        version:
          minimum: 1
          type: integer
          description: Version of the object. The version is required during the update operation because of the optimistic locking mechanism.
      required:
      - version
  requestBodies:
    oauthUpsertBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OAuthRequest'
          examples:
            Create Client Credentials OAuth:
              $ref: '#/components/examples/OAuthRequest'
    oauthPatchBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PatchRequest'
          examples:
            Change clientId:
              value:
              - op: REPLACE
                path: /clientId
                value: client-1-updated
            Disable OAuth:
              value:
              - op: REPLACE
                path: /enabled
                value: false
    QParamSearchBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QParamSearchBody'
          examples:
            Search Request:
              value:
                q: name:~Complaint
  responses:
    409_resp_common:
      description: "There are three possible reasons:\n 1. Resource with given code already exists, please choose unique code for your resource\n 2. Optimistic locking failed. If user sends metadata/version attribute which is outdated (someone else updated resource in the time user was performing his changes). User should retrieve the latest product data and retry the request.\n 3. Optimistic locking failed. User did not provide metadata/version attribute in update request, but someone else updated product while it was internally handled by product service. Resending the same request can result in successful update, but the update can override recently persisted changes.\n"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Resource conflict:
              value:
                code: 409
                status: Conflict
                message: Conflict - a resource with given code or id has already exist.
    403_resp_common:
      description: Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Access forbidden:
              value:
                code: 403
                status: Forbidden
                message: The access to the requested resource has been forbidden by the server.
    400_resp_common:
      description: The request was syntactically incorrect.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Code must not be null:
              value:
                code: 400
                status: Bad Request
                message: Validation problem with request body.
                details:
                - message: code must not be null nor blank
    401_resp_common:
      description: The authorization token is invalid or has expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessageFault'
          examples:
            Invalid access token:
              value:
                fault:
                  faultstring: Invalid access token
                  detail:
                    errorcode: oauth.v2.InvalidAccessToken
            Access token expired:
              value:
                fault:
                  faultstring: Access Token expired
                  detail:
                    errorcode: keymanagement.service.access_token_expired
    404_resp_common:
      description: Example response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Resource not found:
              value:
                resourceId: 628cd20c6e8b2432b6346ca6
                code: 404
                status: Not Found
                message: The resource with id 628cd20c6e8b2432b6346ca6 has not been found.
  examples:
    IdResponse:
      value:
        id: a81bc81b-dead-4e5d-abff-90865d1e13b1
    OAuthResponse:
      value:
        id: oauth-1
        url: https://auth.example.com/token
        clientId: client-1
        clientSecretToken:
          id: token-id
        grantType: client_credentials
        scope: llm read
        enabled: true
    OAuthsResponse:
      value:
      - id: oauth-1
        url: https://auth.example.com/token
        clientId: client-1
        clientSecretToken:
          id: token-id
        grantType: client_credentials
        scope: llm read
        enabled: true
      - id: oauth-2
        url: https://auth2.example.com/token
        clientId: client-2
        clientSecretToken:
          id: token-id-2
        grantType: client_credentials
        scope: llm
        enabled: true
    OAuthRequest:
      value:
        url: https://auth.example.com/token
        clientId: client-1
        clientSecretToken:
          id: token-id
        grantType: client_credentials
        scope: llm read
        enabled: true
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          scopes:
            ai.text_manage: Needed to execute actions related to the text generation.
            ai.completion_manage: Needed to execute actions related to the AI completions.
            ai.agentexecution_manage: Needed to execute agentic chat.
            ai.agentexecution_manage_own: Needed to execute agentic chat by customers.
            ai.agent_read: Needed to read AI agents.
            ai.agent_manage: Needed to manage AI agents.
          tokenUrl: https://api.emporix.io/oauth/token
x-refined-from:
- emporix-ai-service-openapi.yml
- emporix-ai-service-openapi.yml