openapi: 3.0.0
info:
  description: Infra API
  license:
    name: Elastic License v2.0
    url: https://www.elastic.co/licensing/elastic-license
  title: Infra Authentication Users API
  version: 0.0.0
servers:
- url: https://api.infrahq.com
tags:
- name: Users
paths:
  /api/groups/{id}/users:
    patch:
      description: UpdateUsersInGroup
      operationId: UpdateUsersInGroup
      parameters:
      - in: header
        name: Infra-Version
        required: true
        schema:
          description: Version of the API being requested
          example: 0.0.0
          format: \d+\.\d+\(.\d+)?(-.\w(+\w)?)?
          type: string
      - in: header
        name: Authorization
        required: true
        schema:
          description: Bearer followed by your access key
          example: Bearer ACCESSKEY
          format: Bearer [\da-zA-Z]{10}\.[\da-zA-Z]{24}
          type: string
      - in: path
        name: id
        required: true
        schema:
          example: 4yJ3n3D8E2
          format: uid
          pattern: '[1-9a-km-zA-HJ-NP-Z]{1,11}'
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                usersToAdd:
                  description: List of user IDs to add to the group
                  example: '[6dYiUyYgKa,6hPY5vqB2R]'
                  items:
                    description: List of user IDs to add to the group
                    example: '[6dYiUyYgKa,6hPY5vqB2R]'
                    format: uid
                    pattern: '[1-9a-km-zA-HJ-NP-Z]{1,11}'
                    type: string
                  type: array
                usersToRemove:
                  description: List of  user IDs to remove from the group
                  example: '[3w5qrK7ets,4Ajzyzckdn]'
                  items:
                    description: List of  user IDs to remove from the group
                    example: '[3w5qrK7ets,4Ajzyzckdn]'
                    format: uid
                    pattern: '[1-9a-km-zA-HJ-NP-Z]{1,11}'
                    type: string
                  type: array
              type: object
      responses:
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Unauthorized: Requestor is not authenticated'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Forbidden: Requestor does not have the right permissions'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Duplicate Record
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
          description: Success
      summary: UpdateUsersInGroup
      tags:
      - Users
  /api/users:
    get:
      description: ListUsers
      operationId: ListUsers
      parameters:
      - in: header
        name: Infra-Version
        required: true
        schema:
          description: Version of the API being requested
          example: 0.0.0
          format: \d+\.\d+\(.\d+)?(-.\w(+\w)?)?
          type: string
      - in: header
        name: Authorization
        required: true
        schema:
          description: Bearer followed by your access key
          example: Bearer ACCESSKEY
          format: Bearer [\da-zA-Z]{10}\.[\da-zA-Z]{24}
          type: string
      - description: Name of the user
        example: bob@example.com
        in: query
        name: name
        schema:
          description: Name of the user
          example: bob@example.com
          type: string
      - description: Group the user belongs to
        example: admins
        in: query
        name: group
        schema:
          description: Group the user belongs to
          example: admins
          format: uid
          pattern: '[1-9a-km-zA-HJ-NP-Z]{1,11}'
          type: string
      - description: List of User IDs
        in: query
        name: ids
        schema:
          description: List of User IDs
          items:
            description: List of User IDs
            example: 4yJ3n3D8E2
            format: uid
            pattern: '[1-9a-km-zA-HJ-NP-Z]{1,11}'
            type: string
          type: array
      - description: if true, this shows the connector and other internal users
        example: 'false'
        in: query
        name: showSystem
        schema:
          description: if true, this shows the connector and other internal users
          example: 'false'
          type: boolean
      - description: Find the user with a public key that matches this SHA256 fingerprint.
        in: query
        name: publicKeyFingerprint
        schema:
          description: Find the user with a public key that matches this SHA256 fingerprint.
          type: string
      - description: Page number to retrieve
        example: '1'
        in: query
        name: page
        schema:
          description: Page number to retrieve
          example: '1'
          format: int
          minimum: 0
          type: integer
      - description: Number of objects to retrieve per page (up to 1000)
        example: '100'
        in: query
        name: limit
        schema:
          description: Number of objects to retrieve per page (up to 1000)
          example: '100'
          format: int
          maximum: 1000
          minimum: 0
          type: integer
      responses:
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Unauthorized: Requestor is not authenticated'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Forbidden: Requestor does not have the right permissions'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Duplicate Record
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListResponse_User'
          description: Success
      summary: ListUsers
      tags:
      - Users
    post:
      description: CreateUser
      operationId: CreateUser
      parameters:
      - in: header
        name: Infra-Version
        required: true
        schema:
          description: Version of the API being requested
          example: 0.0.0
          format: \d+\.\d+\(.\d+)?(-.\w(+\w)?)?
          type: string
      - in: header
        name: Authorization
        required: true
        schema:
          description: Bearer followed by your access key
          example: Bearer ACCESSKEY
          format: Bearer [\da-zA-Z]{10}\.[\da-zA-Z]{24}
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                name:
                  description: Email address of the new user
                  example: bob@example.com
                  format: email
                  type: string
              required:
              - name
              type: object
      responses:
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Unauthorized: Requestor is not authenticated'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Forbidden: Requestor does not have the right permissions'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Duplicate Record
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateUserResponse'
          description: Success
      summary: CreateUser
      tags:
      - Users
  /api/users/public-key:
    put:
      description: AddUserPublicKey
      operationId: AddUserPublicKey
      parameters:
      - in: header
        name: Infra-Version
        required: true
        schema:
          description: Version of the API being requested
          example: 0.0.0
          format: \d+\.\d+\(.\d+)?(-.\w(+\w)?)?
          type: string
      - in: header
        name: Authorization
        required: true
        schema:
          description: Bearer followed by your access key
          example: Bearer ACCESSKEY
          format: Bearer [\da-zA-Z]{10}\.[\da-zA-Z]{24}
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                name:
                  description: Name of the public key, often the name of the device used to create it
                  format: '[a-zA-Z0-9\-_.]'
                  maxLength: 256
                  minLength: 2
                  type: string
                publicKey:
                  type: string
              required:
              - publicKey
              type: object
      responses:
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Unauthorized: Requestor is not authenticated'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Forbidden: Requestor does not have the right permissions'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Duplicate Record
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPublicKey'
          description: Success
      summary: AddUserPublicKey
      tags:
      - Users
  /api/users/{id}:
    delete:
      description: DeleteUser
      operationId: DeleteUser
      parameters:
      - in: header
        name: Infra-Version
        required: true
        schema:
          description: Version of the API being requested
          example: 0.0.0
          format: \d+\.\d+\(.\d+)?(-.\w(+\w)?)?
          type: string
      - in: header
        name: Authorization
        required: true
        schema:
          description: Bearer followed by your access key
          example: Bearer ACCESSKEY
          format: Bearer [\da-zA-Z]{10}\.[\da-zA-Z]{24}
          type: string
      - in: path
        name: id
        required: true
        schema:
          example: 4yJ3n3D8E2
          format: uid
          pattern: '[1-9a-km-zA-HJ-NP-Z]{1,11}'
          type: string
      responses:
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Unauthorized: Requestor is not authenticated'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Forbidden: Requestor does not have the right permissions'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Duplicate Record
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
          description: Success
      summary: DeleteUser
      tags:
      - Users
    get:
      description: GetUser
      operationId: GetUser
      parameters:
      - in: header
        name: Infra-Version
        required: true
        schema:
          description: Version of the API being requested
          example: 0.0.0
          format: \d+\.\d+\(.\d+)?(-.\w(+\w)?)?
          type: string
      - in: header
        name: Authorization
        required: true
        schema:
          description: Bearer followed by your access key
          example: Bearer ACCESSKEY
          format: Bearer [\da-zA-Z]{10}\.[\da-zA-Z]{24}
          type: string
      - in: path
        name: id
        required: true
        schema:
          description: a uid or the literal self
          example: 4yJ3n3D8E2
          format: uid|self
          pattern: '[1-9a-km-zA-HJ-NP-Z]{1,11}|self'
          type: string
      responses:
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Unauthorized: Requestor is not authenticated'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Forbidden: Requestor does not have the right permissions'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Duplicate Record
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          description: Success
      summary: GetUser
      tags:
      - Users
    put:
      description: UpdateUser
      operationId: UpdateUser
      parameters:
      - in: header
        name: Infra-Version
        required: true
        schema:
          description: Version of the API being requested
          example: 0.0.0
          format: \d+\.\d+\(.\d+)?(-.\w(+\w)?)?
          type: string
      - in: header
        name: Authorization
        required: true
        schema:
          description: Bearer followed by your access key
          example: Bearer ACCESSKEY
          format: Bearer [\da-zA-Z]{10}\.[\da-zA-Z]{24}
          type: string
      - in: path
        name: id
        required: true
        schema:
          example: 4yJ3n3D8E2
          format: uid
          pattern: '[1-9a-km-zA-HJ-NP-Z]{1,11}'
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                oldPassword:
                  description: Old password for the user. Only required when the access key making this request is not owned by an Infra admin
                  example: oldpassword
                  type: string
                password:
                  description: New one-time password for the user
                  example: newpassword
                  type: string
              type: object
      responses:
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Unauthorized: Requestor is not authenticated'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Forbidden: Requestor does not have the right permissions'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Duplicate Record
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateUserResponse'
          description: Success
      summary: UpdateUser
      tags:
      - Users
