openapi: 3.0.1
info:
  title: Gremlin agents users API
  description: The API for interacting with the Gremlin Failure-as-a-Service platform
  termsOfService: https://www.gremlin.com/terms_of_service_2017_03_24
  contact:
    name: Gremlin Support
    email: support@gremlin.com
  license:
    name: Gremlin License
    url: https://www.gremlin.com/license_2017_03_24
  version: '1.0'
servers:
- url: https://api.gremlin.com/v1
  description: Gremlin API v1
tags:
- name: users
  description: Get users (all or active) and activate, deactivate, update, and invite users.
paths:
  /users/active:
    get:
      tags:
      - users
      summary: Get all active users.
      description: Requires the privilege [`USERS_READ`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: active_4
      parameters:
      - name: teamId
        in: query
        description: Required when using company session token.
        required: true
        schema:
          type: string
      responses:
        default:
          description: default response
          content:
            application/json: {}
        '403':
          description: 'User requires privilege for target team: USERS_READ'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - USERS_READ
  /users/active/paged:
    get:
      tags:
      - users
      summary: Get all active users paginated.
      description: Requires the privilege [`USERS_READ`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: activePaginated
      parameters:
      - name: pageSize
        in: query
        description: This value determines how many results will be returned per call.
        schema:
          type: integer
          format: int32
          default: 10
        example: None (unlimited)
      - name: pageToken
        in: query
        description: Token corresponding to the last page of active company users for team retrieved. Pass the pageToken to get the next page of active company users for team
        schema:
          type: string
        example: None (returns first page)
      - name: teamId
        in: query
        description: Required when using company session token.
        required: true
        schema:
          type: string
      responses:
        default:
          description: default response
          content:
            application/json: {}
        '403':
          description: 'User requires privilege for target team: USERS_READ'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - USERS_READ
  /users:
    get:
      tags:
      - users
      summary: Get all users.
      description: Requires the privilege [`USERS_READ`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: all_4
      parameters:
      - name: teamId
        in: query
        description: Required when using company session token.
        required: true
        schema:
          type: string
      responses:
        default:
          description: default response
          content:
            application/json: {}
        '403':
          description: 'User requires privilege for target team: USERS_READ'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - USERS_READ
    post:
      tags:
      - users
      summary: Add an existing user to the target team
      description: 'User must belong to this teams company

        Requires the privilege [`USERS_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)'
      operationId: addUserToTeam
      parameters:
      - name: teamId
        in: query
        description: Required when using company session token.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AddUserRequest'
        required: true
      responses:
        '200':
          description: Users successfully added
        '400':
          description: One or more users were not found or were revoked, no users added
        '409':
          description: One or more users already belong on team, no users added
        '403':
          description: 'User requires privilege for target team: USERS_WRITE'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - USERS_WRITE
  /users/paged:
    get:
      tags:
      - users
      summary: Get all users paginated.
      description: Requires the privilege [`USERS_READ`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: allPaginated
      parameters:
      - name: pageSize
        in: query
        description: This value determines how many results will be returned per call.
        schema:
          type: integer
          format: int32
          default: 10
        example: None (unlimited)
      - name: pageToken
        in: query
        description: Token corresponding to the last page of company users for team retrieved. Pass the pageToken to get the next page of company users for team
        schema:
          type: string
        example: None (returns first page)
      - name: teamId
        in: query
        description: Required when using company session token.
        required: true
        schema:
          type: string
      responses:
        default:
          description: default response
          content:
            application/json: {}
        '403':
          description: 'User requires privilege for target team: USERS_READ'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - USERS_READ
  /users/self:
    get:
      tags:
      - users
      summary: Get information about the authenticated user
      description: Requires the privilege [`MINIMUM_COMPANY_PRIVILEGES`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: getSelf
      parameters: []
      responses:
        default:
          description: default response
          content:
            application/json: {}
        '403':
          description: 'User requires privilege: MINIMUM_COMPANY_PRIVILEGES'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - MINIMUM_COMPANY_PRIVILEGES
    patch:
      tags:
      - users
      summary: Update an existing users info.
      description: 'User must exist.

        Requires the privilege [`MINIMUM_COMPANY_PRIVILEGES`](https://www.gremlin.com/docs/user-management/access-control/#privileges)'
      operationId: rbacUpdateSelf
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserInfoRequest'
        required: true
      responses:
        default:
          description: default response
          content:
            text/plain: {}
        '403':
          description: 'User requires privilege: MINIMUM_COMPANY_PRIVILEGES'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - MINIMUM_COMPANY_PRIVILEGES
  /users/invite:
    post:
      tags:
      - users
      summary: Invite a user.
      description: Requires the privilege [`COMPANY_USERS_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: invite_1
      parameters: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
              - email
              type: object
              properties:
                email:
                  type: string
                source_detail:
                  type: string
                  enum:
                  - Onboarding
      responses:
        default:
          description: default response
          content:
            text/plain: {}
        '403':
          description: 'User requires privilege: COMPANY_USERS_WRITE'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - COMPANY_USERS_WRITE
  /users/renew/rbac:
    post:
      tags:
      - users
      summary: Renew authorization.
      operationId: rbacAuthRenew
      parameters: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
              - companyId
              - email
              - renewToken
              type: object
              properties:
                email:
                  type: string
                companyId:
                  type: string
                teamId:
                  type: string
                renewToken:
                  type: string
      responses:
        default:
          description: default response
          content:
            application/json: {}
        '403':
          description: Response was sent via HTTP, please retry using HTTPS
  /users/{email}:
    put:
      tags:
      - users
      summary: Update an existing user.
      description: 'User must exist.

        Requires the privilege [`USERS_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)'
      operationId: update_2
      parameters:
      - name: email
        in: path
        required: true
        schema:
          type: string
      - name: teamId
        in: query
        description: Required when using company session token.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
              - role
              type: object
              properties:
                role:
                  uniqueItems: true
                  type: array
                  items:
                    type: string
      responses:
        default:
          description: default response
          content:
            application/json: {}
        '403':
          description: 'User requires privilege for target team: USERS_WRITE'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - USERS_WRITE
    delete:
      tags:
      - users
      summary: Deactivate a user.
      description: Requires the privilege [`USERS_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: revokeOrRemoveFromTeam
      parameters:
      - name: email
        in: path
        required: true
        schema:
          type: string
      - name: teamId
        in: query
        description: Required when using company session token.
        required: true
        schema:
          type: string
      responses:
        default:
          description: default response
          content:
            text/plain: {}
        '403':
          description: 'User requires privilege for target team: USERS_WRITE'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - USERS_WRITE
  /users/sessions:
    get:
      tags:
      - users
      summary: Returns the updated user sessions list for the currently authenticated user.
      description: Requires the privilege [`MINIMUM_COMPANY_PRIVILEGES`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: refreshSessions
      parameters:
      - name: getCompanySession
        in: query
        schema:
          type: boolean
      responses:
        default:
          description: default response
          content:
            application/json: {}
        '403':
          description: 'User requires privilege: MINIMUM_COMPANY_PRIVILEGES'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - MINIMUM_COMPANY_PRIVILEGES
  /users/invite/{email}:
    delete:
      tags:
      - users
      summary: Revoke a pending user invite.
      description: Requires the privilege [`COMPANY_USERS_WRITE`](https://www.gremlin.com/docs/user-management/access-control/#privileges)
      operationId: revokeInvite
      parameters:
      - name: email
        in: path
        required: true
        schema:
          type: string
      responses:
        default:
          description: default response
          content:
            text/plain: {}
        '403':
          description: 'User requires privilege: COMPANY_USERS_WRITE'
        '401':
          description: Authorization header missing or malformed. Please provide proper credentials in the authorization header.
      security:
      - privilege:
        - COMPANY_USERS_WRITE
components:
  schemas:
    UpdateUserInfoRequest:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
    AddUserRequest:
      required:
      - identifier
      type: object
      properties:
        identifier:
          type: string
          description: The unique identifier for the user (user's email)
      description: represents a request to add an existing user to a team