REST API Webhooks

Push Security REST API (v1)

Download OpenAPI specification:Download

support: support@pushsecurity.com URL: https://pushsecurity.com/contact/ License: Commercial Terms of Service

Overview

The Push Security REST API provides programmatic access to the administrative functionality of the Push platform. This API adheres to RESTful principles, featuring resource-oriented URLs that are predictable and easy to navigate.

The API uses JSON-formatted request bodies and responses along with standard HTTP response codes, authentication methods, and HTTP verbs.

Rate limits are in place to ensure consistent performance for all users.

Authentication

To interact with the Push Security API, you'll need an API key for authentication. To create or manage your API keys, go to the Settings page in the Push admin console. You can get there by clicking Create API key from the top right corner of this documentation.

When generating a new key, you have two permission levels to choose from: Read only and Full access. A Read only key lets you make GET requests, while Full access allows for all types of requests.

To authenticate your API requests, include a header named x-api-key and set its value to your API key.

All API calls must be made over HTTPS.

Rate limits

The Push Security API enforces rate limiting to ensure equitable access and maintain performance. Each user is permitted up to 10 API requests per second, with a temporary burst capacity that allows an additional 10 requests for brief intervals.

If you surpass these limits, the API will return a 429 status code as an indication.

Errors

The Push Security API uses standard HTTP response codes to signal the outcome of an API call. Here's what you need to know:

2xx codes: These indicate that your request was successful.

4xx codes: A client-side issue, usually because something is missing or incorrect in your request.

5xx codes: These suggest a problem on our end, although these occurrences are infrequent.

Common Response Codes

HTTP Code Description
200 OK Your request was successfully processed.
400 Bad Request Your request is missing something or is incorrect. Double-check your parameters.
429 Too Many Requests You've exceeded the rate limits. Consider implementing exponential backoffs in your API calls.
500 Server Error Something's not right on our end.

Versioning

You're currently working with version 1 of the Push Security API. Should there be any breaking changes in the future, we'll bump up the API version number. If you hold an active API key, we'll send you notifications over email about the deprecation date for the older version.

Accounts

These objects represent the accounts (owned by employees) in your organization.

List accounts

Request
query Parameters
email
string

Filter by email address. Accepts partial email addresses for wildcard searches.

appType
string

Filter by the app associated with this account.

lastUsedTimestampAfter
integer

Filter by when the account was last used by an employee - start time. This is a UNIX timestamp (in seconds).

lastUsedTimestampBefore
integer

Filter by when the account was last used by an employee - end time. This is a UNIX timestamp (in seconds).

limit
integer [ 1 .. 50 ]
Default: 50

Used for pagination. Number of objects to return.

offset
integer
Default: 0

Used for pagination. Number of objects to skip.

Responses
200

OK

Response Schema: application/json
Array of objects (Account)
Array
id
string

Unique identifier for the account

Example: "d6a32ba5-0532-4a66-8137-48cdf409c972"
employeeId
string

Identifier of primary employee that this account belongs to

Example: "72d0347a-2663-4ef5-b1c5-df39163f1603"
appType
string

The app associated with this account

Example: "ATLASSIAN"
appId
string

The ID of the app associated with this account

Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
email
string <email>

The email address used to log into the account

Example: "john.hill@example.com"
mfaRegistered
boolean or null

Whether MFA is registered or not. If unknown, null is provided.

Example: true
mfaMethods
Array of strings or null (MfaMethodsType)

The MFA methods registered for this account

Enum Value Description
APP_TOTP

Time-based one-time password via app

PUSH_NOTIFICATION

Authentication prompt on device

EMAIL_OTP

One-time password sent to email

U2F

Physical security key

HARDWARE_TOTP

Time-based password via hardware token

PHONE_CALL

Voice verification

SMS_OTP

One-time password sent via SMS

APP_PASSWORD

Specialized password for app access

GRID_CARD

Reference card with codes

EXTERNAL_PROVIDER

Third-party authentication service

BACKUP_CODES

Pre-generated one-time codes

WEBAUTHN

Two-factor authentication with biometrics support

passwordId
string or null

Identifier of the password used on this account. The actual password is not sent up by the browser extension and so this is an identifier for it instead. This value is null if password authentication is not used.

Example: "4c13674f-e88a-4411-bfa2-53a70468a898"
object
passwordLogin
required
boolean

Whether or not this account has been logged into with a password

Example: true
oidcLogin
required
string or null

The identity provider that was used to do an OIDC login on this account. This is null if no OIDC login has been performed.

Example: "GOOGLE_WORKSPACE"
samlLogin
required
string or null

The identity provider that was used to do a SAML login on this account. This is null if no SAML login has been performed.

Example: "OKTA"
oktaSwaLogin
required
boolean

Whether or not this account has been logged into with Okta SWA

Example: true
vendorSsoLogin
required
string or null

Whether or not this account has an associated vendor SSO provider.

