Security Audits - Huddle/huddle-apis GitHub Wiki

Summary

Company managers and admins are able to view and export security audits related to login/logout actions of all members in their company.

Operations

Retrieve the security audits

Request

GET identity/companies/{companyId}/securityaudits?page={page}
Accept: application/vnd.huddle.data+json
Authorization: OAuth2 frootymcnooty/vonbootycherooty

Response

HTTP/1.1 200 OK
Content-Type: application/json

{"security_audits":
 [{
  "email":"[email protected]",
  "ip_address":"127.0.0.1", 
  "client_id":"my.huddle",
  "type":"SecurityAuditType",
  "timestamp":"Wed, 21 Jun 2017 11:01:27 GMT"
  },
  ....,
  "links":[links to self/first/next/previous/last page]
}

Note: The api supports pagination which provides links to the first, next, previous and last page of the retrieved results with the page size set to 100. If the page is not provided in the request it's by default set to 1.

Link relations

Name Description Methods
self The URI of the cuurent page of security audits. GET
next The URI of the next page of security audits. GET
prev The URI of the previous page of security audits. GET
first The URI of the first page of security audits. GET
last The URI of the last page of security audits. GET

The 'prev' and 'first' link is not present on the first page of security audits.

The 'next' link is not present on the last page of security audits.

No links (except the self link) are present if there is only a single page.

Other Responses

Case Response
Invalid page 400 Bad Request
Invalid authorization token 401 Unauthorized
Not a manager of company or an admin 403 Forbidden
Requested page does not exist (greater than last page) 404 Not Found

Export all security audits of a Company to a CSV file

This resource supports the creation of a CSV file containing all security audits of a company. As this can take some time, it is treated as an asynchronous process.

A successful POST will initiate this process and return a 202 Accepted response containing a link header with a URI to GET the progress of the action.

Request

POST identity/companies/{companyId}/securityaudits
Accept: application/vnd.huddle.data+json
Authorization: OAuth2 frootymcnooty/vonbootycherooty

Response

HTTP/1.1 202 Accepted
Content-Type: application/json

{
   "status":"InProgress",
   "links":[
      {"rel":"self",
       "href":" "
     }]
}

Response - Member Limit Exceeded

Due to the processing cost, this API is limited to 50,000 security audits per company.

Other Responses

Case Response
Not a manager of company or an admin 403
Company Not Found 404

Get Progress

This resource returns the progress of the action. Clients are expected to poll the progress endpoint to retrieve the current status of the operation. On completion, it will return a link header with a URI to download the CSV file.

Request

GET identity/companies/{companyId}/securityaudits/{securityauditsGUID}
Accept: application/vnd.huddle.data+json
Authorization: OAuth2 frootymcnooty/vonbootycherooty

Response - In Progress

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json

{
  "links": [
    { "rel": "self", "href": "..." }
  ],
  "status": "InProgress"
}

Response - Complete

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json
Link: <...>;rel="content"

{
  "links": [
    { "rel": "self", "href": "..." },
    { "rel": "content", "href": "..." }
  ],
  "status": "Complete"
}

Response - Error

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json

{
  "links": [
    { "rel": "self", "href": "..." }
  ],
  "status": "Error"
}

Response - Other (no body)

Case Response
Not a Manager of Company or an admin 403
Progress Not Found 404

Download CSV

The endpoint to download the CSV file once it has been created.

Request

GET identity/companies/10584/securityaudits/50484e65-8f1b-47ee-84fa-d433e073e532/content HTTP/1.1
Accept: text/html
Authorization: OAuth2 frootymcnooty/vonbootycherooty

Response

CSV The first row of the CSV contains the field names

HTTP/1.1 200 OK
Content-Type: text/csv

Email,Type,ClientId,IP Address,Timestamp
[email protected],Identity.SecurityAuditType,my.huddle,127.0.0.1,01/06/2017 09:37:13
...

CSV Contents Type will be one of the following values:

Type
Identity.UserLoggedOut
Identity.UserLogInFailed
Identity.UserLoggedIn
Identity.UserDeniedClientAccess
Identity.LoggedInViaAssertion
Identity.UserGrantedClientAccess
Identity.UserAutomaticallyLoggedOut

Common ClientIds

ClientId
my.huddle
my.huddle-iCalendarFeed
HuddleReplyByEmail
huddle-pc3
huddle-iphone-app
huddle-android-app2
huddleforoffice3
huddle-mac3
huddlizer-outlook3
huddleofficeonline

Full sample

Type Email ClientIpAddress ClientId Timestamp
Identity.LoggedInViaAssertion [email protected] 1.13.214.205 my.huddle-iCalendarFeed 31/01/2018 10:43
Identity.LoggedInViaAssertion [email protected] 2.60.54.301 my.huddle-iCalendarFeed 31/01/2018 10:43
Identity.UserGrantedClientAccess [email protected] 3.221.113.94 my.huddle 31/01/2018 10:41
Identity.UserLoggedIn [email protected] 3.221.113.94 my.huddle 31/01/2018 10:41
Identity.UserLoggedOut [email protected] 3.221.113.94 my.huddle 31/01/2018 10:40
Identity.LoggedInViaAssertion [email protected] 4.221.190.120 my.huddle-iCalendarFeed 31/01/2018 10:40
Identity.UserLoggedIn [email protected] 555.202.101.146 my.huddle 31/01/2018 10:39
Identity.UserGrantedClientAccess [email protected] 555.202.101.146 my.huddle 31/01/2018 10:39
Identity.LoggedInViaAssertion [email protected] 66.192.250.181 my.huddle-iCalendarFeed 31/01/2018 10:03
Identity.UserLoggedIn [email protected] 3.221.113.94 huddle-pc3 31/01/2018 10:02
Identity.UserGrantedClientAccess [email protected] 3.221.113.94 huddle-pc3 31/01/2018 10:02
Identity.LoggedInViaAssertion [email protected] 7.166.147.146 my.huddle-iCalendarFeed 31/01/2018 10:02
Identity.UserLoggedOut [email protected] 3.221.113.94 huddle-pc3 31/01/2018 10:02
Identity.UserLogInFailed [email protected] 3.221.113.94 my.huddle 31/01/2018 10:02
Identity.UserAutomaticallyLoggedOut [email protected] 18.171.128.72 my.huddle 31/01/2018 10:01
Identity.UserLoggedOut [email protected] 13.128.202.31 my.huddle 31/01/2018 10:01
Identity.UserLoggedOut [email protected] 13.128.202.31 my.huddle 31/01/2018 10:01
Identity.UserLoggedOut [email protected] 13.128.202.31 my.huddle 31/01/2018 10:01
Identity.UserLoggedOut [email protected] 13.128.202.31 my.huddle 31/01/2018 10:01
Identity.LoggedInViaAssertion [email protected] 250.15.96.60 my.huddle-iCalendarFeed 31/01/2018 10:01
Identity.LoggedInViaAssertion [email protected] 250.15.96.60 my.huddle-iCalendarFeed 31/01/2018 10:01

Response - Other (no body)

Case Response
Not a Manager of Company or an admin 403
Company or Progress Not Found 404
⚠️ **GitHub.com Fallback** ⚠️