Developer Docs

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.