Example: "GOOGLE_WORKSPACE"
creationTimestamp
integer

When this account was created, formatted as a UNIX timestamp (in seconds)

Example: 1698064423
lastUsedTimestamp
integer or null

When the account was last used by an employee, formatted as a UNIX timestamp (in seconds)

Example: 1698669168
object
moreResults
boolean

Whether there are more results available

Example: true
next
string

Start of the next page that can be used as the offset for the next request

Example: "51"
400

Bad Request

get/v1/accounts
Request samples 
Response samples 
application/json
{
  • "result": [
    • {
      • "id": "d6a32ba5-0532-4a66-8137-48cdf409c972",
      • "employeeId": "72d0347a-2663-4ef5-b1c5-df39163f1603",
      • "appType": "ATLASSIAN",
      • "appId": "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0",
      • "email": "john.hill@example.com",
      • "mfaRegistered": true,
      • "mfaMethods": [
        • "APP_TOTP"
        ],
      • "passwordId": "4c13674f-e88a-4411-bfa2-53a70468a898",
      • "loginMethods": {
        • "passwordLogin": true,
        • "oidcLogin": "GOOGLE_WORKSPACE",
        • "samlLogin": "OKTA",
        • "oktaSwaLogin": true,
        • "vendorSsoLogin": "GOOGLE_WORKSPACE"
        },
      • "creationTimestamp": 1698064423,
      • "lastUsedTimestamp": 1698669168
      }
    ],
  • "paging": {
    • "moreResults": true,
    • "next": "51"
    }
}
Retrieve an account
Request 
path Parameters
id
required
string
Unique identifier for the account


 
Responses 
200
OK


Response Schema: application/json
id
string
Unique identifier for the account


 
 Example:  "d6a32ba5-0532-4a66-8137-48cdf409c972"
employeeId
string
Identifier of primary employee that this account belongs to


 
 Example:  "72d0347a-2663-4ef5-b1c5-df39163f1603"
appType
string
The app associated with this account


 
 Example:  "ATLASSIAN"
appId
string
The ID of the app associated with this account


 
 Example:  "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
email
string <email> 
The email address used to log into the account


 
 Example:  "john.hill@example.com"
mfaRegistered
boolean or null
Whether MFA is registered or not. If unknown, null is provided.


 
 Example:  true
mfaMethods
Array of strings or null (MfaMethodsType) 
The MFA methods registered for this account


 Enum Value Description
APP_TOTP
Time-based one-time password via app


PUSH_NOTIFICATION
Authentication prompt on device


EMAIL_OTP
One-time password sent to email


U2F
Physical security key


HARDWARE_TOTP
Time-based password via hardware token


PHONE_CALL
Voice verification


SMS_OTP
One-time password sent via SMS


APP_PASSWORD
Specialized password for app access


GRID_CARD
Reference card with codes


EXTERNAL_PROVIDER
Third-party authentication service


BACKUP_CODES
Pre-generated one-time codes


WEBAUTHN
Two-factor authentication with biometrics support


 
passwordId
string or null
Identifier of the password used on this account. The actual password is not sent up by the browser extension and so this is an identifier for it instead. This value is null if password authentication is not used.


 
 Example:  "4c13674f-e88a-4411-bfa2-53a70468a898"
object
 
passwordLogin
required
boolean
Whether or not this account has been logged into with a password


 
 Example:  true
oidcLogin
required
string or null
The identity provider that was used to do an OIDC login on this account. This is null if no OIDC login has been performed.


 
 Example:  "GOOGLE_WORKSPACE"
samlLogin
required
string or null
The identity provider that was used to do a SAML login on this account. This is null if no SAML login has been performed.


 
 Example:  "OKTA"
oktaSwaLogin
required
boolean
Whether or not this account has been logged into with Okta SWA


 
 Example:  true
vendorSsoLogin
required
string or null
Whether or not this account has an associated vendor SSO provider.


 
 Example:  "GOOGLE_WORKSPACE"
creationTimestamp
integer
When this account was created, formatted as a UNIX timestamp (in seconds)


 
 Example:  1698064423
lastUsedTimestamp
integer or null
When the account was last used by an employee, formatted as a UNIX timestamp (in seconds)


 
 Example:  1698669168
400
Bad Request


404
Account Not Found


get/v1/accounts/{id}
Request samples 
Response samples 
application/json
{
  • "id": "d6a32ba5-0532-4a66-8137-48cdf409c972",
  • "employeeId": "72d0347a-2663-4ef5-b1c5-df39163f1603",
  • "appType": "ATLASSIAN",
  • "appId": "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0",
  • "email": "john.hill@example.com",
  • "mfaRegistered": true,
  • "mfaMethods": [
    • "APP_TOTP"
    ],
  • "passwordId": "4c13674f-e88a-4411-bfa2-53a70468a898",
  • "loginMethods": {
    • "passwordLogin": true,
    • "oidcLogin": "GOOGLE_WORKSPACE",
    • "samlLogin": "OKTA",
    • "oktaSwaLogin": true,
    • "vendorSsoLogin": "GOOGLE_WORKSPACE"
    },
  • "creationTimestamp": 1698064423,
  • "lastUsedTimestamp": 1698669168
}
Forget an account
Request 
path Parameters
id
required
string
Unique identifier for the account


 
Responses 
200
OK


