custom/JumpCloud.SDK.DirectoryInsights.json
|
{
"consumes": [ "application/json" ], "produces": [ "application/json" ], "schemes": [ "https" ], "swagger": "2.0", "info": { "description": "# API Overview\n\nThe purpose of this API is to query Jumpcloud Directory Insights events\n\n## Directory Insights\n\nDirectory Insights provides event logs, see activity happening in your directory, and monitor user authentications to the console, SSO apps, RADIUS, and LDAP. Directory Insights shines a light on audit trails leading up to critical events so you know the what, where, when, how, and who of your directory activities.\n\n+ __Directory Events:__ Logs on activity in the Portal, including admin changes in the directory and admin/user authentications to the Portal.\n+ __SAML Events:__ Logs on user authentications to SAML applications.\n+ __RADIUS Events:__ Logs on user authentications to RADIUS used for wifi and VPNs.\n+ __MacOS, Windows and Linux Events__: Logs about user authentications to systems including agent related events on lockout, password changes, and File Disk Encryption key updates.\n+ __LDAP Events__: Logs about user authentications to LDAP, including LDAP bind and search events types.\n+ __MDM Events__: Logs about MDM command results.\n\nHow to retrieve MSP Admin API Key\n\n+ Log into MTP portal.\n+ Launch any one of the child organizations.\n+ Click on the icon for the logged in MTP Admin user account located on the upper right hand corner of the page.\n+ Click \"API Settings\".\n+ Copy the API Key that appears in the popup dialog box. This is the MSP Admin API Key.\n\nDirectory Insights is available in our API, Powershell, and Activity Log. The API uses a single POST endpoint:\n\n```text\nhttps://api.jumpcloud.com/insights/directory/v1/events\n```\n\n## Data Retention\n\nJumpCloud stores 90 days of event logs and removes logs older than the retention period. If you would like to store data for longer periods of time, our [AWS Serverless Application](https://support.jumpcloud.com/support/s/article/The-JumpCloud-Directory-Insights-AWS-Serverless-Application) automatically exports Directory Insights events to a customer's S3 for longer storage options.\n\n# Authentication & Authorization\n\n## Authentication\n\n### Access Your API Key\n\nTo locate your API Key:\n\n1. Log in to the [JumpCloud Admin Portal](https://console.jumpcloud.com/).\n2. Go to the username drop down located in the top-right of the Portal.\n3. Retrieve your API key from API Settings.\n\n### API Key Considerations\n\nThis API key is associated with the currently logged in administrator. Only administrator roles can access the API. Command runners will receive 403 error.\n\nPlease keep this API key secret, as it grants full access to any data accessible via your JumpCloud admin account.\n\nYou can also reset your API key in the same location in the JumpCloud Admin Portal.\n\n#### Recycling or Resetting Your API Key\n\nIn order to revoke access with the current API key, simply reset your API key. This will render all calls using the previous API key inaccessible.\n\n### Example Request (Mac and LINUX)\n\n```bash\ncurl -X POST -H x-api-key:[YOUR_API_KEY_HERE]\" -H \"Content-Type: application/json\" --data '{\"service\": [\"all\"], \"start_time\": \"2020-03-03T14:00:00Z\"}' https://api.jumpcloud.com/insights/directory/v1/events\n```\n\n### Example Request (Windows)\n\nFor Windows we recommend creating a local .txt file to pass in the JSON POST body with the query parameters.\n\n```bash\ncurl -X POST -H \"x-api-key:[YOUR_API_KEY_HERE]\" -H \"Content-Type: application/json\" --data @./fileWithPostBody.txt \"https://api.jumpcloud.com/insights/directory/v1/events\"\n```\n\nIn the example above create a file `fileWithPostBody.txt` with the POST body and execute the command within the directory with the local file. See [how to create a POST body](#json-post-request-body) below.\n\n```json\n{\n \"service\": [\n \"all\"\n ],\n \"start_time\": \"2020-03-03T00:00:00Z\"\n}\n```\n\n## Managed Service Providers\n\nManaged Service Providers can query client organizations and events generated within the Multi-Tenant Portal with an API key from an MSP admin and an organization id for the client org they administrator.\n\n### Example Request With One Organization\n\n```bash\ncurl -X POST -H \"x-api-key:[YOUR_API_KEY_HERE]\" -H \"x-org-id:[ADMINISTERED_ORG_ID]\" -H \"Content-Type: application/json\" --data '{\"service\": [\"all\"], \"start_time\": \"2020-03-03T14:00:00Z\"}' https://api.jumpcloud.com/insights/directory/v1/events\n```\n\n### Example Request With More Than One Organization\n\n```bash\ncurl -X POST -H \"x-api-key:[YOUR_API_KEY_HERE]\" -H \"x-org-id:[ADMINISTERED_ORG_ID_A]\" -H \"x-org-id:[ADMINISTERED_ORG_ID_B]\" -H \"x-org-id:[ADMINISTERED_ORG_ID_C]\" -H \"Content-Type: application/json\" --data '{\"service\": [\"all\"], \"start_time\": \"2020-03-03T14:00:00Z\"}' https://api.jumpcloud.com/insights/directory/v1/events\n```\n\n### Example To Request Multi-Tenant Portal Events Only\n\nThere is no limit to the number of org id's that can be passed in the request.\n\n```bash\ncurl -X POST -H \"x-api-key:[YOUR_API_KEY_HERE]\" -H \"Content-Type: application/json\" --data '{\"service\": [\"all\"], \"start_time\": \"2020-03-03T14:00:00Z\"}' https://api.jumpcloud.com/insights/directory/v1/events\n```\n\n# How to use the Directory Insights API\n\n## JSON POST request body\n\nQueries are made by HTTP POST request to the api's /events web context, using curl or Postman or wget or other HTTP client.\n\nThe two required fields in the JSON body are\n\n```json\n{\n \"service\": [\n \"service name\"\n ],\n \"start_time\": \"RFC 3339 date\"\n}\n```\n\nValid values for __service__ are:\n\n+ __all__: Logs from all services.\n+ __directory__: Logs on activity in the Portal, including admin changes in the directory and admin/user authentications to the Portal.\n+ __radius__: Logs on user authentications to RADIUS used for wifi and VPNs.\n+ __sso__: Logs on user authentications to SAML applications.\n+ __systems__: Logs about user authentications to MacOS, Windows, and Linux systems including agent related events on lockout, password changes, and File Disk Encryption key updates.\n+ __ldap__: Logs about user authentications to LDAP, including LDAP bind and search events types.\n+ __mdm__: Logs about MDM command results.\n\nIf you specify an invalid or unknown value for \"service\", the system will respond with the list of supported values.\n\nChoose a start time you'd like the service to start searching. Specify an RFC3339-formatted UTC date. For example, RFC3339 = \"2020-01-01T14:00:00Z\".\n\n(yyyy-mm-ddTHH:mm:ssZ (timezone optional, please reference RFC3339 or use Z as in the example). You'll be informed about missing or invalid date formats, as well as start dates in the future and end dates before start dates.\n\nPutting the two required fields together, searching for radius events on or after Jan 1st 2020 2pm UTC -- your JSON HTTP body would be:\n\n### Example\n\n```json\n{\n \"service\": [\n \"radius\"\n ],\n \"start_time\": \"2020-01-01T14:00:00Z\"\n}\n```\n\nIf you would prefer to put the post body into a local file for easy edits, save the JSON structure into a file called simple-query.txt, and execute the query:\n\n```bash\ncurl -X POST -H \"x-api-key:[YOUR_API_KEY_HERE]\" -d @./simple-query.txt https://api.jumpcloud.com/insights/directory/v1/events\n```\n\nThe Directory Insights API returns a JSON array, such as the following:\n\n### Example Admin Login Attempt Response\n\n```json\n{\n \"geoip\": {\n \"timezone\": \"America/Denver\",\n \"country_code2\": \"US\",\n \"continent_code\": \"NA\",\n \"region_name\": \"Colorado\",\n \"region_code\": \"CO\"\n },\n \"event_type\": \"admin_login_attempt\",\n \"resource\": {\n \"id\": \"5ce434e77128503e528e747c\",\n \"type\": \"admin\",\n \"email\": \"jane.doe@gmail.com\"\n },\n \"provider\": null,\n \"success\": true,\n \"organization\": \"5ce434e87128303e528e747b\",\n \"@version\": \"1\",\n \"mfa\": true,\n \"client_ip\": \"73.203.76.115\",\n \"id\": \"5e95d60b05e8907888c4e009\",\n \"user_agent\": {\n \"patch\": \"4044\",\n \"minor\": \"0\",\n \"major\": \"81\",\n \"os\": \"Mac OS X\",\n \"build\": \"\",\n \"os_minor\": \"15\",\n \"os_major\": \"10\",\n \"name\": \"Chrome\",\n \"os_name\": \"Mac OS X\",\n \"device\": \"Other\"\n },\n \"timestamp\": \"2020-04-14T15:26:03.218Z\"\n}\n```\n\nEvery response with an HTTP 200 status code will return an array of events (possibly an empty array). Each array element is a row describing an event. They include, at a minimum, the exact timestamp that the event occurred. Other fields are variable and can be queried. Example queries follow in this document.\n\n## Row size limit\n\nBy default, the system returns a maximum of 1000 rows. You can change the number of rows returned to you by adding a value for limit, in the JSON body you send to the service:\n\n### Example | Row Limit\n\n```json\n{\n \"service\": [\n \"radius\"\n ],\n \"limit\": 2000,\n \"start_time\": \"2020-01-01T14:00:00Z\"\n}\n\n```\n\nThe maximum rows you can request is 10,000, and any nonsensical values for limit will cause the system to return the default row count.\n\n## HTTP Response header metadata\n\nIn the HTTP Response headers, you'll find information about your query, including the number of rows returned to you in the results array (\"result_count\"), the search order we used (based on event timestamp) and other fields (\"limit\")which will be discussed later in this document.\n\n HTTP Response Header Metadata | Description |\n ----------------------------- | ------------------------------------------------------------------------------------------------------------- |\n X-Result-Count | is the number of elements in the array returned by the service. |\n X-Limit | the maximum number of rows the service can return in one call. |\n X-Sort | the sort direction of the result array timestamp column. |\n X-Search_after | the token you'll send to the service to get subsequent pages of data. This is explained in the section below. |\n X-Request-Id | is a tracing header we can use to follow a specific query through the system |\n\n### Example | Response Header\n\n```json\n{\n \"X-Result-Count\": 1000,\n \"X-Limit\": 1000,\n \"X-Sort\": \"ASC\",\n \"X-Search_after\": [\n 1576181718000,\n \"DZrPyW8BNsa9iKWoOm7h\"\n ],\n \"X-Request-Id\": \"f5b277fc-7b0b-4c1e-9bee-c5ea1d79302f\"\n}\n```\n\n## Getting all the pages of data\n\nIt is possible that more rows match your query than are initially returned by the service. To retrieve subsequent pages of data, you'll simply specify the exact same query again, adding specific information from the `X-Search_after` response header returned to you in your first query.\n\n### Example | Header\n\n```json\n{\n \"X-Result-Count\": 1000,\n \"X-Limit\": 1000,\n \"X-Sort\": \"ASC\",\n \"X-Search_after\": [\n 1576181718000,\n \"DZrPyW8BNsa9iKWoOm7h\"\n ],\n \"X-Request-Id\": \"f5b277fc-7b0b-4c1e-9bee-c5ea1d79302f\"\n}\n```\n\nFor example, if the system responds with 1000 events and the following HTTP response headers, you can see that the system returned 1000 rows to you (`X-Result-Count`) which equaled the limit of the number of rows the service could return (`X-Limit`). When this happens (result count == limit) you will need to send more requests to the service to get the remaining pages of matching results.\n\nTo get the next page of rows, simply re-issue the exact query you did the first time, but for this query, add the \"search_after\" section with the value from the `X-Search_after` header.\n\n### Example | Query for next page of results\n\n```json\n{\n \"service\": [\n \"radius\"\n ],\n \"start_time\": \"2020-01-01T14:00:00Z\",\n \"search_after\": [\n 1576181718000,\n \"DZrPyW8BNsa9iKWoOm7h\"\n ]\n}\n```\n\nThe system will again respond, with the matching events from the second query, and a new set of HTTP response headers. To retrieve all of the events matching your query, you'll need to continue comparing the `X-Limit` and `X-Result-Count` header values to see if there are still more pages. If so, re-issue the query again, but specify the new \"search_after\" value. Once the `X-Result-Count` value is less than `X-Limit`, you have reached the last page of events data.\n\nPlease note that the `X-Search_after` response header value will continually change. That is, you will get a different `X-Search_after` value every time you specify a search. Don't hold on to a `X-Search_after` value; always parse the specific response you get from the service, then add that value to the \"search_after\" JSON property of your query to get the next page of events.\n\nYou will always need to do this procedure to get all the rows matching your query: Send a request, check the HTTP status code, then check to see if there are further rows, then execute more requests that match your first query but include each \"search_after\" value, until the response header ` X-Result-Count `is less than the page `X-Limit` size.\n\n__Note:__ The header always returns `X-Search_after` values, even when no further pages of data exist. You must compare `X-Result-Count` and `X-Limit` values to know if you're at the last page of data.\n\n## Sort\n\nBy default, the system responds with events in ascending timestamp order. To override this behavior, add the following to the request body, typically above the \"search_term\" section:\n\n### Example | Sort\n\n```json\n{\n \"service\": [\n \"radius\"\n ],\n \"start_time\": \"2020-01-01T14:00:00Z\",\n \"sort\": \"DESC\"\n}\n```\n\n\"sort\" is an optional field and is not required for a query. Nonsensical/missing sort directives cause the system to default to ascending order, silently. The \"sort\" directive is not case sensitive.\n\nThe sort order used by the system is included with the other HTTP response header metadata: `X-Sort:ASC`. If the system responds with a value that doesn't match your requested value, it's likely the system has defaulted back to an ASC sort on time.\n\n## Selecting only specific fields to return\n\nBy default, the system returns all available fields, for each object in the response array. Sometimes, for very large page sizes and result sets, returning less data can improve your download times.\n\nTo limit the fields that the system returns, list the fields in a \"fields\" array, and the system will return only those fields. \"fields\" is an optional field. If you specify an empty list, or a list containing no known fields, the system will respond with a 400 HTTP status.\n\n### Example | Fields\n\n```json\n{\n \"service\": [\n \"radius\"\n ],\n \"start_time\": \"2020-01-01T14:00:00Z\",\n \"fields\": [\n \"timestamp\",\n \"username\",\n \"client_ip\",\n \"success\"\n ]\n}\n```\n\nThe following query returns only the four mentioned fields, for each event result in the returned array of events.\n\n## End time\n\nLike \"start_time\",the system will optionally accept an \"end_time\" value to limit the amount of rows returned, to those between the two dates.\n\n### Example | End time\n\n```json\n{\n \"service\": [\n \"radius\"\n ],\n \"start_time\": \"2020-01-01T14:00:00Z\",\n \"end_time\": \"2020-02-01T14:00:00Z\"\n}\n```\n\nThe following query returns rows between the two specified dates. The field \"end_time\" is not required, but if present, must be specified in the \"search_term\" section, and must come after the value you specify for the \"start_time\" field.\n\n## Search\n\nThe \"search\\_term\" section also allows you to query events based on more advanced criteria. You group these criteria with a logical operator of \"and\" and \"or\" and one or more search terms. To match events with all of a multiple set of criteria, use the \"and\" list of terms. If you wish to match events with _any of a multiple set of criteria_, use the \"or\" list of terms.\n\nValid search terms are any event field returned by the system in the JSON object (\"username\", \"client_ip\", \"success\", etc)\n\n### Example Search | AND\n\n```json\n{\n \"service\": [\n \"radius\"\n ],\n \"start_time\": \"2020-01-01T14:00:00Z\",\n \"search_term\": {\n \"and\": [\n {\n \"username\": \"root\"\n },\n {\n \"client_ip\": \"1.2.3.4\"\n }\n ]\n }\n}\n```\n\nThe following query returns events with both \"username\" of \"root\" and with \"client_ip\" of \"1.2.3.4\"\n\nYou can add one or more field criteria in the \"and\" list. You cannot repeat a field name in the\n\nlist. The system will return events _matching all of the criteria_ in the list.\n\nThere is no system-imposed limit on the number of criteria in the list, however extreme complex searches may result in a HTTP 500 error.\n\n### Example Search | OR\n\n```json\n{\n \"service\": [\n \"radius\"\n ],\n \"start_time\": \"2020-01-01T14:00:00Z\",\n \"search_term\": {\n \"or\": [\n {\n \"username\": \"root\"\n },\n {\n \"client_ip\": \"1.2.3.4\"\n }\n ]\n }\n}\n```\n\nThe proceeding query returns any events that have either a \"username\" of \"root\" or a \"client_ip\" of \"1.2.3.4\". To specify multiple values for the same field, enclose them in an array (brackets).\n\n__Note:__ Field values are coerced to lowercase on insert, please use lowercase values in your search_terms.\n\n__Search Queries Not Supported__\nA majority of the Directory Insights attributes are searchable except for `\"changes\"`, \"user_agent\", and \"system_timestamp\".\n\n__Nested Object Event Data__\nYou may have noticed that the Directory Insights API returns event data that includes objects in one structure. For example, consider the following event data returned by the API:\n\n```json\n{\n \"error_message\": null,\n \"auth_type\": \"eap\",\n \"nas_mfa_state\": \"DISABLED\",\n \"eap_type\": \"MSCHAPv2\",\n \"outer\": {\n \"error_message\": null,\n \"eap_type\": \"PEAP\",\n \"username\": \"zezeye21\"\n },\n \"mfa\": false,\n \"mfa_meta\": {\n \"type\": \"none\"\n },\n \"success\": true,\n \"organization\": \"5dc058bc3f53f95e3972f03f\",\n \"client_ip\": \"209.235.170.66\",\n \"id\": \"ED0ED2C3-0524-3263-BE5B-68C02B70986E\",\n \"username\": \"zezeye21\",\n \"timestamp\": \"2019-12-12T20:15:15Z\"\n}\n```\n\nQueries (and field return lists) accept any of the top-level field names (such as `\"client_ip\"`and `\"username\"`), by default.\n\nIn the event above, you can see event data named \"outer\" that itself is a list of fields. To query one of these sub-fields, simply use a \"dot\" notation, specifying the parent (outer) field name, and the child field name. For example, specify the query:\n\n### Example | Nested searching\n\n```json\n{\n \"service\": [\n \"radius\"\n ],\n \"start_time\": \"2020-01-01T14:00:00Z\",\n \"search_term\": {\n \"and\": [\n {\n \"outer.eap_type\": \"PEAP\"\n }\n ]\n }\n}\n```\n\n...and the service will return only events with an `\"outer\"` field list containing an `\"eap_type\"` value of __`\"PEAP\"`__\nPlease note that you may use this parent-child dot notation anywhere event fields can be specified: and/or queries, and Field projection lists.\n\n## Advanced search: List values\n\nInstead of searching for a single value, you can also specify a list of values to search in the \"and\" and \"or\" criteria.\n\n### Example Advanced Search | AND\n\n```json\n{\n \"service\": [\n \"radius\"\n ],\n \"start_time\": \"2020-01-01T14:00:00Z\",\n \"search_term\": {\n \"and\": [\n {\n \"username\": [\n \"root\",\n \"admin\"\n ]\n }\n ]\n }\n}\n```\n\nThe following example returns any events that have a \"username\" of either \"root\" or \"admin\".\n\n### Example Advanced Search | OR\n\n```json\n{\n \"service\": [\n \"radius\"\n ],\n \"start_time\": \"2020-01-01T14:00:00Z\",\n \"search_term\": {\n \"or\": [\n {\n \"username\": [\n \"root\",\n \"admin\"\n ]\n },\n {\n \"client_ip\": [\n \"1.2.3.4\",\n \"2.3.4.5\"\n ]\n }\n ]\n }\n}\n```\n\nThe following example returns all events that have EITHER:\n\n1. a \"username\" of \"root\" or \"admin\"\n2. or a \"client_ip\" of \"1.2.3.4\" or \"2.3.4.5\"\n\nChanging the query to \"and\" the system would match documents with BOTH those criteria.\n\n__Note:__ JSON does not allow a term to be repeated. For example, you cannot request different values for the same field as in the example below\n\n```json\n{\n \"service\": [\n \"radius\"\n ],\n \"start_time\": \"2020-01-01T14:00:00Z\",\n \"search_term\": {\n \"or\": [\n {\n \"username\": \"root\"\n },\n {\n \"username\": \"admin\"\n }\n ]\n }\n}\n```\n\n## Advanced search: Compound Logic\n\nThe \"search_term\" section allows complex queries using compound logic with \"and\" and \"or\" logical operators. All of the content of both \"and\" and \"or\" should be comma-separated JSON objects, enclosed in a JSON array []\n\n### Example | Search for failed authentications of paul where (initiated_by.username = paul OR username = paul) AND success = false\n\n```json\n{\n \"service\": [\n \"radius\"\n ],\n \"start_time\": \"2020-01-01T14:00:00Z\",\n \"search_term\": {\n \"and\": [\n {\n \"success\": \"false\"\n },\n {\n \"or\": [\n {\n \"initiated_by.username\": \"paul\"\n },\n {\n \"username\": \"paul\"\n }\n ]\n }\n ]\n }\n}\n```\n\n# Schemas\n\n## Directory Attributes\n\n Field | Type | Example | Description |\n ------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |\n id | uuid | 30b03bc3-be76-4919-b341-f9b271a5777e | Unique id for the event |\n event_type | string | systemuser_update | Event type |\n timestamp | RFC3339 Timestamp | 2019-03-04T18:08:26Z | Timestamp of when the event occurred (UTC) |\n resource | object | `{\"type\": \"systemuser\",\"id\": \"5c86b7149fdce00001d38014\",\"username\": \"testexample\",\"recipient_email\": \"testexample@example.com\",\"email_type\": \"company}` | Resource that was changed or attempted the login |\n organization | keyword | 5a2af2a82cf2b0010053ea41 | Organization that the user belongs to |\n changes | Nested objects | `[{\"field\": \"lastname\",\"from\": \"0c7ee32b-345e-473e-a450-ebc7dddb0566\",\"to\": \"48163dd3-e9cf-44d3-b48a-438a0177e308\"}]` | List of changes made in the request. You cannot search on the contents of this field. |\n initiated_by | object | `{\"id\": \"5845d8f9c4894c85596c54f3\",\"type\": \"admin\",\"email\": \"user1@domain.com\",\"source\": \"jumpcloud:scim\",\"source_metadata\": {\"name\": \"okta\"}}` | Object that describes who initiated the request. |\n association | object | `{\"type\": \"admin\",\"id\": \"5c86b6cf9fdce00001d3800c\",\"email\": \"user1@domain.com\"}` | Object that describes a change in association, such as adding a user to a group. |\n client_ip | string | 10.1.2.3 | IP address the request came from |\n useragent | object | `{\"useragent\": {\"os\": \"Fedora\",\"minor\": \"0\",\"major\": \"71\",\"build\": \"\",\"name\": \"Firefox\",\"os_name\": \"Fedora\",\"device\": \"Other\"}` | User agent information for the browser that submitted the request. You cannot search on the contents of this field. |\n auth_method | string | session | Session = console, api-key = api-key |\n success | boolean | true | DeNotes if a login attempt was successful or not |\n mfa | boolean | true | DeNotes if mfa was used on an authentication attempt |\n mfa_meta | object | {\"type\":\"duo\"} | Object that contains meta data around mfa authentication such as the type of mfa. |\n geoip | object | `{\"geoip\": {\"timezone\": \"America/Los_Angeles\",\"continent_code\": \"NA\",\"region_code\": \"OR\",\"country_code\": \"US\",\"region_name\": \"Oregon\"}}` | Geo IP information for the ip address that made the request |\n provider | string | 5c86b6cf9fdce00001d3800c | The org id of the provider if the org is a provider org |\n service | string | directory | Which service the event originated from |\n auth_context | object | `{\"auth_methods\": {\"totp\": {\"success\": true},\"webauthn\": {\"success\": false},\"duo\": {\"success\": false},\"password\": {\"success\": true}},\"system\": {\"hostname\": \"my-host\",\"id\": \"5e90795a9de53959cf505121\",\"displayName\": \"My Computer\",\"os\": \"Microsoft Windows 10 Pro\",\"version\": \"10.0.18362\"},\"policies_applied\": [{\"name\": \"policyA\",\"id\": \"5e90795a9de53959cf505111\"},{\"name\": \"policyB\",\"id\": \"5e90795a9de53959cf505112\"}]}` | Object for authentication context including factors used, device information if cert was present, and policies that were applied. |\n\n## Software Attributes\n\n Name | Type | Example | Description |\n ---------- | ----------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------- |\n event_type | string | software_add, software_change, software_remove | Type of software event. |\n service | string | software | Name of the feature that emits events |\n Provider | string | 5c8fcfe0e7eb500001c71062 | Unique ID for the provider |\n org_id | string | 5c8fcfe0e7eb500001c71062 | Unique ID for the organization |\n system | object | `{\"systemId\": \"5c86b7149fdce00001d38014\",\"hostname\": \"my-host\",\"displayName\": \"My System\"}` | Object that describes the system program |\n timestamp | RFC3339 Timestamp | 2019-03-04T18:08:26Z | Timestamp of when the event occurred (UTC) |\n resource | object | `{\"type\": \"unknown\"}` | Object that describes the software resource |\n\n## MTP/MSP Events\n\n Field | Type | Example | Description |\n ------------ | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n service | string | directory | The service the event originated from. |\n event_type | string | admin_update | Examples of MTP events. admin_password_reset_request, admin_login_attempt, admin_lockout, admin_update, admin_create, admin_activated, admin_suspended, admin_password_change, organization_create, organization_update, provider_update |\n client_ip | string | 34.214.221.231 | The IP address the request came from. |\n resource | object | `{\"type\": \"admin\",\"id\": \"6154d26a4dea2b7ec773b133\",\"email\": \"mital.patel+stageadmin5@jumpcloud.com\"}` | Resource that was changed. |\n changes | list | `[{\"field\": \"lastname\",\"from\": \"\",\"to\": \"Edited\"}]` | List of changes made from the old record to the new record. You cannot search on the contents of this field. |\n timestamp | RFC3339 Timestamp | 2021-10-22T17:38:53.650Z | Timestamp of when the event occurred (UTC). |\n provider | string | 5e160715b7782848e073301e | The Org id of the provider if the org is a provider. |\n geoip | object | `{\"geoip\": {\"timezone\": \"America/Los_Angeles\",\"continent_code\": \"NA\",\"region_code\": \"OR\",\"country_code\": \"US\",\"region_name\": \"Oregon\",\"latitude\": \"45.8491\",\"longitude\": \"-119.7143\"}}` | Geo IP information for the ip address that made the request. |\n id | string | 5c8fcfe0e7eb500001c71062 | Unique ID for the event. |\n user_agent | object | `{\"user_agent\": {\"patch\": \"4472\",\"os\": \"Mac OS X\",\"minor\": \"0\",\"major\": \"91\",\"build\": \"\",\"os_minor\": \"15\",\"os_major\": \"10\",\"name\": \"Chrome\",\"os_name\": \"Mac OS X\",\"device\": \"Other\"}}` | User agent information for the browser that submitted the request. You cannot search on the contents of this field. |\n @version | integer | 1 | The schema version for the document object. |\n initiated_by | object | `{\"type\": \"admin\",\"id\": \"60dca2e6c6b18a68cc4093dc\",\"provider\": \"5e160715b7782848e073301e\",\"email\": \"mital.patel+stageadmin@jumpcloud.com\"}` | Object that describes who initiated the request. |\n auth_method | string | session | Session equals console and api-key equals api-key. |\n organization | string | 5c86b6cf9fdce00001d3800b | The Org associated with the event if it is present on the user, system user or on the request. Otherwise, the value will be null. |\n mfa | boolean | true | True means that Multi-Factor Authentication(MFA) was used on an authentication attempt and false means it wasn't. |\n\n## SSO Attributes\n\n Field | Type | Example | Description |\n ------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |\n id | uuid | 30b03bc3-be76-4919-b341-f9b271a5777e | Unique id for the event |\n event_type | string | sso_auth | Event type, for sso we only have sso_auth at this time |\n timestamp | RFC3339 Timestamp | 2019-03-04T18:08:26Z | Timestamp of when the event occurred (UTC) |\n initiated_by | object | `{\"type\": \"systemuser\",\"id\": \"5c86b7149fdce00001d38014\",\"username\": \"testexample\"}` | User who initiated the auth attempt. |\n organization | keyword | 5a2af2a82cf2b0010053ea41 | Organization that the user belongs to |\n application | object | `{\"id\": \"5c86b7469fdce00001d38016\",\"name\": \"zendesk\",\"sso_url\": \"https://sso.jumpcloud.com/saml2/zendesk\"}` | Information for the application that the sso_auth was initiated for |\n client_ip | string | 10.1.2.3 | IP address the request came from |\n useragent | object | `{\"useragent\": {\"os\": \"Fedora\",\"minor\": \"0\",\"major\": \"71\",\"build\": \"\",\"name\": \"Firefox\",\"os_name\": \"Fedora\",\"device\": \"Other\"}}` | User agent information for the browser that submitted the request |\n geoip | object | `{\"geoip\": {\"timezone\": \"America/Los_Angeles\",\"continent_code\": \"NA\",\"region_code\": \"OR\",\"country_code\": \"US\",\"region_name\": \"Oregon\"}}` | Geo IP information for the ip address that made the request |\n idp_initiated | bool | TRUE | True if the request was initiated from the Identity Provider (JumpCloud). False if the auth was initiated from the service provider. |\n service | string | sso | Which service the event originated from |\n\n## Radius Attributes\n\n Name | Type | Example | Description |\n ------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n id | string | 077ED0A8-1B5F-3EA3-8AAC-E3999451A46D | Unique ID for the event |\n nas_mfa_state | string | disabled, enabled, required, always | __Disabled__: No MFA required. __Enabled__: MFA is required if the user is configured for MFA. __Required__: MFA is required unless the user is excluded and not configured for MFA. __Always__: MFA always required |\n auth_type | string | pap | Authentication Type |\n eap_type | string | MSCHAPv2 | EAP Type |\n client_ip | string | 192.168.0.1 | IP address the request came from |\n Geoip | object | `{\"geoip\": {\"timezone\": \"America/Los_Angeles\",\"continent_code\": \"NA\",\"region_code\": \"OR\",\"country_code\": \"US\",\"region_name\": \"Oregon\"}}` | Geo IP information for the ip address that made the request |\n success | boolean | true or false | Whether the authentication succeeded or not |\n username | string | john.doe | Username provided for the auth attempt |\n organization | string | 5530392c3e2ab2b60c000047 | Org associated with the username and NAS. |\n timestamp | RFC3339 Timestamp | 2019-03-04T18:08:26Z | Timestamp of when the event occurred (UTC) |\n error_message | string | \"pap: Crypt digest does not match \\\\\"known good\\\\\" digest\" | |\n mfa | boolean | true or false | Whether MFA was supplied |\n mfa_meta | string | {\"type\":\"totp\"} | Information on the type of mfa |\n outer | object | `{\"outer\": {\"eap_type\": \"PEAP\",\"error_message\": null,\"username\": \"fguo\"}}` | Object for outer |\n outer:eap_type | string | peap | Outer eap type |\n outer:username | string | steve | Outer username |\n outer:error_message | string | \"eap_peap: The users session was previously rejected: returning reject (again.)\", \"eap: Failed continuing EAP PEAP (25) session. EAP sub-module failed\" | Outer error message |\n service | string | radius | Which service the event originated from |\n initiated_by | object | `{\"id\": \"5845d8f9c4894c85596c54f3\",\"type\": \"admin\",\"email\": \"user1@domain.com\"}` | Object that describes who initiated the request. |\n\n## System Attributes\n\n Name | Type | Example | Description |\n ---------------- | ----------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n timestamp | RFC3339 Timestamp | 2019-03-04T18:08:26Z | Timestamp of when the event occurred (UTC) |\n system_timestamp | RFC3339 Timestamp | 2019-04-09T05:01:18+09:30 | Local system time |\n id | string | 5c8fcfe0e7eb500001c71062 | Unique ID for the event |\n event_type | string | user_login | Event type |\n organization | string | 5c86b6cf9fdce00001d3800b | Org associated with the event |\n system | object | `{\"id\": \"5c86b7149fdce00001d38014\",\"hostname\": \"my-host\",\"displayName\": \"My System\"}` | Object that describes the system |\n message | string | User vagrant logged in from 10.0.2.2, process name: sshd | Log message associated with a login attempt |\n client_ip | string | 10.1.2.3 | IP address the request came from |\n src_ip | string | 10.0.2.2 | IP address the login request came from |\n username | string | vagrant | Username provided for the auth attempt |\n process_name | string | sshd | Process that initiated a login attempt |\n success | bool | TRUE | Whether a system authentication succeeded |\n provider | string | 5c86b6cf9fdce00001d3800b | The org id of the provider if the org is a provider |\n resource | object | `{\"type\": \"systemuser\",\"id\": \"5c86b7149fdce00001d38014\",\"username\": \"testexample\"}` | Object for the resource changed |\n changes | list | `[{\"field\": \"password\"}]` | List of changes made in the request. You cannot search on the contents of this field. |\n initiated_by | object | `{\"type\": \"systemuser\",\"id\": \"5c86b6cf9fdce00001d3800c\",\"username\": \"testuser\"}` | Object that describes who initiated the request. |\n service | string | systems | Which service the event originated from |\n windows_meta | object | `{\"elevated\": true,\"logon_type\": \"5\"}` | Information about windows authentications including if the login had elevated privileges and the logon type. Logon types: 2 Interactive, 3 Network, 4 Batch, 5 Service, 7 Unlock, 8 NetworkCleartext, 9 NewCredentials, 10 RemoteInteractive, 11 CachedInteractive |\n\n## LDAP Attributes\n\n Name | Type | Example | Description |\n ----------------- | ----------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n timestamp | RFC3339 Timestamp | 2019-03-04T18:08:26Z | Timestamp of when the event occurred (UTC) |\n connection_id | string | UhKgFeYIvbsh4so/f8z7xUnH0rDLk5Ph1n6XQnT08ds= | Unique id for every LDAP connection. |\n operation_number | integer | 0 | All operation requests and operation result pairs are given incremental operation numbers beginning with operation_number=0 to identify the distinct operations being performed. |\n event_type | string | ldap_bind | The type of LDAP event: bind or search. |\n dn | string | uid=adminR,ou=Users,o=57600aea6b8a769c6cef11ed,dc=jumpcloud,dc=com | Distinguished name (DN) provided for authentication. In this example we are authing user adminR in org 57600aea6b8a769c6cef11ed |\n auth_method | string | simple, sasl, or anonymous | Authentication method, 128 = simple, 163 = sasl, 0 = anonymous |\n mech | string | simple | The authentication method used. Either simple or SASL (we don't support SASL yet) |\n start_tls | boolean | false | The starttls protocol was used to open the LDAP connection. |\n tls_established | boolean | false | The LDAPS protocol was used to open the LDAP connection. |\n username | string | john.doe | Username provided for the auth attempt |\n organization | string | 5530392c3e2ab2b60c000047 | Org associated with the username and NAS. |\n success | boolean | true or false | Whether the authentication succeeded or not |\n error_code | integer | 10 | Result code |\n error_message | string | invalid DN | Optional error message |\n oid | string | 1.3.6.1.4.1.1466.20037 | LDAP object identifier. |\n base | string | ou=Users,o=55ddd95d90426433661ae1e0,dc=jumpcloud,dc=com | The base of the subtree in which the search is to be constrained. |\n scope | integer | 2 | The search scope. This specifies the portion of the target subtree that should be considered. Can be: base, only return the specified entry. singleLevel (1) only the immediate children of the entry are considered. |\n deref | integer | 0 | The alias dereferencing behavior, which indicates how the server should treat any aliases encountered while processing the search. |\n filter | string | (&(objectClass=sambaDomain)(sambaDomainName=workgroup)) | The filter criteria for the search with the scope. |\n attr | string | sambaDomainName sambaNextRid | A set of attributes to be returned to the client. |\n number_of_results | integer | 1 | Number of rows returned from the srch |\n service | string | ldap | Which service the event originated from |\n initiated_by | object | `{\"id\": \"5845d8f9c4894c85596c54f3\",\"type\": \"admin\",\"email\": \"user1@domain.com\"}` | Object that describes who initiated the request. |\n\n## MDM Attributes\n\n Name | Type | Example | Description |\n ------------------------ | ----------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |\n id | string | 5c8fcfe0e7eb500001c71062 | Unique ID for the event. |\n timestamp | RFC3339 Timestamp | 2019-03-04T18:08:26Z | Timestamp of when the event occurred (UTC) |\n organization | string | 5c86b6cf9fdce00001d3800b | Org associated with the event. |\n event_type | string | mdm_command_result | The type of MDM event. |\n mdm_type | string | apple | The type of MDM service. |\n device_object_id | string | 5ebeb092658f7304f48e2d84 | Unique ID for the device. |\n device_manager_object_id | string | 5e95d0a128b4f8666ef26b87 | Unique ID for the device manager. |\n command_uuid | string | a0325748-b432-42f6-b789-50b3924d64a4 | Unique ID for the command. |\n request_type | string | RestartDevice | The type of command. |\n command | object | `{\"request_type\": \"RestartDevice\"}` | The executed command. |\n status | string | Acknowledged | The command result: Acknowledged, Error, CommandFormatError, and Idle |\n error_chain | object | `[{\"error_code\": INT,\"error_domain\": STRING,\"localized_description\": STRING,\"us_english_description\": STRING}]` | Raw error details as reported by the MDM device. |\n @version | integer | 1 | The schema version for the document object. |\n service | string | mdm | Which service the event originated from |\n\n# Event Types\n\n## Directory - Object Events\n\n Event | Description |\n ----------------------- | ---------------------------------- |\n application_create | SAML application is created. |\n application_delete | SAML application is deleted. |\n application_update | SAML application is modified. |\n association_change | Resource bound/unbound to a group. |\n translation_rule_create | Attribute mapping is created. |\n translation_rule_delete | Attribute mapping is deleted. |\n group_create | Group is created. |\n group_delete | Group is deleted. |\n group_update | Group is modified. |\n notification_delete | Notification is closed. |\n organization_create | Organization is created. |\n organization_update | An organization is updated. |\n system_create | System is created. |\n system_delete | System is deleted. |\n system_update | System is updated. |\n radiusserver_create | RADIUS server is created. |\n radiusserver_delete | RADIUS server is deleted. |\n radiusserver_update | RADIUS server is updated. |\n\n## Directory - User and Admin Events\n\n Event | Description |\n ------------------------------- | ----------------------------------------------------- |\n admin_create | Admin is created. |\n admin_delete | Admin is deleted. |\n admin_login_attempt | Admin logs in success / failure. |\n admin_password_reset_request | Admin requests to resets their password |\n admin_update | An admin account is updated. |\n user_create | A user account is created. |\n user_delete | A user account is deleted. |\n user_lockout | A user account is locked out. |\n user_login_attempt | A user attempted to authenticate to user portal. |\n user_mfa_exclusion_expired | User's MFA enrollment expires. |\n user_password_expired | User's password expires. |\n user_password_reset_request | User requests to change their password. |\n user_password_warning_email | Password warning email is sent to user. |\n user_update | A user account is updated. |\n user_password_change | A user's password changed. |\n user_activated | A user account is activated. |\n user_activation_email | Activation email is sent to user |\n user_password_set | A user account moves out of pending status. |\n user_unlocked | A user account is unlocked. |\n user_suspended | A user account is suspended. |\n user_unsuspended | A user account is unsuspended. |\n user_suspension_schedule_create | A scheduled job to suspend a user account is created. |\n user_suspension_schedule_delete | A scheduled job to suspend a user account is deleted. |\n admin_password_change | An admin's password changed. |\n user_create_provision | User created in external application |\n user_update_provision | User updated in external application |\n user_delete_provision | User deleted in external application |\n user_admin_granted | Admin granted user admin sudo privileges on device(s) |\n user_admin_revoked | Admin revoked user admin sudo privileges on device(s) |\n\n## Directory - Command and Policy Events\n\n Event | Description |\n -------------------- | ---------------------------------- |\n command_create | Command is created. |\n command_delete | Command is deleted. |\n command_run | Command runs. |\n command_update | Command is modified. |\n commandresult_delete | Command result is deleted. |\n file_create | File is uploaded in a command. |\n file_delete | File is deleted in a command. |\n file_update | File is changed in a command. |\n policy_create | Policy is created. |\n policy_delete | Policy is deleted. |\n policy_update | Policy is modified. |\n authnpolicy_create | Conditional access policy created. |\n authnpolicy_delete | Conditional access policy deleted. |\n authpolicy_update | Conditional access policy updated. |\n iplist_create | IP address list created |\n iplist_delete | IP address list deleted |\n iplist_update | IP address list updated |\n\n## Directory - Integrations\n\n Event | Description |\n ----------------------- | -------------------------------------------- |\n activedirectory_create | Active Directory instance created. |\n activedirectory_delete | Active Directory instance deleted. |\n idsource_create | AD Bridge V1 created. |\n idsource_delete | AD Bridge v1 deleted. |\n idsource_update | AD Bridge V1 updated. |\n sambadomain_create | Enabling Samba for LDAP directory. |\n sambadomain_delete | Disabling/removing Samba for LDAP directory. |\n sambadomain_update | Updating Samba configuration. |\n workday_create | Workday directory created. |\n workday_delete | Workday directory deleted. |\n workday_update | Workday directory updated. |\n integration_activate | SCIM integration activated |\n integration_deactivate | SCIM integration deactivated |\n gsuite_directory_create | Gsuite directory created. |\n gsuite_directory_update | Gsuite directory updated. |\n gsuite_directory_delete | Gsuite directory deleted. |\n o365_directory_create | O365 directory created. |\n o365_directory_update | O365 directory updated. |\n o365_directory_delete | O365 directory deleted. |\n\n## Directory - MTP/MSP Events\n\n### MTP Events Overview\n\nMTP (multi-tenant portal) tracks administrator actions as events within\nthe MTP portal and allows MTPs to search for events across their managed\norganizations. Reports can be created that help you understand how your\nadministrators access and use the multi-tenant portal, and to view all\nevents across MTP client organizations centrally. Use the Directory\nInsights API to analyze the event data in these reports and to create\ncustom solutions tailored to your organization's specific needs.\n\nThe availability of the events data is governed by the JumpCloud data\nretention policies. For more information, see data retention policies.\n\n#### What are the MTP activity events?\n\nMTP provides the following types of events:\n\n Event | Description |\n ---------------------------- | ------------------------------------------------------------------------------------------------------------ |\n admin_activated | Created when admin unsuspends an admin. |\n admin_create | Created when admin creates an admin. |\n admin_delete | Created when admin deletes a user or bulk deletes users. |\n admin_lockout | Created when an admin has multiple login failures into MTP portal. |\n admin_login_attempt | Created when an admin logs into the MTP portal or admin launches an child org. |\n admin_password_reset_request | Created when an admin resets their password. |\n admin_suspended | Created when admin suspends an admin. |\n admin_update | Created when admin enables/disables TOTP, changes contact info, role for an admin or admin updates an admin. |\n organization_create | Created when an admin creates an organization. |\n organization_update | Created when admin updates org name. |\n provider_update | Created when admin changes billing info. |\n\n## RADIUS Events\n\n Event | Description |\n ----------- | ----------------------------- |\n radius_auth | User authenticates to radius. |\n\n## SSO Events\n\n Event | Description |\n -------- | ----------------------------------------- |\n sso_auth | User authenticates to an SSO application. |\n\n## System Events\n\n Event | Description |\n ---------------------- | -------------------------------------------------- |\n login_attempt | User authenticates to a system. |\n system_fde_key_update | A system's file disk encryption key updates. |\n user_password_change | User password changes on a system. |\n user_lockout | User is locked out of a system. |\n system_fde_key_decrypt | A device's file disk encryption key was decrypted. |\n\n## LDAP Events\n\n Event | Description |\n ----------- | ----------------------------------------------- |\n ldap_bind | User authenticates to an LDAP directory server. |\n ldap_search | LDAP search operation performed. |\n\n## MDM Events\n\n Event | Description |\n ------------------ | ------------------- |\n mdm_command_result | MDM command result. |", "title": "Directory Insights API", "contact": { "email": "support@jumpcloud.com" }, "version": "1.0" }, "host": "api.jumpcloud.com", "basePath": "/insights/directory/v1", "paths": { "/events": { "post": { "security": [ { "x-api-key": [], "x-org-id": [] } ], "description": "Query the API for Directory Insights events\n#### Sample Request\n```\ncurl -X POST 'https://api.jumpcloud.com/insights/directory/v1/events' -H 'Content-Type: application/json' -H 'x-api-key: {API_KEY}' --data '{\"service\": [\"all\"], \"start_time\": \"2021-07-14T23:00:00Z\", \"end_time\": \"2021-07-28T14:00:00Z\", \"sort\": \"DESC\", \"fields\": [\"timestamp\", \"event_type\", \"initiated_by\", \"success\", \"client_ip\", \"provider\", \"organization\"]}'\n```", "consumes": [ "application/json" ], "produces": [ "application/json" ], "summary": "Query Events", "operationId": "Event_Get", "parameters": [ { "description": "JSON event query body", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/EventQuery" } } ], "responses": { "200": { "description": "Array of Directory Insights events JSON objects", "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "x-codeSamples": [ { "lang": "Shell", "source": "curl --request POST \\\n --url https://api.jumpcloud.com/insights/directory/v1/events \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --header 'x-api-key: REPLACE_KEY_VALUE' \\\n --data '{\"end_time\":\"2019-08-24T14:15:22Z\",\"service\":[\"all\"],\"start_time\":\"2019-08-24T14:15:22Z\",\"fields\":[\"string\"],\"limit\":0,\"search_after\":[{}],\"search_term\":{\"and\":{},\"or\":{}},\"sort\":\"string\"}'" }, { "lang": "Python", "source": "import requests\n\nurl = \"https://api.jumpcloud.com/insights/directory/v1/events\"\n\npayload = {\n \"end_time\": \"2019-08-24T14:15:22Z\",\n \"service\": [\"all\"],\n \"start_time\": \"2019-08-24T14:15:22Z\",\n \"fields\": [\"string\"],\n \"limit\": 0,\n \"search_after\": [{}],\n \"search_term\": {\n \"and\": {},\n \"or\": {}\n },\n \"sort\": \"string\"\n}\nheaders = {\n \"accept\": \"application/json\",\n \"x-api-key\": \"REPLACE_KEY_VALUE\",\n \"content-type\": \"application/json\"\n}\n\nresponse = requests.request(\"POST\", url, json=payload, headers=headers)\n\nprint(response.text)" }, { "lang": "Powershell", "source": "$headers=@{}\n$headers.Add(\"accept\", \"application/json\")\n$headers.Add(\"x-api-key\", \"REPLACE_KEY_VALUE\")\n$headers.Add(\"content-type\", \"application/json\")\n$response = Invoke-RestMethod -Uri 'https://api.jumpcloud.com/insights/directory/v1/events' -Method POST -Headers $headers -ContentType 'application/json' -Body '{\"end_time\":\"2019-08-24T14:15:22Z\",\"service\":[\"all\"],\"start_time\":\"2019-08-24T14:15:22Z\",\"fields\":[\"string\"],\"limit\":0,\"search_after\":[{}],\"search_term\":{\"and\":{},\"or\":{}},\"sort\":\"string\"}'" } ] } }, "/events/count": { "post": { "security": [ { "x-api-key": [], "x-org-id": [] } ], "description": "Query the API for a count of matching events\n#### Sample Request\n```\ncurl -X POST 'https://api.jumpcloud.com/insights/directory/v1/events/count' -H 'Content-Type: application/json' -H 'x-api-key: {API_KEY}' --data '{\"service\": [\"all\"], \"start_time\": \"2021-07-14T23:00:00Z\", \"end_time\": \"2021-07-28T14:00:00Z\", \"sort\": \"DESC\", \"fields\": [\"timestamp\", \"event_type\", \"initiated_by\", \"success\", \"client_ip\", \"provider\", \"organization\"]}'\n```", "consumes": [ "application/json" ], "produces": [ "application/json" ], "summary": "Count Events", "operationId": "EventCount_Get", "parameters": [ { "description": "JSON event query body", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/EventQuery" } } ], "responses": { "200": { "description": "Count of matching event rows", "schema": { "$ref": "#/definitions/EventCount" } } }, "x-codeSamples": [ { "lang": "Shell", "source": "curl --request POST \\\n --url https://api.jumpcloud.com/insights/directory/v1/events/count \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --header 'x-api-key: REPLACE_KEY_VALUE' \\\n --data '{\"end_time\":\"2019-08-24T14:15:22Z\",\"service\":[\"all\"],\"start_time\":\"2019-08-24T14:15:22Z\",\"fields\":[\"string\"],\"limit\":0,\"search_after\":[{}],\"search_term\":{\"and\":{},\"or\":{}},\"sort\":\"string\"}'" }, { "lang": "Python", "source": "import requests\n\nurl = \"https://api.jumpcloud.com/insights/directory/v1/events/count\"\n\npayload = {\n \"end_time\": \"2019-08-24T14:15:22Z\",\n \"service\": [\"all\"],\n \"start_time\": \"2019-08-24T14:15:22Z\",\n \"fields\": [\"string\"],\n \"limit\": 0,\n \"search_after\": [{}],\n \"search_term\": {\n \"and\": {},\n \"or\": {}\n },\n \"sort\": \"string\"\n}\nheaders = {\n \"accept\": \"application/json\",\n \"x-api-key\": \"REPLACE_KEY_VALUE\",\n \"content-type\": \"application/json\"\n}\n\nresponse = requests.request(\"POST\", url, json=payload, headers=headers)\n\nprint(response.text)" }, { "lang": "Powershell", "source": "$headers=@{}\n$headers.Add(\"accept\", \"application/json\")\n$headers.Add(\"x-api-key\", \"REPLACE_KEY_VALUE\")\n$headers.Add(\"content-type\", \"application/json\")\n$response = Invoke-RestMethod -Uri 'https://api.jumpcloud.com/insights/directory/v1/events/count' -Method POST -Headers $headers -ContentType 'application/json' -Body '{\"end_time\":\"2019-08-24T14:15:22Z\",\"service\":[\"all\"],\"start_time\":\"2019-08-24T14:15:22Z\",\"fields\":[\"string\"],\"limit\":0,\"search_after\":[{}],\"search_term\":{\"and\":{},\"or\":{}},\"sort\":\"string\"}'" } ] } }, "/events/distinct": { "post": { "security": [ { "x-api-key": [], "x-org-id": [] } ], "description": "Query the API for a list of distinct values for a field\n#### Sample Request\n```\ncurl -X POST 'https://api.jumpcloud.com/insights/directory/v1/events/distinct' -H 'Content-Type: application/json' -H 'x-api-key: {API_KEY}' --data '{\"service\": [\"all\"], \"start_time\": \"2021-07-14T23:00:00Z\", \"end_time\": \"2021-07-28T14:00:00Z\", \"sort\": \"DESC\", \"field\": \"event_type\"}'\n```", "consumes": [ "application/json" ], "produces": [ "application/json" ], "summary": "Query event distinct field values", "operationId": "EventDistinct_Get", "parameters": [ { "description": "JSON event distinct query body", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/EventDistinctQuery" } } ], "responses": { "200": { "description": "List of distinct field values", "schema": { "$ref": "#/definitions/EventCount" } } }, "x-codeSamples": [ { "lang": "Shell", "source": "curl --request POST \\\n --url https://api.jumpcloud.com/insights/directory/v1/events/distinct \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --header 'x-api-key: REPLACE_KEY_VALUE' \\\n --data '{\"end_time\":\"2019-08-24T14:15:22Z\",\"service\":[\"all\"],\"start_time\":\"2019-08-24T14:15:22Z\",\"field\":\"string\",\"search_term\":{\"and\":{},\"or\":{}}}'" }, { "lang": "Python", "source": "import requests\n\nurl = \"https://api.jumpcloud.com/insights/directory/v1/events/distinct\"\n\npayload = {\n \"end_time\": \"2019-08-24T14:15:22Z\",\n \"service\": [\"all\"],\n \"start_time\": \"2019-08-24T14:15:22Z\",\n \"field\": \"string\",\n \"search_term\": {\n \"and\": {},\n \"or\": {}\n }\n}\nheaders = {\n \"accept\": \"application/json\",\n \"x-api-key\": \"REPLACE_KEY_VALUE\",\n \"content-type\": \"application/json\"\n}\n\nresponse = requests.request(\"POST\", url, json=payload, headers=headers)\n\nprint(response.text)" }, { "lang": "Powershell", "source": "$headers=@{}\n$headers.Add(\"accept\", \"application/json\")\n$headers.Add(\"x-api-key\", \"REPLACE_KEY_VALUE\")\n$headers.Add(\"content-type\", \"application/json\")\n$response = Invoke-RestMethod -Uri 'https://api.jumpcloud.com/insights/directory/v1/events/distinct' -Method POST -Headers $headers -ContentType 'application/json' -Body '{\"end_time\":\"2019-08-24T14:15:22Z\",\"service\":[\"all\"],\"start_time\":\"2019-08-24T14:15:22Z\",\"field\":\"string\",\"search_term\":{\"and\":{},\"or\":{}}}'" } ] } }, "/events/interval": { "post": { "security": [ { "x-api-key": [], "x-org-id": [] } ], "description": "Query the API for a list of counts by time interval\n#### Sample Request\n```\ncurl -X POST 'https://api.jumpcloud.com/insights/directory/v1/events/interval' -H 'Content-Type: application/json' -H 'x-api-key: {API_KEY}' --data '{\"service\": [\"all\"], \"start_time\": \"2021-07-14T23:00:00Z\", \"end_time\": \"2021-07-28T14:00:00Z\", \"timezone\": \"-0500\", \"interval_unit\": \"h\", \"interval_value\": \"2\"}'\n```", "consumes": [ "application/json" ], "produces": [ "application/json" ], "summary": "Query event counts by bucketed by a time interval", "operationId": "EventInterval_Get", "parameters": [ { "description": "JSON event interval query body", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/EventIntervalQuery" } } ], "responses": { "200": { "description": "List of bucketed event counts", "schema": { "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "doc_count": { "type": "integer" }, "key": { "type": "integer" }, "key_as_string": { "type": "string" } } } } } } } }, "x-codeSamples": [ { "lang": "Shell", "source": "curl --request POST \\\n --url https://api.jumpcloud.com/insights/directory/v1/events/interval \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --header 'x-api-key: REPLACE_KEY_VALUE' \\\n --data '{\"end_time\":\"2019-08-24T14:15:22Z\",\"service\":[\"all\"],\"start_time\":\"2019-08-24T14:15:22Z\",\"interval_unit\":\"s\",\"interval_value\":\"string\",\"search_term\":{\"and\":{},\"or\":{}},\"timezone\":\"string\"}'" }, { "lang": "Python", "source": "import requests\n\nurl = \"https://api.jumpcloud.com/insights/directory/v1/events/interval\"\n\npayload = {\n \"end_time\": \"2019-08-24T14:15:22Z\",\n \"service\": [\"all\"],\n \"start_time\": \"2019-08-24T14:15:22Z\",\n \"interval_unit\": \"s\",\n \"interval_value\": \"string\",\n \"search_term\": {\n \"and\": {},\n \"or\": {}\n },\n \"timezone\": \"string\"\n}\nheaders = {\n \"accept\": \"application/json\",\n \"x-api-key\": \"REPLACE_KEY_VALUE\",\n \"content-type\": \"application/json\"\n}\n\nresponse = requests.request(\"POST\", url, json=payload, headers=headers)\n\nprint(response.text)" }, { "lang": "Powershell", "source": "$headers=@{}\n$headers.Add(\"accept\", \"application/json\")\n$headers.Add(\"x-api-key\", \"REPLACE_KEY_VALUE\")\n$headers.Add(\"content-type\", \"application/json\")\n$response = Invoke-RestMethod -Uri 'https://api.jumpcloud.com/insights/directory/v1/events/interval' -Method POST -Headers $headers -ContentType 'application/json' -Body '{\"end_time\":\"2019-08-24T14:15:22Z\",\"service\":[\"all\"],\"start_time\":\"2019-08-24T14:15:22Z\",\"interval_unit\":\"s\",\"interval_value\":\"string\",\"search_term\":{\"and\":{},\"or\":{}},\"timezone\":\"string\"}'" } ] } } }, "definitions": { "EventCount": { "description": "EventCount JSON struct with count of matching events", "type": "object", "properties": { "count": { "type": "integer", "format": "int64", "x-go-name": "Count" } } }, "EventDistinctQuery": { "description": "EventDistinctQuery is the users' command to search our auth logs for distinct values of the specified field", "allOf": [ { "$ref": "#/definitions/EventServiceTimeQuery" }, { "type": "object", "required": [ "field" ], "properties": { "field": { "description": "field is what they wish to query on", "type": "string", "x-go-name": "Field" }, "search_term": { "$ref": "#/definitions/SearchTerm" } } } ] }, "EventIntervalQuery": { "description": "EventIntervalQuery is the users' command to search our auth logs for bucketed counts of values of the specified field", "allOf": [ { "$ref": "#/definitions/EventServiceTimeQuery" }, { "type": "object", "required": [ "interval_unit" ], "properties": { "interval_unit": { "type": "string", "enum": [ "s", "m", "h", "d", "w" ], "x-go-name": "IntervalUnit" }, "interval_value": { "description": "Interval Value. This specifies how many units you want to bucket the event counts by", "type": "string", "x-go-name": "IntervalValue" }, "search_term": { "$ref": "#/definitions/SearchTerm" }, "timezone": { "description": "TimeZone. Specify the timezone in which the user is in\noptional", "type": "string", "x-go-name": "TimeZone" } } } ] }, "EventQuery": { "description": "EventQuery is the users' command to search our auth logs", "allOf": [ { "$ref": "#/definitions/EventServiceTimeQuery" }, { "type": "object", "properties": { "fields": { "description": "optional list of fields to return from query", "type": "array", "items": { "type": "string" }, "x-go-name": "Projection" }, "limit": { "description": "Max number of rows to return", "type": "integer", "format": "int64", "x-go-name": "Limit" }, "search_after": { "description": "Specific query to search after, see x-* response headers for next values", "type": "array", "items": { "type": "string" }, "x-go-name": "SearchAfter" }, "search_term": { "$ref": "#/definitions/SearchTerm" }, "sort": { "description": "ASC or DESC order for timestamp", "type": "string", "x-go-name": "Sort" } } } ] }, "EventServiceTimeQuery": { "description": "EventServiceTimeQuery is the base struct for most event queries\nit includes the minimum-required fields of service and start/end times", "type": "object", "required": [ "service", "start_time" ], "properties": { "end_time": { "description": "optional query end time, UTC in RFC3339 format", "type": "string", "format": "date-time", "x-go-name": "EndTime" }, "service": { "description": "service name to query.", "type": "array", "items": { "type": "string", "enum": [ "all", "systems", "radius", "sso", "directory", "ldap", "mdm" ] }, "x-go-name": "Service" }, "start_time": { "description": "query start time, UTC in RFC3339 format", "type": "string", "format": "date-time", "x-go-name": "StartTime" } } }, "SearchTerm": { "description": "SearchTerm is the filter portion of the query\nit contains only one of 'and' or 'or' conjunction maps", "type": "object", "properties": { "and": { "$ref": "#/definitions/TermConjunction" }, "or": { "$ref": "#/definitions/TermConjunction" } } }, "TermConjunction": { "description": "TermConjunction represents a conjunction (and/or)\nNOTE: the validator limits what the operator can be, not the object\nfor future-proof-ness\nand a list of sub-values", "type": "object", "additionalProperties": true } }, "securityDefinitions": { "x-api-key": { "type": "apiKey", "name": "x-api-key", "in": "header" }, "x-org-id": { "type": "apiKey", "name": "x-org-id", "in": "header" } } } |