Dow Jones User API

openapi: 3.2.0
info:
  title: Advanced Screening and Monitoring User API
  description: 'Dow Jones


    ### Rate limits


    Most endpoints are subject to a general rate limit of 10,000 requests per user per 15 minutes.


    Some endpoints are also subject to a global concurrent request limit of 5 simultaneous requests per customer.'
  version: '3'
  license: {}
  contact: {}
servers:
- url: API_INSTANCE
security:
- basicAuth: []
- jwt: []
- clientCert: []
tags:
- name: User
  description: The User API allows clients to import and manage user accounts in the system.
paths:
  /user/search:
    post:
      summary: Search users
      description: 'Search users that

        ### Rate Limits


        This endpoint is subject to a general rate limit of 10,000 requests per user per 15 minutes.

        '
      operationId: userSearch
      tags:
      - User
      parameters:
      - in: query
        name: includeDeleted
        description: Return deleted users
        required: false
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: object
              properties:
                cn:
                  type: string
                  description: The user's canonical name. Used to lookup user accounts when performing certificate-based authentication.
                cns:
                  type: array
                  description: Array of user's canonical names. Used to lookup user accounts when performing certificate-based authentication.
                  items:
                    type: string
                id:
                  type: number
                  example: 10000
                ids:
                  type: array
                  items:
                    type: number
                  example:
                  - 10000
                  - 10001
                email:
                  type: string
                  example: john.smith@ripjar.com
                username:
                  type: string
                  example: John Smith
                roles:
                  type: array
                  items:
                    type: string
                  example:
                  - ROLE_1
                externalId:
                  type: string
                  example: john.smith@ripjar.com
      responses:
        '200':
          description: Success - returns an array of user records that matches the given filter
          content:
            text/plain:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    username:
                      type: string
                      example: John Smith
                    email:
                      type: string
                      example: john.smith@ripjar.com
                    cn:
                      type: string
                      example: john.smith@ripjar.com
                    clientKey:
                      type: string
                      example: lowercasekey
                    customerExcludedApps:
                      type: array
                      nullable: true
                      items:
                        type: string
                        example: app
                    roles:
                      type: array
                      items:
                        type: string
                        example: ADMINISTRATOR
                    security:
                      type: object
                    id:
                      type: number
                      example: 10000
                    externalId":
                      type: string
                      example: john.smith@ripjar.com
                    mobile:
                      type: string
                      example: 01234567890
                    username_lowercase:
                      type: string
                      example: john smith
                    accountLocked:
                      type: boolean
                      example: false
                    failed_login_attempts:
                      type: number
                      example: 0
                    failed_login_timestamp:
                      type: number
                      example: -1
                    whitelistedPermissions:
                      type: array
                      example:
                      - Admin
                      - AlertClose
                      items:
                        type: string
                    customerName:
                      type: string
                    permissions:
                      type: array
                      items:
                        type: string
                        example: Admin
        '400':
          description: Your request was invalid and the search could not be performed
        '401':
          description: Unauthenticated request
        '403':
          description: The authenticated user cannot search / view user records
        '500':
          description: An unexpected error occurred performing the search
          content:
            application/json:
              schema:
                type: object
                required:
                - code
                - message
                properties:
                  code:
                    type: string
                    description: Error code that can be used when contacting support or looking up information
                  message:
                    type: string
                    description: Human-readable description of the error, which will usually indicate possible next steps if applicable
                  status:
                    type: number
                    description: HTTP Error code
  /user/import:
    post:
      summary: Bulk import multiple users to the system
      description: 'Create or update multiple user accounts within the system.

        ### Rate Limits


        This endpoint is subject to a general rate limit of 10,000 requests per user per 15 minutes.

        '
      operationId: userImport
      tags:
      - User
      requestBody:
        required: true
        description: A list of line-delimited JSON records, where each line is a complete JSON object that conforms to the user schema.
        content:
          text/plain:
            schema:
              type: object
              description: An object representing a user in the system.
              required:
              - username
              - email
              - cn
              properties:
                excludedApps:
                  type: array
                  items:
                    type: string
                  description: A list of the applications that this user is excluded from accessing. Not used in Labyrinth Screening.
                username:
                  type: string
                  description: The name of the user. This is the value displayed when the user is referenced in the UI.
                email:
                  type: string
                  description: The email address of the user. Can be used as part of basic authentication.
                mobile:
                  type: string
                  description: The mobile/cell phone number of the user.
                roles:
                  type: array
                  items:
                    type: string
                  description: 'A list of the user roles that this user has.

                    Labyrinth Screening makes use of defined user roles to control the actions a user may perform and to tailor the interface to the needs of particular users.

                    Each role is made up of a set of permissions which provide fine grained control over the actions a user can perform. Roles can be configured to match the business roles required by the users of the Screening system.

                    These permissions used by the Screening system are described in the Ripjar Security Implementation document.

                    When users are loaded into the system, each user account should include the list of roles they are allowed to perform.

                    '
                password:
                  type: string
                  description: 'The user''s password, used for basic authentication or to retrieve a bearer auth (JWT) token. Not available in API responses. Required when creating or updating users.

                    '
                cn:
                  type: string
                  description: The user's canonical name. Used to lookup user accounts when performing certificate-based authentication.
                externalId:
                  type: string
                  description: The user's ID external to the system. Typically maps to a username or ID in an external user entitlement system.
                security:
                  type: object
                  description: 'The security attributes for this user.

                    A user''s security attributes govern the data items in the system (such as clients, alerts and assessments) that the user has visibility of. These are distinct from the user''s roles, which govern the operations a user can carry out in the system.

                    The security schema contains a set of generic attributes that the user can be assigned. The meaning of these attributes varies depending on the security policy installed on the system.

                    By default, the security policy will compare the list of strings (also known as tags) in dataRolesN fields of the user to the list of strings in the orTagsN field in the security attributes of the data item. If the user has any of the tags that appear on the data item, they can view that item.

                    If the data item has multiple orTags fields, for example orTags1 and orTags2, the user must has at least one of the tags in each of the corresponding dataRoles fields, i.e. there is an AND logic between each attribute.

                    '
                  properties:
                    dataRoles1:
                      type: array
                      items:
                        type: string
                    dataRoles2:
                      type: array
                      items:
                        type: string
                    dataRoles3:
                      type: array
                      items:
                        type: string
                    compositeDataRoles1:
                      type: array
                      items:
                        type: object
      responses:
        '200':
          description: Success - returns the set of user records that were added or updated
          content:
            text/plain:
              schema:
                type: object
                description: An object representing a user in the system.
                required:
                - username
                - email
                - cn
                properties:
                  excludedApps:
                    type: array
                    items:
                      type: string
                    description: A list of the applications that this user is excluded from accessing. Not used in Labyrinth Screening.
                  username:
                    type: string
                    description: The name of the user. This is the value displayed when the user is referenced in the UI.
                  email:
                    type: string
                    description: The email address of the user. Can be used as part of basic authentication.
                  mobile:
                    type: string
                    description: The mobile/cell phone number of the user.
                  roles:
                    type: array
                    items:
                      type: string
                    description: 'A list of the user roles that this user has.

                      Labyrinth Screening makes use of defined user roles to control the actions a user may perform and to tailor the interface to the needs of particular users.

                      Each role is made up of a set of permissions which provide fine grained control over the actions a user can perform. Roles can be configured to match the business roles required by the users of the Screening system.

                      These permissions used by the Screening system are described in the Ripjar Security Implementation document.

                      When users are loaded into the system, each user account should include the list of roles they are allowed to perform.

                      '
                  password:
                    type: string
                    description: 'The user''s password, used for basic authentication or to retrieve a bearer auth (JWT) token. Not available in API responses. Required when creating or updating users.

                      '
                  cn:
                    type: string
                    description: The user's canonical name. Used to lookup user accounts when performing certificate-based authentication.
                  externalId:
                    type: string
                    description: The user's ID external to the system. Typically maps to a username or ID in an external user entitlement system.
                  security:
                    type: object
                    description: 'The security attributes for this user.

                      A user''s security attributes govern the data items in the system (such as clients, alerts and assessments) that the user has visibility of. These are distinct from the user''s roles, which govern the operations a user can carry out in the system.

                      The security schema contains a set of generic attributes that the user can be assigned. The meaning of these attributes varies depending on the security policy installed on the system.

                      By default, the security policy will compare the list of strings (also known as tags) in dataRolesN fields of the user to the list of strings in the orTagsN field in the security attributes of the data item. If the user has any of the tags that appear on the data item, they can view that item.

                      If the data item has multiple orTags fields, for example orTags1 and orTags2, the user must has at least one of the tags in each of the corresponding dataRoles fields, i.e. there is an AND logic between each attribute.

                      '
                    properties:
                      dataRoles1:
                        type: array
                        items:
                          type: string
                      dataRoles2:
                        type: array
                        items:
                          type: string
                      dataRoles3:
                        type: array
                        items:
                          type: string
                      compositeDataRoles1:
                        type: array
                        items:
                          type: object
        '400':
          description: The request was invalid and the import could not be performed
        '401':
          description: Unauthenticated request
        '403':
          description: The authenticated user cannot add / update user records
        '500':
          description: An unexpected error occurred performing the import
          content:
            application/json:
              schema:
                type: object
                required:
                - code
                - message
                properties:
                  code:
                    type: string
                    description: Error code that can be used when contacting support or looking up information
                  message:
                    type: string
                    description: Human-readable description of the error, which will usually indicate possible next steps if applicable
                  status:
                    type: number
                    description: HTTP Error code
  /users:
    delete:
      summary: Delete a list of users from the system.
      description: 'The Delete Users Endpoint is used to delete a large number of users in a single call. ### Rate Limits

        This endpoint is subject to a general rate limit of 10,000 requests per user per 15 minutes.

        User records are soft-deleted: the system retains basic essential information about the user for audit and display purposes, but the user account will be inaccessible.

        '
      operationId: usersDelete
      tags:
      - User
      requestBody:
        required: true
        description: A line-delimited list of JSON records conforming to the user delete request schema, and representing the IDs of the users to delete.
        content:
          application/octet-stream:
            schema:
              type: object
              description: The identity of the user to delete.
              oneOf:
              - externalId: null
                type: string
                description: The external ID of the user to delete.
              - id: null
                type: integer
                description: The internal Labyrinth Screening ID of the user to delete.
          text/plain:
            schema:
              type: object
              description: The identity of the user to delete.
              oneOf:
              - externalId: null
                type: string
                description: The external ID of the user to delete.
              - id: null
                type: integer
                description: The internal Labyrinth Screening ID of the user to delete.
      responses:
        '200':
          description: Users deleted successfully
        '400':
          description: Invalid request
        '401':
          description: Unauthenticated request
        '403':
          description: Forbidden request
        '500':
          description: An unexpected error occurred when performing client deletion
          content:
            application/json:
              schema:
                type: object
                required:
                - code
                - message
                properties:
                  code:
                    type: string
                    description: Error code that can be used when contacting support or looking up information
                  message:
                    type: string
                    description: Human-readable description of the error, which will usually indicate possible next steps if applicable
                  status:
                    type: number
                    description: HTTP Error code
  /users/sync:
    post:
      summary: Synchronize users to the system by replacing all current users with a new set
      description: 'The Synchronize Users endpoint will replace all of the users currently defined in the Labyrinth system with those in the payload received. The following rules are observed: - Any user currently within the system and not mentioned in the payload will be deleted. - The system will update any existing user where the `id` or `externalId` fields match. - Any user that is absent, both the `id` and `externalId` fields will be created. - If an `id` is provided, but could not be found, then an error will be returned. ### Rate Limits

        This endpoint is subject to a general rate limit of 10,000 requests per user per 15 minutes.

        `id` is a field created by the Labyrinth system.  Any record that contains an id that cannot be found in the system will result in a 404 error response. `externalId` is not a required field and so will be missing in the response if not provided. To update a user, then one or both of the `id` or `externalId` fields must be provided. The combination of the lineNumber and errors fields in the response should be used to diagnose which records could not be updated and why the operation was not successful.

        *Care should be taken with this mechanism since it is possible to delete all users by sending an empty payload.*

        '
      operationId: usersSync
      tags:
      - User
      requestBody:
        required: true
        description: A list of line-delimited JSON records that conform to the user schema and represent the full set of user records that should exist in the system once the operation has completed.
        content:
          text/plain:
            schema:
              type: object
              description: An object representing a user in the system.
              required:
              - username
              - email
              - cn
              properties:
                excludedApps:
                  type: array
                  items:
                    type: string
                  description: A list of the applications that this user is excluded from accessing. Not used in Labyrinth Screening.
                username:
                  type: string
                  description: The name of the user. This is the value displayed when the user is referenced in the UI.
                email:
                  type: string
                  description: The email address of the user. Can be used as part of basic authentication.
                mobile:
                  type: string
                  description: The mobile/cell phone number of the user.
                roles:
                  type: array
                  items:
                    type: string
                  description: 'A list of the user roles that this user has.

                    Labyrinth Screening makes use of defined user roles to control the actions a user may perform and to tailor the interface to the needs of particular users.

                    Each role is made up of a set of permissions which provide fine grained control over the actions a user can perform. Roles can be configured to match the business roles required by the users of the Screening system.

                    These permissions used by the Screening system are described in the Ripjar Security Implementation document.

                    When users are loaded into the system, each user account should include the list of roles they are allowed to perform.

                    '
                password:
                  type: string
                  description: 'The user''s password, used for basic authentication or to retrieve a bearer auth (JWT) token. Not available in API responses. Required when creating or updating users.

                    '
                cn:
                  type: string
                  description: The user's canonical name. Used to lookup user accounts when performing certificate-based authentication.
                externalId:
                  type: string
                  description: The user's ID external to the system. Typically maps to a username or ID in an external user entitlement system.
                security:
                  type: object
                  description: 'The security attributes for this user.

                    A user''s security attributes govern the data items in the system (such as clients, alerts and assessments) that the user has visibility of. These are distinct from the user''s roles, which govern the operations a user can carry out in the system.

                    The security schema contains a set of generic attributes that the user can be assigned. The meaning of these attributes varies depending on the security policy installed on the system.

                    By default, the security policy will compare the list of strings (also known as tags) in dataRolesN fields of the user to the list of strings in the orTagsN field in the security attributes of the data item. If the user has any of the tags that appear on the data item, they can view that item.

                    If the data item has multiple orTags fields, for example orTags1 and orTags2, the user must has at least one of the tags in each of the corresponding dataRoles fields, i.e. there is an AND logic between each attribute.

                    '
                  properties:
                    dataRoles1:
                      type: array
                      items:
                        type: string
                    dataRoles2:
                      type: array
                      items:
                        type: string
                    dataRoles3:
                      type: array
                      items:
                        type: string
                    compositeDataRoles1:
                      type: array
                      items:
                        type: object
      responses:
        '200':
          description: Success - returns a list of line-delimited JSON records representing any errors that were encountered.
          content:
            text/plain:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  externalId:
                    type: string
                  lineNumber:
                    type: integer
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: integer
                        message:
                          type: string
        '400':
          description: Your request was invalid and the sync could not be performed
        '401':
          description: Unauthenticated request
        '403':
          description: The authenticated user cannot perform a synchronization
        '500':
          description: An unexpected error occurred performing the synchronization
          content:
            application/json:
              schema:
                type: object
                required:
                - code
                - message
                properties:
                  code:
                    type: string
                    description: Error code that can be used when contacting support or looking up information
                  message:
                    type: string
                    description: Human-readable description of the error, which will usually indicate possible next steps if applicable
                  status:
                    type: number
                    description: HTTP Error code
components:
  securitySchemes:
    jwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT authentication is the preferred authentication method, and should be used for new integrations.  Contact support to request a service account.
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication is supported for existing users, but is deprecated.  Existing users are encouraged to contact support for a dedicated service account and switch to JWT authentication.