Response Schema: application/json
id
string
Unique identifier for the account


 
 Example:  "d6a32ba5-0532-4a66-8137-48cdf409c972"
object
string
The type of object that has been removed by this operation


 
 Example:  "ACCOUNT"
deleted
boolean
Whether the account has been successfully removed or not


 
 Example:  "true"
400
Bad Request


404
Account Not Found


delete/v1/accounts/{id}
Request samples 
Response samples 
application/json
{
  • "id": "d6a32ba5-0532-4a66-8137-48cdf409c972",
  • "object": "ACCOUNT",
  • "deleted": "true"
}
List all employees who are using an account
Request 
path Parameters
id
required
string
Unique identifier for the account


 
query Parameters
limit
integer  [ 1 .. 50 ] 
 Default:  50
Used for pagination. Number of objects to return.


 
offset
integer
 Default:  0
Used for pagination. Number of objects to skip.


 
Responses 
200
OK


Response Schema: application/json
employeeId
string
Identifier of the employee has access to this account


 
 Example:  "bf4cf562-7830-41ac-80e3-d261da1c9bb9"
lastUsedTimestamp
integer or null
When the account was last used by an employee, formatted as a UNIX timestamp (in seconds)


 
 Example:  1698669223
passwordManuallyTyped
boolean
Whether the password was manually typed (or a password manager was used) on the last login. This value is null if password authentication is not used


 
 Example:  true
400
Bad Request


get/v1/accounts/{id}/usedBy
Request samples 
Response samples 
application/json
{
  • "employeeId": "bf4cf562-7830-41ac-80e3-d261da1c9bb9",
  • "lastUsedTimestamp": 1698669223,
  • "passwordManuallyTyped": true
}
Accounts (Other)
These objects represent the accounts (other) (owned by employees) in your organization.


List accounts (other)
Request 
query Parameters
email
string
Filter by email address. Accepts partial email addresses for wildcard searches.


 
otherAppId
string
Filter by other app ID.


 
lastUsedTimestampAfter
integer
Filter by when the account was last used by an employee - start time. This is a UNIX timestamp (in seconds).


 
lastUsedTimestampBefore
integer
Filter by when the account was last used by an employee - end time. This is a UNIX timestamp (in seconds).


 
limit
integer  [ 1 .. 50 ] 
 Default:  50
Used for pagination. Number of objects to return.


 
offset
integer
 Default:  0
Used for pagination. Number of objects to skip.


 
Responses 
200
OK


Response Schema: application/json
Array of objects (Account (other)) 
 
 Array 
id
string
Unique identifier for the account


 
 Example:  "1009e8cb-497b-49ae-ac87-e083e42078d2"
employeeId
string
Identifier of primary employee that this account belongs to


 
 Example:  "72d0347a-2663-4ef5-b1c5-df39163f1603"
otherAppId
string
The ID of the app associated with this account


 
 Example:  "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
email
string <email> 
The email address used to log into the account


 
 Example:  "john.hill@example.com"
object
 
passwordLogin
required
boolean
Whether or not this account has been logged into with a password


 
 Example:  true
oidcLogin
required
string or null
The identity provider that was used to do an OIDC login on this account. This is null if no OIDC login has been performed.


 
 Example:  "GOOGLE_WORKSPACE"
samlLogin
required
string or null
The identity provider that was used to do a SAML login on this account. This is null if no SAML login has been performed.


 
 Example:  "OKTA"
creationTimestamp
integer
When the account was first observed, formatted as a UNIX timestamp (in seconds)


 
 Example:  1698064423
lastUsedTimestamp
integer or null
When the account was last used by an employee, formatted as a UNIX timestamp (in seconds)


 
 Example:  1698669168
object
 
moreResults
boolean
Whether there are more results available


 
 Example:  true
next
string
Start of the next page that can be used as the offset for the next request


 
 Example:  "51"
400
Bad Request


get/v1/accountsOther
Request samples 
Response samples 
application/json
{
  • "result": [
    • {
      • "id": "1009e8cb-497b-49ae-ac87-e083e42078d2",
      • "employeeId": "72d0347a-2663-4ef5-b1c5-df39163f1603",
      • "otherAppId": "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0",
      • "email": "john.hill@example.com",
      • "loginMethods": {
        • "passwordLogin": true,
        • "oidcLogin": "GOOGLE_WORKSPACE",
        • "samlLogin": "OKTA"
        },
      • "creationTimestamp": 1698064423,
      • "lastUsedTimestamp": 1698669168
      }
    ],
  • "paging": {
    • "moreResults": true,
    • "next": "51"
    }
}
Retrieve an account (other)
Request 
path Parameters
id
required
string <uuid> 
Unique identifier for the account (other) record


 
Responses 
200
OK


