openapi: 3.0.1
info:
  title: Elevate Authentication & Users API
  description: >
    ### Authentication


    Elevate API uses Bearer authentication (also called token authentication) -
    this is an HTTP authentication scheme that uses security tokens called
    bearer tokens

    The bearer tokens used by Elevate are the industry standard [JSON Web
    Tokens](http://jwt.io) (JWT)


    The client can obtain the token from this endpoint and must send this token
    in the Authorization header when making requests to other endpoints

    Tokens will be valid for 15 minutes before a new token must be obtained
  version: '1.5'
servers:
  - url: https://rest.elevatebilling.com/v1
tags:
  - name: authentication
    description: The Elevate REST API uses JWT Bearer tokens for authentication
  - name: users
    description: An identification used by a person with access to Elevate
  - name: user-roles
    description: Permission groups that can be assigned to users
  - name: app-clients
    description: >-
      An identification used by a service that access Elevate APIs
      programmatically
paths:
  /authenticate:
    post:
      tags:
        - authentication
      summary: Create bearer token
      security: []
      operationId: createBearerToken
      requestBody:
        description: request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticationRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /users:
    get:
      tags:
        - users
      summary: Get a list of available users
      operationId: getUsers
      x-si-permissions:
        - VIEW_USER
      security:
        - bearerAuth: []
      x-si-filterable: true
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/fields'
        - name: username
          in: query
          description: Filter by username
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
        - name: email
          in: query
          description: Filter by email
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
        - name: firstName
          in: query
          description: Filter by first name
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
        - name: lastName
          in: query
          description: Filter by last name
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
        - name: contractOwner
          in: query
          description: Filter by contract owner name
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
        - name: enabled
          in: query
          description: A boolean flag to specify if the user is enabled or disabled
          schema:
            $ref: '#/components/schemas/BooleanFilterParam'
          required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '400':
          description: Bad Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
    head:
      tags:
        - users
      summary: Check if user exists
      operationId: checkUser
      x-si-response-headers: true
      x-si-permissions:
        - VIEW_USER
      security:
        - bearerAuth: []
      parameters:
        - name: username
          in: query
          description: Filter by username
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
        - name: email
          in: query
          description: Filter by email
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
        - name: firstName
          in: query
          description: Filter by first name
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
        - name: lastName
          in: query
          description: Filter by last name
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
        - name: contractOwner
          in: query
          description: Filter by contract owner name
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
        - name: enabled
          in: query
          description: A boolean flag to specify if the user is enabled or disabled
          schema:
            $ref: '#/components/schemas/BooleanFilterParam'
          required: false
      responses:
        '200':
          description: Exists
          headers:
            X-Total-Count:
              schema:
                type: integer
                description: Total number of users matching the criteria
        '400':
          description: Invalid Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
        '404':
          description: Not Found
          content: {}
    post:
      tags:
        - users
      summary: Create a user
      security: []
      operationId: createUser
      x-si-permissions:
        - CREATE_USER
      requestBody:
        description: request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /users/{user_id}:
    get:
      tags:
        - users
      summary: Get a specific user
      operationId: getUser
      x-si-permissions:
        - VIEW_USER
      security:
        - bearerAuth: []
      parameters:
        - name: user_id
          in: path
          description: User identifier
          required: true
          schema:
            $ref: '#/components/schemas/IdParam'
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Bad Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
        '404':
          description: Not Found
          content: {}
    patch:
      tags:
        - users
      summary: Update a user
      operationId: updateUser
      x-si-json-patch: true
      x-si-allow-patch:
        - /username
        - /firstName
        - /lastName
        - /email
        - /telephoneNumber
        - /mobileNumber
        - /contractOwnerId
        - /enabled
        - /userRoles/.*
        - /userRoles
      x-si-permissions:
        - UPDATE_USER
      security:
        - bearerAuth: []
      parameters:
        - name: user_id
          in: path
          description: User identifier
          required: true
          schema:
            $ref: '#/components/schemas/IdParam'
      requestBody:
        description: A set of JSONPatch operations to be performed
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/PatchRequest'
            examples:
              Rename:
                value:
                  - op: replace
                    path: /firstName
                    value: Frank
                  - op: replace
                    path: /lastName
                    value: Simpson
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Invalid Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
        '404':
          description: Not Found
          content: {}
  /user-roles:
    get:
      tags:
        - user-roles
      summary: Get a list of available user roles
      operationId: getUserRoles
      x-si-permissions:
        - VIEW_ROLE
      security:
        - bearerAuth: []
      x-si-filterable: true
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/fields'
        - name: name
          in: query
          description: Filter by name
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserRole'
        '400':
          description: Bad Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
  /app-clients:
    get:
      tags:
        - app-clients
      summary: Get a list of App Clients
      operationId: getAppClients
      x-si-permissions:
        - VIEW_USER
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/fields'
        - name: name
          in: query
          description: Filter by name
          schema:
            $ref: '#/components/schemas/StringFilterParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AppClient'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    post:
      tags:
        - app-clients
      summary: Create an App Client
      operationId: createAppClient
      x-si-permissions:
        - CREATE_USER
      requestBody:
        description: request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppClientCreateRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppClientCreateResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /app-clients/{id}:
    get:
      tags:
        - app-clients
      summary: Get App Client by ID
      operationId: getAppClient
      x-si-permissions:
        - VIEW_USER
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          description: App Client ID
          required: true
          schema:
            $ref: '#/components/schemas/IdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppClient'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
    patch:
      tags:
        - app-clients
      summary: Update App Client
      operationId: updateAppClient
      x-si-json-patch: true
      x-si-allow-patch:
        - /name
        - /description
        - /userRoles/.*
        - /userRoles
      x-si-permissions:
        - UPDATE_USER
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          description: App Client ID
          required: true
          schema:
            $ref: '#/components/schemas/IdParam'
      requestBody:
        description: A set of JSONPatch operations to be performed
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/PatchRequest'
            examples:
              Rename:
                value:
                  - op: replace
                    path: /name
                    value: application name
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppClient'
        '400':
          description: Invalid Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
        '404':
          description: Not Found
          content: {}
    delete:
      tags:
        - app-clients
      summary: Delete App Client
      operationId: deleteAppClient
      x-si-permissions:
        - DELETE_USER
      parameters:
        - name: id
          in: path
          description: App Client ID
          required: true
          schema:
            $ref: '#/components/schemas/IdParam'
      responses:
        '200':
          description: Success
          content: {}
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
components:
  schemas:
    AuthenticationRequest:
      type: object
      required:
        - brand
        - username
        - password
      properties:
        brand:
          description: Brand name as provided by Strategic Imperatives
          type: string
        username:
          description: API user name
          type: string
          minLength: 1
          maxLength: 100
        password:
          description: API user password
          type: string
          minLength: 1
          maxLength: 100
    AuthenticationResponse:
      type: object
      properties:
        token:
          description: JWT Bearer token to use in subsequent requests
          type: string
        username:
          description: API user name
          type: string
          minLength: 1
          maxLength: 100
    User:
      required:
        - username
        - firstName
        - lastName
        - email
        - userRoles
      type: object
      properties:
        id:
          description: User identifier
          type: integer
          readOnly: true
          format: int64
          example: 1
        username:
          type: string
          description: Username
          minLength: 1
          maxLength: 100
          pattern: '[a-zA-Z0-9\p{L}@.\-_]+'
        firstName:
          type: string
          description: First name
          minLength: 1
          maxLength: 50
        lastName:
          type: string
          description: Last name
          minLength: 1
          maxLength: 50
        email:
          type: string
          description: Email address
          minLength: 5
          maxLength: 255
          pattern: >-
            [a-zA-Z0-9.!#$%&'\*\+\/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*
          example: annon@annon.com
        telephoneNumber:
          type: string
          description: Telephone number
          minLength: 1
          maxLength: 100
        mobileNumber:
          type: string
          description: Mobile telephone number
          minLength: 1
          maxLength: 30
        contractOwnerId:
          description: >-
            Contract Owner identifier (Optional Contract Owner to associate the
            user to. If they are associated to a Contract Owner then they will
            only be able to see and manage that Contract Owner's data)
          type: integer
          example: 1
        enabled:
          description: User is enabled
          type: boolean
          default: true
        userRoles:
          type: array
          items:
            type: integer
            example: 1
    UserRole:
      required:
        - name
      type: object
      properties:
        id:
          description: User role identifier
          type: integer
          readOnly: true
          format: int64
          example: 1
        name:
          type: string
          description: Role name
          minLength: 1
          maxLength: 50
    AppClient:
      type: object
      required:
        - id
        - name
        - appClientId
        - userRoles
      properties:
        id:
          description: User identifier
          type: integer
          readOnly: true
          format: int64
          example: 1
        contractOwnerId:
          description: >-
            Contract Owner identifier (Optional Contract Owner to associate the
            user to. If they are associated to a Contract Owner then they will
            only be able to see and manage that Contract Owner's data)
          type: integer
          example: 1
          readOnly: true
        name:
          type: string
        description:
          type: string
        appClientId:
          type: string
          readOnly: true
        lastSuccessfulAuthentication:
          type: string
          format: date-time
          readOnly: true
        lastFailedAuthentication:
          type: string
          format: date-time
          readOnly: true
        userRoles:
          type: array
          items:
            type: integer
            example: 1
    AppClientCreateRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        description:
          type: string
        userRoles:
          type: array
          items:
            type: integer
            example: 1
    AppClientCreateResponse:
      allOf:
        - $ref: '#/components/schemas/AppClient'
        - type: object
          properties:
            clientSecret:
              type: string
    PageParam:
      description: Page of results to show
      minimum: 1
      type: integer
      format: int32
      example: 1
    ResultsPerPageParam:
      description: Results to return per page
      maximum: 1000
      minimum: 1
      type: integer
      format: int32
      example: 100
    SortParam:
      description: >-
        Comma-delimited list of the fields to sort by - defaults to ascending
        order, suffix :desc to change
      example: id,name | name:desc
      type: string
    FieldsParam:
      description: >-
        Comma-delimited list of the field(s) to return if only a subset is
        required
      example: id,name
      type: string
    StringFilterParam:
      description: >-
        Filter by this string value where value can optionally be prefixed
        (in:|like:)
      example: xyz | in:x,y | like:xyz
      type: string
    BooleanFilterParam:
      description: Filter by this boolean value (true or false)
      example: true | false
      type: string
    IdParam:
      description: Identifier
      minimum: 1
      type: integer
      format: int64
      example: 1
    PatchDocument:
      description: A JSONPatch document as defined by RFC 6902
      required:
        - op
        - path
      type: object
      properties:
        op:
          type: string
          description: The JSON Patch operation to be performed
          x-si-exclude: true
          enum:
            - add
            - remove
            - replace
            - move
            - copy
            - test
        path:
          type: string
          description: A JSON-Pointer
        value:
          type: object
          properties: {}
          description: The value to be used within the operations
        from:
          type: string
          description: A string containing a JSON Pointer value
    PatchRequest:
      type: array
      description: >-
        JSON Patch is a format for describing changes to a JSON document as
        specified in RFC 6902. Refer to [jsonpatch.com](http://jsonpatch.com/)
        for more information
      items:
        $ref: '#/components/schemas/PatchDocument'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    page:
      name: page
      in: query
      description: Page of results to show
      schema:
        $ref: '#/components/schemas/PageParam'
      required: true
    pageSize:
      name: pageSize
      description: Results to return per page
      in: query
      schema:
        $ref: '#/components/schemas/ResultsPerPageParam'
      required: true
    sort:
      name: sort
      in: query
      description: >-
        Comma-delimited list of the fields to sort by - defaults to ascending
        order, suffix :desc to change
      schema:
        $ref: '#/components/schemas/SortParam'
      required: false
    fields:
      name: fields
      in: query
      description: >-
        Comma-delimited list of the field(s) to return if only a subset is
        required
      schema:
        $ref: '#/components/schemas/FieldsParam'
      required: false
