openapi: 3.2.0
info:
  description: '# Introduction

    This API is documented using the **OpenAPI 2.0** specification.'
  title: Logz.io Manage users API
  termsOfService: https://logz.io/about-us/terms-of-use/
  contact:
    email: help@logz.io
    url: https://docs.logz.io/
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.logz.io/
security:
- X-API-TOKEN: []
tags:
- name: Manage users
paths:
  /v1/user-management/recursive:
    get:
      summary: Retrieve users in all associated accounts
      description: 'Returns a list of users in the main account and all associated sub accounts as an array of JSON objects per account.


        If a user appears in multiple accounts, it will be listed separately under each account.


        **Note:** Must be run with an API token belonging to the main account.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Manage users
      operationId: listAllAccountUsers
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
  /v1/user-management:
    get:
      summary: Retrieve all users
      description: 'Returns a list of users as an array of JSON objects. If you run this endpoint without the accountID, then you will retrieve all users within the account the token of which you provide. If you run this endpoint with the accountID, then you will retrieve users only from the given accountID. In this case you must run it with the token of the main account that the accountID belongs to.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Manage users
      operationId: listUsers
      parameters:
      - name: accountId
        in: query
        required: false
        description: Logz.io sub-account ID.
        schema:
          type: integer
          format: int32
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      summary: Create a user
      description: 'Creates a new user with specified permissions to access your log data. If you run this endpoint with the token of the main account, then you can perform actions on the main account or any sub-account within the main account by providing the sub-account’s accountID. If you run this endpoint with the token of the sub-account, then you can perform actions only on the given sub-account.


        **Note:** Creating users through Logzio API requires email approval and activation of the request. To disable email verification for the API, contact the Logz.io support team.

        Please ensure to change the region in the URL to match your account''s region.'
      tags:
      - Manage users
      operationId: createUser
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserManagementUpsertResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserManagementUpsertRequest'
  /v1/user-management/{id}:
    get:
      tags:
      - Manage users
      summary: Retrieve a user by ID
      description: 'Returns user information and permissions as a JSON object.

        Please ensure to change the region in the URL to match your account''s region.'
      operationId: getUser
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the user
        schema:
          type: integer
          format: int32
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
    put:
      tags:
      - Manage users
      summary: Update a user
      description: 'Changes an existing user''s details or permissions. If you run this endpoint with the token of the main account, then you can perform actions on the main account or any sub-account within the main account by providing the sub-account’s accountID. If you run this endpoint with the token of the sub-account, then you can perform actions only on the given sub-account.

        Please ensure to change the region in the URL to match your account''s region.'
      operationId: updateUser
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the user
        schema:
          type: integer
          format: int32
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserManagementUpsertResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserManagementUpsertRequest'
    delete:
      tags:
      - Manage users
      summary: Delete a user
      description: 'Revokes a user''s access to the account. The API token determines the account the user will be deleted from. If you run this endpoint without the accountID, then you can perform actions on the account that belongs to the token you provided. If you run this endpoint with the accountID, then you will delete only the user from the given accountID. In this case you must run it with the token of the main account that the accountID belongs to.

        Please ensure to change the region in the URL to match your account''s region.'
      operationId: deleteUser
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the user
        schema:
          type: integer
          format: int32
      - name: accountId
        in: query
        required: false
        description: Logz.io sub-account ID.
        schema:
          type: integer
          format: int32
      responses:
        200:
          description: successful operation
  /v1/user-management/{id}/recursive:
    delete:
      tags:
      - Manage users
      summary: Delete a user from all accounts
      description: 'Deletes a user from the main account and all associated sub accounts. Must be run with an API token for the main account.


        The user will not be deleted from accounts for which there are no other users. In other words, any accounts where the user is the last user will be skipped. The success message will list accounts that were skipped.

        Please ensure to change the region in the URL to match your account''s region.'
      operationId: deleteUserRecursively
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the user
        schema:
          type: integer
          format: int32
      responses:
        200:
          description: successful operation
  /v1/user-management/suspend/{id}:
    post:
      tags:
      - Manage users
      summary: Suspend a user
      description: 'Locks a user''s access to your accounts.

        Please ensure to change the region in the URL to match your account''s region.'
      operationId: suspendUser
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the user
        schema:
          type: integer
          format: int32
      responses:
        200:
          description: successful operation
  /v1/user-management/unsuspend/{id}:
    post:
      tags:
      - Manage users
      summary: Unsuspend a user
      description: 'Restores a suspended user''s access to your accounts.

        Please ensure to change the region in the URL to match your account''s region.'
      operationId: unsuspendUser
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the user
        schema:
          type: integer
          format: int32
      responses:
        200:
          description: successful operation
  /v1/user-management/{id}/suspend/recursive:
    put:
      tags:
      - Manage users
      summary: Suspend a user from all accounts
      description: 'Suspends a user from the main account and all associated sub accounts. Must be run with an API token for the main account.

        The user will not be suspended from accounts for which there are no other users. In other words, any accounts where the user is the last user will be skipped. The success message will list accounts that were skipped.

        Please ensure to change the region in the URL to match your account''s region.'
      operationId: suspendUserRecursively
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the user
        schema:
          type: integer
          format: int32
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Finished suspending user 11300 from accounts.
  /v1/user-management/{id}/unsuspend/recursive:
    put:
      tags:
      - Manage users
      summary: Unsuspend a user from all accounts
      description: 'Unsuspends a user from the main account and all associated sub accounts. Must be run with an API token for the main account.

        Please ensure to change the region in the URL to match your account''s region.'
      operationId: unsuspendUserRecursively
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the user
        schema:
          type: integer
          format: int32
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Finished unsuspending user 11300 from accounts.
components:
  schemas:
    UserManagementUpsertRequest:
      type: object
      required:
      - fullName
      - username
      - roles
      - accountID
      properties:
        username:
          type: string
          pattern: ^[_A-Za-z0-9-\+]+(\.[_A-Za-z0-9-]+)*@[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)*(\.[A-Za-z]{2,})$
          description: Email address used to sign in to Logz.io. This property cannot be updated. A new user will need to be created for each email address.
          example: drvenkman@gbusters.com
        fullName:
          type: string
          description: The user's first and last name
          example: Peter Venkman
        accountID:
          type: integer
          format: int32
          description: ID of the account attached to the user
        role:
          type: string
          description: User role. Can be `USER_ROLE_READONLY`, `USER_ROLE_REGULAR` or `USER_ROLE_ACCOUNT_ADMIN`.
          example: USER_ROLE_READONLY
    User:
      type: object
      properties:
        id:
          type: integer
          format: int32
          description: ID of the user
          example: 33265
        username:
          type: string
          description: Email address used to sign in to Logz.io
          example: steve@winslows.com
        fullName:
          type: string
          description: First and last name of the user
          example: Stefan Urkel
        accountID:
          type: integer
          format: int32
          description: Logz.io account ID.
          example: 55555
        role:
          type: string
          description: User role. Can be `USER_ROLE_READONLY`, `USER_ROLE_REGULAR` or `USER_ROLE_ACCOUNT_ADMIN`.
          example: USER_ROLE_READONLY
        active:
          type: boolean
          description: If the user is active, `true`. If the user is suspended, `false`.
          example: true
    UserManagementUpsertResponse:
      type: object
      properties:
        id:
          type: integer
          format: int32
          description: ID of the user
          example: 13485
  securitySchemes:
    X-API-TOKEN:
      description: 'You can manage your API tokens from the [Logz.io API tokens](https://app.logz.io/#/dashboard/settings/manage-tokens/api) page.


        API tokens are account-specific. You will need to be logged into the relevant Log Management or SIEM account to view the API tokens associated with it.


        To manage your API tokens, log into the relevant account in your Logz.io platform, click the gear in the top-right menu, and select [**Tools > Manage tokens > API tokens**](https://app.logz.io/#/dashboard/settings/manage-tokens/api).


        It''s important to keep your tokens secure. API tokens carry privileges to make changes to users and accounts, so if you believe an API token has been compromised, delete it, and replace it with a new token in your integrations.'
      type: apiKey
      in: header
      name: X-API-TOKEN
x-servers:
- url: https://api.logz.io
  description: US East (Northern Virginia)
- url: https://api-au.logz.io
  description: Asia Pacific (Sydney)
- url: https://api-ca.logz.io
  description: Canada (Central)
- url: https://api-eu.logz.io
  description: Europe (Frankfurt)
- url: https://api-uk.logz.io
  description: Europe (London)
x-tagGroups:
- name: Log Monitoring
  tags:
  - Search logs
  - Alerts
  - Deployments
  - Insights
  - Logz.io snapshots
- name: Cloud SIEM
  tags:
  - Security account
  - Security rules
  - Security events
  - Lookup lists
- name: Account administration
  tags:
  - Manage users
  - Manage metrics account
  - Associated accounts
  - Authentication groups
  - Who am I
  - Manage time-based log accounts
  - Manage shared tokens
  - Manage API tokens
  - Manage notification endpoints
  - Import or export Kibana objects
- name: Manage data shipping
  tags:
  - Manage log shipping tokens
  - Drop filters
  - Archive logs
  - Restore logs
  - Parsing
  - Delete object API
- name: Data security
  tags:
  - Retrieve audit trail
- name: Connect to AWS resources
  tags:
  - Connect to CloudTrail
  - Connect to S3 Buckets
- name: Metrics API Gateway
  tags:
  - Grafana contact points
  - Grafana data source
  - Grafana alerting provisioning
  - Grafana silence management
  - Grafana annotations
  - Grafana dashboards
  - Grafana dashboard search
  - Grafana snapshots
  - Grafana get all folders
  description: Metrics API Gateway to supported endpoints.