Push Security REST API (v1)

Download OpenAPI specification:Download

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"
}

Delete a login method from an account

Request
path Parameters
id
required
string

Unique identifier for the account

Request Body schema: application/json
required

Delete one of the login methods from the account.

loginMethod
required
string

The login method to remove from the account.

Enum: "USERNAME_PASSWORD" "OKTA_SWA" "OIDC" "SAML"
Example: "OIDC"
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

delete/v1/accounts/{id}/loginMethods
Request samples
Response samples
application/json
{
  • "employeeId": "bf4cf562-7830-41ac-80e3-d261da1c9bb9",
  • "lastUsedTimestamp": 1698669223,
  • "passwordManuallyTyped": 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
}

Update an app

Request
path Parameters
id
required
string

Unique identifier for the app

Request Body schema: application/json
required

Update an app's approval status, sensitivity level, and/or notes.

approvalStatus
string or null

The desired approval status for the app. If null, the current approval status will be unset.

Enum: "APPROVED" "NOT_APPROVED" "UNDER_REVIEW"
Example: "APPROVED"
sensitivityLevel
string or null

The desired sensitivity level for the app. If null, the current sensitivity level will be unset.

Enum: "HIGH" "MEDIUM" "LOW"
Example: "HIGH"
notes
string or null

The desired notes for the app. If null, any existing notes will be deleted.

Example: "Last security audit: 16 January 2024"
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

patch/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
}

Add a label to an app.

Request
path Parameters
id
required
string

Unique identifier for the app

Request Body schema: application/json
required

Add a label to an app.

label
required
string

The label to add to the app (max 50 characters)

Example: "personal-use"
Responses
200

OK. Returns all labels associated with the app.

Response Schema: application/json
labels
required
Array of strings

The labels associated with the app.

Example: ["personal-use","other-label"]
400

Invalid input

404

App Not Found

post/v1/apps/{id}/labels
Request samples
Response samples
application/json
{
  • "labels": [
    • "personal-use",
    • "other-label"
    ]
}

Delete a label from an app.

Request
path Parameters
id
required
string

Unique identifier for the app

Request Body schema: application/json
required

Delete a label from an app.

label
required
string

The label to delete from the app.

Example: "personal-use"
Responses
200

OK. Returns all labels still associated with the app after the label is deleted.

Response Schema: application/json
labels
required
Array of strings

The labels associated with the app.

Example: ["other-label"]
400

Invalid input

404

The app with the given ID is not found or the given label is not associated with the app.

delete/v1/apps/{id}/labels
Request samples
Response samples
application/json
{
  • "labels": [
    • "other-label"
    ]
}

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
}

Browsers

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

List browsers

Retrieve a list of browser objects

Request
query Parameters
email
string

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

employeeId
string

Filter by employee ID.

browser
any (BrowserType)

Filter by browser name.

Enum: "CHROME" "FIREFOX" "EDGE" "SAFARI" "OPERA" "BRAVE" "ARC" "UNKNOWN"
os
any (OSType)

Filter by operating system name.

Enum: "MACOS" "WINDOWS" "LINUX" "CHROME_OS" "IOS" "ANDROID" "UNKNOWN"
lastOnlineTimestampAfter
integer

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

lastOnlineTimestampBefore
integer

Filter by when the browser 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 or null (Browser)
Array
id
string

Unique identifier for the browser

Example: "1852b6ab-0cca-4c8d-8f14-4905497504ec"
employeeId
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"
version
string

Version of the browser

Example: "125.0.0.0"
tokenType
string

Type of enrollment token used

Enum: "INDIVIDUAL" "TEAM"
isActive
boolean

Whether the browser extension is used by a licensed employee

Example: true
browser
any (BrowserType)

The browser used by the employee

Enum: "CHROME" "FIREFOX" "EDGE" "SAFARI" "OPERA" "BRAVE" "ARC" "UNKNOWN"
os
any (OSType)

The OS used by the employee

