Coralogix Users Management Service API

openapi: 3.2.0
info:
  title: Coralogix Management Users Management Service API
  version: '5'
  description: 'Management API for the Coralogix observability platform. The base URL is region-specific: pick the `servers` entry matching your Coralogix domain. Authentication is a bearer API key.'
servers:
- url: https://api.eu1.coralogix.com/mgmt/openapi/5
- url: https://api.eu2.coralogix.com/mgmt/openapi/5
- url: https://api.us1.coralogix.com/mgmt/openapi/5
- url: https://api.us2.coralogix.com/mgmt/openapi/5
- url: https://api.us3.coralogix.com/mgmt/openapi/5
- url: https://api.ap1.coralogix.com/mgmt/openapi/5
- url: https://api.ap2.coralogix.com/mgmt/openapi/5
- url: https://api.ap3.coralogix.com/mgmt/openapi/5
- url: https://api.gov1.coralogixgov.us/mgmt/openapi/5
security:
- apiKeyAuth: []
tags:
- name: Users Management Service
  description: Manage team members (users) including creation, updates, search, and status management.
paths:
  /aaa/users/v2:
    get:
      description: Searches for team members by query.
      operationId: UsersMgmtService_SearchUsers
      parameters:
      - description: 'Team ID to search within. Optional on the /aaa/users/v2 routes, which bind no team in the path: omit it and the team of the API key making the call is used.'
        in: query
        name: team_id
        required: false
        schema:
          description: 'Team ID to search within. Optional on the /aaa/users/v2 routes, which bind no team in the path: omit it and the team of the API key making the call is used.'
          format: int64
          minimum: 0
          type: integer
      - description: Optional filter by username (partial match supported)
        in: query
        name: username
        required: false
        schema:
          description: Optional filter by username (partial match supported)
          minLength: 0
          type: string
          x-coralogix-presence: true
      - description: Optional filter by user status (e.g., 'active', 'inactive')
        in: query
        name: status
        required: false
        schema:
          allOf:
          - $ref: '#/components/schemas/UserStatus'
          description: Optional filter by user status (e.g., 'active', 'inactive')
          x-coralogix-presence: true
      - description: Number of results per page
        in: query
        name: page_size
        required: false
        schema:
          description: Number of results per page
          format: int64
          minimum: 0
          type: integer
      - description: Token for pagination to retrieve the next page of results
        in: query
        name: page_token
        required: false
        schema:
          description: Token for pagination to retrieve the next page of results
          format: int64
          minimum: 0
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchUsersResponse'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Team not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      summary: Search Users
      tags:
      - Users Management Service
    put:
      description: Updates team members for the specified team.
      operationId: UsersMgmtService_UpdateUsers
      parameters:
      - description: 'Team ID containing the users to update. Optional on the /aaa/users/v2 routes, which bind no team in the path: omit it and the team of the API key making the call is used.'
        in: query
        name: team_id
        required: false
        schema:
          description: 'Team ID containing the users to update. Optional on the /aaa/users/v2 routes, which bind no team in the path: omit it and the team of the API key making the call is used.'
          format: int64
          minimum: 0
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              description: List of users to update. Multiple users can be updated in a single request.
              items:
                $ref: '#/components/schemas/UpdateUserRequest'
              minItems: 0
              type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateUsersResponse'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: User not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      summary: Update Users
      tags:
      - Users Management Service
    post:
      description: Adds members to the specified team.
      operationId: UsersMgmtService_CreateUsers
      parameters:
      - description: 'Team ID where the users will be created. Optional on the /aaa/users/v2 routes, which bind no team in the path: omit it and the team of the API key making the call is used.'
        in: query
        name: team_id
        required: false
        schema:
          description: 'Team ID where the users will be created. Optional on the /aaa/users/v2 routes, which bind no team in the path: omit it and the team of the API key making the call is used.'
          format: int64
          minimum: 0
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              description: List of users to create. Multiple users can be created in a single request.
              items:
                $ref: '#/components/schemas/CreateUserRequest'
              minItems: 0
              type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateUsersResponse'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Team not found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: User already exists
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      summary: Create Users
      tags:
      - Users Management Service
  /aaa/users/v2/{user_account_id}:
    get:
      description: Returns the details of a specific team member.
      operationId: UsersMgmtService_GetUser
      parameters:
      - description: User account ID to retrieve
        in: path
        name: user_account_id
        required: true
        schema:
          description: User account ID to retrieve
          format: int64
          minimum: 0
          type: integer
      - description: 'Team ID to search within. Optional on the /aaa/users/v2 routes, which bind no team in the path: omit it and the team of the API key making the call is used.'
        in: query
        name: team_id
        required: false
        schema:
          description: 'Team ID to search within. Optional on the /aaa/users/v2 routes, which bind no team in the path: omit it and the team of the API key making the call is used.'
          format: int64
          minimum: 0
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetUserResponse'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: User not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      summary: Get User
      tags:
      - Users Management Service
  /aaa/users/v2:updateStatuses:
    patch:
      description: Updates the active status of multiple team members.
      operationId: UsersMgmtService_UpdateUsersStatuses
      requestBody:
        content:
          application/json:
            schema:
              description: Request to activate or revoke (deactivate) one or more users within a team. This operation changes the user status to either Active (enables access) or Inactive (disables access).
              properties:
                status:
                  allOf:
                  - $ref: '#/components/schemas/UserStatus'
                  description: 'New status for the users: Active (enables system access) or Inactive (disables system access)'
                teamId:
                  description: 'Team ID containing the users to update. Optional on the /aaa/users/v2 routes, which bind no team in the path: omit it and the team of the API key making the call is used.'
                  format: int64
                  minimum: 0
                  type: integer
                userAccountIds:
                  description: List of user account IDs to update. All users will be set to the same status.
                  items:
                    description: List of user account IDs to update. All users will be set to the same status.
                    format: int64
                    minimum: 0
                    type: integer
                  minItems: 0
                  type: array
                userIds:
                  description: 'Stable ids of the users to update, as an alternative to `userAccountIds`. All users will be set to the same status. Mutually exclusive with `userAccountIds`: set exactly one of the two.'
                  items:
                    description: 'Stable ids of the users to update, as an alternative to `userAccountIds`. All users will be set to the same status. Mutually exclusive with `userAccountIds`: set exactly one of the two.'
                    maxLength: 255
                    minLength: 1
                    pattern: ^[\s\S]+$
                    type: string
                  maxItems: 1000
                  minItems: 1
                  type: array
              title: UpdateUserStatusRequest
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateUsersStatusesResponse'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: User not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      summary: Activate/Revoke Users
      tags:
      - Users Management Service
