API Guidelines

SpyCloud's APIs provide a programmatic interface into our vast collection of breach records and surrounding metadata. The API is organized around basic REST principles. It has easy to understand, resource-oriented URLs, and uses HTTP response codes to indicate API errors. JSON is returned by all API responses, including those with errors.

---

Authentication

You can authenticate your account when using the API by including your secret API key in the request header. They key must be specified in the x-api-key header. You can securely access your API key(s) in your Customer Portal account. Your API keys carry many privileges, so be sure to keep them secret. Please do not share your API keys in any publicly accessible areas such as source code repositories, client-side web application code, etc.

All API requests must be made over HTTPS. HTTP requests are insecure and should be strictly avoided. API requests without valid authentication will fail with an HTTP 403 status code.

IP Allow-list

To further secure access to the API we will require a list of IPv4 addresses or IPv4 network CIDRs to allow.

If you call the API from a non-whitelisted IP address you will receive an HTTP 403 status code.

---

Configuration

Asset Allow-list

We can return specific assets to you and mask the rest. For example, many users only require email and password. Any other assets that are returned, such as PII, are not needed and can be a liability for the user. All other fields will be masked with a fixed length string of 8 asterisks.

You can provide a list of assets to allow or this will be determined by your contract. See Breach Records for all possible assets.

The following fields will always be displayed:

• document_id
• source_id
• spycloud_publish_date

Asset Hashing

To further secure the Breach Records returned to you we can hash and salt the assets returned. If this is enabled for your API key we will ask for the following configuration items:

• The list of assets to hash. See our Data Schema for all possible assets.
• The hashing algorithm to use. Possible values are sha1, sha224, sha256, sha384, sha512
• When creating a hash for an email address, it must first be in lower case.
• A 10 to 24 character salt with high entropy. You have the option to pass a dynamic salt in as a query parameter with each API call or use the pre-configured salt.
• The position of the salt. We can place the salt to the left or right of the value being hashed. By default the salt will be placed to the right of the asset value.

API Function Allow-list

You will either have access to all API functions or specific functions that will be determined by your contract.

If you call a function that you do not have access to you will receive an HTTP 403 status code.

---

Pagination

Some SpyCloud APIs have support for paginating response data. SpyCloud utilizes cursor-based pagination via the cursor parameter. The API uses a fixed page size of 1,000 records. Any time an API request results in more than one page of records the response will contain a non-empty cursor value. That value can then be used to iterate through the next page of results.

Due to technical limitations a cursor value has a lifespan of 2 minutes, after which it can no longer be used.

---

CORS

We support Cross-Origin Resource Sharing (CORS), allowing you to interact securely with our API from client-side web applications. A word of caution: please do not expose your API key in any public client-side code as that could allow others to make API calls on your behalf.

---

Errors

SpyCloud uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, parameter format was not valid, etc.), and codes in the 5xx range indicate an error with our API servers (these are rare).

Here are the most common HTTP status codes returned by our API:

---

Data Encoding

All data returned by the API is UTF-8 encoded.

---

Versioning

When we make backwards-incompatible changes to the API, we release a new version without affecting the old codebase. We also release a changelog, noting any possible change in behavior.

All requests will use your current API version, unless you manually override the version specifier in the request URL. To set the API version on a specific request, modify the version number in the URL. As a precaution, please test a new API version before committing to an upgrade.

---

Date Parameters

Certain API resources accept date-type parameters. Date-type parameters must follow the standard date ISO 8601 date format of "yyyy-mm-dd" with a four digit year, two digit month, and two digit day.

---

Limitations

• Our API keys do have quota limits. If you are receiving 429 errors, please contact us to discuss the possibility of increasing the quota for your API key(s).
• Pagination cursor tokens have a short lifetime, usually around 2 minutes.
• Response pages are limited to 1,000 items per page. Beyond that you will have to use pagination. This value is not customizable.
• For certain username and password resource requests you will have to URL escape special characters. Your API client will need to do this before issuing the request.
• We do not perform any additional normalization of email addresses. For example, we do not remove periods or +string from an email address.
• Each API might have specific limitations which will be listed in their respective sections.

---

API Retry Logic

There are a couple of approaches to implementing retry logic in the event you exceed your rate limit or receive an error. The same retry logic can be used for current API endpoints such as the Email endpoint.

Each approach assumes a default starting wait time of 3 seconds, though you can modify that.

Exponential Backoff

1. Call API endpoint. The call fails.
2. Wait 3 seconds, then retry the call.
3. If the call fails again, exponentially increase the timeout to 9 seconds (3*3s). Then try the call again.
4. If the call fails again, log the error and fail open.

Sliding Retry

1. Call API endpoint. The call fails.
2. Wait 3 seconds, then retry the call.
3. If the call fails again, wait for 4 seconds (1+3s). Then try the call again.
4. If the call fails again, log the error and fail open.