Skip to content
/
Retrieve an account

Push Security REST API (v1)

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.

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 CodeDescription
200 OKYour request was successfully processed.
400 Bad RequestYour request is missing something or is incorrect. Double-check your parameters.
429 Too Many RequestsYou've exceeded the rate limits. Consider implementing exponential backoffs in your API calls.
500 Server ErrorSomething'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.

Download OpenAPI description
rest-v1.json
rest-v1.yaml
Overview
URL
https://pushsecurity.com/contact/
support
support@pushsecurity.com
License
Commercial
Terms of Service
Languages
Servers
https://api.pushsecurity.com/

Accounts

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

Operations

List accounts

Request

Security
x-api-key
Query
emailstring

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

appTypestring

Filter by the app associated with this account.

employeeIdstring

Filter by an employee ID associated with this account.

passwordIdstring

Filter by a password ID associated with this account.

lastUsedTimestampAfterinteger

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

lastUsedTimestampBeforeinteger

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

limitinteger[ 1 .. 500 ]

Used for pagination. Number of objects to return.

Default 500
nextTokenstring

Used for pagination. Token to be used for the next request. Cannot be set when offset is also set.

offsetintegerDeprecated

Used for pagination. Number of objects to skip. Cannot be set when nextToken is also set.

curl -i -X GET \
  https://api.pushsecurity.com/v1/accounts \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
resultArray of objects(Account)
result[].​idstring

Unique identifier for the account

Example: "d6a32ba5-0532-4a66-8137-48cdf409c972"
result[].​employeeIdstring

Identifier of primary employee that this account belongs to

Example: "72d0347a-2663-4ef5-b1c5-df39163f1603"
result[].​appTypestring

The app associated with this account

Example: "ATLASSIAN"
result[].​appIdstring

The ID of the app associated with this account

Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
result[].​emailstring(email)

The email address used to log into the account

Example: "john.hill@example.com"
result[].​mfaRegisteredboolean or null

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

Example: true
result[].​mfaMethodsArray of strings or null(MfaMethodsType)

The MFA methods registered for this account

Enum ValueDescription
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

result[].​passwordIdstring 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"
result[].​loginMethodsobject
result[].​loginMethods.​passwordLoginboolean

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

Example: true
result[].​loginMethods.​lastPasswordLoginTimestampinteger

When the account was last logged into using a password, formatted as a UNIX timestamp (in seconds)

Example: 1698064423
result[].​loginMethods.​oidcLoginstring 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"
result[].​loginMethods.​lastOidcLoginTimestampinteger

When the account was last logged into using OIDC, formatted as a UNIX timestamp (in seconds)

Example: 1698064423
result[].​loginMethods.​samlLoginstring 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"
result[].​loginMethods.​lastSamlLoginTimestampinteger

When the account was last logged into using SAML, formatted as a UNIX timestamp (in seconds)

Example: 1698064423
result[].​loginMethods.​oktaSwaLoginboolean

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

Example: true
result[].​loginMethods.​lastOktaSwaLoginTimestampinteger

When the account was last logged into using Okta SWA, formatted as a UNIX timestamp (in seconds)

Example: 1698064423
result[].​loginMethods.​vendorSsoLoginstring or null

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

Example: "GOOGLE_WORKSPACE"
result[].​loginMethods.​fedCmLoginstring or null

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

Example: "GOOGLE_WORKSPACE"
result[].​loginMethods.​lastFedCmLoginTimestampinteger

When the account was last logged into using FedCM, formatted as a UNIX timestamp (in seconds)

Example: 1698064423
result[].​creationTimestampinteger

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

Example: 1698064423
result[].​lastUsedTimestampinteger or null

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

Example: 1698669168
pagingobject
paging.​moreResultsboolean

Whether there are more results available

Example: true
paging.​nextTokenstring or null

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

Example: "0b9972aa-fe8d-4095-82d3-2e13cf3cfd43"
paging.​nextstring or nullDeprecated

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

Example: "501"
Response
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,
        "lastPasswordLoginTimestamp": 1698064423,
        "oidcLogin": "GOOGLE_WORKSPACE",
        "lastOidcLoginTimestamp": 1698064423,
        "samlLogin": "OKTA",
        "lastSamlLoginTimestamp": 1698064423,
        "oktaSwaLogin": true,
        "lastOktaSwaLoginTimestamp": 1698064423,
        "vendorSsoLogin": "GOOGLE_WORKSPACE",
        "fedCmLogin": "GOOGLE_WORKSPACE",
        "lastFedCmLoginTimestamp": 1698064423
      },
      "creationTimestamp": 1698064423,
      "lastUsedTimestamp": 1698669168
    }
  ],
  "paging": {
    "moreResults": true,
    "next": "501",
    "nextToken": "0b9972aa-fe8d-4095-82d3-2e13cf3cfd43"
  }
}

