Getting Started

Use the instructions on this page to learn how to authenticate with the Firmhouse GraphQL API and how to make your first API calls.

Authentication

All calls to the Firmhouse GraphQL API require a valid X-Project-Access-Token HTTP header to be passed in every request. You can generate a Project Access Token by going to the Settings > Integrations page in your Firmhouse project as a project manager.

Access Token Types

Each Project Access Token has a specific access type. The access type controls what the token can do (or cannot do) and which data is accessible via the token.

There a currently two access types: write and storefront. In the near future we will also introduce a read type. Read below on the details per access type.

Write

The write access type gives you full API access to all data. Treat this as an administrative secret that you should not expose to the public. This token can read and modify all data in your project. Always securely embed this token into your application and never expose this token to regular users or the public.

Storefront

The storefront access type is meant for building Headless applications or storefronts without needing a server-side component in your app. For example in your frontend React application or Apollo JS client. It is safe to expose this token to the public as part of your runtime codebase.

A storefront token will only give limited access to available products and plans. And it allows you to build a cart and initiate a subscription checkout and payment flow. This token does not give you access to subscription data after the subscription has signed up.

Making calls

The API is exposed on the following endpoint:

POST https://portal.firmhouse.com/graphql

All calls towards our API should be made with a HTTP POST. Your HTTP POST should include a valid X-Project-Access-Token HTTP header as explained under Authentication.

Certain queries and mutations also need a X-Subscription-Token HTTP header to be present, alongside the X-Project-Access-Token. This is usually the case when a query or mutation accesses data of an individual subscription.

Calls can be made via standard server-to-server HTTP communication, but also by using Fetch from your customer's browser if you're building a frontend or headless experience without server-side component.

Clients and libraries

There are several ways and clients that can be used to interact with the API. For example:

• Use a tool such as GraphiQL or Insomnia to interactively explore the API and its documentation.

• Use cURL to manually make calls from the command-line.

• Use the GraphQL Ruby Client to make calls from a Ruby on Rails app.

• Use Apollo when using React, Vue, or Next.js.

Query Complexity

Every call to our API has a calculated query complexity. In the near future we will be rejecting queries that exceed a total complexity of 1000 for a single query.

New projects already have this limit applied. Existing API consumers will be notified of this change and will get the time to update their queries.

How is complexity calculated?

Take the following example query, its total complexity is 27. The complexity is calculated based on the maximum possible value. In this example "collectionCases" could be less then 10 pages but its attributes are still multiplied by 10.

query {
  getSubscription(token: "token") {                  # +1
    token                                            # +1
    collectionCases(first: 10) {                     # +1
      nodes {                                        # +1
        id                                           # +10 (+1, multiplied by `first:` above)
        caseNumber                                   # +10 (+1, multiplied by `first:` above)
      }
      pageInfo {                                     # +1
        endCursor                                    # +1
      }
      totalCount                                     # +1
    }
  }
}

These are the defaults but it could be that certain fields take more resources to compute. We might increase the complexity manually for such fields.

The response of every query includes information about the requested complexity found in the path: "extensions.complexity.requestedQueryComplexity".

{
  "data": {
    "getSubscription": {
      "token": "token",
      "collectionCases": {
        "nodes": [...],
        "pageInfo": {
          "endCursor": "..."
        },
        "totalCount": 1
      }
    }
  },
  "extensions": {
    "complexity": {
      "requestedQueryComplexity": 27
    }
  }
}

Take a look at the pagination documentation for more information about how to paginate over large result sets and optimize your queries.