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:
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 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.
Last updated