openapi: 3.1.0
info:
  title: API Reference agentic-search > agenticSearch systemCredentials API
  version: 1.0.0
servers:
- url: https://api.coactive.ai
  description: Production
- url: https://app.coactive.ai
  description: Production
tags:
- name: systemCredentials
paths:
  /api/v1/auth-management/clients:
    post:
      operationId: create-credentials
      summary: Create Credentials
      description: 'Create new system-level credentials. System-level credentials are not tied to a specific

        user and never expire.


        The access of the system-level credentials are scoped to the specified roles. **If no

        roles are provided, the system-level credentials will have full access to all resources**.


        The client id and client secret of the created credentials can be exchanged for access tokens

        which can be used to make requests to the API. These credentials should only be used for

        programmatic access to the API as they are not tied to a specific user.'
      tags:
      - systemCredentials
      parameters:
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '201':
          description: The details of the created system-level credentials, including the client ID and secret
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError1'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateClientRequest'
    get:
      operationId: list-credentials
      summary: List Credentials
      description: 'List all system-level credentials in the organization.


        System-level credentials are not tied to a specific user and never expire.'
      tags:
      - systemCredentials
      parameters:
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A list of system-level credentials
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ClientResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError1'
  /api/v1/auth-management/clients/{client_id}:
    delete:
      operationId: delete-credentials
      summary: Delete Credentials
      description: 'Delete system-level credentials.


        This endpoint permanently deletes the system-level credentials and revokes all associated tokens.

        This action cannot be undone.'
      tags:
      - systemCredentials
      parameters:
      - name: client_id
        in: path
        description: The client ID of the system-level credentials
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError1'
    get:
      operationId: get-credentials
      summary: Get Credentials
      description: 'Get specific system-level credentials by id.


        This endpoint retrieves the details of specific system-level credentials,

        including its roles and configuration.'
      tags:
      - systemCredentials
      parameters:
      - name: client_id
        in: path
        description: The client ID of the system-level credentials
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The details of a specific system-level credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError1'
    put:
      operationId: update-credentials
      summary: Update Credentials
      description: 'Update system-level credentials.


        This endpoint allows updating the name and roles of existing system-level credentials.


        The access of the system-level credentials is scoped to its roles. **If no roles are provided,

        the system-level credentials will have full access to all resources**. If the credentials

        was previously assigned roles and no roles are provided in the update request, the credentials

        will gain full access to all resources.'
      tags:
      - systemCredentials
      parameters:
      - name: client_id
        in: path
        description: The client ID of the system-level credentials
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The updated system-level credentials details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError1'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateClientRequest'
components:
  schemas:
    ValidationError1:
      type: object
      properties:
        loc:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError1LocItems'
        msg:
          type: string
        type:
          type: string
      required:
      - loc
      - msg
      - type
      title: ValidationError1
    ClientResponse:
      type: object
      properties:
        client_id:
          type: string
          description: OAuth client ID
        client_secret:
          type: string
          description: OAuth client secret (only returned on creation)
        name:
          type: string
          description: Display name for the OAuth client
        roles:
          type: array
          items:
            $ref: '#/components/schemas/Role'
          description: List of roles assigned to the client
      required:
      - client_id
      - client_secret
      - name
      - roles
      description: System-level credentials
      title: ClientResponse
    CreateClientRequest:
      type: object
      properties:
        name:
          type: string
          description: Display name for the system-level credentials
        roles:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Role'
          description: List of roles to assign to the system-level credentials. This is only available to organizations that are RBAC-enabled. Please contact support if you would like to enable RBAC for your organization.
      required:
      - name
      description: Create system-level credentials request model
      title: CreateClientRequest
    Role:
      type: object
      properties:
        role_id:
          type: string
          description: Name of the role (e.g., 'admin', 'editor', 'viewer')
        resource:
          type:
          - string
          - 'null'
          description: Optional resource type the role applies to (e.g., 'dataset')
        resource_instance:
          type:
          - string
          - 'null'
          description: Optional resource instance ID the role applies to
      required:
      - role_id
      description: Role model for user and client roles
      title: Role
    HTTPValidationError1:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError1'
      title: HTTPValidationError1
    ValidationError1LocItems:
      oneOf:
      - type: string
      - type: integer
      title: ValidationError1LocItems
    UpdateClientRequest:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: Display name for the system-level credentials
        roles:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Role'
          description: List of roles to assign to the system-level credentials. This is only available to organizations that are RBAC-enabled. Please contact support if you would like to enable RBAC for your organization.
        roles_context:
          type:
          - string
          - 'null'
          description: Context for the roles to update. This can either be 'system' for system-level roles or 'dataset:{dataset_id}' for dataset-level roles.
      description: Update system-level credentials request model
      title: UpdateClientRequest
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer