BreachRx API

Table of Contents

Working with our GraphQL API
- Endpoint
- Authentication
Getting Started
- Querying: Reading Data
- Mutations: Creating and Updating Data
Other Tips
- Pagination
- Ordering
Support

Working with our GraphQL API #

The BreachRx public API is built using GraphQL. It’s the same API we use internally for developing our applications.

If you’re new to GraphQL, Apollo has excellent resources for beginners and support for most popular programming languages. The official documentation is another great starting point.

Endpoint #

The BreachRx GraphQL endpoint is:

https://graphql.app.breachrx.io/graphql

It supports introspection so you can query the whole schema.

Two headers are required: a typical Content-Type header and a BreachRx-specific orgName header which matches the custom portion of your BreachRx app URL (which typically aligns with your organization’s name).

curl
  -H "Content-Type: application/json"
  -H "orgName: example"

Authentication #

Right now we support the use of basic authentication with API keys as well as OAuth2 authentication.

API Keys

For scripts and simple integrations, API keys are the easiest way to access the BreachRx API. Keys can be generated by Admins in the BreachRx platform UI on the API Keys page. BreachRx recommends you rotate API keys routinely, such as every 90 days.

curl \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <replace with your Base64-encoded key:secret>" \
  -H "orgName: <replace with your organization's name>" \
  --data '{ "query": "{ version }" }' \
  https://graphql.app.breachrx.io/graphql

Don’t forget the colon between the key and secret before encoding

OAuth2

If you’re building a more complex integration or long-lasting application for others to use, we recommend you use OAuth2 authentication.

First, complete the authentication flow above once to acquire an access token from the response. Here’s an example of a successful response:

date: Tue, 26 Jul 2022 16:13:50 GMT
content-type: application/json; charset=utf-8
content-length: 2243
authorization: Bearer eyJraWQiOiJKSHNidzhJb3...fnvt94_w
access-control-allow-origin: *

You can then pass the provided access token in future requests, such as here:

curl \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJraWQiOiJKSHNidzhJb3...fnvt94_w" \
  -H "orgName: <replace with your organization's name>" \
  --data '{ "query": "{ version }" }' \
  https://graphql.app.breachrx.io/graphql

The access token will eventually expire and a new token will need to be refetched when that happens.

Getting Started #

We recommend using a GraphQL client to introspect and explore the schema. Insomnia is an excellent free client that supports GraphQL and introspection. Point the client to the BreachRx GraphQL endpoint, set up authentication and the headers, and set the query type to “GraphQL Query”.

Once you have your client installed, you can start making queries (read) and mutations (write) to the API.

Querying: Reading Data #

You can check that you’ve configured your client correctly with the version query:

query Version {
version
}

The BreachRx API supports standard GraphQL queries for customers to access their data. In addition, for some of the more complex queries, the BreachRx team is continuously adding shortcut queries to make this easier for API users. Here’s an example to get information about the current authenticated user:

query CurrentUser {
  currentUser {
    id
    email
    fullName
    nickname
  }
}

While there are many ways to interact with objects, it is typically easiest when you have a specific ID for that object. For example, if you wanted to query for the incidents for which you are the Incident Leader, you can use the id returned from the currentUser query above (for this example, we will assume the user’s id is 12).

query IncidentsIAmLeading {
  incidents(
    where:{leadUser:{is:{id:{equals:12}}}}
) {
    id
    name
    description
    createdAt
  }
}

To get the full list of available queries and mutations, introspect the GraphQL API with your favorite GraphQL client.

Mutations: Creating and Updating Data #

To create or update data, we’ll need to create a mutation. Here’s an example of creating a tag (in this example, a ticket id from another application):

mutation CreateTag {
  createOneTag(
    data: {
      key: “tag”
      value: “IT-4321”
    }
) {
    id
  }
}

For common actions, such as creating incidents, the BreachRx team is continuously adding shortcut mutations to make this easier for API users. Here’s an example:

mutation CreateIncident {
  createIncident(
    name: "CSR Email Improper Disclosure"
    type: "Improper Disclosure"
    severity: "Medium"
    description: "Our CSR John Smith sent one customer’s details to another customer"
) {
    id
  }
}

Don’t forget that schema items can be added, referenced, and customized by Admins in the BreachRx platform UI on the Data Customization page.

Other Tips #

Pagination #

All list responses from queries return can be paginated using the standard pagination model with take/skip arguments. For example, to simply query get the first 10 approved incidents for your organization:

query ApprovedIncidents {
  incidents(
    where:{isApproved:{equals:true}}
    take:10
) {
    id
    name
    isApproved
  }
}

To query for the next 10, just repeat but leverage the skip argument to indicate how many you’ve already pulled:

query ApprovedIncidents {
  incidents(
    where:{isApproved:{equals:true}}
    take:10
    skip:10
) {
    id
    name
    isApproved
  }
}

Ordering #

The standard orderBy and asc/desc arguments for ascending and descending order, respectively, can be used to order responses. For example:

query OrderedIncidents {
  incidents(
    orderBy:{createdAt:desc}
) {
    id
    name
    createdAt
  }
}

Support #

BreachRx platform status can be found here (https://breachrx.statuspage.io/).

If you have questions, suggestions, or run into issues, please send us a note (support@breachrx.com).

BREACHRX PLATFORM