Response Schema: application/json
id
string
Unique identifier for the account


 
 Example:  "1009e8cb-497b-49ae-ac87-e083e42078d2"
employeeId
string
Identifier of primary employee that this account belongs to


 
 Example:  "72d0347a-2663-4ef5-b1c5-df39163f1603"
otherAppId
string
The ID of the app associated with this account


 
 Example:  "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
email
string <email> 
The email address used to log into the account


 
 Example:  "john.hill@example.com"
object
 
passwordLogin
required
boolean
Whether or not this account has been logged into with a password


 
 Example:  true
oidcLogin
required
string or null
The identity provider that was used to do an OIDC login on this account. This is null if no OIDC login has been performed.


 
 Example:  "GOOGLE_WORKSPACE"
samlLogin
required
string or null
The identity provider that was used to do a SAML login on this account. This is null if no SAML login has been performed.


 
 Example:  "OKTA"
creationTimestamp
integer
When the account was first observed, formatted as a UNIX timestamp (in seconds)


 
 Example:  1698064423
lastUsedTimestamp
integer or null
When the account was last used by an employee, formatted as a UNIX timestamp (in seconds)


 
 Example:  1698669168
400
Bad Request


404
Account (Other) Not Found


get/v1/accountsOther/{id}
Request samples 
Response samples 
application/json
{
  • "id": "1009e8cb-497b-49ae-ac87-e083e42078d2",
  • "employeeId": "72d0347a-2663-4ef5-b1c5-df39163f1603",
  • "otherAppId": "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0",
  • "email": "john.hill@example.com",
  • "loginMethods": {
    • "passwordLogin": true,
    • "oidcLogin": "GOOGLE_WORKSPACE",
    • "samlLogin": "OKTA"
    },
  • "creationTimestamp": 1698064423,
  • "lastUsedTimestamp": 1698669168
}
Apps
These objects represent the apps that have been found in your organization.


List apps
Request 
query Parameters
creationTimestampAfter
integer
Filter by when the app was first observed - start time. This is a UNIX timestamp (in seconds).


 
creationTimestampBefore
integer
Filter by when the app was first observed - end time. This is a UNIX timestamp (in seconds).


 
limit
integer  [ 1 .. 50 ] 
 Default:  50
Used for pagination. Number of objects to return.


 
offset
integer
 Default:  0
Used for pagination. Number of objects to skip.


 
Responses 
200
OK


Response Schema: application/json
Array of objects (App) 
 
 Array 
id
string
Unique identifier for this object


 
 Example:  "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
type
string
The type of app, formatted as an ENUM value.


 
 Example:  "ZAPIER"
approvalStatus
string or null (ApprovalStatusType) 
Approval status of the app, null if not set


 Enum Value Description
UNDER_REVIEW
The app is under review


APPROVED
The app has been approved


NOT_APPROVED
The app has not been approved


 
sensitivityLevel
string or null (SensitivityLevelType) 
The sensitivity level of the app, null if not set


 Enum Value Description
HIGH
The sensitivity of the app is high


MEDIUM
The sensitivity of the app is medium


LOW
The sensitivity of the app is low


 
ownerId
string or null
Identifier of the employee who is the owner of this platform


 
 Example:  "87569da6-fb7a-4df7-8ce2-246c14044911"
notes
string
Notes recorded on this app


 
 Example:  "Last security audit: 16 January 2023"
website
string
URL to the app's homepage


 
 Example:  "https://zapier.com/"
description
string
Description of the app's purpose


 
 Example:  "Zapier is a cloud-based automation tool that enables users to integrate and automate various web applications without requiring extensive coding knowledge, potentially streamlining workflows and processes."
friendlyName
string
The friendly name of the app


 
 Example:  "Zapier"
labels
Array of strings
Labels associated with this app


 
 Example:  ["GenAI","marketing"]
creationTimestamp
integer
When the app was first observed, formatted as a UNIX timestamp (in seconds)


 
 Example:  1698064423
object
 
moreResults
boolean
Whether there are more results available


 
 Example:  true
next
string
Start of the next page that can be used as the offset for the next request


 
 Example:  "51"
400
Bad Request


get/v1/apps
Request samples 
Response samples 
application/json
{
  • "result": [
    • {
      • "id": "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0",
      • "type": "ZAPIER",
      • "approvalStatus": "UNDER_REVIEW",
      • "sensitivityLevel": "HIGH",
      • "ownerId": "87569da6-fb7a-4df7-8ce2-246c14044911",
      • "notes": "Last security audit: 16 January 2023",
      • "website": "https://zapier.com/",
      • "description": "Zapier is a cloud-based automation tool that enables users to integrate and automate various web applications without requiring extensive coding knowledge, potentially streamlining workflows and processes.",
      • "friendlyName": "Zapier",
      • "labels": [
        • "GenAI",
        • "marketing"
        ],
      • "creationTimestamp": 1698064423
      }
    ],
  • "paging": {
    • "moreResults": true,
    • "next": "51"
    }
}
Retrieve an app
Request 
path Parameters
id
required
string
Unique identifier for the app


 
Responses 
200
OK