Enum: "MACOS" "WINDOWS" "LINUX" "CHROME_OS" "IOS" "ANDROID" "UNKNOWN"
extensionVersion
string

Version of the Push extension

Example: "1.66.17"
creationTimestamp
integer

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

Example: 1698669223
lastOnlineTimestamp
integer

When this browser was last seen, formatted as a UNIX timestamp (in seconds)

Example: 1716290202
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/browsers
Request samples
Response samples
application/json
{
  • "result": [
    • {
      • "id": "1852b6ab-0cca-4c8d-8f14-4905497504ec",
      • "employeeId": "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0",
      • "email": "john.hill@example.com",
      • "version": "125.0.0.0",
      • "tokenType": "INDIVIDUAL",
      • "isActive": true,
      • "browser": "CHROME",
      • "os": "MACOS",
      • "extensionVersion": "1.66.17",
      • "creationTimestamp": 1698669223,
      • "lastOnlineTimestamp": 1716290202
      }
    ],
  • "paging": {
    • "moreResults": true,
    • "next": "51"
    }
}

Retrieve a browser

Request
path Parameters
id
required
string

Unique identifier for the browser

Responses
200

OK

Response Schema: application/json
id
string

Unique identifier for the browser

Example: "1852b6ab-0cca-4c8d-8f14-4905497504ec"
employeeId
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"
version
string

Version of the browser

Example: "125.0.0.0"
tokenType
string

Type of enrollment token used

Enum: "INDIVIDUAL" "TEAM"
isActive
boolean

Whether the browser extension is used by a licensed employee

Example: true
browser
any (BrowserType)

The browser used by the employee

Enum: "CHROME" "FIREFOX" "EDGE" "SAFARI" "OPERA" "BRAVE" "ARC" "UNKNOWN"
os
any (OSType)

The OS used by the employee

Enum: "MACOS" "WINDOWS" "LINUX" "CHROME_OS" "IOS" "ANDROID" "UNKNOWN"
extensionVersion
string

Version of the Push extension

Example: "1.66.17"
creationTimestamp
integer

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

Example: 1698669223
lastOnlineTimestamp
integer

When this browser was last seen, formatted as a UNIX timestamp (in seconds)

Example: 1716290202
400

Bad Request

get/v1/browsers/{id}
Request samples
Response samples
application/json
{
  • "id": "1852b6ab-0cca-4c8d-8f14-4905497504ec",
  • "employeeId": "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0",
  • "email": "john.hill@example.com",
  • "version": "125.0.0.0",
  • "tokenType": "INDIVIDUAL",
  • "isActive": true,
  • "browser": "CHROME",
  • "os": "MACOS",
  • "extensionVersion": "1.66.17",
  • "creationTimestamp": 1698669223,
  • "lastOnlineTimestamp": 1716290202
}

Employees

These objects represent the employees in your organization.

List employees

Request
query Parameters
chatopsEnabled
boolean
Deprecated

Filter by whether they have ChatOps enabled

Deprecation notice: this value no longer does anything unless you still have access to the legacy Employee chat topics functionality on your account. It will be removed in the next API version.

licensed
boolean

Filter by whether they are licensed on the Push platform

groups
Array of strings

Filter by groups the employee is in.

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
Deprecated

Whether the employee has ChatOps enabled

Deprecation notice: this value no longer does anything unless you still have access to the legacy Employee chat topics functionality on your account. It will be removed in the next API version.

Example: true
groups
Array of strings

Groups the employee is in

Example: ["engineering","marketing"]
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,
      • "groups": [
        • "engineering",
        • "marketing"
        ],
      • "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
Deprecated

Whether the employee has ChatOps enabled

Deprecation notice: this value no longer does anything unless you still have access to the legacy Employee chat topics functionality on your account. It will be removed in the next API version.

Example: true
groups
Array of strings

Groups the employee is in

Example: ["engineering","marketing"]
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,
  • "groups": [
    • "engineering",
    • "marketing"
    ],
  • "creationTimestamp": 1698669223
}

