openapi: 3.2.0
info:
  version: 1.0.0
  title: Umbrella Admin User API
  description: The admin API is accessible via `/api-umbrella/v1`.
security:
- api_key: []
- admin_auth_token: []
tags:
- name: User
paths:
  /api-umbrella/v1/users:
    get:
      tags:
      - User
      summary: Get a list of all API users/API keys
      description: 'Get a listing of all API user/API key records the currently authenticated admin user has permissions to.


        This API''s query parameters and responses are intended to be compatible with the DataTables server-side processing API.'
      parameters:
      - $ref: '#/components/parameters/datatables-start'
      - $ref: '#/components/parameters/datatables-length'
      - $ref: '#/components/parameters/datatables-search-value'
      - $ref: '#/components/parameters/datatables-order-column'
      - $ref: '#/components/parameters/datatables-order-dir'
      - $ref: '#/components/parameters/datatables-columns-data'
      - $ref: '#/components/parameters/datatables-columns-name'
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                title: Response
                type: object
                properties:
                  draw:
                    type: integer
                  recordsTotal:
                    type: integer
                  recordsFiltered:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
      operationId: getApiUmbrellaV1Users
      x-operation-id-source: derived
    post:
      tags:
      - User
      summary: Create a new API user/API key
      responses:
        201:
          description: Successfully created record
      requestBody:
        content:
          application/json:
            schema:
              title: Request
              type: object
              properties:
                user:
                  $ref: '#/components/schemas/User'
        description: API user object to create
        required: true
      operationId: postApiUmbrellaV1Users
      x-operation-id-source: derived
  /api-umbrella/v1/users/{id}:
    parameters:
    - name: id
      in: path
      description: UUID of the API user/API key
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - User
      summary: Get the API user/API key
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                title: Response
                type: object
                properties:
                  user:
                    type: object
                    $ref: '#/components/schemas/User'
      operationId: getApiUmbrellaV1UsersById
      x-operation-id-source: derived
    put:
      tags:
      - User
      summary: Update the API user/API key
      responses:
        204:
          description: Successfully updated record
      requestBody:
        content:
          application/json:
            schema:
              title: Request
              type: object
              properties:
                user:
                  $ref: '#/components/schemas/User'
        description: API user object to update
        required: true
      operationId: putApiUmbrellaV1UsersById
      x-operation-id-source: derived
    delete:
      tags:
      - User
      summary: Delete the API user/API key
      responses:
        204:
          description: Successfully deleted record
      operationId: deleteApiUmbrellaV1UsersById
      x-operation-id-source: derived
components:
  parameters:
    datatables-columns-name:
      name: columns[i][name]
      in: query
      description: The human-readable name of the column displayed at index `i`
      required: false
      schema:
        type: string
    datatables-length:
      name: length
      in: query
      description: Limit the number of records returned for pagination
      required: false
      schema:
        type: integer
    datatables-columns-data:
      name: columns[i][data]
      in: query
      description: The database field name of the column displayed at index `i`
      required: false
      schema:
        type: string
    datatables-order-dir:
      name: order[i][dir]
      in: query
      description: Size of array
      required: false
      schema:
        type: string
        enum:
        - asc
        - desc
    datatables-order-column:
      name: order[i][column]
      in: query
      description: Size of array
      required: false
      schema:
        type: integer
    datatables-start:
      name: start
      in: query
      description: Offset for pagination (0 based - 0 is the first record)
      required: false
      schema:
        type: integer
    datatables-search-value:
      name: search[value]
      in: query
      description: Perform a text search across all records for this string
      required: false
      schema:
        type: string
  schemas:
    CreatedAt:
      type: string
      format: date-time
      readOnly: true
      description: The time the record was created (ISO 8601 format)
    UpdatedAt:
      type: string
      format: date-time
      readOnly: true
      description: The time the record was last updated (ISO 8601 format)
    AdminUpdater:
      type: object
      readOnly: true
      properties:
        username:
          type: string
          format: email
          readOnly: true
          description: E-mail address of the admin that last updated the record
    AdminCreator:
      type: object
      readOnly: true
      properties:
        username:
          type: string
          format: email
          readOnly: true
          description: E-mail address of the admin that created the record
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
        website:
          type: string
        use_description:
          type: string
        registration_source:
          type: string
        throttle_by_ip:
          type: boolean
        roles:
          type: string
        enabled:
          type: string
        api_key:
          type: string
          description: The full API key. This is only returned on initial user creation and to the administrator who created the user for 10 minutes after creation.
        api_key_hides_at:
          type: string
          format: date-time
          description: When an administrator creates an API key, the full API key will be returned initially, but it's suggested that the full API key be hidden after this expiration date (10 minutes after creation).
        api_key_preview:
          type: string
          description: The first 6 characters of the API key. This is intended to allow administrators to identify API keys without exposing the full API keys to admins.
        email_verified:
          type: boolean
        registration_ip:
          type: string
        registration_user_agent:
          type: string
        registration_referer:
          type: string
        registration_origin:
          type: string
        created_at:
          $ref: '#/components/schemas/CreatedAt'
        creator:
          $ref: '#/components/schemas/AdminCreator'
        updated_at:
          $ref: '#/components/schemas/UpdatedAt'
        updater:
          $ref: '#/components/schemas/AdminUpdater'
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: X-Api-Key
    admin_auth_token:
      type: apiKey
      in: header
      name: X-Admin-Auth-Token