Response Schema: application/json
id
string
Unique identifier for this object


 
 Example:  "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
type
string
The type of app, formatted as an ENUM value.


 
 Example:  "ZAPIER"
approvalStatus
string or null (ApprovalStatusType) 
Approval status of the app, null if not set


 Enum Value Description
UNDER_REVIEW
The app is under review


APPROVED
The app has been approved


NOT_APPROVED
The app has not been approved


 
sensitivityLevel
string or null (SensitivityLevelType) 
The sensitivity level of the app, null if not set


 Enum Value Description
HIGH
The sensitivity of the app is high


MEDIUM
The sensitivity of the app is medium


LOW
The sensitivity of the app is low


 
ownerId
string or null
Identifier of the employee who is the owner of this platform


 
 Example:  "87569da6-fb7a-4df7-8ce2-246c14044911"
notes
string
Notes recorded on this app


 
 Example:  "Last security audit: 16 January 2023"
website
string
URL to the app's homepage


 
 Example:  "https://zapier.com/"
description
string
Description of the app's purpose


 
 Example:  "Zapier is a cloud-based automation tool that enables users to integrate and automate various web applications without requiring extensive coding knowledge, potentially streamlining workflows and processes."
friendlyName
string
The friendly name of the app


 
 Example:  "Zapier"
labels
Array of strings
Labels associated with this app


 
 Example:  ["GenAI","marketing"]
creationTimestamp
integer
When the app was first observed, formatted as a UNIX timestamp (in seconds)


 
 Example:  1698064423
400
Bad Request


get/v1/apps/{id}
Request samples 
Response samples 
application/json
{
  • "id": "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0",
  • "type": "ZAPIER",
  • "approvalStatus": "UNDER_REVIEW",
  • "sensitivityLevel": "HIGH",
  • "ownerId": "87569da6-fb7a-4df7-8ce2-246c14044911",
  • "notes": "Last security audit: 16 January 2023",
  • "website": "https://zapier.com/",
  • "description": "Zapier is a cloud-based automation tool that enables users to integrate and automate various web applications without requiring extensive coding knowledge, potentially streamlining workflows and processes.",
  • "friendlyName": "Zapier",
  • "labels": [
    • "GenAI",
    • "marketing"
    ],
  • "creationTimestamp": 1698064423
}
Apps (Other)
These objects represent the apps (other) that have been found in your organization.


List Apps (Other)
Request 
query Parameters
creationTimestampAfter
integer
Filter by when the app was first observed - start time. This is a UNIX timestamp (in seconds).


 
creationTimestampBefore
integer
Filter by when the app was first observed - end time. This is a UNIX timestamp (in seconds).


 
limit
integer  [ 1 .. 50 ] 
 Default:  50
Used for pagination. Number of objects to return.


 
offset
integer
 Default:  0
Used for pagination. Number of objects to skip.


 
Responses 
200
OK


Response Schema: application/json
Array of objects (App (Other)) 
 
 Array 
id
string
Unique identifier for this object


 
 Example:  "35603905-ff98-4b7d-8940-eb1906a2bdf6"
domain
string or null
Domain the user logged into. This value is null if a OIDC login is used


 
 Example:  "app.pushsecurity.com"
oauthAppId
string or null
ID of the oauth app from the Identity Provider. This value is null if a password login is used.


 
 Example:  "1234567890"
name
string or null
Name of the app. This value is null if a password login is used.


 
 Example:  "Push Security"
hidden
boolean
Whether the app is hidden or not.


 
requestSupportStatus
string
Current request support status of the app


 
 Example:  "DISCOVERED"
creationTimestamp
integer
When the app was first observed, formatted as a UNIX timestamp (in seconds)


 
 Example:  1698064423
object
 
moreResults
boolean
Whether there are more results available


 
 Example:  true
next
string
Start of the next page that can be used as the offset for the next request


 
 Example:  "51"
400
Bad Request


get/v1/appsOther
Request samples 
Response samples 
application/json
{
  • "result": [
    • {
      • "id": "35603905-ff98-4b7d-8940-eb1906a2bdf6",
      • "domain": "app.pushsecurity.com",
      • "oauthAppId": "1234567890",
      • "name": "Push Security",
      • "hidden": true,
      • "requestSupportStatus": "DISCOVERED",
      • "creationTimestamp": 1698064423
      }
    ],
  • "paging": {
    • "moreResults": true,
    • "next": "51"
    }
}
Retrieve an app (other) record
Request 
path Parameters
id
required
string
Unique identifier for the app (other) record


 
Responses 
200
OK