Update an employee

Request
path Parameters
id
required
string

Unique identifier for the employee

Request Body schema: application/json
chatopsEnabled
boolean
Deprecated

Set whether the employee has ChatOps enabled

Deprecation notice: this value no longer does anything unless you still have access to the legacy Employee chat topics functionality on your account. It will be removed in the next API version.

licensed
boolean

Set whether the employee is licensed on the Push platform

groups
Array of strings

Set the groups an employee is in (this will overwrite the existing groups)

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
Deprecated

Whether the employee has ChatOps enabled

Deprecation notice: this value no longer does anything unless you still have access to the legacy Employee chat topics functionality on your account. It will be removed in the next API version.

Example: true
groups
Array of strings

Groups the employee is in

Example: ["engineering","marketing"]
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,
  • "groups": [
    • "engineering",
    • "marketing"
    ],
  • "creationTimestamp": 1698669223
}

Add an employee to a group.

Request
path Parameters
id
required
string

Unique identifier for the employee

Request Body schema: application/json
required

Add an employee to a group

group
required
string

The name of the group.

Example: "Engineering team"
Responses
200

OK. Returns all groups associated with the employee.

Response Schema: application/json
groups
required
Array of strings

The groups associated with the employee.

Example: ["Engineering team","Marketing team"]
400

Invalid input

404

Employee Not Found

post/v1/employees/{id}/groups
Request samples
Response samples
application/json
{
  • "groups": [
    • "Engineering team",
    • "Marketing team"
    ]
}

Delete an employee from a group

Request
path Parameters
id
required
string

Unique identifier for the employee

Request Body schema: application/json
required

Delete an employee from a group.

group
required
string

The group to remove employee from.

Example: "Engineering team"
Responses
200

OK. Returns all groups still associated with the employee after being removed.

Response Schema: application/json
groups
required
Array of strings

The groups associated with the employee.

Example: ["Other team"]
400

Invalid input

404

The employee with the given ID is not found or the employee is not a member of the given group.

delete/v1/employees/{id}/groups
Request samples
Response samples
application/json
{
  • "groups": [
    • "Other team"
    ]
}

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.

STOLEN_CREDENTIALS

The credentials used on the account have been identified as stolen.

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.

STOLEN_CREDENTIALS

The credentials used on the account have been identified as stolen.

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
}

App banners

These objects represent the app banners configured in your organization.

List app banners

Request
query Parameters
enabled
boolean
Default: true

Used to filter out apps that do not have an app banner enabled

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 Banner)
Array
id
string

Unique identifier for this object

Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
appType
string

The type of app, formatted as an ENUM value.

Example: "ZAPIER"
enabled
boolean

Whether the app banner is enabled or disabled

Example: true
title
string

Title of the app banner.

Example: "This is a title"
subtext
string

Subtext of the app banner.

Example: "This is the subtext that supports limited [markdown](https://markdown.org)"
mode
string (AppBannerModeType)

All possible ENUM values for app banner modes

Enum: "INFORM" "ACKNOWLEDGE" "REASON" "BLOCK"
buttonText
string or null

Button text of the app banner. Only applicable when the app banner is in ACKNOWLEDGE or REASON mode, or is in BLOCK mode with allowReasonSubmission set to true.

Example: "Proceed anyway"
allowReasonSubmission
boolean or null

Whether the user is allowed to submit a request to access a blocked page. Only applicable when the app banner is in BLOCK mode.

Example: false
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/controls/appBanners
Request samples
Response samples
application/json
{
  • "result": [
    • {
      • "id": "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0",
      • "appType": "ZAPIER",
      • "enabled": true,
      • "title": "This is a title",
      • "subtext": "This is the subtext that supports limited [markdown](https://markdown.org)",
      • "mode": "INFORM",
      • "buttonText": "Proceed anyway",
      • "allowReasonSubmission": false
      }
    ],
  • "paging": {
    • "moreResults": true,
    • "next": "51"
    }
}