components:
  schemas:
    CreateUserResponse:
      properties:
        id:
          description: User ID
          example: 4yJ3n3D8E2
          format: uid
          pattern: '[1-9a-km-zA-HJ-NP-Z]{1,11}'
          type: string
        name:
          description: Email address of the user
          example: bob@example.com
          type: string
        oneTimePassword:
          description: One-time password (only returned when self-hosted)
          example: password
          type: string
    Error:
      properties:
        code:
          format: int32
          type: integer
        fieldErrors:
          items:
            properties:
              errors:
                items:
                  type: string
                type: array
              fieldName:
                type: string
            type: object
          type: array
        message:
          type: string
    UpdateUserResponse:
      properties:
        created:
          description: Date the user was created
          example: '2022-03-14T09:48:00Z'
          format: date-time
          type: string
        id:
          description: User ID
          example: 4ACFkc434M
          format: uid
          pattern: '[1-9a-km-zA-HJ-NP-Z]{1,11}'
          type: string
        lastSeenAt:
          description: Date the user was last seen
          example: '2022-03-14T09:48:00Z'
          format: date-time
          type: string
        name:
          description: Name of the user
          example: bob@example.com
          type: string
        oneTimePassword:
          type: string
        providerNames:
          description: List of providers this user belongs to
          example: '[''okta'']'
          items:
            description: List of providers this user belongs to
            example: '[''okta'']'
            type: string
          type: array
        publicKeys:
          description: List of the users public keys
          items:
            description: List of the users public keys
            properties:
              created:
                description: formatted as an RFC3339 date-time
                example: '2022-03-14T09:48:00Z'
                format: date-time
                type: string
              expires:
                description: formatted as an RFC3339 date-time
                example: '2022-03-14T09:48:00Z'
                format: date-time
                type: string
              fingerprint:
                description: SHA256 fingerprint of the key
                type: string
              id:
                example: 4yJ3n3D8E2
                format: uid
                pattern: '[1-9a-km-zA-HJ-NP-Z]{1,11}'
                type: string
              keyType:
                type: string
              name:
                type: string
              publicKey:
                type: string
            type: object
          type: array
        sshLoginName:
          description: Username for SSH destinations
          example: bob
          type: string
        updated:
          description: Date the user was updated
          example: '2022-03-14T09:48:00Z'
          format: date-time
          type: string
    UserPublicKey:
      properties:
        created:
          description: formatted as an RFC3339 date-time
          example: '2022-03-14T09:48:00Z'
          format: date-time
          type: string
        expires:
          description: formatted as an RFC3339 date-time
          example: '2022-03-14T09:48:00Z'
          format: date-time
          type: string
        fingerprint:
          description: SHA256 fingerprint of the key
          type: string
        id:
          example: 4yJ3n3D8E2
          format: uid
          pattern: '[1-9a-km-zA-HJ-NP-Z]{1,11}'
          type: string
        keyType:
          type: string
        name:
          type: string
        publicKey:
          type: string
    ListResponse_User:
      properties:
        count:
          description: Total number of items on the current page
          example: '100'
          format: int
          type: integer
        items:
          items:
            properties:
              created:
                description: Date the user was created
                example: '2022-03-14T09:48:00Z'
                format: date-time
                type: string
              id:
                description: User ID
                example: 4ACFkc434M
                format: uid
                pattern: '[1-9a-km-zA-HJ-NP-Z]{1,11}'
                type: string
              lastSeenAt:
                description: Date the user was last seen
                example: '2022-03-14T09:48:00Z'
                format: date-time
                type: string
              name:
                description: Name of the user
                example: bob@example.com
                type: string
              providerNames:
                description: List of providers this user belongs to
                example: '[''okta'']'
                items:
                  description: List of providers this user belongs to
                  example: '[''okta'']'
                  type: string
                type: array
              publicKeys:
                description: List of the users public keys
                items:
                  description: List of the users public keys
                  properties:
                    created:
                      description: formatted as an RFC3339 date-time
                      example: '2022-03-14T09:48:00Z'
                      format: date-time
                      type: string
                    expires:
                      description: formatted as an RFC3339 date-time
                      example: '2022-03-14T09:48:00Z'
                      format: date-time
                      type: string
                    fingerprint:
                      description: SHA256 fingerprint of the key
                      type: string
                    id:
                      example: 4yJ3n3D8E2
                      format: uid
                      pattern: '[1-9a-km-zA-HJ-NP-Z]{1,11}'
                      type: string
                    keyType:
                      type: string
                    name:
                      type: string
                    publicKey:
                      type: string
                  type: object
                type: array
              sshLoginName:
                description: Username for SSH destinations
                example: bob
                type: string
              updated:
                description: Date the user was updated
                example: '2022-03-14T09:48:00Z'
                format: date-time
                type: string
            type: object
          type: array
        limit:
          description: Number of objects per page
          example: '100'
          format: int
          type: integer
        page:
          description: Page number retrieved
          example: '1'
          format: int
          type: integer
        totalCount:
          description: Total number of objects
          example: '485'
          format: int
          type: integer
        totalPages:
          description: Total number of pages
          example: '5'
          format: int
          type: integer
    User:
      properties:
        created:
          description: Date the user was created
          example: '2022-03-14T09:48:00Z'
          format: date-time
          type: string
        id:
          description: User ID
          example: 4ACFkc434M
          format: uid
          pattern: '[1-9a-km-zA-HJ-NP-Z]{1,11}'
          type: string
        lastSeenAt:
          description: Date the user was last seen
          example: '2022-03-14T09:48:00Z'
          format: date-time
          type: string
        name:
          description: Name of the user
          example: bob@example.com
          type: string
        providerNames:
          description: List of providers this user belongs to
          example: '[''okta'']'
          items:
            description: List of providers this user belongs to
            example: '[''okta'']'
            type: string
          type: array
        publicKeys:
          description: List of the users public keys
          items:
            description: List of the users public keys
            properties:
              created:
                description: formatted as an RFC3339 date-time
                example: '2022-03-14T09:48:00Z'
                format: date-time
                type: string
              expires:
                description: formatted as an RFC3339 date-time
                example: '2022-03-14T09:48:00Z'
                format: date-time
                type: string
              fingerprint:
                description: SHA256 fingerprint of the key
                type: string
              id:
                example: 4yJ3n3D8E2
                format: uid
                pattern: '[1-9a-km-zA-HJ-NP-Z]{1,11}'
                type: string
              keyType:
                type: string
              name:
                type: string
              publicKey:
                type: string
            type: object
          type: array
        sshLoginName:
          description: Username for SSH destinations
          example: bob
          type: string
        updated:
          description: Date the user was updated
          example: '2022-03-14T09:48:00Z'
          format: date-time
          type: string
    EmptyResponse: {}