Retrieve an account

Request

Security
x-api-key
Path
idstringrequired

Unique identifier for the account

curl -i -X GET \
  'https://api.pushsecurity.com/v1/accounts/{id}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
idstring

Unique identifier for the account

Example: "d6a32ba5-0532-4a66-8137-48cdf409c972"
employeeIdstring

Identifier of primary employee that this account belongs to

Example: "72d0347a-2663-4ef5-b1c5-df39163f1603"
appTypestring

The app associated with this account

Example: "ATLASSIAN"
appIdstring

The ID of the app associated with this account

Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
emailstring(email)

The email address used to log into the account

Example: "john.hill@example.com"
mfaRegisteredboolean or null

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

Example: true
mfaMethodsArray of strings or null(MfaMethodsType)

The MFA methods registered for this account

Enum ValueDescription
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

passwordIdstring 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"
loginMethodsobject
loginMethods.​passwordLoginboolean

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

Example: true
loginMethods.​lastPasswordLoginTimestampinteger

When the account was last logged into using a password, formatted as a UNIX timestamp (in seconds)

Example: 1698064423
loginMethods.​oidcLoginstring 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"
loginMethods.​lastOidcLoginTimestampinteger

When the account was last logged into using OIDC, formatted as a UNIX timestamp (in seconds)

Example: 1698064423
loginMethods.​samlLoginstring 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"
loginMethods.​lastSamlLoginTimestampinteger

When the account was last logged into using SAML, formatted as a UNIX timestamp (in seconds)

Example: 1698064423
loginMethods.​oktaSwaLoginboolean

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

Example: true
loginMethods.​lastOktaSwaLoginTimestampinteger

When the account was last logged into using Okta SWA, formatted as a UNIX timestamp (in seconds)

Example: 1698064423
loginMethods.​vendorSsoLoginstring or null

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

Example: "GOOGLE_WORKSPACE"
loginMethods.​fedCmLoginstring or null

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

Example: "GOOGLE_WORKSPACE"
loginMethods.​lastFedCmLoginTimestampinteger

When the account was last logged into using FedCM, formatted as a UNIX timestamp (in seconds)

Example: 1698064423
creationTimestampinteger

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

Example: 1698064423
lastUsedTimestampinteger or null

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

Example: 1698669168
Response
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,
    "lastPasswordLoginTimestamp": 1698064423,
    "oidcLogin": "GOOGLE_WORKSPACE",
    "lastOidcLoginTimestamp": 1698064423,
    "samlLogin": "OKTA",
    "lastSamlLoginTimestamp": 1698064423,
    "oktaSwaLogin": true,
    "lastOktaSwaLoginTimestamp": 1698064423,
    "vendorSsoLogin": "GOOGLE_WORKSPACE",
    "fedCmLogin": "GOOGLE_WORKSPACE",
    "lastFedCmLoginTimestamp": 1698064423
  },
  "creationTimestamp": 1698064423,
  "lastUsedTimestamp": 1698669168
}

Forget an account

Request

Security
x-api-key
Path
idstringrequired

Unique identifier for the account

curl -i -X DELETE \
  'https://api.pushsecurity.com/v1/accounts/{id}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
idstring

Unique identifier for the account

Example: "d6a32ba5-0532-4a66-8137-48cdf409c972"
objectstring

The type of object that has been removed by this operation

Example: "ACCOUNT"
deletedboolean

Whether the account has been successfully removed or not

Example: true
Response
application/json
{
  "id": "d6a32ba5-0532-4a66-8137-48cdf409c972",
  "object": "ACCOUNT",
  "deleted": true
}

Accounts (Other)

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

Operations

Apps

These objects represent the apps that have been found in your organization.

Operations

Apps (Other)

These objects represent the apps (other) that have been found in your organization.

Operations

Browsers

These objects represent the browsers (used by employees) in your organization.

Operations

Browser Extensions

Operations

Detections

Operations

Employees

These objects represent the employees in your organization.

Operations

Findings

These objects represent the findings that have been found in your organization.

Operations

URL blocking

These objects represent the blocked URLs configured in your organization.

Operations

Stolen credential detection

Manage custom stolen credentials that you have added to your organization for monitoring and enforcement.

Operations