Response Schema: application/json
id
string
Unique identifier for this object


 
 Example:  "35603905-ff98-4b7d-8940-eb1906a2bdf6"
domain
string or null
Domain the user logged into. This value is null if a OIDC login is used


 
 Example:  "app.pushsecurity.com"
oauthAppId
string or null
ID of the oauth app from the Identity Provider. This value is null if a password login is used.


 
 Example:  "1234567890"
name
string or null
Name of the app. This value is null if a password login is used.


 
 Example:  "Push Security"
hidden
boolean
Whether the app is hidden or not.


 
requestSupportStatus
string
Current request support status of the app


 
 Example:  "DISCOVERED"
creationTimestamp
integer
When the app was first observed, formatted as a UNIX timestamp (in seconds)


 
 Example:  1698064423
400
Bad Request


404
App (Other) Not Found


get/v1/appsOther/{id}
Request samples 
Response samples 
application/json
{
  • "id": "35603905-ff98-4b7d-8940-eb1906a2bdf6",
  • "domain": "app.pushsecurity.com",
  • "oauthAppId": "1234567890",
  • "name": "Push Security",
  • "hidden": true,
  • "requestSupportStatus": "DISCOVERED",
  • "creationTimestamp": 1698064423
}
Employees
These objects represent the employees in your organization.


List employees
Request 
query Parameters
chatopsEnabled
boolean
Filter by whether they have ChatOps enabled


 
licensed
boolean
Filter by whether they are licensed on the Push platform


 
email
string
Filter by email address. Accepts partial email addresses for wildcard searches.


 
limit
integer  [ 1 .. 50 ] 
 Default:  50
Used for pagination. Number of objects to return.


 
offset
integer
 Default:  0
Used for pagination. Number of objects to skip.


 
Responses 
200
OK


Response Schema: application/json
Array of objects (Employee) 
 
 Array 
id
string
Unique identifier for the employee


 
 Example:  "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
email
string <email> 
Email address of the employee


 
 Example:  "john.hill@example.com"
firstName
string
First name of the employee


 
 Example:  "John"
lastName
string
Last name of the employee


 
 Example:  "Hill"
department
string
Department - as provided by connected API integrations


 
 Example:  "Security Engineering"
location
string
Location - as provided by connected API integrations


 
 Example:  "New York"
licensed
boolean
Whether the employee is licensed on the Push platform


 
 Example:  true
chatopsEnabled
boolean
Whether the employee has ChatOps enabled


 
 Example:  true
creationTimestamp
integer
When this employee was created, formatted as a UNIX timestamp (in seconds)


 
 Example:  1698669223
object
 
moreResults
boolean
Whether there are more results available


 
 Example:  true
next
string
Start of the next page that can be used as the offset for the next request


 
 Example:  "51"
400
Bad Request


get/v1/employees
Request samples 
Response samples 
application/json
{
  • "result": [
    • {
      • "id": "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0",
      • "email": "john.hill@example.com",
      • "firstName": "John",
      • "lastName": "Hill",
      • "department": "Security Engineering",
      • "location": "New York",
      • "licensed": true,
      • "chatopsEnabled": true,
      • "creationTimestamp": 1698669223
      }
    ],
  • "paging": {
    • "moreResults": true,
    • "next": "51"
    }
}
Retrieve an employee
Request 
path Parameters
id
required
string
Unique identifier for the employee


 
Responses 
200
OK


Response Schema: application/json
id
string
Unique identifier for the employee


 
 Example:  "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
email
string <email> 
Email address of the employee


 
 Example:  "john.hill@example.com"
firstName
string
First name of the employee


 
 Example:  "John"
lastName
string
Last name of the employee


 
 Example:  "Hill"
department
string
Department - as provided by connected API integrations


 
 Example:  "Security Engineering"
location
string
Location - as provided by connected API integrations


 
 Example:  "New York"
licensed
boolean
Whether the employee is licensed on the Push platform


 
 Example:  true
chatopsEnabled
boolean
Whether the employee has ChatOps enabled


 
 Example:  true
creationTimestamp
integer
When this employee was created, formatted as a UNIX timestamp (in seconds)


 
 Example:  1698669223
400
Bad Request


404
Employee Not Found


get/v1/employees/{id}
Request samples 
Response samples 
application/json
{
  • "id": "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0",
  • "email": "john.hill@example.com",
  • "firstName": "John",
  • "lastName": "Hill",
  • "department": "Security Engineering",
  • "location": "New York",
  • "licensed": true,
  • "chatopsEnabled": true,
  • "creationTimestamp": 1698669223
}
Update an employee
Request 
path Parameters
id
required
string
Unique identifier for the employee


 
Request Body schema: application/json
chatopsEnabled
boolean
Set whether the employee has ChatOps enabled


 
licensed
boolean
Set whether the employee is licensed on the Push platform


 
Responses 
200
OK. Returns null if you unlicense an employee that hasn't got any accounts


