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.