# Push Security REST API

## 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](#section/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](https://pushsecurity.com/app/settings/api-keys) 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 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.

Version: v1
License: Commercial

## Servers

```
https://api.pushsecurity.com
```

## Security

### x-api-key

API key authentication

Type: apiKey
In: header
Name: x-api-key

## Download OpenAPI description

[Push Security REST API](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/_bundle/rest-v1.yaml)

## Accounts

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

### List accounts

 - [GET /v1/accounts](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/accounts/get-accounts.md)

### Retrieve an account

 - [GET /v1/accounts/{id}](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/accounts/get-accounts-id.md)

### Forget an account

 - [DELETE /v1/accounts/{id}](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/accounts/delete-accounts-id.md)

### Delete a login method from an account

 - [DELETE /v1/accounts/{id}/loginMethods](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/accounts/delete-accounts-id-login-methods.md)

### List all employees who are using an account

 - [GET /v1/accounts/{id}/usedBy](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/accounts/get-accounts-id-used-by.md)

## Accounts (Other)

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

### List accounts (other)

 - [GET /v1/accountsOther](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/accounts-(other)/get-accounts-other.md)

### Retrieve an account (other)

 - [GET /v1/accountsOther/{id}](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/accounts-(other)/get-accounts-other-id.md)

## Apps

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

### List apps

 - [GET /v1/apps](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/apps/get-apps.md)

### Retrieve an app

 - [GET /v1/apps/{id}](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/apps/get-apps-id.md)

### Update an app

 - [PATCH /v1/apps/{id}](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/apps/patch-apps-id.md)

### Add a label to an app.

 - [POST /v1/apps/{id}/labels](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/apps/post-apps-id-labels.md)

### Delete a label from an app.

 - [DELETE /v1/apps/{id}/labels](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/apps/delete-apps-id-labels.md)

## Apps (Other)

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

### List Apps (Other)

 - [GET /v1/appsOther](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/apps-(other)/get-apps-other.md)

### Retrieve an app (other) record

 - [GET /v1/appsOther/{id}](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/apps-(other)/get-apps-other-id.md)

## Browsers

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

### List browsers

 - [GET /v1/browsers](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/browsers/get-browsers.md): Retrieve a list of browser objects

### Retrieve a browser

 - [GET /v1/browsers/{id}](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/browsers/get-browsers-id.md)

## Browser Extensions

### List browser extensions

 - [GET /v1/browserExtensions](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/browser-extensions/get-browser-extensions.md): Retrieve a list of browser extension objects

## Detections

### List detections

 - [GET /v1/detections](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/detections/get-detections.md): Retrieve a list of detection objects

### Retrieve a detection

 - [GET /v1/detections/{id}](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/detections/get-detections-id.md)

### Update a detection

 - [PATCH /v1/detections/{id}](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/detections/patch-detections-id.md)

## Employees

These objects represent the employees in your organization.

### List employees

 - [GET /v1/employees](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/employees/get-employees.md)

### Add an employee

 - [POST /v1/employees](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/employees/post-employees.md)

### Retrieve an employee

 - [GET /v1/employees/{id}](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/employees/get-employees-id.md)

### Update an employee

 - [PATCH /v1/employees/{id}](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/employees/patch-employees-id.md)

### Generate a browser enrollment link

 - [POST /v1/employees/{id}/enrollmentLink](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/employees/post-employees-id-enrollmentlink.md)

### Add an employee to a group.

 - [POST /v1/employees/{id}/groups](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/employees/post-employee-id-groups.md)

### Delete an employee from a group

 - [DELETE /v1/employees/{id}/groups](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/employees/delete-employee-id-groups.md)

### Merge employees

 - [POST /v1/employees/{id}/merge](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/employees/post-employees-id-merge.md)

### Unmerge employee

 - [POST /v1/employees/{id}/unmerge](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/employees/post-employees-id-unmerge.md)

## Findings

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

### List findings

 - [GET /v1/findings](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/findings/get-findings.md)

### Retrieve a finding

 - [GET /v1/findings/{id}](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/findings/get-findings-id.md)

## URL blocking

These objects represent the blocked URLs configured in your organization.

### List all blocked URLs

 - [GET /v1/controls/blockedUrls](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/url-blocking/get-controls-blockedurls.md)

### Add a new blocked URL

 - [POST /v1/controls/blockedUrls](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/url-blocking/post-controls-blockedurls.md)

### Delete all blocked URLs

 - [DELETE /v1/controls/blockedUrls](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/url-blocking/delete-controls-blockedurls.md)

## Stolen credential detection

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

### Add new stolen credentials

 - [POST /v1/controls/stolenCredentials](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/stolen-credential-detection/post-controls-stolencredentials.md): Add stolen credentials sourced from other threat intelligence feeds within your organization.

### Delete all stolen credentials

 - [DELETE /v1/controls/stolenCredentials](https://push-security-prd-ba8f0f76-a2d2-42f5-aea2-d421.redocly.app/rest-v1/stolen-credential-detection/delete-controls-stolencredentials.md): Delete all the custom stolen credentials that you have added to your organization.