components:
  schemas:
    UpdateUserRequest:
      type: object
      properties:
        userAccountId:
          minimum: 0
          type: integer
          description: User account ID of the user to update
          format: int64
        userId:
          description: 'Stable id of the user to update, as an alternative to `userAccountId`. Mutually exclusive with `userAccountId`: exactly one must be set.'
          maxLength: 255
          minLength: 1
          pattern: ^[\s\S]+$
          type: string
          x-coralogix-presence: true
        userTemplate:
          allOf:
          - $ref: '#/components/schemas/UserTemplate'
          description: Template containing updated user properties. Only provided fields will be updated.
    AllowedLoginMode:
      enum:
      - ALLOWED_LOGIN_MODE_UNSPECIFIED
      - ALLOWED_LOGIN_MODE_SSO
      - ALLOWED_LOGIN_MODE_LOCAL
      type: string
    GetUserResponse:
      title: GetUserResponse
      type: object
      properties:
        user:
          allOf:
          - $ref: '#/components/schemas/rbac.v2.User'
          description: Complete user details
      description: Response containing the complete details of the requested user, including account information, status, login modes, and access configuration.
      externalDocs:
        description: Find out more about user management
        url: https://coralogix.com/docs/user-guides/account-management/user-management/assign-user-roles-and-scopes-via-groups/
    rbac.v2.User:
      title: User
      type: object
      properties:
        accessType:
          allOf:
          - $ref: '#/components/schemas/AccessType'
          description: Access type configuration - defines whether user access is permanent or temporary with expiration
        allowedLoginMode:
          maxItems: 2
          minItems: 0
          type: array
          items:
            $ref: '#/components/schemas/AllowedLoginMode'
          description: List of allowed login modes. Can include SSO, local authentication, or both.
        firstName:
          minLength: 0
          type: string
          description: User first name
        groupIds:
          minItems: 0
          type: array
          items:
            minimum: 0
            type: integer
            description: IDs of the team groups this user is a member of.
            format: int64
          description: IDs of the team groups this user is a member of.
        lastName:
          minLength: 0
          type: string
          description: User last name
        status:
          allOf:
          - $ref: '#/components/schemas/UserStatus'
          description: 'User status: [Active, Inactive]'
        userAccountId:
          minimum: 0
          type: integer
          description: Associated account id. An account can have many users.
          format: int64
        userId:
          minLength: 0
          type: string
          description: Unique user id
        username:
          minLength: 0
          type: string
          description: Unique username
      description: A user is an entity that is always part of a team and has an account associated with it
    Error:
      type: object
      properties:
        code:
          maximum: 599
          minimum: 100
          type: integer
          description: HTTP status code of the error (for example 400, 404, 500).
          format: int32
        message:
          maxLength: 4096
          minLength: 0
          pattern: ^[\s\S]*$
          type: string
          description: Human-readable description of the error.
      description: Standard error response body returned for a failed request.
    UserTemplate:
      title: UserTemplate
      type: object
      properties:
        accessType:
          allOf:
          - $ref: '#/components/schemas/AccessType'
          description: Access type configuration - defines whether user access is permanent or temporary with expiration
        allowedLoginMode:
          minItems: 0
          type: array
          items:
            $ref: '#/components/schemas/AllowedLoginMode'
          description: List of allowed login modes. Can include SSO, local authentication, or both. Not supported in invite onboarding mode
        firstName:
          minLength: 0
          type: string
          description: User's first name
        lastName:
          minLength: 0
          type: string
          description: User's last name
        status:
          allOf:
          - $ref: '#/components/schemas/UserStatus'
          description: 'User status: Active (user can access the system) or Inactive (user access is disabled)'
        username:
          minLength: 0
          type: string
          description: Unique username for the user. Must be unique within the system. Updating username for existing users is not supported and ignored.
      description: Template containing all user properties that can be set when creating or updating a user. Includes personal information, status, authentication methods, and access duration.
      externalDocs:
        description: Find out more about user management
        url: https://coralogix.com/docs/user-guides/account-management/user-management/assign-user-roles-and-scopes-via-groups/
    OnboardingMode:
      enum:
      - ONBOARDING_MODE_UNSPECIFIED
      - ONBOARDING_MODE_INVITE_LINK
      - ONBOARDING_MODE_NO_INVITE
      type: string
      description: Onboarding mode.
    CreateUserStatus:
      enum:
      - CREATE_USER_STATUS_UNSPECIFIED
      - CREATE_USER_STATUS_CREATED
      - CREATE_USER_STATUS_ALREADY_EXISTS
      - CREATE_USER_STATUS_INVITED
      - CREATE_USER_STATUS_ALREADY_INVITED
      - CREATE_USER_STATUS_DOMAIN_NOT_ALLOWED
      - CREATE_USER_STATUS_FAILED
      type: string
    PermanentAccess:
      title: PermanentAccess
      type: object
      additionalProperties: false
      description: User with permanent access. The user's access does not expire and remains active until manually revoked or deactivated.
    UpdateUsersStatusesResponse:
      title: UpdateUserStatusResponse
      type: object
      properties:
        userAccountIds:
          minItems: 0
          type: array
          items:
            minimum: 0
            type: integer
            description: List of user account IDs for users whose status was successfully updated
            format: int64
          description: List of user account IDs for users whose status was successfully updated
      description: Response confirming the successful status update of users. Contains the user account IDs of all users whose status was changed.
      externalDocs:
        description: Find out more about user management
        url: https://coralogix.com/docs/user-guides/account-management/user-management/assign-user-roles-and-scopes-via-groups/
    UserStatus:
      enum:
      - USER_STATUS_UNSPECIFIED
      - USER_STATUS_ACTIVE
      - USER_STATUS_INACTIVE
      type: string
      description: User status.
    UpdateUsersResponse:
      title: UpdateUsersResponse
      type: object
      properties:
        userAccountIds:
          minItems: 0
          type: array
          items:
            minimum: 0
            type: integer
            description: List of user account IDs for the successfully updated users
            format: int64
          description: List of user account IDs for the successfully updated users
        users:
          minItems: 0
          type: array
          items:
            $ref: '#/components/schemas/rbac.v2.User'
          description: Full details of the successfully updated users, as returned by GetUser.
      description: Response confirming the successful update of users. Contains the user account IDs of all users that were updated.
      externalDocs:
        description: Find out more about user management
        url: https://coralogix.com/docs/user-guides/account-management/user-management/assign-user-roles-and-scopes-via-groups/
    SearchUsersResponse:
      title: SearchUsersResponse
      type: object
      properties:
        nextPageToken:
          description: Token for the next page of results. Empty if no more pages available.
          format: int64
          minimum: 0
          type: integer
          x-coralogix-presence: true
        totalCount:
          minimum: 0
          type: integer
          description: Total number of users matching the search criteria across all pages
          format: int64
        users:
          minItems: 0
          type: array
          items:
            $ref: '#/components/schemas/rbac.v2.User'
          description: List of users matching the search criteria
      description: Response containing a paginated list of users matching the search criteria, along with pagination tokens and total count.
      externalDocs:
        description: Find out more about user management
        url: https://coralogix.com/docs/user-guides/account-management/user-management/assign-user-roles-and-scopes-via-groups/
    CreateUsersResponse:
      title: CreateUsersResponse
      type: object
      properties:
        results:
          maxItems: 1000
          minItems: 0
          type: array
          items:
            $ref: '#/components/schemas/CreateUserResult'
          description: Exactly one entry per user in the request, in request order. Each entry also echoes its `username`, so a caller can join on that instead of on position.
      description: Empty response indicating successful processing of all user creation and invitation requests. Ensure failures are returned via gRPC status codes.
      externalDocs:
        description: Find out more about user management
        url: https://coralogix.com/docs/user-guides/account-management/user-management/assign-user-roles-and-scopes-via-groups/
    AccessType:
      title: AccessType
      required:
      - accessType
      type: object
      oneOf:
      - required:
        - permanentAccess
        type: object
      - required:
        - temporaryAccess
        type: object
      - type: object
        not:
          anyOf:
          - required:
            - permanentAccess
            type: object
          - required:
            - temporaryAccess
            type: object
      properties:
        accessType:
          minLength: 0
          type: string
          description: 'Type of access: ''permanent'' or ''temporary'''
        permanentAccess:
          allOf:
          - $ref: '#/components/schemas/PermanentAccess'
          description: Permanent access configuration - user has indefinite access
        temporaryAccess:
          allOf:
          - $ref: '#/components/schemas/TemporaryAccess'
          description: Temporary access configuration - user access expires at a specified time
      description: Defines the access duration for a user. Can be either permanent (indefinite) or temporary (expires at a specific time).
      discriminator:
        propertyName: accessType
    TemporaryAccess:
      title: TemporaryAccess
      type: object
      properties:
        expireAt:
          description: Timestamp when the user's temporary access will expire. After this time, the user will no longer be able to access the system.
          examples:
          - '2021-01-01T00:00:00.000Z'
          format: date-time
          minLength: 0
          type: string
          x-coralogix-presence: true
      description: User with temporary access. The user's access will automatically expire at the specified timestamp.
    CreateUserRequest:
      type: object
      properties:
        onboardingMode:
          allOf:
          - $ref: '#/components/schemas/OnboardingMode'
          description: Onboarding mode determines whether the user receives an invite link or is created without one
        userTemplate:
          allOf:
          - $ref: '#/components/schemas/UserTemplate'
          description: Template containing all user properties to set during creation
    CreateUserResult:
      required:
      - username
      type: object
      properties:
        message:
          description: Human-readable detail about this outcome. Set where a status alone is not enough, such as `CREATE_USER_STATUS_FAILED`.
          maxLength: 1024
          minLength: 1
          pattern: ^[\s\S]+$
          type: string
          x-coralogix-presence: true
        status:
          $ref: '#/components/schemas/CreateUserStatus'
        user:
          allOf:
          - $ref: '#/components/schemas/rbac.v2.User'
          description: Full details of the created user, as returned by GetUser. Absent when the outcome produced no user, such as an invited user, who has none until the invitation is accepted.
        userAccountId:
          format: int64
          minimum: 0
          type: integer
          x-coralogix-presence: true
        userId:
          description: Stable id of the user. Absent when the outcome produced no user, such as an invited user, who has none until the invitation is accepted.
          maxLength: 255
          minLength: 1
          pattern: ^[\s\S]+$
          type: string
          x-coralogix-presence: true
        username:
          maxLength: 255
          minLength: 1
          pattern: ^[\s\S]+$
          type: string
          description: The username from the request this result belongs to
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API key authentication
externalDocs:
  description: Coralogix API reference
  url: https://coralogix.com/docs/api-reference/v5/
x-provenance:
  method: harvested
  publisher: Coralogix
  source: https://coralogix.com/docs/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)