Cases API
Who is this article for?
Incydr, yes.
CrashPlan for Enterprise, no.
Code42 for Enterprise, no.
CrashPlan for Small Business, no.
This article applies to Code42 cloud environments.
Overview
This article explains how to use the Code42 API to interact with Cases.
The examples in this article use curl, but the concepts apply to any tool you choose for interacting with the Code42 API.
Cases API details
- United States
- If you sign in to the Code42 console at https://console.us.code42.com/console, use: https://east-cases.us.code42.com
- If you sign in to the Code42 console at https://www.crashplan.com/console, use: https://default-cases.prod.ffs.us2.code42.com
- Code42 federal environment: If you sign in to the Code42 console at https://console.gov.code42.com/console, use: https://default-cases.gov.code42.com
- Ireland: https://default-cases.ie.code42.com
- United States:
- Ireland: https://default-cases.ie.code42.com/swagger-ui.html#/Cases
Authentication
Authentication tokens are required in the header of all requests. To obtain an authentication token, use your Code42 administrator credentials to submit a GET
request to:
- United States:
- If you sign in to the Code42 console at https://console.us.code42.com/console, use:
https://console.us.code42.com/c42api/v3/auth/jwt?useBody=true - If you sign in to the Code42 console at https://www.crashplan.com/console, use:
https://www.crashplan.com/c42api/v3/auth/jwt?useBody=true - If you sign in to the Code42 console for the Code42 federal environment at https://console.gov.code42.com/console, use:
https://console.gov.code42.com/c42api/v3/auth/jwt?useBody=true
- If you sign in to the Code42 console at https://console.us.code42.com/console, use:
- Ireland: https://console.ie.code42.com/c42api/v3/auth/jwt?useBody=true
For example:
curl -X GET -u "admin@example.com
" -H "Accept: application/json" "https://console.us.code42.com/c42api/v3/auth/jwt?useBody=true"
If your organization uses two-factor authentication for local users, you must also include a totp-auth header value containing the Time-based One-Time Password (TOTP) supplied by the Google Authenticator mobile app. The example below includes a TOTP value of 424242.
curl -X GET -u "admin@example.com
" -H "totp-auth: 424242" "Accept: application/json" "https://console.us.code42.com/c42api/v3/auth/jwt?useBody=true"
A successful request returns an authentication token. For example:
{ "v3_user_token": "eyJjdHkiOiJKV1QiLCJlbmMiOiJBMTI4R0NNIiwiZXhwIjoiMjAxOC0wNC0zMFQyMTo0MDoyNy4xMDZaIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.0H-4bl43zA3cIE5D3o_8vZzJIUgtJt64mZbimNa2TNha761RgVBFaTfttMODXF1ntLUTHl-rD0JuHEAMrIxjpnaODictPizrDVeTA1PgkPrsKot9jp6D7uTEC1Y56qHS1qjP6WHQBpv6ADBfrAfePX3NnwkA5a1I8pB88kSWc1MXZ4uMt-rFcNtlLLPVfwtEXHyNG_bxYJOOn28y2ysJGSBD_Xx1-uK4zKvjWwXfVQG581TntFPy0LamJfJ7IM4wOIG-QrKeV796fJAaHBxNfOe4UWC8WeNcDEvgNZvOPchWTHY4l66OaOjHNeEkoKkxvc35j4V_QpYxe6GXRYK4NA.TJXe9M6goiZbw-tr.y0lUTHHkHU5tRS7bWI8jntMLcxv0HajXTXquV62IG4400i7wi0YSX-6vpsXVgivzztxnPaukgUsLavhZ8-wCiMdEkut4GfijTlDAM_tfmJyZG6Cn5GKIJgSCENrR1JTxvC6dhTvHc41p6T3jXqBWikoJwD9z9Ec3u-OhM3gotQZUfCq0rR8T043RZSN9-0TpxhpPUEUAS6rkAI07QP08l_nUqdQTsNF0Tafe1yfPTYJabkslHhYMlLRYuXwhWr_39h5BY89ud0cW_OyUtjzz83m9iGxv6sba9VBIb2Y95ipXLu6Ie-5wz8zivfjizX6ZQatp5Ep4UZxzsMdqD9j0BFXkXQZuITJLtKfmUX-FZYR8utNrbwtt8u2tvNUK8Ix4Fwa3bWPxlkwrhOdz70M-mxluxpR6EKSrf8xwHagMcahzVPcW5NVL2khr4MwMUKyRV69dAdGiaTKh2rd52znA0aE3OCtelnBrBn4rls0KX71_qZEAdPaLyyqZ4VaurWUfl35zSi2LW_a3-TebgIebHZxC-MxvFEH4DQq6gJDdoX92_YEYEn4tO_dhUTlD0CZ9HhT39XFrO9MBe4DoDzG-Iql_A-nhmCyOrRmQvUlR72XpHVFQQx3X6tqdPxFocgDh5z03-kLB4SjznQSlzJNbzl_knXTBGopoFLn3WHvjX8q327Vmwx1hjrQnO8Eg5rJMoXTJCMEEOkMyjkbFeEzEhTf2jcvvAlnNnxdtjb1Zo05RWwMsPwwHAgGr-0mm-ungNjIGW0MyMTZtK0StP1uRqfI1Q6ghqnGZxEZN_0fvsVlsz4u9A1eBYRE0xzg8p-0g62nAQ8GftpYaUoymgqbL2WCL15r38emLklXSruztosGU4Dtusg4JHEhYPxO4ieqeBu6FLX9fPSA_y3zmd_AEjW40-_6zC3quPYJwytaEIwVH6phtfa2phsOLLw-U-b2QY09-d27YirIjgNRZ7rO4GF3iX8hW3LfFIWj0WKA5HGtGHg.JzHVCE8zfy1qRBf__rhchA" }
- Use this authentication token in your search requests (see sample use cases below).
- Authentication tokens expire after one hour.
- You must have credentials for a Code42 user with either the Customer Cloud Admin or Security Center User role.
- The example above only applies to users who authenticate locally with Code42. Single sign-on (SSO) users must also complete SAML authentication with their SSO provider. If you need assistance with this process, contact your SSO provider.
- The URL to obtain the authentication token is different than the URL used to query Cases data.
Request parameters
In the sample use cases, items formatted as <value>
represent values you need to customize for your specific request. See below for steps to obtain these values. Do not include the brackets in the request.
- Replace
<Base_URL>
with the address of your Code42 environment. - Replace
<token>
with the authentication token obtained above.
- Replace
<case number>
with the number of the case you want to view or modify. There are two ways to obtain the case number:- Use the Return list of cases filtered by status request below to return a list of cases. The case number is the
number
field in the response. - From the Code42 console:
- Select Cases.
- Select a case.
- Select the Case Details tab.
- Note the Case ID.
- Use the Return list of cases filtered by status request below to return a list of cases. The case number is the
- Replace
<eventId>
with a specific event id string. To obtain the event id, either:- Use the Forensic Search API to search for file events and obtain the value of the
eventId
parameter. - Use the Return events associated with a case request below to return events for a case and note the
eventId
. (Note: The same event can be included in multiple cases, but duplicate events are not allowed in the same case.)
- Use the Forensic Search API to search for file events and obtain the value of the
- Replace
<status>
with either:OPEN
to keep the case active and editable.CLOSED
to resolve the case. Closed cases cannot be re-opened or modified.
- Replace
<subject User UID>
with the User UID of the person being investigated in the case. - Replace
<assignee User UID>
with the User UID of the security analyst or administrator assigned to investigate the case.
Sample use cases
Create a case
Only the name field is required. To leave a field blank, supply the value null
.
curl -X POST '<Base URL>
/api/v1/case' -H 'content-type: application/json' -H 'authorization: Bearer<token>
' -d '{ "name": "Sample case name", "description": "Sample description", "findings": "Sample findings", "subject": null, "assignee": null }'
{ "number": 1, "name": "Sample case name", "createdAt": "2020-10-27T15:16:05.369203Z", "updatedAt": "2020-10-27T15:16:05.369203Z", "description": "Sample description", "findings": "Sample findings", "subject": null, "subjectUsername": null, "status": "OPEN", "assignee": null, "assigneeUsername": null, "createdByUserUid": "806150685834341101", "createdByUsername": "05c28ad3-7eca-4d99-8bb7-a5d0995806c8", "lastModifiedByUserUid": "806150685834341101", "lastModifiedByUsername": "05c28ad3-7eca-4d99-8bb7-a5d0995806c8" }
Update an existing case
Before updating a case, perform a GET
request for that case number to obtain all existing values. For example:
curl -X GET '<Base URL>
/api/v1/case/<case number>
' -H 'content-type: application/json' -H 'authorization: Bearer<token>
'
Resubmit all values in the sample
PUT
command below, even if they're not changing. If you don't send an explicit value for each of these fields, they will be updated to null
.curl -X PUT '<Base URL>
/api/v1/case/<case number>
' -H 'content-type: application/json' -H 'authorization: Bearer<token>
' -d '{ "name": "<updated case name>
", "description": "<updated description>
", "findings": "<updated findings>
", "subject":<subject user UID>
, "assignee":<assignee user UID>
, "status": "<status>
" }'
{ "number": 1, "name": "Updated name", "createdAt": "2020-10-27T15:16:05.369203Z", "updatedAt": "2020-10-27T15:20:26.311894Z", "description": "Updated description", "findings": "Updated findings", "subject": 421380797518239242 "subjectUsername": casey@example.com, "status": "OPEN", "assignee": 273411254592236331, "assigneeUsername": admin@example.com, "createdByUserUid": "806150685834341101", "createdByUsername": "05c28ad3-7eca-4d99-8bb7-a5d0995806c8", "lastModifiedByUserUid": "806150685834341101", "lastModifiedByUsername": "05c28ad3-7eca-4d99-8bb7-a5d0995806c8" }
Add events to a case
curl -X POST '<Base URL>
/api/v1/case/<case_number>
/fileevent/<eventId>
' -H 'content-type: application/json' -H 'authorization: Bearer<token>
'
None (204 on success)
Return events associated with a case
curl -X GET '<Base URL>
/api/v1/case/<case_number>
/fileevent' -H 'content-type: application/json' -H 'authorization: Bearer<token>
'
{ "events": [ { "eventId": "734430974935_09970279-be77-4cd1-ba08-19d958969832", "eventTimestamp": "2020-10-26T18:56:04.661Z", "exposure": [ "SharedToDomain", "OutsideTrustedDomains" ], "fileName": "Products.png", "filePath": null } ] }
Return list of cases filtered by status
The sample below filters for open cases. To filter for closed cases, change the query parameter to ?status=CLOSED
. Other parameters that support filtering include: assignee
, createdAt
, isAssigned
, lastModifiedBy
, name
, subject
, and updatedAt
.
curl -X GET '<Base URL>
/api/v1/case?status=OPEN
' -H 'content-type: application/json' -H 'authorization: Bearer<token>
'
{ "cases": [ { "number": 1, "name": "Example Case", "createdAt": "2020-10-27T15:16:05.369203Z", "updatedAt": "2020-10-27T15:20:26.311894Z", "subject": null, "subjectUsername": null, "status": "OPEN", "assignee": null, "assigneeUsername": null, "createdByUserUid": "806150685834341101", "createdByUsername": "05c28ad3-7eca-4d99-8bb7-a5d0995806c8", "lastModifiedByUserUid": "806150685834341101", "lastModifiedByUsername": "05c28ad3-7eca-4d99-8bb7-a5d0995806c8" } ], "totalCount": 1 }
Export a case
There are two options for exporting cases:
- Case summary: Exports a PDF with the case subject, details, and findings. Detailed file activity is not included.
- File activity: Exports a CSV file with extensive file metadata details for all events in this case. For field definitions, see the Forensic Search event details.
- Use the
-o <sample_export.csv>
argument to specify a unique filename. Update the filename as appropriate for your request. Do not include the brackets in the request. - Use the
-O
argument (capital "O") to automatically name the file. This is not recommended if you need to export more than one file, because this method uses the same filename for each export and therefore overwrites the previous file. - Files are saved in the directory from which you issue the curl request in the command line. For example, in the command prompt
COMPUTER:~ clyde.bailey$ curl -X GET...
the file is saved in the Users/clyde.bailey directory on the device that issued the request.
Case summary PDF
curl -X GET '<Base URL>
/api/v1/case/<case number>
/export' -o<sample_export.pdf>
-H 'authorization: Bearer<token>
'
% Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 1618 0 1618 0 0 2528 0 --:--:-- --:--:-- --:--:-- 2524
The PDF is saved to your device.
File activity CSV
curl -X GET '<Base URL>
/api/v1/case/<case number>
/fileevent/export' -o<sample_export.csv>
-H 'authorization: Bearer<token>
'
% Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 3771 0 3771 0 0 6843 0 --:--:-- --:--:-- --:--:-- 6843
The CSV is saved to your device.