Response Schema: application/json
id
string
Unique identifier for the employee


 
 Example:  "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
email
string <email> 
Email address of the employee


 
 Example:  "john.hill@example.com"
firstName
string
First name of the employee


 
 Example:  "John"
lastName
string
Last name of the employee


 
 Example:  "Hill"
department
string
Department - as provided by connected API integrations


 
 Example:  "Security Engineering"
location
string
Location - as provided by connected API integrations


 
 Example:  "New York"
licensed
boolean
Whether the employee is licensed on the Push platform


 
 Example:  true
chatopsEnabled
boolean
Whether the employee has ChatOps enabled


 
 Example:  true
creationTimestamp
integer
When this employee was created, formatted as a UNIX timestamp (in seconds)


 
 Example:  1698669223
400
Bad Request with status EMPLOYEE_NOT_LICENSED, EXCEEDED_MAX_LICENSED_EMPLOYEES or CHATOPS_NOT_IN_WORKING_STATE


404
Employee Not Found


patch/v1/employees/{id}
Request samples 
Response samples 
application/json
{
  • "id": "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0",
  • "email": "john.hill@example.com",
  • "firstName": "John",
  • "lastName": "Hill",
  • "department": "Security Engineering",
  • "location": "New York",
  • "licensed": true,
  • "chatopsEnabled": true,
  • "creationTimestamp": 1698669223
}
Findings
These objects represent the findings that have been found in your organization.


List findings
Request 
query Parameters
state
string
Filter by finding state.


 
type
string
Filter by the type of finding.


 
employeeId
string
Filter by the employee associated with the finding.


 
appType
string
Filter by the app that is associated with the finding.


 
accountId
string
Filter by the account that is associated with the finding.


 
passwordId
string
Filter by the password identifier that is associated with the finding.


 
creationTimestampAfter
string
Filter by when the finding was first observed - start time. This is a UNIX timestamp (in seconds).


 
creationTimestampBefore
integer
Filter by when the finding was first observed - end time. This is a UNIX timestamp (in seconds).


 
limit
integer  [ 1 .. 50 ] 
 Default:  50
Used for pagination. Number of objects to return.


 
offset
integer
 Default:  0
Used for pagination. Number of objects to skip.


 
Responses 
200
OK


Response Schema: application/json
Array of objects (Finding) 
 
 Array 
id
string
Unique identifier for the finding


 
 Example:  "d6a32ba5-0532-4a66-8137-48cdf409c972"
type
string (FindingType) 
The type of finding


 Enum Value Description
MFA_NOT_REGISTERED
This account does not have MFA.


REUSED_PASSWORD
The password used on the account is being reused.


SHARED_ACCOUNT
The account credentials are being shared with another employee.


UNUSED_THIRD_PARTY_APP
The third-party integration has not been used in 90 days or more.


WEAK_PASSWORD
The password used on the account is weak.


LEAKED_PASSWORD
The password used on the account has been leaked in a data breach.


PASSWORD_MANAGER_NOT_USED
The employee typically uses manually typed passwords, rather than a password manager.


 
state
string (FindingState) 
The state of the finding


 Enum Value Description
OPEN
The finding has been confirmed and is open.


RESOLVED
The finding has been resolved and is no longer an issue.


 
employeeId
string or null
ID of the employee this finding is linked to, null if finding is not linked to an employee.


 
 Example:  "379ac7ea-ff2a-42ef-af37-06d2020dc46a"
passwordId
string or null
ID of the password this finding is linked to, null if finding is not linked to a password.


 
 Example:  "c4a045a1-5331-4714-af83-6a361e98960d"
accountId
string or null
ID of the account this finding is linked to, null if finding is not linked to an account.


 
appType
string or null
The type of app this finding is linked to, null if finding is not linked to an app.


 
 Example:  "PUSH_SECURITY"
appId
string or null
ID of the app this finding is linked to, null if finding is not linked to an app.


 
 Example:  "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
weakPasswordReasons
Array of strings or null (FindingType) 
Reasons a password is weak, null if not a WEAK_PASSWORD finding.


 Enum Value Description
COMPROMISED_HIBP
Password appears in the Have I Been Pwnd database.


COMMON_BASE_WORD
The base word is a derivative of top 10000 most used passwords.


BANNED_BASE_WORD
The password is a derivative of a custom banned word.


 
creationTimestamp
integer
When this finding was first observed, formatted as a UNIX timestamp (in seconds)


 
 Example:  1698064423
object
 
moreResults
boolean
Whether there are more results available


 
 Example:  true
next
string
Start of the next page that can be used as the offset for the next request


 
 Example:  "51"
400
Bad Request


