openapi: 3.2.0
info:
  description: '# Authentication

    The Chef Automate API typically uses an API token passed in the header of your API request.'
  title: Chef Automate API Documentation User Settings Service API
  termsOfService: https://www.chef.io/terms-and-conditions-of-use/
  contact:
    url: https://www.chef.io/support/
    email: support@chef.io
  license:
    name: Apache 2.0
    url: https://github.com/chef/automate/blob/main/LICENSE
  version: version not set
  x-logo:
    altText: Chef logo
    url: /images/chef-automate-logo.svg
servers:
- url: https://automate.chef.io
tags:
- name: UserSettingsService
  x-displayName: User Settings and Audit Logs
paths:
  /api/v0/audit/admin/request:
    get:
      tags:
      - UserSettingsService
      summary: RequestAdminAuditLogs initiates async generation of audit logs for selected…
      operationId: UserSettingsService_RequestAdminAuditLogs
      parameters:
      - description: 'Start time for audit log retrieval (optional, default: 3 hours ago).'
        name: from
        in: query
        schema:
          type: string
          format: date-time
      - description: 'End time for audit log retrieval (optional, default: now).'
        name: to
        in: query
        schema:
          type: string
          format: date-time
      - description: 'Sort order for logs (optional, default: desc)

          Valid values: asc, desc.'
        name: order
        in: query
        schema:
          type: string
      - description: 'Usernames to filter audit logs by (optional).

          If empty, returns logs for all users in the time range.

          Query param name is "usernames". Prefer repeated params (usernames=a&usernames=b).

          The server also accepts a single comma-separated value (usernames=a,b).'
        name: usernames
        in: query
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.user_settings.SelfAuditResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
  /api/v0/audit/download:
    get:
      description: 'Streams the audit log file generated by a prior request to `/api/v0/audit/self/request` or `/api/v0/audit/admin/request`.


        If `request_id` is omitted, the latest completed request for the authenticated user is downloaded.


        Supports the standard HTTP `Range` header (e.g. `Range: bytes=0-1048575`) for partial or multi-part downloads. When a range is requested, the server responds with `206 Partial Content` and a `Content-Range` header. The response also includes an `Accept-Ranges: bytes` header indicating that range requests are supported.


        Note: This endpoint is served by a custom HTTP handler in the gateway (not via gRPC-gateway) to support streaming and `Range` requests.'
      tags:
      - UserSettingsService
      summary: Download audit logs
      operationId: UserSettingsService_DownloadAuditLogs
      parameters:
      - description: Optional UUID of the specific audit log request to download. If omitted, the latest completed request for the authenticated user is downloaded.
        name: request_id
        in: query
        schema:
          type: string
      - description: 'Optional standard HTTP Range header for partial downloads. Format: `bytes=start-end` (e.g. `bytes=0-1048575`). If omitted, the entire file is returned.'
        name: Range
        in: header
        schema:
          type: string
      responses:
        '200':
          description: Full audit log file content.
          headers:
            Accept-Ranges:
              description: 'Indicates that the server supports byte-range requests (value: `bytes`).'
              schema:
                type: string
            Content-Disposition:
              description: Attachment header with the audit log filename.
              schema:
                type: string
            Content-Length:
              description: Total size of the file in bytes.
              schema:
                type: integer
                format: int64
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                type: string
                format: binary
        '206':
          description: Partial content response when a `Range` header is supplied.
          headers:
            Accept-Ranges:
              description: 'Indicates that the server supports byte-range requests (value: `bytes`).'
              schema:
                type: string
            Content-Length:
              description: Length of the partial content in bytes.
              schema:
                type: integer
                format: int64
            Content-Range:
              description: Range of bytes returned in this response (e.g. `bytes 0-1048575/10485760`).
              schema:
                type: string
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                type: string
                format: binary
        '404':
          description: No audit log file found for the given (or latest) request.
        '416':
          description: Requested range is not satisfiable.
        default:
          description: An unexpected error response.
          content:
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
  /api/v0/audit/self/request:
    get:
      tags:
      - UserSettingsService
      summary: RequestSelfAuditLogs initiates async generation of audit logs for the current…
      operationId: UserSettingsService_RequestSelfAuditLogs
      parameters:
      - description: 'Start time for audit log retrieval (optional, default: 3 hours ago).'
        name: from
        in: query
        schema:
          type: string
          format: date-time
      - description: 'End time for audit log retrieval (optional, default: now).'
        name: to
        in: query
        schema:
          type: string
          format: date-time
      - description: 'Sort order for logs (optional, default: desc)

          Valid values: asc, desc.'
        name: order
        in: query
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.user_settings.SelfAuditResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
  /api/v0/audit/status:
    get:
      tags:
      - UserSettingsService
      summary: GetAuditLogsRequestStatus checks the status of an audit log request
      operationId: UserSettingsService_GetAuditLogsRequestStatus
      parameters:
      - description: 'Optional UUID of the specific request to check

          If not provided, returns status of the latest request for the current user.'
        name: request_id
        in: query
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.user_settings.AuditLogsRequestStatusResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
  /api/v0/user-settings/{user.name}/{user.connector}:
    get:
      tags:
      - UserSettingsService
      summary: GetUserSettings returns all of the preferences for a given user
      operationId: UserSettingsService_GetUserSettings
      parameters:
      - name: user.name
        in: path
        required: true
        schema:
          type: string
      - name: user.connector
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.user_settings.GetUserSettingsResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
    put:
      tags:
      - UserSettingsService
      summary: PutUserSettings upserts all of the preferences for a given user
      operationId: UserSettingsService_PutUserSettings
      parameters:
      - name: user.name
        in: path
        required: true
        schema:
          type: string
      - name: user.connector
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.user_settings.PutUserSettingsResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/chef.automate.api.user_settings.PutUserSettingsRequest'
        required: true
    delete:
      tags:
      - UserSettingsService
      summary: DeleteUserSettings deletes all settings for a given user
      operationId: UserSettingsService_DeleteUserSettings
      parameters:
      - name: user.name
        in: path
        required: true
        schema:
          type: string
      - name: user.connector
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema: {}
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
components:
  schemas:
    chef.automate.api.user_settings.PutUserSettingsResponse:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/chef.automate.api.user_settings.User'
    chef.automate.api.user_settings.GetUserSettingsResponse:
      type: object
      properties:
        settings:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/chef.automate.api.user_settings.UserSettingValue'
        user:
          $ref: '#/components/schemas/chef.automate.api.user_settings.User'
    grpc.gateway.runtime.Error:
      type: object
      properties:
        code:
          type: integer
          format: int32
        details:
          type: array
          items:
            $ref: '#/components/schemas/google.protobuf.Any'
        error:
          type: string
        message:
          type: string
    chef.automate.api.user_settings.AuditLogsRequestStatusResponse:
      type: object
      title: AuditLogsRequestStatusResponse is the response containing the status of an audit log request
      properties:
        download_url:
          type: string
          title: Download URL for the log file - only present when status is "completed"
        error:
          type: string
          title: 'Error code - only present when status indicates an error

            Possible values: "audit_disabled", "not_found", "no_requested_logs"'
        file_size:
          type: string
          title: Human-readable file size (e.g., "15.2 MB") - only present when status is "completed"
        message:
          type: string
          title: Human-readable message describing the status or error
        request_id:
          type: string
          title: UUID of the audit log request
        status:
          type: string
          title: 'Status of the request: "processing", "completed", "error", "not_found"'
    chef.automate.api.user_settings.SelfAuditResponse:
      type: object
      title: SelfAuditResponse is the response after initiating async audit log generation
      properties:
        message:
          type: string
          title: Human-readable message about the request
        request_id:
          type: string
          title: Unique identifier for the audit log request
        status:
          type: string
          title: Current status of the request (e.g., "processing")
    google.protobuf.Any:
      type: object
      properties:
        type_url:
          type: string
        value:
          type: string
          format: byte
    chef.automate.api.user_settings.User:
      type: object
      properties:
        connector:
          type: string
        name:
          type: string
    chef.automate.api.user_settings.UserSettingValue:
      type: object
      properties:
        default_value:
          description: Default value for this setting.
          type: string
        enabled:
          type: boolean
          title: Enabled
        valid_values:
          description: Valid values for this setting.
          type: array
          items:
            type: string
        value:
          description: Value for this setting.
          type: string
    chef.automate.api.user_settings.PutUserSettingsRequest:
      type: object
      properties:
        settings:
          description: The user settings to persist.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/chef.automate.api.user_settings.UserSettingValue'
        user:
          description: ID of the user. Cannot be changed. Used to sign in.
          $ref: '#/components/schemas/chef.automate.api.user_settings.User'
  securitySchemes:
    APIToken:
      description: Authenticate with the Automate API using an API Token.
      type: apiKey
      name: api-token
      in: header
x-tagGroups:
- name: Compliance
  tags:
  - ReportingService
  - StatsService
  - JobsService
  - ProfilesService
  - Comp_Assets
- name: Report Manager
  tags:
  - ReportManagerService
- name: Infra
  tags:
  - ConfigMgmt
  - InfraProxy
- name: Ingest
  tags:
  - ChefIngester
  - JobScheduler
- name: Node Management
  tags:
  - NodeManagerService
  - NodesService
- name: Event Feed
  tags:
  - EventFeedService
- name: Secrets
  tags:
  - SecretsService
- name: Applications
  tags:
  - service_groups
  - retention
  - ApplicationsService
- name: Data Feed
  tags:
  - DatafeedService
- name: Data Lifecycle
  tags:
  - DataLifecycle
- name: Notifications
  tags:
  - Notifications
- name: Content Delivery
  tags:
  - Cds
- name: Audit and Settings
  tags:
  - UserSettingsService
- name: System
  tags:
  - Gateway
  - Deployment
  - License
  - Telemetry
  - LegacyDataCollector
- name: Identity
  tags:
  - users
  - teams
  - tokens
- name: Access Management
  tags:
  - policies
  - roles
  - projects
  - rules
  - Authorization