Retrieve an app banner

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"
appType
string

The type of app, formatted as an ENUM value.

Example: "ZAPIER"
enabled
boolean

Whether the app banner is enabled or disabled

Example: true
title
string

Title of the app banner.

Example: "This is a title"
subtext
string

Subtext of the app banner.

Example: "This is the subtext that supports limited [markdown](https://markdown.org)"
mode
string (AppBannerModeType)

All possible ENUM values for app banner modes

Enum: "INFORM" "ACKNOWLEDGE" "REASON" "BLOCK"
buttonText
string or null

Button text of the app banner. Only applicable when the app banner is in ACKNOWLEDGE or REASON mode, or is in BLOCK mode with allowReasonSubmission set to true.

Example: "Proceed anyway"
allowReasonSubmission
boolean or null

Whether the user is allowed to submit a request to access a blocked page. Only applicable when the app banner is in BLOCK mode.

Example: false
400

Bad Request

404

Not Found

get/v1/controls/appBanners/{id}
Request samples
Response samples
application/json
{
  • "id": "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0",
  • "appType": "ZAPIER",
  • "enabled": true,
  • "title": "This is a title",
  • "subtext": "This is the subtext that supports limited [markdown](https://markdown.org)",
  • "mode": "INFORM",
  • "buttonText": "Proceed anyway",
  • "allowReasonSubmission": false
}

Set an app banner

Request
path Parameters
id
required
string

Unique identifier for the app

Request Body schema: application/json
required

Set an app banner for a specific app

enabled
required
boolean

Set whether the app banner is enabled or disabled

title
string

Set the title of the app banner (max 75 characters)

Example: "This is a title"
subtext
string

Set the subtext of the app banner (supports markdown links) (max 1000 characters)

Example: "This is the subtext that supports limited [markdown](https://markdown.org)"
mode
string (AppBannerModeType)

All possible ENUM values for app banner modes

Enum: "INFORM" "ACKNOWLEDGE" "REASON" "BLOCK"
buttonText
string

Set the button text of the app banner (max 75 characters). Only applicable when the app banner is in ACKNOWLEDGE or REASON mode, or is in BLOCK mode with allowReasonSubmission set to true.

Example: "Proceed anyway"
allowReasonSubmission
boolean

Set whether the user is allowed to submit a request to access a blocked page. Only applicable when the app banner is in BLOCK mode.

Responses
200

OK. Returns the app banner details.

Response Schema: application/json
id
string

Unique identifier for this object

Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
appType
string

The type of app, formatted as an ENUM value.

Example: "ZAPIER"
enabled
boolean

Whether the app banner is enabled or disabled

Example: true
title
string

Title of the app banner.

Example: "This is a title"
subtext
string

Subtext of the app banner.

Example: "This is the subtext that supports limited [markdown](https://markdown.org)"
mode
string (AppBannerModeType)

All possible ENUM values for app banner modes

Enum: "INFORM" "ACKNOWLEDGE" "REASON" "BLOCK"
buttonText
string or null

Button text of the app banner. Only applicable when the app banner is in ACKNOWLEDGE or REASON mode, or is in BLOCK mode with allowReasonSubmission set to true.

Example: "Proceed anyway"
allowReasonSubmission
boolean or null

Whether the user is allowed to submit a request to access a blocked page. Only applicable when the app banner is in BLOCK mode.

Example: false
400

Invalid input

404

App Not Found

post/v1/controls/appBanners/{id}
Request samples
Response samples
application/json
{
  • "id": "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0",
  • "appType": "ZAPIER",
  • "enabled": true,
  • "title": "This is a title",
  • "subtext": "This is the subtext that supports limited [markdown](https://markdown.org)",
  • "mode": "INFORM",
  • "buttonText": "Proceed anyway",
  • "allowReasonSubmission": false
}

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*"]
400

Bad Request

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.

One of:
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

400

Bad Request

delete/v1/controls/blockedUrls
Request samples