get/v1/findings
Request samples 
Response samples 
application/json
{
  • "result": [
    • {
      • "id": "d6a32ba5-0532-4a66-8137-48cdf409c972",
      • "type": "MFA_NOT_REGISTERED",
      • "state": "OPEN",
      • "employeeId": "379ac7ea-ff2a-42ef-af37-06d2020dc46a",
      • "passwordId": "c4a045a1-5331-4714-af83-6a361e98960d",
      • "accountId": "string",
      • "appType": "PUSH_SECURITY",
      • "appId": "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0",
      • "weakPasswordReasons": [
        • "COMPROMISED_HIBP"
        ],
      • "creationTimestamp": 1698064423
      }
    ],
  • "paging": {
    • "moreResults": true,
    • "next": "51"
    }
}
Retrieve a finding
Request 
path Parameters
id
required
string
Unique identifier for the finding


 
Responses 
200
OK


Response Schema: application/json
id
string
Unique identifier for the finding


 
 Example:  "d6a32ba5-0532-4a66-8137-48cdf409c972"
type
string (FindingType) 
The type of finding


 Enum Value Description
MFA_NOT_REGISTERED
This account does not have MFA.


REUSED_PASSWORD
The password used on the account is being reused.


SHARED_ACCOUNT
The account credentials are being shared with another employee.


UNUSED_THIRD_PARTY_APP
The third-party integration has not been used in 90 days or more.


WEAK_PASSWORD
The password used on the account is weak.


LEAKED_PASSWORD
The password used on the account has been leaked in a data breach.


PASSWORD_MANAGER_NOT_USED
The employee typically uses manually typed passwords, rather than a password manager.


 
state
string (FindingState) 
The state of the finding


 Enum Value Description
OPEN
The finding has been confirmed and is open.


RESOLVED
The finding has been resolved and is no longer an issue.


 
employeeId
string or null
ID of the employee this finding is linked to, null if finding is not linked to an employee.


 
 Example:  "379ac7ea-ff2a-42ef-af37-06d2020dc46a"
passwordId
string or null
ID of the password this finding is linked to, null if finding is not linked to a password.


 
 Example:  "c4a045a1-5331-4714-af83-6a361e98960d"
accountId
string or null
ID of the account this finding is linked to, null if finding is not linked to an account.


 
appType
string or null
The type of app this finding is linked to, null if finding is not linked to an app.


 
 Example:  "PUSH_SECURITY"
appId
string or null
ID of the app this finding is linked to, null if finding is not linked to an app.


 
 Example:  "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
weakPasswordReasons
Array of strings or null (FindingType) 
Reasons a password is weak, null if not a WEAK_PASSWORD finding.


 Enum Value Description
COMPROMISED_HIBP
Password appears in the Have I Been Pwnd database.


COMMON_BASE_WORD
The base word is a derivative of top 10000 most used passwords.


BANNED_BASE_WORD
The password is a derivative of a custom banned word.


 
creationTimestamp
integer
When this finding was first observed, formatted as a UNIX timestamp (in seconds)


 
 Example:  1698064423
400
Bad Request


get/v1/findings/{id}
Request samples 
Response samples 
application/json
{
  • "id": "d6a32ba5-0532-4a66-8137-48cdf409c972",
  • "type": "MFA_NOT_REGISTERED",
  • "state": "OPEN",
  • "employeeId": "379ac7ea-ff2a-42ef-af37-06d2020dc46a",
  • "passwordId": "c4a045a1-5331-4714-af83-6a361e98960d",
  • "accountId": "string",
  • "appType": "PUSH_SECURITY",
  • "appId": "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0",
  • "weakPasswordReasons": [
    • "COMPROMISED_HIBP"
    ],
  • "creationTimestamp": 1698064423
}
URL blocking
These objects represent the blocked URLs configured in your organization.


List all blocked URLs
Responses 
200
OK


Response Schema: application/json
result
Array of strings (Blocked URL) 
 
 Example:  ["*://*.example.com/*","*://other.example.com/path/to*"]
get/v1/controls/blockedUrls
Request samples 
Response samples 
application/json
{
  • "result": [
    • "*://*.example.com/*",
    • "*://other.example.com/path/to*"
    ]
}
Add a new blocked URL
Request 
Request Body schema: application/json
required
A URL pattern used to block access to matching sites.


host
required
string
The host part of the URL pattern. This can be a domain or a subdomain. Wildcards are supported for subdomains.


 
 Example:  "*.sub.domain.com"
path
string
The path part of the URL pattern. Wildcards are supported. If not specified, the wildcard * is assumed, matching all paths for the given host.


 
 Example:  "/path/to*"
Responses 
200
OK


Response Schema: application/json
string (Blocked URL) 
This object represents a URL pattern used to block access to matching sites.


 
400
Bad Request


post/v1/controls/blockedUrls
Request samples 
Response samples 
application/json
"*://*.example.com/*"
Delete all blocked URLs
Responses 
200
OK


delete/v1/controls/blockedUrls
Request samples